Update engine CLI docs, stubs, and TOC

_data/engine-cli-edge/docker_config_create.yaml

@@ -14,6 +14,14 @@ options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+- option: template-driver
+  value_type: string
+  description: Template driver
+  deprecated: false
+  experimental: false
+  experimentalcli: false
+  kubernetes: false
+  swarm: false
 deprecated: false
 min_api_version: "1.30"
 experimental: false

_data/engine-cli-edge/docker_deploy.yaml

@@ -17,7 +17,8 @@ options:
   swarm: true
 - option: compose-file
   shorthand: c
-  value_type: string
+  value_type: stringSlice
+  default_value: '[]'
   description: Path to a Compose file
   deprecated: false
   min_api_version: "1.25"

_data/engine-cli-edge/docker_events.yaml

@@ -150,7 +150,7 @@ long: |-
   * container (`container=<name or id>`)
   * daemon (`daemon=<name or id>`)
   * event (`event=<event action>`)
-  * image (`image=<tag or id>`)
+  * image (`image=<repository or tag>`)
   * label (`label=<key>` or `label=<key>=<value>`)
   * network (`network=<name or id>`)
   * node (`node=<id>`)

_data/engine-cli-edge/docker_export.yaml

@@ -22,7 +22,7 @@ options:
   kubernetes: false
   swarm: false
 examples: |-
-  ch of these commands has the same result.
+  Each of these commands has the same result.
 
   ```bash
   $ docker export red_panda > latest.tar

_data/engine-cli-edge/docker_image_prune.yaml

@@ -34,8 +34,8 @@ options:
   experimentalcli: false
   kubernetes: false
   swarm: false
-examples: |2-
-   output:
+examples: |-
+  Example output:
 
   ```bash
   $ docker image prune -a
@@ -97,6 +97,19 @@ examples: |2-
   format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
   images without the specified labels.
 
+  > **Predicting what will be removed**
+  >
+  > If you are using positive filtering (testing for the existence of a label or
+  > that a label has a specific value), you can use `docker image ls` with the
+  > same filtering syntax to see which images match your filter.
+  >
+  > However, if you are using negative filtering (testing for the absence of a
+  > label or that a label does *not* have a specific value), this type of filter
+  > does not work with `docker image ls` so you cannot easily predict which images
+  > will be removed. In addition, the confirmation prompt for `docker image prune`
+  > always warns that *all* dangling images will be removed, even if you are using
+  > `--filter`.
+
   The following removes images created before `2017-01-04T00:00:00`:
 
   ```bash
@@ -163,6 +176,35 @@ examples: |2-
   alpine              latest              88e169ea8f46        8 days ago           3.98 MB
   busybox             latest              e02e811dd08f        2 months ago         1.09 MB
   ```
+
+  The following example removes images with the label `deprecated`:
+
+  ```bash
+  $ docker image prune --filter="label=deprecated"
+  ```
+
+  The following example removes images with the label `maintainer` set to `john`:
+
+  ```bash
+  $ docker image prune --filter="label=maintainer=john"
+  ```
+
+  This example removes images which have no `maintainer` label:
+
+  ```bash
+  $ docker image prune --filter="label!=maintainer"
+  ```
+
+  This example removes images which have a maintainer label not set to `john`:
+
+  ```bash
+  $ docker image prune --filter="label!=maintainer=john"
+  ```
+
+  > **Note**: You are prompted for confirmation before the `prune` removes
+  > anything, but you are not shown a list of what will potentially be removed.
+  > In addition, `docker image ls` does not support negative filtering, so it
+  > difficult to predict what images will actually be removed.
 deprecated: false
 min_api_version: "1.25"
 experimental: false

_data/engine-cli-edge/docker_inspect.yaml

@@ -1,7 +1,7 @@
 command: docker inspect
 short: Return low-level information on Docker objects
 long: |-
-  ker inspect provides detailed information on constructs controlled by Docker.
+  Docker inspect provides detailed information on constructs controlled by Docker.
 
   By default, `docker inspect` will render results in a JSON array.
 usage: docker inspect [OPTIONS] NAME|ID [NAME|ID...]

_data/engine-cli-edge/docker_kill.yaml

@@ -1,8 +1,10 @@
 command: docker kill
 short: Kill one or more running containers
 long: |-
-  The main process inside the container will be sent `SIGKILL`, or any
-  signal specified with option `--signal`.
+  The `docker kill` subcommand kills one or more containers. The main process
+  inside the container is sent `SIGKILL` signal (default), or the signal that is
+  specified with the `--signal` option. You can kill a container using the
+  container's ID, ID-prefix, or name.
 
   > **Note**: `ENTRYPOINT` and `CMD` in the *shell* form run as a subcommand of
   > `/bin/sh -c`, which does not pass signals. This means that the executable is
@@ -21,6 +23,37 @@ options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+examples: |-
+  ### Send a KILL signal  to a container
+
+  The following example sends the default `KILL` signal to the container named
+  `my_container`:
+
+  ```bash
+  $ docker kill my_container
+  ```
+
+  ### Send a custom signal  to a container
+
+  The following example sends a `SIGHUP` signal to the container named
+  `my_container`:
+
+  ```bash
+  $ docker kill --signal=SIGHUP  my_container
+  ```
+
+
+  You can specify a custom signal either by _name_, or _number_. The `SIG` prefix
+  is optional, so the following examples are equivalent:
+
+  ```bash
+  $ docker kill --signal=SIGHUP my_container
+  $ docker kill --signal=HUP my_container
+  $ docker kill --signal=1 my_container
+  ```
+
+  Refer to the [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html)
+  man-page for a list of standard Linux signals.
 deprecated: false
 experimental: false
 experimentalcli: false

_data/engine-cli-edge/docker_network_create.yaml

@@ -48,6 +48,18 @@ long: |-
   Network names must be unique. The Docker daemon attempts to identify naming
   conflicts but this is not guaranteed. It is the user's responsibility to avoid
   name conflicts.
+
+  ### Overlay network limitations
+
+  You should create overlay networks with `/24` blocks (the default), which limits
+  you to 256 IP addresses, when you create networks using the default VIP-based
+  endpoint-mode. This recommendation addresses
+  [limitations with swarm mode](https://github.com/moby/moby/issues/30820). If you
+  need more than 256 IP addresses, do not increase the IP block size. You can
+  either use `dnsrr` endpoint mode with an external load balancer, or use multiple
+  smaller overlay networks. See
+  [Configure service discovery](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery)
+  for more information about different endpoint modes.
 usage: docker network create [OPTIONS] NETWORK
 pname: docker network
 plink: docker_network.yaml
@@ -248,15 +260,16 @@ examples: |-
 
   If you omit the `--gateway` flag the Engine selects one for you from inside a
   preferred pool. For `overlay` networks and for network driver plugins that
-  support it you can create multiple subnetworks.
+  support it you can create multiple subnetworks. This example uses two `/25`
+  subnet mask to adhere to the current guidance of not having more than 256 IPs in
+  a single overlay network. Each of the subnetworks has 126 usable addresses.
 
   ```bash
   $ docker network create -d overlay \
-    --subnet=192.168.0.0/16 \
-    --subnet=192.170.0.0/16 \
-    --gateway=192.168.0.100 \
-    --gateway=192.170.0.100 \
-    --ip-range=192.168.1.0/24 \
+    --subnet=192.168.1.0/25 \
+    --subnet=192.170.2.0/25 \
+    --gateway=192.168.1.100 \
+    --gateway=192.170.2.100 \
     --aux-address="my-router=192.168.1.5" --aux-address="my-switch=192.168.1.6" \
     --aux-address="my-printer=192.170.1.5" --aux-address="my-nas=192.170.1.6" \
     my-multihost-network

_data/engine-cli-edge/docker_network_disconnect.yaml

@@ -1,7 +1,7 @@
 command: docker network disconnect
 short: Disconnect a container from a network
-long: |2-
-   a container from a network. The container must be running to
+long: |-
+  Disconnects a container from a network. The container must be running to
   disconnect it from the network.
 usage: docker network disconnect [OPTIONS] NETWORK CONTAINER
 pname: docker network

_data/engine-cli-edge/docker_node_demote.yaml

@@ -1,7 +1,7 @@
 command: docker node demote
 short: Demote one or more nodes from manager in the swarm
 long: |-
-  motes an existing manager so that it is no longer a manager. This command
+  Demotes an existing manager so that it is no longer a manager. This command
   targets a docker engine that is a manager in the swarm.
 usage: docker node demote NODE [NODE...]
 pname: docker node

_data/engine-cli-edge/docker_node_ls.yaml

@@ -77,13 +77,13 @@ examples: "```bash\n$ docker node ls\n\nID                           HOSTNAME
   \       | Node status\n`.Availability`  | Node availability (\"active\", \"pause\",
   or \"drain\")\n`.ManagerStatus` | Manager status of the node\n`.TLSStatus`     |
   TLS status of the node (\"Ready\", or \"Needs Rotation\" has TLS certificate signed
-  by an old CA)\n\nWhen using the `--format` option, the `node ls` command will either\noutput
-  the data exactly as the template declares or, when using the\n`table` directive,
-  includes column headers as well.\n\nThe following example uses a template without
-  headers and outputs the\n`ID`, `Hostname`, and `TLS Status` entries separated by
-  a colon for all nodes:\n\n```bash\n$ docker node ls --format \"{{.ID}}: {{.Hostname}}
-  {{.TLSStatus}}\"\ne216jshn25ckzbvmwlnh5jr3g: swarm-manager1 Ready\n35o6tiywb700jesrt3dmllaza:
-  swarm-worker1 Needs Rotation  \n```"
+  by an old CA)\n`.EngineVersion` | Engine version\n\nWhen using the `--format` option,
+  the `node ls` command will either\noutput the data exactly as the template declares
+  or, when using the\n`table` directive, includes column headers as well.\n\nThe following
+  example uses a template without headers and outputs the\n`ID`, `Hostname`, and `TLS
+  Status` entries separated by a colon for all nodes:\n\n```bash\n$ docker node ls
+  --format \"{{.ID}}: {{.Hostname}} {{.TLSStatus}}\"\ne216jshn25ckzbvmwlnh5jr3g: swarm-manager1
+  Ready\n35o6tiywb700jesrt3dmllaza: swarm-worker1 Needs Rotation  \n```"
 deprecated: false
 min_api_version: "1.24"
 experimental: false

_data/engine-cli-edge/docker_plugin_disable.yaml

@@ -1,7 +1,7 @@
 command: docker plugin disable
 short: Disable a plugin
 long: |-
-  ables a plugin. The plugin must be installed before it can be disabled,
+  Disables a plugin. The plugin must be installed before it can be disabled,
   see [`docker plugin install`](plugin_install.md). Without the `-f` option,
   a plugin that has references (e.g., volumes, networks) cannot be disabled.
 usage: docker plugin disable [OPTIONS] PLUGIN

_data/engine-cli-edge/docker_plugin_enable.yaml

@@ -9,7 +9,7 @@ plink: docker_plugin.yaml
 options:
 - option: timeout
   value_type: int
-  default_value: "0"
+  default_value: "30"
   description: HTTP client timeout (in seconds)
   deprecated: false
   experimental: false

_data/engine-cli-edge/docker_plugin_set.yaml

@@ -7,7 +7,7 @@ long: |-
    * env variables
    * source of mounts
    * path of devices
-   * arg
+   * args
 usage: docker plugin set PLUGIN KEY=VALUE [KEY=VALUE...]
 pname: docker plugin
 plink: docker_plugin.yaml

_data/engine-cli-edge/docker_run.yaml

@@ -1063,12 +1063,12 @@ examples: |-
   ### Publish or expose port (-p, --expose)
 
   ```bash
-  $ docker run -p 127.0.0.1:80:8080 ubuntu bash
+  $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash
   ```
 
-  This binds port `8080` of the container to port `80` on `127.0.0.1` of the host
-  machine. The [Docker User
-  Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/)
+  This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host
+  machine. You can also specify `udp` and `sctp` ports.
+  The [Docker User Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/)
   explains in detail how to manipulate ports in Docker.
 
   ```bash
@@ -1312,6 +1312,7 @@ examples: |-
   |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | `no`                       | Do not automatically restart the container when it exits. This is the default.                                                                                                                                                                                   |
   | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts.                                                                                                                     |
+  | `unless-stopped`           | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. |
   | `always`                   | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. |
 
   ```bash

_data/engine-cli-edge/docker_secret_create.yaml

@@ -12,7 +12,7 @@ options:
   value_type: string
   description: Secret driver
   deprecated: false
-  min_api_version: "1.31"
+  min_api_version: "1.37"
   experimental: false
   experimentalcli: false
   kubernetes: false
@@ -26,6 +26,14 @@ options:
   experimentalcli: false
   kubernetes: false
   swarm: false
+- option: template-driver
+  value_type: string
+  description: Template driver
+  deprecated: false
+  experimental: false
+  experimentalcli: false
+  kubernetes: false
+  swarm: false
 examples: |-
   ### Create a secret