Merge pull request #3430 from thaJeztah/20.10_backport_docs_fixes

[20.10 backport] assorted documentation fixes

docs/reference/builder.md

@@ -112,7 +112,7 @@ instructions.
 
 Whenever possible, Docker uses a build-cache to accelerate the `docker build`
 process significantly. This is indicated by the `CACHED` message in the console
-output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/):
+output. (For more information, see the [`Dockerfile` best practices guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/)):
 
 ```console
 $ docker build -t svendowideit/ambassador .
@@ -159,8 +159,8 @@ implementation. For example, BuildKit can:
 To use the BuildKit backend, you need to set an environment variable
 `DOCKER_BUILDKIT=1` on the CLI before invoking `docker build`.
 
-To learn about the experimental Dockerfile syntax available to BuildKit-based
-builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/experimental.md).
+To learn about the Dockerfile syntax available to BuildKit-based
+builds [refer to the documentation in the BuildKit repository](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md).
 
 ## Format
 
@@ -1824,6 +1824,11 @@ RUN pwd
 The output of the final `pwd` command in this `Dockerfile` would be
 `/path/$DIRNAME`
 
+If not specified, the default working directory is `/`. In practice, if you aren't building a Dockerfile from scratch (`FROM scratch`), 
+the `WORKDIR` may likely be set by the base image you're using.
+
+Therefore, to avoid unintended operations in unknown directories, it is best practice to set your `WORKDIR` explicitly.
+
 ## ARG
 
 ```dockerfile

docs/reference/commandline/create.md

@@ -225,9 +225,8 @@ Linux namespaces. On Microsoft Windows, you can specify these values:
 
 
 | Value     | Description                                                  |
-|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value if the
-daemon is running on Windows server, or `hyperv` if running on Windows client.  |
+| --------- | ------------------------------------------------------------ |
+| `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value if the daemon is running on Windows server, or `hyperv` if running on Windows client. |
 | `process` | Namespace isolation only.                                    |
 | `hyperv`  | Hyper-V hypervisor partition-based isolation.                |
 

docs/reference/commandline/dockerd.md

@@ -115,8 +115,8 @@ Options with [] may be specified multiple times.
 uses different binaries for the daemon and client. To run the daemon you
 type `dockerd`.
 
-To run the daemon with debug output, use `dockerd -D` or add `"debug": true` to
-the `daemon.json` file.
+To run the daemon with debug output, use `dockerd --debug` or add `"debug": true`
+to [the `daemon.json` file](#daemon-configuration-file).
 
 > **Enabling experimental features**
 > 
@@ -312,7 +312,7 @@ article explains how to tune your existing setup without the use of options.
 
 The `btrfs` driver is very fast for `docker build` - but like `devicemapper`
 does not share executable memory between devices. Use
-`dockerd -s btrfs -g /mnt/btrfs_partition`.
+`dockerd --storage-driver btrfs --data-root /mnt/btrfs_partition`.
 
 The `zfs` driver is probably not as fast as `btrfs` but has a longer track record
 on stability. Thanks to `Single Copy ARC` shared blocks between clones will be
@@ -1233,14 +1233,14 @@ for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be
 set like this:
 
 ```console
-$ DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
+$ DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
 ```
 
 or
 
 ```console
 $ export DOCKER_TMPDIR=/mnt/disk2/tmp
-$ /usr/local/bin/dockerd -D -g /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
+$ /usr/local/bin/dockerd --data-root /var/lib/docker -H unix:// > /var/lib/docker-machine/docker.log 2>&1
 ````
 
 #### Default cgroup parent
@@ -1554,7 +1554,7 @@ The list of currently supported options that can be reconfigured is this:
   be used to run containers.
 - `authorization-plugin`: it specifies the authorization plugins to use.
 - `allow-nondistributable-artifacts`: Replaces the set of registries to which the daemon will push nondistributable artifacts with a new set of registries.
-- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure resgitries, these existing ones will be removed from daemon's config.
+- `insecure-registries`: it replaces the daemon insecure registries with a new set of insecure registries. If some existing insecure registries in daemon's configuration are not in newly reloaded insecure registries, these existing ones will be removed from daemon's config.
 - `registry-mirrors`: it replaces the daemon registry mirrors with a new set of registry mirrors. If some existing registry mirrors in daemon's configuration are not in newly reloaded registry mirrors, these existing ones will be removed from daemon's config.
 - `shutdown-timeout`: it replaces the daemon's existing configuration timeout with a new timeout for shutting down all containers.
 - `features`: it explicitly enables or disables specific features.

docs/reference/commandline/pull.md

@@ -109,8 +109,8 @@ refer to [understand images, containers, and storage drivers](https://docs.docke
 So far, you've pulled images by their name (and "tag"). Using names and tags is
 a convenient way to work with images. When using tags, you can `docker pull` an
 image again to make sure you have the most up-to-date version of that image.
-For example, `docker pull ubuntu:14.04` pulls the latest version of the Ubuntu
-14.04 image.
+For example, `docker pull ubuntu:20.04` pulls the latest version of the Ubuntu
+20.04 image.
 
 In some cases you don't want images to be updated to newer versions, but prefer
 to use a fixed version of an image. Docker enables you to pull an image by its
@@ -119,7 +119,7 @@ of an image to pull. Doing so, allows you to "pin" an image to that version,
 and guarantee that the image you're using is always the same.
 
 To know the digest of an image, pull the image first. Let's pull the latest
-`ubuntu:14.04` image from Docker Hub:
+`ubuntu:20.04` image from Docker Hub:
 
 ```console
 $ docker pull ubuntu:20.04

docs/reference/commandline/run.md

@@ -348,7 +348,7 @@ explains in detail how to manipulate ports in Docker.
 
 Note that ports which are not bound to the host (i.e., `-p 80:80` instead of
 `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if
-you configured UFW to block this specific port, as Docker manages his
+you configured UFW to block this specific port, as Docker manages its
 own iptables rules. [Read more](https://docs.docker.com/network/iptables/)
 
 ```console
@@ -403,10 +403,10 @@ VAR1=value1
 VAR2=value2
 USER
 
-$ docker run --env-file env.list ubuntu env | grep VAR
+$ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER'
 VAR1=value1
 VAR2=value2
-USER=denis
+USER=jonzeolla
 ```
 
 ### Set metadata on container (-l, --label, --label-file)
@@ -634,7 +634,7 @@ $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubu
 The example below exposes the first and third GPUs.
 
 ```console
-$ docker run -it --rm --gpus device=0,2 nvidia-smi
+$ docker run -it --rm --gpus '"device=0,2"' nvidia-smi
 ```
 
 ### Restart policies (--restart)
@@ -719,7 +719,7 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
 > In other words, the following script is not supported:
 >
 > ```console
-> $ docker run -it --ulimit as=1024 fedora /bin/bash`
+> $ docker run -it --ulimit as=1024 fedora /bin/bash
 > ```
 
 The values are sent to the appropriate `syscall` as they are set.

docs/reference/commandline/stats.md

@@ -85,6 +85,13 @@ b95a83497c91        awesome_brattain    0.28%               5.629MiB / 1.952GiB
 67b2525d8ad1        foobar              0.00%               1.727MiB / 1.952GiB   0.09%               2.48kB / 0B         4.11MB / 0B         2
 ```
 
+Running `docker stats` on container with name nginx and getting output in `json` format.
+
+```console
+$ docker stats nginx --no-stream --format "{{ json . }}"
+{"BlockIO":"0B / 13.3kB","CPUPerc":"0.03%","Container":"nginx","ID":"ed37317fbf42","MemPerc":"0.24%","MemUsage":"2.352MiB / 982.5MiB","Name":"nginx","NetIO":"539kB / 606kB","PIDs":"2"}
+```
+
 Running `docker stats` with customized format on all (Running and Stopped) containers.
 
 ```console