Merge pull request #32332 from mstanleyjones/1.13.x1.13.x

Cherry-pick command-line ref improvements

1 files changed, 40 insertions, 14 deletions

diff --git a/docs/reference/commandline/exec.md b/docs/reference/commandline/exec.md
index 38891c9ea0..1ae46cf194 100644
--- a/docs/reference/commandline/exec.md
+++ b/docs/reference/commandline/exec.md
@@ -31,35 +31,61 @@ Options:
   -u, --user           Username or UID (format: <name|uid>[:<group|gid>])
 ```
 
+## Description
+
 The `docker exec` command runs a new command in a running container.
 
 The command started using `docker exec` only runs while the container's primary
 process (`PID 1`) is running, and it is not restarted if the container is
 restarted.
 
-If the container is paused, then the `docker exec` command will fail with an error:
+## Examples
 
-    $ docker pause test
-    test
-    $ docker ps
-    CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
-    1ae3b36715d2        ubuntu:latest       "bash"              17 seconds ago      Up 16 seconds (Paused)                       test
-    $ docker exec test ls
-    FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec
-    $ echo $?
-    1
+### Run `docker exec` on a running container
 
-## Examples
+First, start a container.
 
-    $ docker run --name ubuntu_bash --rm -i -t ubuntu bash
+```bash
+$ docker run --name ubuntu_bash --rm -i -t ubuntu bash
+```
 
 This will create a container named `ubuntu_bash` and start a Bash session.
 
-    $ docker exec -d ubuntu_bash touch /tmp/execWorks
+Next, execute a command on the container.
+
+```bash
+$ docker exec -d ubuntu_bash touch /tmp/execWorks
+```
 
 This will create a new file `/tmp/execWorks` inside the running container
 `ubuntu_bash`, in the background.
 
-    $ docker exec -it ubuntu_bash bash
+Next, execute an interactive `bash` shell on the container.
+
+```bash
+$ docker exec -it ubuntu_bash bash
+```
 
 This will create a new Bash session in the container `ubuntu_bash`.
+
+### Try to run `docker exec` on a paused container
+
+If the container is paused, then the `docker exec` command will fail with an error:
+
+```bash
+$ docker pause test
+
+test
+
+$ docker ps
+
+CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
+1ae3b36715d2        ubuntu:latest       "bash"              17 seconds ago      Up 16 seconds (Paused)                       test
+
+$ docker exec test ls
+
+FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec
+
+$ echo $?
+1
+```