engine: update cli-reference yaml-docs

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

data/engine-cli/docker_build.yaml

@@ -141,7 +141,7 @@ options:
       swarm: false
     - option: cgroup-parent
       value_type: string
-      description: Optional parent cgroup for the container
+      description: Set the parent cgroup for the `RUN` instructions during build
       details_url: '#cgroup-parent'
       deprecated: false
       hidden: false

data/engine-cli/docker_builder_build.yaml

@@ -36,7 +36,7 @@ options:
       swarm: false
     - option: cgroup-parent
       value_type: string
-      description: Optional parent cgroup for the container
+      description: Set the parent cgroup for the `RUN` instructions during build
       deprecated: false
       hidden: false
       experimental: false

data/engine-cli/docker_config_inspect.yaml

@@ -6,7 +6,7 @@ long: |-
     By default, this renders all results in a JSON array. If a format is specified,
     the given template will be executed for each result.
 
-    Go's [text/template](https://golang.org/pkg/text/template/) package
+    Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     For detailed information about using configs, refer to [store configuration data using Docker Configs](/engine/swarm/configs/).

data/engine-cli/docker_events.yaml

@@ -175,7 +175,7 @@ long: |-
 
     If a format (`--format`) is specified, the given template will be executed
     instead of the default
-    format. Go's [text/template](https://golang.org/pkg/text/template/) package
+    format. Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     If a format is set to `{{json .}}`, the events are streamed as valid JSON
@@ -196,7 +196,11 @@ options:
       swarm: false
     - option: format
       value_type: string
-      description: Format the output using the given Go template
+      description: |-
+        Format output using a custom template:
+        'json':             Print in JSON format
+        'TEMPLATE':         Print output using the given Go template.
+        Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates
       deprecated: false
       hidden: false
       experimental: false
@@ -432,8 +436,11 @@ examples: |-
 
     #### Format as JSON
 
+    To list events in JSON format, use the `json` directive, which is the equivalent
+    of `--format '{{ json . }}`.
+
     ```console
-    $ docker events --format '{{json .}}'
+    $ docker events --format json
 
     {"status":"create","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     {"status":"attach","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
@@ -441,6 +448,8 @@ examples: |-
     {"status":"start","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f42..
     {"status":"resize","id":"196016a57679bf42424484918746a9474cd905dd993c4d0f4..
     ```
+
+    .
 deprecated: false
 experimental: false
 experimentalcli: false

data/engine-cli/docker_exec.yaml

@@ -162,10 +162,10 @@ examples: |-
 
     Next, set environment variables in the current bash session.
 
-    By default, the `docker exec` command, inherits the environment variables that
+    The `docker exec` command inherits the environment variables that are set at the
-    are set at the time the container is created. Use the `--env` (or the `-e` shorthand)
+    time the container is created. Use the `--env` (or the `-e` shorthand) to
-    to override global environment variables, or to set additional environment variables
+    override global environment variables, or to set additional environment
-    for the process started by `docker exec`.
+    variables for the process started by `docker exec`.
 
     The example below creates a new shell session in the container `mycontainer` with
     environment variables `$VAR_A` and `$VAR_B` set to "1" and "2" respectively.

data/engine-cli/docker_image_build.yaml

@@ -36,7 +36,7 @@ options:
       swarm: false
     - option: cgroup-parent
       value_type: string
-      description: Optional parent cgroup for the container
+      description: Set the parent cgroup for the `RUN` instructions during build
       deprecated: false
       hidden: false
       experimental: false

data/engine-cli/docker_info.yaml

@@ -8,7 +8,7 @@ long: |-
     under different names is counted only once.
 
     If a format is specified, the given template will be executed instead of the
-    default format. Go's [text/template](https://golang.org/pkg/text/template/) package
+    default format. Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     Depending on the storage driver in use, additional information can be shown, such

data/engine-cli/docker_inspect.yaml

@@ -9,7 +9,7 @@ long: |-
 
     If a format is specified, the given template will be executed for each result.
 
-    Go's [text/template](https://golang.org/pkg/text/template/) package describes
+    Go's [text/template](https://pkg.go.dev/text/template) package describes
     all the details of the format.
 
     ### Specify target type (--type) {#type}

data/engine-cli/docker_load.yaml

@@ -3,7 +3,7 @@ aliases: docker image load, docker load
 short: Load an image from a tar archive or STDIN
 long: |-
     Load an image or repository from a tar archive (even if compressed with gzip,
-    bzip2, or xz) from a file or STDIN. It restores both images and tags.
+    bzip2, xz or zstd) from a file or STDIN. It restores both images and tags.
 usage: docker load [OPTIONS]
 pname: docker
 plink: docker.yaml

data/engine-cli/docker_logs.yaml

@@ -13,7 +13,7 @@ long: |-
     Passing a negative number or a non-integer to `--tail` is invalid and the
     value is set to `all` in that case.
 
-    The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants)
+    The `docker logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano)
     , for example `2014-09-16T06:17:46.000000000Z`, to each
     log entry. To ensure that the timestamps are aligned the
     nano-second part of the timestamp will be padded with zero when necessary.

data/engine-cli/docker_node_inspect.yaml

@@ -4,7 +4,7 @@ long: |-
     Returns information about a node. By default, this command renders all results
     in a JSON array. You can specify an alternate format to execute a
     given template for each result. Go's
-    [text/template](https://golang.org/pkg/text/template/) package describes all the
+    [text/template](https://pkg.go.dev/text/template) package describes all the
     details of the format.
 
     > **Note**

data/engine-cli/docker_ps.yaml

@@ -262,9 +262,19 @@ examples: |-
 
     #### status
 
-    The `status` filter matches containers by status. You can filter using
+    The `status` filter matches containers by status. The possible values for the container status are:
-    `created`, `restarting`, `running`, `removing`, `paused`, `exited` and `dead`. For example,
+
-    to filter for `running` containers:
+    | Status       | Description                                                                                                                                                                                     |
+    | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `created`    | A container that has never been started.                                                                                                                                                        |
+    | `running`    | A running container, started by either `docker start` or `docker run`.                                                                                                                          |
+    | `paused`     | A paused container. See `docker pause`.                                                                                                                                                         |
+    | `restarting` | A container which is starting due to the designated restart policy for that container.                                                                                                          |
+    | `exited`     | A container which is no longer running. For example, the process inside the container completed or the container was stopped using the `docker stop` command.                                   |
+    | `removing`   | A container which is in the process of being removed. See `docker rm`.                                                                                                                          |
+    | `dead`       | A "defunct" container; for example, a container that was only partially removed because resources were kept busy by an external process. `dead` containers cannot be (re)started, only removed. |
+
+    For example, to filter for `running` containers:
 
     ```console
     $ docker ps --filter status=running

data/engine-cli/docker_pull.yaml

@@ -104,18 +104,18 @@ examples: |-
     Docker images can consist of multiple layers. In the example above, the image
     consists of a single layer; `e756f3fdd6a3`.
 
-    Layers can be reused by images. For example, the `debian:bullseye` image shares
+    Layers can be reused by images. For example, the `debian:bookworm` image shares
-    its layer with the `debian:latest`. Pulling the `debian:bullseye` image therefore
+    its layer with the `debian:latest`. Pulling the `debian:bookworm` image therefore
     only pulls its metadata, but not its layers, because the layer is already present
     locally:
 
     ```console
-    $ docker image pull debian:bullseye
+    $ docker image pull debian:bookworm
 
-    bullseye: Pulling from library/debian
+    bookworm: Pulling from library/debian
     Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
-    Status: Downloaded newer image for debian:bullseye
+    Status: Downloaded newer image for debian:bookworm
-    docker.io/library/debian:bullseye
+    docker.io/library/debian:bookworm
     ```
 
     To see which images are present locally, use the [`docker images`](images.md)
@@ -125,13 +125,13 @@ examples: |-
     $ docker images
 
     REPOSITORY   TAG        IMAGE ID       CREATED        SIZE
-    debian       bullseye   4eacea30377a   8 days ago     124MB
+    debian       bookworm   4eacea30377a   8 days ago     124MB
     debian       latest     4eacea30377a   8 days ago     124MB
     ```
 
     Docker uses a content-addressable image store, and the image ID is a SHA256
     digest covering the image's configuration and layers. In the example above,
-    `debian:bullseye` and `debian:latest` have the same image ID because they are
+    `debian:bookworm` and `debian:latest` have the same image ID because they are
     the *same* image tagged with different names. Because they are the same image,
     their layers are stored only once and do not consume extra disk space.
 

data/engine-cli/docker_run.yaml

@@ -1360,6 +1360,8 @@ examples: |-
     You can also load the environment variables from a file. This file should use
     the syntax `<variable>=value` (which sets the variable to the given value) or
     `<variable>` (which takes the value from the local environment), and `#` for comments.
+    Additionally, it's important to note that lines beginning with `#` are treated as line comments
+    and are ignored, whereas a `#` appearing anywhere else in a line is treated as part of the variable value.
 
     ```console
     $ cat env.list
@@ -1622,7 +1624,7 @@ examples: |-
     following rule:
 
     ```console
-    $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image
+    $ docker run -d --device-cgroup-rule='c 42:* rmw' --name my-container my-image
     ```
 
     Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>`

data/engine-cli/docker_secret_inspect.yaml

@@ -6,7 +6,7 @@ long: |-
     By default, this renders all results in a JSON array. If a format is specified,
     the given template will be executed for each result.
 
-    Go's [text/template](https://golang.org/pkg/text/template/) package
+    Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     For detailed information about using secrets, refer to [manage sensitive data with Docker secrets](/engine/swarm/secrets/).

data/engine-cli/docker_service_create.yaml

@@ -1682,7 +1682,7 @@ examples: |-
     ### Create services using templates
 
     You can use templates for some flags of `service create`, using the syntax
-    provided by the Go's [text/template](https://golang.org/pkg/text/template/) package.
+    provided by the Go's [text/template](https://pkg.go.dev/text/template) package.
 
     The supported flags are the following :
 

data/engine-cli/docker_service_inspect.yaml

@@ -6,7 +6,7 @@ long: |-
     By default, this renders all results in a JSON array. If a format is specified,
     the given template will be executed for each result.
 
-    Go's [text/template](https://golang.org/pkg/text/template/) package
+    Go's [text/template](https://pkg.go.dev/text/template) package
     describes all the details of the format.
 
     > **Note**

data/engine-cli/docker_service_logs.yaml

@@ -29,7 +29,7 @@ long: |-
     Passing a negative number or a non-integer to `--tail` is invalid and the
     value is set to `all` in that case.
 
-    The `docker service logs --timestamps` command will add an [RFC3339Nano timestamp](https://golang.org/pkg/time/#pkg-constants)
+    The `docker service logs --timestamps` command will add an [RFC3339Nano timestamp](https://pkg.go.dev/time#RFC3339Nano)
     , for example `2014-09-16T06:17:46.000000000Z`, to each
     log entry. To ensure that the timestamps are aligned the
     nano-second part of the timestamp will be padded with zero when necessary.

data/engine-cli/docker_system_events.yaml

@@ -140,7 +140,11 @@ options:
       swarm: false
     - option: format
       value_type: string
-      description: Format the output using the given Go template
+      description: |-
+        Format output using a custom template:
+        'json':             Print in JSON format
+        'TEMPLATE':         Print output using the given Go template.
+        Refer to https://docs.docker.com/go/formatting/ for more information about formatting output with templates
       details_url: '#format'
       deprecated: false
       hidden: false
@@ -340,7 +344,7 @@ examples: |-
     ### Format the output (--format) {#format}
 
     If a format (`--format`) is specified, the given template will be executed
-    instead of the default format. Go's [text/template](https://golang.org/pkg/text/template/)
+    instead of the default format. Go's [text/template](https://pkg.go.dev/text/template)
     package describes all the details of the format.
 
     ```console

data/engine-cli/docker_system_prune.yaml

@@ -43,7 +43,7 @@ options:
     - option: volumes
       value_type: bool
       default_value: "false"
-      description: Prune volumes
+      description: Prune anonymous volumes
       deprecated: false
       hidden: false
       experimental: false
@@ -90,7 +90,7 @@ examples: |-
 
     By default, volumes are not removed to prevent important data from being
     deleted if there is currently no container using the volume. Use the `--volumes`
-    flag when running the command to prune volumes as well:
+    flag when running the command to prune anonymous volumes as well:
 
     ```console
     $ docker system prune -a --volumes
@@ -98,7 +98,7 @@ examples: |-
     WARNING! This will remove:
             - all stopped containers
             - all networks not used by at least one container
-            - all volumes not used by at least one container
+            - all anonymous volumes not used by at least one container
             - all images without at least one container associated to them
             - all build cache
     Are you sure you want to continue? [y/N] y

data/engine-cli/docker_tag.yaml

@@ -13,7 +13,7 @@ long: |-
     canonical reference for Docker's public registry.
     - `PORT_NUMBER`: If a hostname is present, it may optionally be followed by a
     registry port number in the format `:8080`.
-    - `PATH`: The path consists consists of slash-separated components. Each
+    - `PATH`: The path consists of slash-separated components. Each
     component may contain lowercase letters, digits and separators. A separator is
     defined as a period, one or two underscores, or one or more hyphens. A component
     may not start or end with a separator. While the

data/engine-cli/docker_volume_inspect.yaml

@@ -4,7 +4,7 @@ long: |-
     Returns information about a volume. By default, this command renders all results
     in a JSON array. You can specify an alternate format to execute a
     given template for each result. Go's
-    [text/template](https://golang.org/pkg/text/template/) package describes all the
+    [text/template](https://pkg.go.dev/text/template) package describes all the
     details of the format.
 usage: docker volume inspect [OPTIONS] VOLUME [VOLUME...]
 pname: docker volume

data/engine-cli/docker_volume_prune.yaml

@@ -1,5 +1,5 @@
 command: docker volume prune
-short: Remove all unused local volumes
+short: Remove unused local volumes
 long: |-
     Remove all unused local volumes. Unused local volumes are those which are not
     referenced by any containers. By default, it only removes anonymous volumes.