Merge pull request #5312 from ostezer/docs-illusion-confusion

Urgent fix for crazy docs error on volumes.

docs/sources/use/working_with_volumes.md

@@ -94,24 +94,24 @@ upgrade, or effectively migrate data volumes between containers.
 
     -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
 
-You must specify an absolute path for `host-dir`. If
+You must specify an absolute path for `host-dir`. If `host-dir` is missing from
-`host-dir` is missing from the command, then docker
+the command, then Docker creates a new volume. If `host-dir` is present but
-creates a new volume. If `host-dir` is present but
+points to a non-existent directory on the host, Docker will automatically
-points to a non-existent directory on the host, Docker will
+create this directory and use it as the source of the bind-mount.
-automatically create this directory and use it as the source of the
-bind-mount.
 
-Note that this is not available from a Dockerfile due the portability
+Note that this is not available from a Dockerfile due the portability and
-and sharing purpose of it. The `host-dir` volumes
+sharing purpose of it. The `host-dir` volumes are entirely host-dependent
-are entirely host-dependent and might not work on any other machine.
+and might not work on any other machine.
 
 For example:
 
-    sudo docker run -t -i -v /var/logs:/var/host_logs:ro ubuntu bash
+    # Usage:
+    # sudo docker run [OPTIONS] -v /(dir. on host):/(dir. in container):(Read-Write or Read-Only) [ARG..]
+    # Example:
+    sudo docker run -i -t -v /var/log:/logs_from_host:ro ubuntu bash
 
-The command above mounts the host directory `/var/logs`
+The command above mounts the host directory `/var/log` into the container
-into the container with read only permissions as
+with *read only* permissions as `/logs_from_host`.
-`/var/host_logs`.
 
 New in version v0.5.0.