document post-processor execpt more

website/source/docs/commands/build.html.md

@@ -27,11 +27,12 @@ artifacts that are created will be outputted at the end of the build.
     This will allow the user to inspect state and so on.
 
 -   `-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
-    default are their type, unless a specific `name` attribute is specified
-    within the configuration. Any post-processor following a skipped
-    post-processor will not run. Because post-processors can be nested in
-    arrays a differ post-processor chain can still run.
+    with the given comma-separated names. Build names by default are their
+    type, unless a specific `name` attribute is specified within the
+    configuration. 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.
 
 -   `-force` - Forces a builder to run when artifacts from a previous build
     prevent a build from running. The exact behavior of a forced build is left

website/source/docs/commands/validate.html.md

@@ -33,10 +33,11 @@ Errors validating build 'vmware'. 1 error(s) occurred:
 -   `-syntax-only` - Only the syntax of the template is checked. The
     configuration is not validated.
 
--   `-except=foo,bar,baz` - Builds all the builds except those with the given
-    comma-separated names. Build names by default are the names of their
-    builders, unless a specific `name` attribute is specified within the
-    configuration.
+-   `-except=foo,bar,baz` - Builds all the builds and post-processors except
+    those with the given comma-separated names. Build names by default are the
+    names of their builders, unless a specific `name` attribute is specified
+    within the configuration. A post-processor with an empty name will be
+    ignored.
 
 -   `-only=foo,bar,baz` - Only build the builds with the given comma-separated
     names. Build names by default are the names of their builders, unless a

website/source/docs/templates/post-processors.html.md

@@ -38,7 +38,8 @@ defined builders and send it through the post-processors. This means that if
 you have one post-processor defined and two builders defined in a template, the
 post-processor will run twice (once for each builder), by default. There are
 ways, which will be covered later, to control what builders post-processors
-apply to, if you wish.
+apply to, if you wish. It is also possible to prevent a post-processor from
+running.
 
 ## Post-Processor Definition
 
@@ -136,21 +137,40 @@ post-processor requested that the input be kept, so it will keep it around.
 
 ## Run on Specific Builds
 
-You can use the `only` or `except` configurations to run a post-processor only
-with specific builds. These two configurations do what you expect: `only` will
-only run the post-processor on the specified builds and `except` will run the
-post-processor on anything other than the specified builds.
+You can use the `only` or `except` fields to run a post-processor only with
+specific builds. These two fields do what you expect: `only` will only run the
+post-processor on the specified builds and `except` will run the post-processor
+on anything other than the specified builds. A sequence of post-processors will
+execute until a skipped post-processor.
 
 An example of `only` being used is shown below, but the usage of `except` is
 effectively the same. `only` and `except` can only be specified on "detailed"
-configurations. If you have a sequence of post-processors to run, `only` and
-`except` will only affect that single post-processor in the sequence.
+fields. If you have a sequence of post-processors to run, `only` and `except`
+will affect that post-processor and stop the sequence.
+
+The `-except` option can specifically skip a named post processor.
 
 ``` json
-{
+[
+  {
+    // can also be skipped when running `packer build -except vbox`
+    "name": "vbox",
     "type": "vagrant",
     "only": ["virtualbox-iso"]
-}
+  },
+  {
+    "type": "compress" // will only be executed when vbox is
+  }
+],
+[
+  "compress", // will run even if vbox is skipped, from the same start as vbox.
+  {
+    "type": "upload",
+    "endpoint": "http://example.com"
+  }
+  // this list of post processors will execute
+  // using build, not another post-processor.
+]
 ```
 
 The values within `only` or `except` are *build names*, not builder types. If