website: document machine-readable

website/source/docs/command-line/build.html.markdown

@@ -1,5 +1,6 @@
 ---
 layout: "docs"
+page_title: "Build - Command-Line"
 ---
 
 # Command-Line: Build
@@ -22,7 +23,7 @@ artifacts that are created will be outputted at the end of the build.
   In general, a builder supporting the forced build will remove the artifacts from
   the previous build. This will allow the user to repeat a build without having to
   manually clean these artifacts beforehand.
-  
+
 * `-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.

website/source/docs/command-line/fix.html.markdown

@@ -1,6 +1,6 @@
 ---
 layout: "docs"
-page_title: "Command-line: Fix"
+page_title: "Fix - Command-Line"
 ---
 
 # Command-Line: Fix

website/source/docs/command-line/machine-readable.html.markdown

@@ -0,0 +1,83 @@
+---
+layout: "docs"
+page_title: "Machine-Readable Output - Command-Line"
+---
+
+# Machine-Readable Output
+
+By default, the output of Packer is very human-readable. It uses nice
+formatting, spacing, and colors in order to make Packer a pleasure to use.
+However, Packer was built with automation in mind. To that end, Packer
+supports a fully machine-readable output setting, allowing you to use
+Packer in automated environments.
+
+The machine-readable output format is easy to use and read and was made
+with Unix tools in mind, so it is awk/sed/grep/etc. friendly.
+
+## Enabling
+
+The machine-readable output format can be enabled by passing the
+`-machine-readable` flag to any Packer command. This immediately enables
+all output to become machine-readable on stdout. Logging, if enabled,
+continues to appear on stderr. An example of the output is shown
+below:
+
+```
+$ packer -machine-readable version
+1376289459,,version,0.2.4
+1376289459,,version-prerelease,
+1376289459,,version-commit,eed6ece
+1376289459,,ui,say,Packer v0.2.4.dev (eed6ece+CHANGES)
+```
+
+The format will be covered in more detail later. But as you can see,
+the output immediately becomes machine-friendly. Try some other commands
+with the `-machine-readable` flag to see!
+
+## Format
+
+The machine readable format is a line-oriented, comma-delimeted text
+format. This makes it extremely to parse using standard Unix tools such
+as awk or grep in addition to full programming languages like Ruby or
+Python.
+
+The format is:
+
+```
+timestamp,target,type,data...
+```
+
+Each component is explained below:
+
+* **timestamp** is a Unix timestamp in UTC of when the message was
+  printed.
+
+* **target** is the target of the following output. This is empty if
+  the message is related to Packer globally. Otherwise, this is generally
+  a build name so you can relate output to a specific build while parallel
+  builds are running.
+
+* **type** is the type of machine-readable message being outputted. There
+  are a set of standard types which are covered later, but each component
+  of Packer (builders, provisioners, etc.) may output their own custom types
+  as well, allowing the machine-readable output to be infinitely flexible.
+
+* **data** is zero or more comma-seperated values associated with the prior
+  type. The exact amount and meaning of this data is type-dependent, so you
+  must read the documentation associated with the type to understand fully.
+
+Within the format, if data contains a comma, it is replaced with
+`%!(PACKER_COMMA)`. This was preferred over an escape character such as
+`\'` because it is more friendly to tools like awk.
+
+Newlines within the format are replaced with their respective standard
+escape sequence. Newlines become a literal `\n` within the output. Carriage
+returns become a literal `\r`.
+
+## Message Types
+
+The set of machine-readable message types can be found in the
+[machine-readable format](#)
+complete documentation section. This section contains documentation
+on all the message types exposed by Packer core as well as all the
+components that ship with Packer by default.

website/source/docs/command-line/validate.html.markdown

@@ -1,5 +1,6 @@
 ---
 layout: "docs"
+page_title: "Validate - Command-Line"
 ---
 
 # Command-Line: Validate

website/source/layouts/docs.erb

@@ -13,6 +13,7 @@
 			<li><a href="/docs/command-line/build.html">Build</a></li>
 			<li><a href="/docs/command-line/fix.html">Fix</a></li>
 			<li><a href="/docs/command-line/validate.html">Validate</a></li>
+			<li><a href="/docs/command-line/machine-readable.html">Machine-Readable Output</a></li>
 		</ul>
 
 		<ul>