Merge pull request #8807 from erikh/builder_docs

builder: Update documentation WRT environment replacement

docs/sources/reference/builder.md

@@ -104,6 +104,47 @@ be treated as an argument. This allows statements like:
 Here is the set of instructions you can use in a `Dockerfile` for building
 images.
 
+### Environment Replacement
+
+**Note:** prior to 1.3, `Dockerfile` environment variables were handled
+similarly, in that they would be replaced as described below. However, there
+was no formal definition on as to which instructions handled environment
+replacement at the time. After 1.3 this behavior will be preserved and
+canonical.
+
+Environment variables (declared with the `ENV` statement) can also be used in
+certain instructions as variables to be interpreted by the `Dockerfile`. Escapes
+are also handled for including variable-like syntax into a statement literally.
+
+Environment variables are notated in the `Dockerfile` either with
+`$variable_name` or `${variable_name}`. They are treated equivalently and the
+brace syntax is typically used to address issues with variable names with no
+whitespace, like `${foo}_bar`.
+
+Escaping is possible by adding a `\` before the variable: `\$foo` or `\${foo}`,
+for example, will translate to `$foo` and `${foo}` literals respectively.
+ 
+Example (parsed representation is displayed after the `#`):
+
+    FROM busybox
+    ENV foo /bar
+    WORKDIR ${foo}   # WORKDIR /bar
+    ADD . $foo       # ADD . /bar
+    COPY \$foo /quux # COPY $foo /quux
+
+The instructions that handle environment variables in the `Dockerfile` are:
+
+* `ENV`
+* `ADD`
+* `COPY`
+* `WORKDIR`
+* `EXPOSE`
+* `VOLUME`
+* `USER`
+
+`ONBUILD` instructions are **NOT** supported for environment replacement, even
+the instructions above.
+
 ## The `.dockerignore` file
 
 If a file named `.dockerignore` exists in the source repository, then it