better docs

website/pages/docs/from-1.5/blocks/build/index.mdx

@@ -13,6 +13,13 @@ sidebar_title: <tt>build</tt>
 The `build` block defines what builders are started, how to `provision` them
 and if necessary what to do with their artifacts using `post-process`.
 
+To use builders in a `build` block you can either: 
+
+* Set the `sources` array of string with references to pre-defined sources.
+
+* Define [build-level `source` blocks](/docs/from-1.5/blocks/build/source) or
+`sources` to use builders. This also allows you to set specific fields.
+
 `@include 'from-1.5/builds/example-block.mdx'`
 
 
@@ -20,12 +27,6 @@ Define [top-level `source` blocks](/docs/from-1.5/blocks/source) to configure
 your builders. The list of available builders can be found in the
 [builders](/docs/builders) section.
 
-To use builders in a `build` block you can either: 
-
-* Set the `sources` array of string with references to defined sources.
-
-* Define [build-level `source` blocks](/docs/from-1.5/blocks/build/source) or
-`sources` to use builders. This also allows you to set specific fields.
 
 ## Related
 

website/pages/partials/from-1.5/builds/example-block.mdx

@@ -1,16 +1,19 @@
 ```hcl
 # build.pkr.hcl
 build {
+    # use the `name` field to name a build in the logs.
+    # For example this present config will display 
+    # "buildname.amazon-ebs.example-1" and "buildname.amazon-ebs.example-2"
+    name = "buildname"
 
     sources = [
-        # use the plural `sources` block to simply use sources
+        # use the optional plural `sources` list to simply use a `source`
         # without changing any field.
-        "source.amazon-ebs.example",
+        "source.amazon-ebs.example-1",
     ]
 
-    source "source.amazon-ebs.example" {
-        # Use the singular `source` block set
-        # specific fields.
+    source "source.amazon-ebs.example-2" {
+        # Use the singular `source` block set specific fields.
         # Note that fields cannot be overwritten, in other words, you cannot 
         # set the 'output' field from the top-level source block and here.
         output = "different value"

website/pages/partials/from-1.5/locals/example-block.mdx

@@ -3,7 +3,7 @@
 locals {
     # locals can be bare values like:
     wee = local.baz
-    # locals can also be set with input variables :
-    baz = "Foo is '${var.foo}'"
+    # locals can also be set with other variables :
+    baz = "Foo is '${var.foo}' but not '${local.wee}'"
 }
 ```

website/pages/partials/from-1.5/sources/example-block.mdx

@@ -1,6 +1,6 @@
 ```hcl
 # sources.pkr.hcl
-source "amazon-ebs" "example" {
+source "amazon-ebs" "example-1" {
     // ...
 }
 ```