builder: add note about alternative syntax

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
(cherry picked from commit a4a3d2f94d)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/builder.md

@@ -1025,25 +1025,43 @@ The environment variables set using `ENV` will persist when a container is run
 from the resulting image. You can view the values using `docker inspect`, and
 change them using `docker run --env <key>=<value>`.
 
-> **Note**
+Environment variable persistence can cause unexpected side effects. For example,
+setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`,
+and may confuse users of your image.
+
+If an environment variable is only needed during build, and not in the final
+image, consider setting a value for a single command instead:
+
+```dockerfile
+RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ...
+```
+ 
+Or using [`ARG`](#arg), which is not persisted in the final image:
+
+```dockerfile
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y ...
+```
+
+> **Alternative syntax**
 >
-> Environment variable persistence can cause unexpected side effects. For example,
+> The `ENV` instruction also allows an alternative syntax `ENV <key> <value>`,
-> setting `ENV DEBIAN_FRONTEND=noninteractive` changes the behavior of `apt-get`,
+> omitting the `=`. For example:
-> and may confuse users of your image.
->
-> If an environment variable is only needed during build, and not in the final
-> image, consider setting a value for a single command instead:
 >
 > ```dockerfile
-> RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y ...
+> ENV MY_VAR my-value
 > ```
 > 
-> Or using [`ARG`](#arg), which is not persisted in the final image:
+> This syntax does not allow for multiple environment-variables to be set in a
+> single `ENV` instruction, and can be confusing. For example, the following
+> sets a single environment variable (`ONE`) with value `"TWO= THREE=world"`:
 >
 > ```dockerfile
-> ARG DEBIAN_FRONTEND=noninteractive
+> ENV ONE TWO= THREE=world
-> RUN apt-get update && apt-get install -y ...
 > ```
+> 
+> The alternative syntax is supported for backward compatibility, but discouraged
+> for the reasons outlined above, and may be removed in a future release.
 
 ## ADD