incorporate doc review comments

Signed-off-by: Madhav Puri <madhav.puri@gmail.com>

docs/reference/api/docker_remote_api_v1.21.md

@@ -1367,11 +1367,11 @@ Query Parameters:
 -   **memswap** - Total memory (memory + swap), `-1` to disable swap.
 -   **cpushares** - CPU shares (relative weight).
 -   **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).
--   **buildargs** – JSON map of string pairs for build-time variables. Users can
+-   **buildargs** – JSON map of string pairs for build-time variables. Users pass
-        set these values at build-time and they are used as environment context
+        these values at build-time. Docker uses the `buildargs` as the environment
-        for the command(s) run as part of the Dockerfile's `RUN` instruction or
+        context for command(s) run via the Dockerfile's `RUN` instruction or for
-        for variable expansion in other Dockerfile instructions. Read more about
+        variable expansion in other Dockerfile instructions. This is not meant for
-        the `ARG` instruction [here](/reference/builder/#arg)
+        passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg)
 
     Request Headers:
 

docs/reference/builder.md

@@ -1058,19 +1058,20 @@ useful interactions between `ARG` and `ENV` instructions:
 4 RUN echo $CONT_IMG_VER
 ```
 
-The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG
+Unlike an `ARG` instruction, `ENV` values are always persisted in the built
-CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV`
+image. Consider a docker build without the --build-arg flag:
-instruction of the same name resolves to `v2.0.1` as the build-time variable
+
-was passed from the command line and expanded here.
+```
+$ docker build Dockerfile
+```
+
+Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but
+its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction.
 
 The variable expansion technique in this example allows you to pass arguments
-from the command line and persist them in the final image by leveraging the `ENV`
+from the command line and persist them in the final image by leveraging the
-instruction. Variable expansion is only supported for the `Dockerfile` instructions
+`ENV` instruction. Variable expansion is only supported for [a limited set of
-described [here](#environment-replacement).
+Dockerfile instructions.](#environment-replacement)
-
-Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If
-`docker build` were run without setting the `--build-arg` flag, then
-`CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`.
 
 Docker has a set of predefined `ARG` variables that you can use without a
 corresponding `ARG` instruction in the Dockerfile.

man/Dockerfile.5.md

@@ -408,19 +408,20 @@ A Dockerfile is similar to a Makefile.
   4 RUN echo $CONT_IMG_VER
   ```
 
-  The command line passes the `--build-arg` and sets the `v2.0.1` value. And the `ARG
+  Unlike an `ARG` instruction, `ENV` values are always persisted in the built
-  CONT_IMG_VER` is defined on line 2 of the Dockerfile. On line 3, the `ENV`
+  image. Consider a docker build without the --build-arg flag:
-  instruction of the same name resolves to `v2.0.1` as the build-time variable
+
-  was passed from the command line and expanded here.
+  ```
+  $ docker build Dockerfile
+  ```
+
+  Using this Dockerfile example, `CONT_IMG_VER` is still persisted in the image but
+  its value would be `v1.0.0` as it is the default set in line 3 by the `ENV` instruction.
 
   The variable expansion technique in this example allows you to pass arguments
-  from the command line and persist them in the final image by leveraging the `ENV`
+  from the command line and persist them in the final image by leveraging the
-  instruction. Variable expansion is only supported for the `Dockerfile` instructions
+  `ENV` instruction. Variable expansion is only supported for [a limited set of
-  described [here](#environment-replacement).
+  Dockerfile instructions.](#environment-replacement)
-
-  Unlike an `ARG` instruction, `ENV` values are always persisted in the built image. If
-  `docker build` were run without setting the `--build-arg` flag, then
-  `CONT_IMG_VER` is still persisted in the image but its value would be `v1.0.0`.
 
   Docker has a set of predefined `ARG` variables that you can use without a
   corresponding `ARG` instruction in the Dockerfile.

man/docker-build.1.md

@@ -53,22 +53,15 @@ cloned locally and then sent as the context.
    The default is *Dockerfile*.
 
 **--build-arg**=*variable*
-   Set value for build-time variable. This option allows you to specify
+   name and value of a **buildarg**.
-values of the variables that are available for expansion/substitution in the
-Dockerfile instructions like ADD, COPY etc, without an explicit prior definition by
-the ENV instruction. The build-time variables are also passed as environment
-context for the command(s) that will be executed as part of RUN instruction
-of Dockerfile, if there is no explicit prior definition by the ENV instruction.
-Normally, these variables are not persisted in the resulting Docker image. This gives
-the flexibility to build an image by passing host specific environment variables (like
-http_proxy) that will be used on the RUN commands without affecting portability
-of the generated image.
-However, as with any variable, they can be persisted in the final image if they are used in an
-ENV instruction (e.g. ENV myName=$myName will save myName in the image).
 
-Only the build-time variables that are defined using the ARG instruction of Dockerfile
+   For example, if you want to pass a value for `http_proxy`, use
-are allowed to be expanded or passed as environment to the RUN command. Read more about
+   `--bulid-arg=http_proxy="http://some.proxy.url"`
-ARG instruction in Dockerfile reference.
+
+   Users pass these values at build-time. Docker uses the `buildargs` as the
+   environment context for command(s) run via the Dockerfile's `RUN` instruction
+   or for variable expansion in other Dockerfile instructions. This is not meant
+   for passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg)
 
 **--force-rm**=*true*|*false*
    Always remove intermediate containers, even after unsuccessful builds. The default is *false*.