[20.10 backport] docs: add anchor tags for command-line flags

docs/extend/config.md

@@ -1,5 +1,5 @@
 ---
-description: "How develop and use a plugin with the managed plugin system"
+description: "How to develop and use a plugin with the managed plugin system"
 keywords: "API, Usage, plugins, documentation, developer"
 ---
 
@@ -15,17 +15,14 @@ keywords: "API, Usage, plugins, documentation, developer"
 
 # Plugin Config Version 1 of Plugin V2
 
-This document outlines the format of the V0 plugin configuration. The plugin
-config described herein was introduced in the Docker daemon in the [v1.12.0
-release](https://github.com/docker/docker/commit/f37117045c5398fd3dca8016ea8ca0cb47e7312b).
+This document outlines the format of the V0 plugin configuration.
 
 Plugin configs describe the various constituents of a docker plugin. Plugin
 configs can be serialized to JSON format with the following media types:
 
-Config Type  | Media Type
-------------- | -------------
-config  | "application/vnd.docker.plugin.v1+json"
-
+| Config Type | Media Type                              |
+|-------------|-----------------------------------------|
+| config      | "application/vnd.docker.plugin.v1+json" |
 
 ## *Config* Field Descriptions
 

docs/reference/commandline/attach.md

@@ -45,12 +45,12 @@ a container and leave it running using the `CTRL-p CTRL-q` key sequence.
 > so.
 
 It is forbidden to redirect the standard input of a `docker attach` command
-while attaching to a tty-enabled container (i.e.: launched with `-t`).
+while attaching to a TTY-enabled container (using the `-i` and `-t` options).
 
-While a client is connected to container's stdio using `docker attach`, Docker
-uses a ~1MB memory buffer to maximize the throughput of the application. If
-this buffer is filled, the speed of the API connection will start to have an
-effect on the process output writing speed. This is similar to other
+While a client is connected to container's `stdio` using `docker attach`, Docker
+uses a ~1MB memory buffer to maximize the throughput of the application.
+Once this buffer is full, the speed of the API connection is affected, and so
+this impacts the output process' writing speed. This is similar to other
 applications like SSH. Because of this, it is not recommended to run
 performance critical applications that generate a lot of output in the
 foreground over a slow client connection. Instead, users should use the
@@ -84,45 +84,68 @@ containers, see [**Configuration file** section](cli.md#configuration-files).
 
 ### Attach to and detach from a running container
 
+The following example starts an ubuntu container running `top` in detached mode,
+then attaches to the container;
+
 ```console
-$ docker run -d --name topdemo ubuntu /usr/bin/top -b
+$ docker run -d --name topdemo ubuntu:22.04 /usr/bin/top -b
 
 $ docker attach topdemo
 
-top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
+top - 12:27:44 up 3 days, 21:54,  0 users,  load average: 0.00, 0.00, 0.00
 Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
-Cpu(s):  0.1%us,  0.2%sy,  0.0%ni, 99.7%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
-Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
-Swap:   786428k total,        0k used,   786428k free,   221740k cached
+%Cpu(s):  0.1 us,  0.1 sy,  0.0 ni, 99.8 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
+MiB Mem :   3934.3 total,    770.1 free,    674.2 used,   2490.1 buff/cache
+MiB Swap:   1024.0 total,    839.3 free,    184.7 used.   2814.0 avail Mem
+
+  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+    1 root      20   0    7180   2896   2568 R   0.0   0.1   0:00.02 top
+```
 
-PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
- 1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
+As the container was started without the `-i`, and `-t` options, signals are
+forwarded to the attached process, which means that the default `CTRL-p CTRL-q`
+detach key sequence produces no effect, but pressing `CTRL-c` terminates the
+container:
 
- top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
- Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
- Cpu(s):  0.0%us,  0.2%sy,  0.0%ni, 99.8%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
- Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
- Swap:   786428k total,        0k used,   786428k free,   221776k cached
+```console
+<...>
+  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+    1 root      20   0    7180   2896   2568 R   0.0   0.1   0:00.02 top^P^Q
+^C
 
-   PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-       1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
+$ docker ps -a --filter name=topdemo
 
+CONTAINER ID   IMAGE          COMMAND             CREATED              STATUS                          PORTS     NAMES
+4cf0d0ebb079   ubuntu:22.04   "/usr/bin/top -b"   About a minute ago   Exited (0) About a minute ago             topdemo
+```
 
- top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
- Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
- Cpu(s):  0.2%us,  0.3%sy,  0.0%ni, 99.5%id,  0.0%wa,  0.0%hi,  0.0%si,  0.0%st
- Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
- Swap:   786428k total,        0k used,   786428k free,   221776k cached
+Repeating the example above, but this time with the `-i` and `-t` options set;
 
- PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
-      1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
-^C$
+```console
+$ docker run -dit --name topdemo2 ubuntu:22.04 /usr/bin/top -b
+```
 
-$ echo $?
-0
-$ docker ps -a | grep topdemo
+Now, when attaching to the container, and pressing the `CTRL-p CTRL-q` ("read
+escape sequence"), the Docker CLI is handling the detach sequence, and the
+`attach` command is detached from the container. Checking the container's status
+with `docker ps` shows that the container is still running in the background:
 
-7998ac8581f9        ubuntu:14.04        "/usr/bin/top -b"   38 seconds ago      Exited (0) 21 seconds ago                          topdemo
+```console
+$ docker attach topdemo2
+
+top - 12:44:32 up 3 days, 22:11,  0 users,  load average: 0.00, 0.00, 0.00
+Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
+%Cpu(s): 50.0 us,  0.0 sy,  0.0 ni, 50.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
+MiB Mem :   3934.3 total,    770.6 free,    672.4 used,   2491.4 buff/cache
+MiB Swap:   1024.0 total,    839.3 free,    184.7 used.   2815.8 avail Mem
+
+  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
+    1 root      20   0    7180   2776   2452 R   0.0   0.1   0:00.02 topread escape sequence
+
+$ docker ps -a --filter name=topdemo2
+
+CONTAINER ID   IMAGE          COMMAND             CREATED         STATUS         PORTS     NAMES
+b1661dce0fc2   ubuntu:22.04   "/usr/bin/top -b"   2 minutes ago   Up 2 minutes             topdemo2
 ```
 
 ### Get the exit code of the container's command
@@ -131,18 +154,17 @@ And in this second example, you can see the exit code returned by the `bash`
 process is returned by the `docker attach` command to its caller too:
 
 ```console
-$ docker run --name test -d -it debian
+$ docker run --name test -dit alpine
 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab
 
 $ docker attach test
-root@f38c87f2a42d:/# exit 13
-
-exit
+/# exit 13
 
 $ echo $?
 13
 
-$ docker ps -a | grep test
+$ docker ps -a --filter name=test
 
-275c44472aeb        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
+CONTAINER ID   IMAGE     COMMAND     CREATED              STATUS                       PORTS     NAMES
+a2fe3fd886db   alpine    "/bin/sh"   About a minute ago   Exited (13) 40 seconds ago             test
 ```

docs/reference/commandline/build.md

@@ -332,7 +332,7 @@ found, the `.dockerignore` file is used if present. Using a Dockerfile based
 expect to ignore different sets of files.
 
 
-### Tag an image (-t)
+### <a name="tag"></a> Tag an image (-t, --tag)
 
 ```console
 $ docker build -t vieux/apache:2.0 .
@@ -352,7 +352,7 @@ For example, to tag an image both as `whenry/fedora-jboss:latest` and
 $ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
 ```
 
-### Specify a Dockerfile (-f)
+### <a name="file"></a> Specify a Dockerfile (-f, --file)
 
 ```console
 $ docker build -f Dockerfile.debug .
@@ -399,17 +399,17 @@ the command line.
 > repeatable builds on remote Docker hosts. This is also the reason why
 > `ADD ../file` does not work.
 
-### Use a custom parent cgroup (--cgroup-parent)
+### <a name="cgroup-parent"></a> Use a custom parent cgroup (--cgroup-parent)
 
 When `docker build` is run with the `--cgroup-parent` option the containers
 used in the build will be run with the [corresponding `docker run` flag](../run.md#specify-custom-cgroups).
 
-### Set ulimits in container (--ulimit)
+### <a name="ulimit"></a> Set ulimits in container (--ulimit)
 
 Using the `--ulimit` option with `docker build` will cause each build step's
-container to be started using those [`--ulimit` flag values](run.md#set-ulimits-in-container---ulimit).
+container to be started using those [`--ulimit` flag values](run.md#ulimit).
 
-### Set build-time variables (--build-arg)
+### <a name="build-arg"></a> Set build-time variables (--build-arg)
 
 You can use `ENV` instructions in a Dockerfile to define variable
 values. These values persist in the built image. However, often
@@ -444,16 +444,16 @@ $ export HTTP_PROXY=http://10.20.30.2:1234
 $ docker build --build-arg HTTP_PROXY .
 ```
 
-This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)
+This is similar to how `docker run -e` works. Refer to the [`docker run` documentation](run.md#env)
 for more information.
 
-### Optional security options (--security-opt)
+### <a name="security-opt"></a> Optional security options (--security-opt)
 
 This flag is only supported on a daemon running on Windows, and only supports
 the `credentialspec` option. The `credentialspec` must be in the format
 `file://spec.txt` or `registry://keyname`.
 
-### Specify isolation technology for container (--isolation)
+### <a name="isolation"></a> Specify isolation technology for container (--isolation)
 
 This option is useful in situations where you are running Docker containers on
 Windows. The `--isolation=<value>` option sets a container's isolation
@@ -469,15 +469,15 @@ Linux namespaces. On Microsoft Windows, you can specify these values:
 
 Specifying the `--isolation` flag without a value is the same as setting `--isolation="default"`.
 
-### Add entries to container hosts file (--add-host)
+### <a name="add-host"></a> Add entries to container hosts file (--add-host)
 
 You can add other hosts into a container's `/etc/hosts` file by using one or
 more `--add-host` flags. This example adds a static address for a host named
 `docker`:
 
     $ docker build --add-host=docker:10.180.0.1 .
 
-### Specifying target build stage (--target)
+### <a name="target"></a> Specifying target build stage (--target)
 
 When building a Dockerfile with multiple build stages, `--target` can be used to
 specify an intermediate build stage by name as a final stage for the resulting
@@ -495,7 +495,14 @@ FROM alpine AS production-env
 $ docker build -t mybuildimage --target build-env .
 ```
 
-### Custom build outputs
+### <a name="output"></a> Custom build outputs (--output)
+
+> **Note**
+>
+> This feature requires the BuildKit backend. You can either
+> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
+> use the [buildx](https://github.com/docker/buildx) plugin which provides more
+> output type options.
 
 By default, a local container image is created from the build result. The
 `--output` (or `-o`) flag allows you to override this behavior, and a specify a
@@ -582,14 +589,14 @@ $ ls ./out
 vndr
 ```
 
+### <a name="cache-from"></a> Specifying external cache sources (--cache-from)
+
 > **Note**
 >
 > This feature requires the BuildKit backend. You can either
 > [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
-> use the [buildx](https://github.com/docker/buildx) plugin which provides more
-> output type options.
-
-### Specifying external cache sources
+> use the [buildx](https://github.com/docker/buildx) plugin. The previous
+> builder has limited support for reusing cache from pre-pulled images.
 
 In addition to local build cache, the builder can reuse the cache generated from
 previous builds with the `--cache-from` flag pointing to an image in the registry.
@@ -625,14 +632,7 @@ On another machine:
 $ docker build --cache-from myname/myapp .
 ```
 
-> **Note**
->
-> This feature requires the BuildKit backend. You can either
-> [enable BuildKit](https://docs.docker.com/build/buildkit/#getting-started) or
-> use the [buildx](https://github.com/docker/buildx) plugin. The previous
-> builder has limited support for reusing cache from pre-pulled images.
-
-### Squash an image's layers (--squash) (experimental)
+### <a name="squash"></a> Squash an image's layers (--squash) (experimental)
 
 #### Overview
 

docs/reference/commandline/cli.md

@@ -154,17 +154,17 @@ different location.
 These fields allow you to customize the default output format for some commands
 if no `--format` flag is provided.
 
-| Property               | Description                                                                                                                                                                                                                         |
-|:-----------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `configFormat`         | Custom default format for `docker config ls` output. Refer to the [**format the output** section in the `docker config ls` documentation](config_ls.md#format-the-output) for a list of supported formatting directives.            |
-| `imagesFormat`         | Custom default format for `docker images` / `docker image ls` output. Refer to the [**format the output** section in the `docker images` documentation](images.md#format-the-output) for a list of supported formatting directives. |
-| `nodesFormat`          | Custom default format for `docker node ls` output. Refer to the [**formatting** section in the `docker node ls` documentation](node_ls.md#formatting) for a list of supported formatting directives.                                |
-| `pluginsFormat`        | Custom default format for `docker plugin ls` output. Refer to the [**formatting** section in the `docker plugin ls` documentation](plugin_ls.md#formatting) for a list of supported formatting directives.                          |
-| `psFormat`             | Custom default format for `docker ps` / `docker container ps` output. Refer to the [**formatting** section in the `docker ps` documentation](ps.md#formatting) for a list of supported formatting directives.                       |
-| `secretFormat`         | Custom default format for `docker secret ls` output. Refer to the [**format the output** section in the `docker secret ls` documentation](secret_ls.md#format-the-output) for a list of supported formatting directives.            |
-| `serviceInspectFormat` | Custom default format for `docker service inspect` output. Refer to the [**formatting** section in the `docker service inspect` documentation](service_inspect.md#formatting) for a list of supported formatting directives.        |
-| `servicesFormat`       | Custom default format for `docker service ls` output. Refer to the [**formatting** section in the `docker service ls` documentation](service_ls.md#formatting) for a list of supported formatting directives.                       |
-| `statsFormat`          | Custom default format for `docker stats` output. Refer to the [**formatting** section in the `docker stats` documentation](stats.md#formatting) for a list of supported formatting directives.                                      |
+| Property               | Description                                                                                                                                                                                                              |
+|:-----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `configFormat`         | Custom default format for `docker config ls` output. Refer to the [**format the output** section in the `docker config ls` documentation](config_ls.md#format) for a list of supported formatting directives.            |
+| `imagesFormat`         | Custom default format for `docker images` / `docker image ls` output. Refer to the [**format the output** section in the `docker images` documentation](images.md#format) for a list of supported formatting directives. |
+| `nodesFormat`          | Custom default format for `docker node ls` output. Refer to the [**formatting** section in the `docker node ls` documentation](node_ls.md#format) for a list of supported formatting directives.                         |
+| `pluginsFormat`        | Custom default format for `docker plugin ls` output. Refer to the [**formatting** section in the `docker plugin ls` documentation](plugin_ls.md#format) for a list of supported formatting directives.                   |
+| `psFormat`             | Custom default format for `docker ps` / `docker container ps` output. Refer to the [**formatting** section in the `docker ps` documentation](ps.md#format) for a list of supported formatting directives.                |
+| `secretFormat`         | Custom default format for `docker secret ls` output. Refer to the [**format the output** section in the `docker secret ls` documentation](secret_ls.md#format) for a list of supported formatting directives.            |
+| `serviceInspectFormat` | Custom default format for `docker service inspect` output. Refer to the [**formatting** section in the `docker service inspect` documentation](service_inspect.md#format) for a list of supported formatting directives. |
+| `servicesFormat`       | Custom default format for `docker service ls` output. Refer to the [**formatting** section in the `docker service ls` documentation](service_ls.md#format) for a list of supported formatting directives.                |
+| `statsFormat`          | Custom default format for `docker stats` output. Refer to the [**formatting** section in the `docker stats` documentation](stats.md#format) for a list of supported formatting directives.                               |
 
 
 ### Custom HTTP headers