clarify onlyexcept docs further (#10679)

website/content/docs/commands/validate.mdx

@@ -33,12 +33,20 @@ Errors validating build 'vmware'. 1 error(s) occurred:
   configuration is not validated.
 
 - `-except=foo,bar,baz` - Validates all the builds except those with the
-  comma-separated names. Build names by default are the names of their
+  comma-separated names. In legacy JSON templates, build names default to the
-  builders, unless a specific `name` attribute is specified within the configuration.
+  types of their builders (e.g. `docker` or
+  `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is
+  specified within the configuration. In HCL2 templates, the "name" is the
+  source block's "name" label, unless an in-build source definition adds the
+  "name" configuration option.
 
 - `-only=foo,bar,baz` - Only validate the builds with the given comma-separated
-  names. Build names by default are the names of their builders, unless a
+  names. In legacy JSON templates, build names default to the
-  specific `name` attribute is specified within the configuration.
+  types of their builders (e.g. `docker` or
+  `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is
+  specified within the configuration. In HCL2 templates, the "name" is the
+  source block's "name" label, unless an in-build source definition adds the
+  "name" configuration option.
 
 - `-machine-readable` Sets all output to become machine-readable on stdout.
   Logging, if enabled, continues to appear on stderr.

website/content/docs/templates/hcl_templates/onlyexcept.mdx

@@ -25,9 +25,10 @@ build {
   sources [
     "source.amazon-ebs.first-example",
   ]
-  source "source.amazon-ebs.second-example" {
+  source "source.amazon-ebs.second-example"
-    // setting the name field allows to rename the source only for this build
+    // setting the name field allows you to rename the source only for this
-    // section.
+    // build section. To match this builder, you need to use
+    // second-example-local-name, not second-example
     name = "second-example-local-name"
   }
 
@@ -68,4 +69,4 @@ configuration:
 
 -> Note: In the cli `only` and `except` will match agains **build names** (for
 example:`my_build.amazon-ebs.first-example`) but in a provisioner they will
-match on the **source type** (for example:`source.amazon-ebs.third-example`).
+match on the **source name** (for example:`amazon-ebs.third-example`).

website/content/docs/templates/legacy_json_templates/post-processors.mdx

@@ -169,7 +169,8 @@ option _ignores_ post-processors.
 ])
 ```
 
-The values within `only` or `except` are _build names_, not builder types. If
+The values within `only` or `except` are _build names_, not builder types.
-you recall, build names by default are just their builder type, but if you
+Name is a required block label in HCL, but in legacy JSON, build names default
-specify a custom `name` parameter, then you should use that as the value
+to the types of their builders (e.g. `docker` or `amazon-ebs` or
-instead of the type.
+`virtualbox-iso`, unless a specific `name` attribute is specified within the
+configuration.

website/content/partials/commands/except.mdx

@@ -1,7 +1,10 @@
 - `-except=foo,bar,baz` - Run all the builds and post-processors except those
-  with the given comma-separated names. Build and post-processor names by
+  with the given comma-separated names. In legacy JSON templates, build names default to the
-  default are their type, unless a specific `name` attribute is specified
+  types of their builders (e.g. `docker` or
-  within the configuration. Any post-processor following a skipped
+  `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is
-  post-processor will not run. Because post-processors can be nested in
+  specified within the configuration. In HCL2 templates, the "name" is the
-  arrays a different post-processor chain can still run. A post-processor
+  source block's "name" label, unless an in-build source definition adds the
+  "name" configuration option.Any post-processor following
+  a skipped post-processor will not run. Because post-processors can be nested
+  in arrays a different post-processor chain can still run. A post-processor
   with an empty name will be ignored.

website/content/partials/commands/only.mdx

@@ -1,4 +1,7 @@
 - `-only=foo,bar,baz` - Only run the builds with the given comma-separated
-  names. Build names by default are their type, unless a specific `name`
+  names. In legacy JSON templates, build names default to the
-  attribute is specified within the configuration. `-only` does not apply to
+  types of their builders (e.g. `docker` or
-  post-processors.
+  `amazon-ebs` or `virtualbox-iso`, unless a specific `name` attribute is
+  specified within the configuration. In HCL2 templates, the "name" is the
+  source block's "name" label, unless an in-build source definition adds the
+  "name" configuration option.