document hcl language & syntax

website/source/docs/configuration/from-1.5/index.html.md

@@ -0,0 +1,74 @@
+---
+layout: "docs"
+page_title: "Configuration Language"
+sidebar_current: "configuration"
+description: |-
+  Packer uses text files to describe infrastructure and to set variables.
+  These text files are called Packer _configurations_ and are
+  written in the HCL language.
+---
+
+# HCL Configuration Language
+
+Packer uses the Hashicorp Configuration Language - HCL - designed to allow
+concise descriptions of the required steps to get to a build file.
+
+## Builds
+
+The main purpose of the HCL language is defining builds and sources. All other
+language features exist only to make the definition of builds more flexible and
+convenient.
+
+
+`packer build` takes one argument. When a directory is passed, all files in the
+folder with a name ending with ".pkr.hcl" or ".pkr.json" will be parsed using
+the HCL2 format. When a file ending with ".pkr.hcl" or ".pkr.json" is passed it
+will be parsed using the HCL2 schema. For every other case; the *JSON only* old
+packer schema will be used.
+
+## Arguments, Blocks, and Expressions
+
+The syntax of the HCL language consists of only a few basic elements:
+
+```hcl
+source "amazon-ebs" "main" {
+  ami_name = "main-ami"
+}
+
+<BLOCK TYPE> "<BLOCK LABEL>" "<BLOCK LABEL>" {
+  # Block body
+  <IDENTIFIER> = <EXPRESSION> # Argument
+}
+```
+
+- _Blocks_ are containers for other content and usually represent the
+  configuration of some kind of object, like a source. Blocks have a
+  _block type,_ can have zero or more _labels,_ and have a _body_ that contains
+  any number of arguments and nested blocks. Most of Packer's features are
+  controlled by top-level blocks in a configuration file.
+- _Arguments_ assign a value to a name. They appear within blocks.
+- _Expressions_ represent a value, either literally or by referencing and
+  combining other values. They appear as values for arguments, or within other
+  expressions.
+
+For full details about Packer's syntax, see:
+
+- [Configuration Syntax](./syntax.html)
+- [Expressions](./expressions.html)
+
+## Code Organization
+
+The HCL language uses configuration files that are named with the `.pkr.hcl`
+file extension. There is also [a JSON-based variant of the
+language](./syntax-json.html) that is named with the `.pkr.json` file
+extension.
+
+Configuration files must always use UTF-8 encoding, and by convention are
+usually maintained with Unix-style line endings (LF) rather than Windows-style
+line endings (CRLF), though both are accepted.
+
+## Configuration Ordering
+
+The ordering of root blocks is not significant. The order of `provisioner` or
+`post-processor` blocks within a `build` is the only major feature where block
+order matters.

website/source/docs/configuration/from-1.5/syntax.html.md

@@ -0,0 +1,119 @@
+---
+layout: "docs"
+page_title: "Syntax - Configuration Language"
+sidebar_current: configuration-syntax
+description: |-
+  HCL has its own syntax, intended to combine declarative
+  structure with expressions in a way that is easy for humans to read and
+  understand.
+---
+
+# HCL Configuration Syntax
+
+Other pages in this section have described various configuration constructs
+that can appear in HCL. This page describes the lower-level syntax of the
+language in more detail, revealing the building blocks that those constructs
+are built from.
+
+This page describes the _native syntax_ of HCL, which is a rich language
+designed to be easy for humans to read and write. The constructs in HCL can
+also be expressed in [JSON syntax](/syntax-json.html), which is harder for
+humans to read and edit but easier to generate and parse programmatically.
+
+This low-level syntax of HCL is defined in terms of a syntax called _HCL_,
+which is also used by configuration languages in other applications, and in
+particular other HashiCorp products. It is not necessary to know all of the
+details of HCL in order to use Packer, and so this page summarizes the most
+important details. If you are interested, you can find a full definition of HCL
+syntax in [the HCL native syntax
+specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).
+
+## Arguments and Blocks
+
+HCL syntax is built around two key syntax constructs:
+arguments and blocks.
+
+### Arguments
+
+An _argument_ assigns a value to a particular name:
+
+```hcl
+image_id = "abc123"
+```
+
+The identifier before the equals sign is the _argument name_, and the expression
+after the equals sign is the argument's value.
+
+The context where the argument appears determines what value types are valid
+(for example, each source type has a schema that defines the types of its
+arguments), but many arguments accept arbitrary
+[expressions](/expressions.html), which allow the value to
+either be specified literally or generated from other values programmatically.
+
+### Blocks
+
+A _block_ is a container for other content:
+
+```hcl
+source "amazon-ebs" "example" {
+  ami_name = "abc123"
+
+  tags {
+    # ...
+  }
+}
+```
+
+A block has a _type_ (`source` in this example). Each block type defines
+how many _labels_ must follow the type keyword. The `source` block type
+expects two labels, which are `amazon-ebs` and `example` in the example above.
+A particular block type may have any number of required labels, or it may
+require none as with the nested `tags` block type.
+
+After the block type keyword and any labels, the block _body_ is delimited
+by the `{` and `}` characters. Within the block body, further arguments
+and blocks may be nested, creating a hierarchy of blocks and their associated
+arguments.
+
+HCL uses a limited number of _top-level block types,_ which
+are blocks that can appear outside of any other block in a configuration file.
+Most of Packer's features (including resources, input variables, output
+values, data sources, etc.) are implemented as top-level blocks.
+
+## Identifiers
+
+Argument names, block type names, and the names of most Packer-specific
+constructs like resources, input variables, etc. are all _identifiers_.
+
+Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
+The first character of an identifier must not be a digit, to avoid ambiguity
+with literal numbers.
+
+For complete identifier rules, Packer implements
+[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
+include the ASCII hyphen character `-`.
+
+## Comments
+
+HCL supports three different syntaxes for comments:
+
+* `#` begins a single-line comment, ending at the end of the line.
+* `//` also begins a single-line comment, as an alternative to `#`.
+* `/*` and `*/` are start and end delimiters for a comment that might span
+  over multiple lines.
+
+The `#` single-line comment style is the default comment style and should be
+used in most cases. Automatic configuration formatting tools may automatically
+transform `//` comments into `#` comments, since the double-slash style is
+not idiomatic.
+
+## Character Encoding and Line Endings
+
+Packer configuration files must always be UTF-8 encoded. While the
+delimiters of the language are all ASCII characters, Packer accepts
+non-ASCII characters in identifiers, comments, and string values.
+
+Packer accepts configuration files with either Unix-style line endings
+(LF only) or Windows-style line endings (CR then LF), but the idiomatic style
+is to use the Unix convention, and so automatic configuration formatting tools
+may automatically transform CRLF endings to LF.

website/source/layouts/docs.erb

@@ -1,6 +1,17 @@
 <% wrap_layout :inner do %>
   <% content_for :sidebar do %>
     <ul class="nav docs-sidenav">
+
+      <li<%= sidebar_current("configuration") %>>
+        <a href="/docs/configuration/from-1.5/index.html">HCL</a>
+        <ul class="nav">
+          <li<%= sidebar_current("configuration-syntax") %>>
+            <a href="/docs/configuration/from-1.5/syntax.html">Syntax</a>
+          </li>
+        </ul>
+      </li>
+
+      <hr>
       
       <li><a href="/docs/basics/terminology.html">Terminology</a></li>