builder: Update documentation WRT environment replacement
Docker-DCO-1.1-Signed-off-by: Erik Hollensbe (github: erikh)
@@ -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
