docs: improve docs on container identification

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

docs/reference/commandline/run.md

@@ -128,27 +128,58 @@ Use `docker ps -a` to view a list of all containers, including those that are st
 
 ## Examples
 
-### <a name="name"></a> Assign name and allocate pseudo-TTY (--name, -it)
+### <a name="name"></a> Assign name (--name)
+
+The `--name` flag lets you specify a custom identifier for a container. The
+following example runs a container named `test` using the `nginx:alpine` image
+in [detached mode](#detach).
 
 ```console
-$ docker run --name test -it debian
+$ docker run --name test -d nginx:alpine
-
+4bed76d3ad428b889c56c1ecc2bf2ed95cb08256db22dc5ef5863e1d03252a19
-root@d6c0fe130dba:/# exit 13
+$ docker ps
-$ echo $?
+CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS                  PORTS     NAMES
-13
+4bed76d3ad42   nginx:alpine   "/docker-entrypoint.…"   1 second ago   Up Less than a second   80/tcp    test
-$ docker ps -a | grep test
-d6c0fe130dba        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
 ```
 
-This example runs a container named `test` using the `debian:latest`
+You can reference the container by name with other commands. For example, the
-image. The `-it` instructs Docker to allocate a pseudo-TTY connected to
+following commands stop and remove a container named `test`:
-the container's stdin; creating an interactive `bash` shell in the container.
+
-The example quits the `bash` shell by entering
+```console
-`exit 13`, passing the exit code on to the caller of
+$ docker stop test
-`docker run`, and recording it in the `test` container's metadata.
+test
+$ docker rm test
+test
+```
+
+If you don't specify a custom name using the `--name` flag, the daemon assigns
+a randomly generated name, such as `vibrant_cannon`, to the container. Using a
+custom-defined name provides the benefit of having an easy-to-remember ID for a
+container.
+
+Moreover, if you connect the container to a user-defined bridge network, other
+containers on the same network can refer to the container by name via DNS.
+
+```console
+$ docker network create mynet
+cb79f45948d87e389e12013fa4d969689ed2c3316985dd832a43aaec9a0fe394
+$ docker run --name test --net mynet -d nginx:alpine
+58df6ecfbc2ad7c42d088ed028d367f9e22a5f834d7c74c66c0ab0485626c32a
+$ docker run --net mynet busybox:latest ping test
+PING test (172.18.0.2): 56 data bytes
+64 bytes from 172.18.0.2: seq=0 ttl=64 time=0.073 ms
+64 bytes from 172.18.0.2: seq=1 ttl=64 time=0.411 ms
+64 bytes from 172.18.0.2: seq=2 ttl=64 time=0.319 ms
+64 bytes from 172.18.0.2: seq=3 ttl=64 time=0.383 ms
+...
+```
 
 ### <a name="cidfile"></a> Capture container ID (--cidfile)
 
+To help with automation, you can have Docker write the container ID out to a
+file of your choosing. This is similar to how some programs might write out
+their process ID to a file (you might've seen them as PID files):
+
 ```console
 $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
 ```

docs/reference/run.md

@@ -22,14 +22,43 @@ A `docker run` command takes the following form:
 $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
 ```
 
-The `docker run` command must specify an [image](https://docs.docker.com/glossary/#image)
+The `docker run` command must specify an [image reference](#image-references)
 to create the container from.
 
+### Image references
+
+The image reference is the name and version of the image. You can use the image
+reference to create or run a container based on an image.
+
+- `docker run IMAGE[:TAG][@DIGEST]`
+- `docker create IMAGE[:TAG][@DIGEST]`
+
+An image tag is the image version, which defaults to `latest` when omitted. Use
+the tag to run a container from specific version of an image. For example, to
+run version `23.10` of the `ubuntu` image: `docker run ubuntu:23.10`.
+
+#### Image digests
+
+Images using the v2 or later image format have a content-addressable identifier
+called a digest. As long as the input used to generate the image is unchanged,
+the digest value is predictable.
+
+The following example runs a container from the `alpine` image with the
+`sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest:
+
+```console
+$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date
+```
+
+### Options
+
 `[OPTIONS]` let you configure options for the container. For example, you can
 give the container a name (`--name`), or run it as a background process (`-d`).
 You can also set options to control things like resource constraints and
 networking.
 
+### Commands and arguments
+
 You can use the `[COMMAND]` and `[ARG...]` positional arguments to specify
 commands and arguments for the container to run when it starts up. For example,
 you can specify `sh` as the `[COMMAND]`, combined with the `-i` and `-t` flags,
@@ -95,55 +124,41 @@ For more information about re-attaching to a background container, see
 
 ## Container identification
 
-### Name (--name)
+You can identify a container in three ways:
-
-The operator can identify a container in three ways:
 
 | Identifier type       | Example value                                                      |
 |:----------------------|:-------------------------------------------------------------------|
-| UUID long identifier  | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" |
+| UUID long identifier  | `f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778` |
-| UUID short identifier | "f78375b1c487"                                                     |
+| UUID short identifier | `f78375b1c487`                                                     |
-| Name                  | "evil_ptolemy"                                                     |
+| Name                  | `evil_ptolemy`                                                     |
 
-The UUID identifiers come from the Docker daemon. If you do not assign a
+The UUID identifier is a random ID assigned to the container by the daemon.
-container name with the `--name` option, then the daemon generates a random
-string name for you. Defining a `name` can be a handy way to add meaning to a
-container. If you specify a `name`, you can use it  when referencing the
-container within a Docker network. This works for both background and foreground
-Docker containers.
 
-> **Note**
+The daemon generates a random string name for containers automatically. You can
->
+also defined a custom name using [the `--name` flag](./commandline/run.md#name).
-> Containers on the default bridge network must be linked to communicate by name.
+Defining a `name` can be a handy way to add meaning to a container. If you
+specify a `name`, you can use it when referring to the container in a
+user-defined network. This works for both background and foreground Docker
+containers.
 
-### PID equivalent
+A container identifier is not the same thing as an image reference. The image
+reference specifies which image to use when you run a container. You can't run
+`docker exec nginx:alpine sh` to open a shell in a container based on the
+`nginx:alpine` image, because `docker exec` expects a container identifier
+(name or ID), not an image.
 
-Finally, to help with automation, you can have Docker write the
+While the image used by a container is not an identifier for the container, you
-container ID out to a file of your choosing. This is similar to how some
+find out the IDs of containers using an image by using the `--filter` flag. For
-programs might write out their process ID to a file (you've seen them as
+example, the following `docker ps` command gets the IDs of all running
-PID files):
+containers based on the `nginx:alpine` image:
-
-    --cidfile="": Write the container ID to the file
-
-### Image[:tag]
-
-While not strictly a means of identifying a container, you can specify a version of an
-image you'd like to run the container with by adding `image[:tag]` to the command. For
-example, `docker run ubuntu:22.04`.
-
-### Image[@digest]
-
-Images using the v2 or later image format have a content-addressable identifier
-called a digest. As long as the input used to generate the image is unchanged,
-the digest value is predictable and referenceable.
-
-The following example runs a container from the `alpine` image with the
-`sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest:
 
 ```console
-$ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date
+$ docker ps -q --filter ancestor=nginx:alpine
 ```
 
+For more information about using filters, see
+[Filtering](https://docs.docker.com/config/filter/).
+
 ## PID settings (--pid)
 
     --pid=""  : Set the PID (Process) Namespace mode for the container,