user facing documentation changes in master atm

Docker-DCO-1.1-Signed-off-by: SvenDowideit <SvenDowideit@home.org.au> (github: SvenDowideit)

docs/sources/reference/commandline/cli.md

@@ -738,7 +738,8 @@ specify this by adding the server name.
 
     Log out from a Docker registry, if no server is specified "https://index.docker.io/v1/" is the default.
 
-    example:
+For example:
+
     $ docker logout localhost:8080
 
 ## logs
@@ -953,20 +954,23 @@ removed before the image is removed.
 
     Run a command in a new container
 
-      -a, --attach=[]            Attach to stdin, stdout or stderr.
+      -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
       -c, --cpu-shares=0         CPU shares (relative weight)
+      --cap-add=[]               Add Linux capabilities
+      --cap-drop=[]              Drop Linux capabilities
       --cidfile=""               Write the container ID to the file
       --cpuset=""                CPUs in which to allow execution (0-3, 0,1)
-      -d, --detach=false         Detached mode: Run container in the background, print new container id
-      --dns=[]                   Set custom dns servers
-      --dns-search=[]            Set custom dns search domains
+      -d, --detach=false         Detached mode: run container in the background and print new container ID
+      --device=[]                Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc)
+      --dns=[]                   Set custom DNS servers
+      --dns-search=[]            Set custom DNS search domains
       -e, --env=[]               Set environment variables
-      --entrypoint=""            Overwrite the default entrypoint of the image
-      --env-file=[]              Read in a line delimited file of ENV variables
+      --entrypoint=""            Overwrite the default ENTRYPOINT of the image
+      --env-file=[]              Read in a line delimited file of environment variables
       --expose=[]                Expose a port from the container without publishing it to your host
       -h, --hostname=""          Container host name
-      -i, --interactive=false    Keep stdin open even if not attached
-      --link=[]                  Add link to another container (name:alias)
+      -i, --interactive=false    Keep STDIN open even if not attached
+      --link=[]                  Add link to another container in the form of name:alias
       --lxc-conf=[]              (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
       -m, --memory=""            Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
       --name=""                  Assign a name to the container
@@ -981,12 +985,11 @@ removed before the image is removed.
                                    (use 'docker port' to see the actual mapping)
       --privileged=false         Give extended privileges to this container
       --rm=false                 Automatically remove the container when it exits (incompatible with -d)
-      --sig-proxy=true           Proxy received signals to the process (even in non-tty mode). SIGCHLD, SIGKILL, and SIGSTOP are not proxied.
-      -t, --tty=false            Allocate a pseudo-tty
+      --sig-proxy=true           Proxy received signals to the process (even in non-TTY mode). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.
+      -t, --tty=false            Allocate a pseudo-TTY
       -u, --user=""              Username or UID
-      -v, --volume=[]            Bind mount a volume (e.g., from the host: -v /host:/container, from docker: -v /container)
+      -v, --volume=[]            Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container)
       --volumes-from=[]          Mount volumes from the specified container(s)
-      --device=[]                Add a host device to the container (e.g. --device=/dev/sdc[:/dev/xvdc[:rwm]])
       -w, --workdir=""           Working directory inside the container
 
 The `docker run` command first `creates` a writeable container layer over the
@@ -1272,7 +1275,7 @@ grace period, SIGKILL
 
 ## tag
 
-    Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]
+    Usage: docker tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]
 
     Tag an image into a repository
 
@@ -1292,7 +1295,7 @@ them to [*Share Images via Repositories*](
 
     Usage: docker unpause CONTAINER
 
-    Resumes a paused container.
+    Unpause all processes within a container
 
 The `docker unpause` command uses the cgroups freezer to un-suspend all
 processes in a container.