Merge pull request #2178 from thaJeztah/19.03_backport_docs_updates

[19.03 backport] docs updates
Upstream-commit: ad6c6670340a726e3f3fd280b17266ba1145aa3b
Component: cli

Author: andrewhsu

components/cli/README.md

@@ -1,4 +1,5 @@
-[![build status](https://circleci.com/gh/docker/cli.svg?style=shield)](https://circleci.com/gh/docker/cli/tree/master) [![Build Status](https://jenkins.dockerproject.org/job/docker/job/cli/job/master/badge/icon)](https://jenkins.dockerproject.org/job/docker/job/cli/job/master/)
+[![build status](https://circleci.com/gh/docker/cli.svg?style=shield)](https://circleci.com/gh/docker/cli/tree/master)
+[![Build Status](https://ci.docker.com/public/job/cli/job/master/badge/icon)](https://ci.docker.com/public/job/cli/job/master)
 
 docker/cli
 ==========

components/cli/docs/reference/builder.md

@@ -157,10 +157,12 @@ be UPPERCASE to distinguish them from arguments more easily.
 
 
 Docker runs instructions in a `Dockerfile` in order. A `Dockerfile` **must
-start with a \`FROM\` instruction**. The `FROM` instruction specifies the [*Base
-Image*](glossary.md#base-image) from which you are building. `FROM` may only be
-preceded by one or more `ARG` instructions, which declare arguments that are used
-in `FROM` lines in the `Dockerfile`.
+begin with a \`FROM\` instruction**. This may be after [parser
+directives](#parser-directives), [comments](#format), and globally scoped
+[ARGs](#arg). The `FROM` instruction specifies the [*Parent
+Image*](glossary.md#parent-image) from which you are building. `FROM`
+may only be preceded by one or more `ARG` instructions, which declare arguments
+that are used in `FROM` lines in the `Dockerfile`.
 
 Docker treats lines that *begin* with `#` as a comment, unless the line is
 a valid [parser directive](#parser-directives). A `#` marker anywhere
@@ -1720,8 +1722,8 @@ The following `ARG` variables are set automatically:
 * `TARGETVARIANT` - variant component of TARGETPLATFORM
 * `BUILDPLATFORM` - platform of the node performing the build.
 * `BUILDOS` - OS component of BUILDPLATFORM
-* `BUILDARCH` - OS component of BUILDPLATFORM
-* `BUILDVARIANT` - OS component of BUILDPLATFORM
+* `BUILDARCH` - architecture component of BUILDPLATFORM
+* `BUILDVARIANT` - variant component of BUILDPLATFORM
 
 These arguments are defined in the global scope so are not automatically
 available inside build stages or for your `RUN` commands. To expose one of

components/cli/docs/reference/commandline/cli.md

@@ -54,7 +54,7 @@ each `docker` command with `sudo`. To avoid having to use `sudo` with the
 For more information about installing Docker or `sudo` configuration, refer to
 the [installation](https://docs.docker.com/install/) instructions for your operating system.
 
-### Environment variables
+## Environment variables
 
 For easy reference, the following list of environment variables are supported
 by the `docker` command line:
@@ -99,7 +99,7 @@ By default, the Docker command line stores its configuration files in a
 directory called `.docker` within your `$HOME` directory.
 
 Docker manages most of the files in the configuration directory
-and you should not modify them. However, you *can modify* the
+and you should not modify them. However, you *can* modify the
 `config.json` file to control certain aspects of how the `docker`
 command behaves.
 
@@ -111,12 +111,12 @@ variable. Command line options override environment variables and environment
 variables override properties you specify in a `config.json` file.
 
 
-#### Change the `.docker` directory
+### Change the `.docker` directory
 
 To specify a different directory, use the `DOCKER_CONFIG`
 environment variable or the `--config` command line option. If both are
 specified, then the `--config` option overrides the `DOCKER_CONFIG` environment
-variable. The example below overrides runs the `docker ps` command using a
+variable. The example below overrides the `docker ps` command using a
 `config.json` file located in the `~/testconfigs/` directory.
 
 ```bash
@@ -132,7 +132,7 @@ directory to be `HOME/newdir/.docker`.
 echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile
 ```
 
-#### `config.json` properties
+### `config.json` properties
 
 The `config.json` file stores a JSON encoding of several properties:
 

components/cli/docs/reference/commandline/pause.md

@@ -27,14 +27,14 @@ Options:
 ## Description
 
 The `docker pause` command suspends all processes in the specified containers.
-On Linux, this uses the cgroups freezer. Traditionally, when suspending a process
+On Linux, this uses the freezer cgroup. Traditionally, when suspending a process
 the `SIGSTOP` signal is used, which is observable by the process being suspended.
-With the cgroups freezer the process is unaware, and unable to capture,
+With the freezer cgroup the process is unaware, and unable to capture,
 that it is being suspended, and subsequently resumed. On Windows, only Hyper-V
 containers can be paused.
 
 See the
-[cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
+[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
 for further details.
 
 ## Examples

components/cli/docs/reference/commandline/ps.md

@@ -75,6 +75,22 @@ $ docker ps -a
 container that exposes TCP ports `100, 101, 102` displays `100-102/tcp` in
 the `PORTS` column.
 
+### Show disk usage by container
+
+The `docker ps -s` command displays two different on-disk-sizes for each container:
+
+```bash
+$ docker ps -s
+CONTAINER ID   IMAGE          COMMAND                  CREATED        STATUS       PORTS   NAMES        SIZE                                                                                      SIZE
+e90b8831a4b8   nginx          "/bin/bash -c 'mkdir "   11 weeks ago   Up 4 hours           my_nginx     35.58 kB (virtual 109.2 MB)
+00c6131c5e30   telegraf:1.5   "/entrypoint.sh"         11 weeks ago   Up 11 weeks          my_telegraf  0 B (virtual 209.5 MB)
+```
+  * The "size" information shows the amount of data (on disk) that is used for the _writable_ layer of each container
+  * The "virtual size" is the total amount of disk-space used for the read-only _image_ data used by the container and the writable layer.
+  
+For more information, refer to the [container size on disk](https://docs.docker.com/storage/storagedriver/#container-size-on-disk) section.
+
+
 ### Filtering
 
 The filtering flag (`-f` or `--filter`) format is a `key=value` pair. If there is more
@@ -431,4 +447,4 @@ a87ecb4f327c        com.docker.swarm.node=ubuntu,com.docker.swarm.storage=ssd
 01946d9d34d8
 c1d3b0166030        com.docker.swarm.node=debian,com.docker.swarm.cpu=6
 41d50ecd2f57        com.docker.swarm.node=fedora,com.docker.swarm.cpu=3,com.docker.swarm.storage=ssd
-```
+```

components/cli/docs/reference/commandline/search.md

@@ -83,7 +83,7 @@ This example displays images with a name containing 'busybox',
 at least 3 stars and the description isn't truncated in the output:
 
 ```bash
-$ docker search --stars=3 --no-trunc busybox
+$ docker search --filter=stars=3 --no-trunc busybox
 NAME                 DESCRIPTION                                                                               STARS     OFFICIAL   AUTOMATED
 busybox              Busybox base image.                                                                       325       [OK]       
 progrium/busybox                                                                                               50                   [OK]

components/cli/docs/reference/commandline/unpause.md

@@ -27,10 +27,10 @@ Options:
 ## Description
 
 The `docker unpause` command un-suspends all processes in the specified containers.
-On Linux, it does this using the cgroups freezer.
+On Linux, it does this using the freezer cgroup.
 
 See the
-[cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
+[freezer cgroup documentation](https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt)
 for further details.
 
 ## Examples

components/cli/man/src/container/pause.md

@@ -1,11 +1,11 @@
 The `docker container pause` command suspends all processes in the specified containers.
-On Linux, this uses the cgroups freezer. Traditionally, when suspending a process
+On Linux, this uses the freezer cgroup. Traditionally, when suspending a process
 the `SIGSTOP` signal is used, which is observable by the process being suspended.
-With the cgroups freezer the process is unaware, and unable to capture,
+With the freezer cgroup the process is unaware, and unable to capture,
 that it is being suspended, and subsequently resumed. On Windows, only Hyper-V
 containers can be paused.
 
-See the [cgroups freezer documentation]
+See the [freezer cgroup documentation]
 (https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for
 further details.
 

components/cli/man/src/container/unpause.md

@@ -1,6 +1,6 @@
 The `docker container unpause` command un-suspends all processes in a container.
-On Linux, it does this using the cgroups freezer.
+On Linux, it does this using the freezer cgroup.
 
-See the [cgroups freezer documentation]
+See the [freezer cgroup documentation]
 (https://www.kernel.org/doc/Documentation/cgroup-v1/freezer-subsystem.txt) for
 further details.