Merge pull request #10534 from timblaktu/patch-1

Improve Documentation for Build-level Source Block

website/content/docs/templates/hcl_templates/blocks/build/source.mdx

@@ -1,7 +1,8 @@
 ---
 description: >
   A source block nested in a build block allows you to use an already defined
-  source and to set specific fields.
+  source and to set specific fields which aren't already set in the top-level 
+  source block.
 page_title: source - build - Blocks
 sidebar_title: <tt>source</tt>
 ---
@@ -10,8 +11,16 @@ sidebar_title: <tt>source</tt>
 
 `@include 'from-1.5/beta-hcl2-note.mdx'`
 
-A `source` block nested in a `build` block allows to use an already defined
+A `source` block nested in a `build` block allows you to use an already defined
-source and to set specific fields.
+source and to "fill in" those fields _which aren't already set in the top-level 
+source block_. 
+
+Build-level source blocks are implemented by merging their contents with the 
+corresponding top-level source block, and a packer build will fail when it 
+encounters the ambiguity that arises when a source parameter is defined twice. 
+For example, in the below example, if the top-level "lxd.arch" source block 
+also defined an `output_image` field (or if one of the build-level source blocks 
+redefined and image field), Packer would error.
 
 ```hcl
 # builds.pkr.hcl
@@ -43,11 +52,3 @@ build {
   }
 }
 ```
-
-This allows to have commonly defined source settings with specific parts of it
-defined inside the specific build block.
-
--> **Note:** It is **not allowed** to set the same field in a top-level source
-block and in a used source block. For example, if in the above example, the
-top-level "amazon-ebs.example" source block also had an `output` field;
-Packer would error.