add some more text to the cli docs

Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@fosiki.com> (github: SvenDowideit)

docs/sources/reference/commandline/cli.rst

@@ -148,9 +148,14 @@ TMPDIR and the data directory can be set like this:
       --no-stdin=false: Do not attach stdin
       --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
 
+The ``attach`` command will allow you to view or interact with any
+running container, detached (``-d``) or interactive (``-i``). You can
+attach to the same container at the same time - screen sharing style,
+or quickly view the progress of your daemonized process.
+
 You can detach from the container again (and leave it running) with
-``CTRL-c`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of
-the Docker client when it quits.  When you detach from the container's
+``CTRL-C`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of
+the Docker client when it quits. When you detach from the container's
 process the exit code will be returned to the client.
 
 To stop a container, use ``docker stop``.
@@ -211,6 +216,8 @@ Examples:
       --no-cache: Do not use the cache when building the image.
       --rm=true: Remove intermediate containers after a successful build
 
+Use this command to build Docker images from a ``Dockerfile`` and a "context".
+
 The files at ``PATH`` or ``URL`` are called the "context" of the build.
 The build process may refer to any of the files in the context, for example when
 using an :ref:`ADD <dockerfile_add>` instruction.
@@ -317,6 +324,12 @@ by using the ``git://`` schema.
       -m, --message="": Commit message
       -a, --author="": Author (eg. "John Hannibal Smith <hannibal@a-team.com>"
 
+It can be useful to commit a container's file changes or settings into a new image.
+This allows you debug a container by running an interactive shell, or to export
+a working dataset to another server.
+Generally, it is better to use Dockerfiles to manage your images in a documented
+and maintainable way.
+
 .. _cli_commit_examples:
 
 Commit an existing container
@@ -562,7 +575,7 @@ Listing the full length image IDs
     Create an empty filesystem image and import the contents of the tarball
     (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then optionally tag it.
 
-At this time, the URL must start with ``http`` and point to a single
+URLs must start with ``http`` and point to a single
 file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a
 root filesystem. If you would like to import from a local directory or
 archive, you can use the ``-`` parameter to take the data from *stdin*.
@@ -625,6 +638,8 @@ preserved.
 	Kernel Version: 3.8.0-33-generic
 	WARNING: No swap limit support
 
+When sending issue reports, please use ``docker version`` and ``docker info`` to
+ensure we know how your setup is configured.
 
 .. _cli_inspect:
 
@@ -788,10 +803,7 @@ Restores both images and tags.
 
     -f, --follow=false: Follow log output
 
-The ``docker logs`` command is a convenience which batch-retrieves whatever
-logs are present at the time of execution. This does not guarantee execution
-order when combined with a ``docker run`` (i.e. your run may not have generated
-any logs at the time you execute ``docker logs``).
+The ``docker logs`` command batch-retrieves all logs present at the time of execution.
 
 The ``docker logs --follow`` command combines ``docker logs`` and ``docker attach``:
 it will first return all logs from the beginning and then continue streaming
@@ -839,9 +851,6 @@ Running ``docker ps`` showing 2 linked containers.
     CONTAINER ID        IMAGE                        COMMAND                CREATED              STATUS              PORTS               NAMES
     4c01db0b339c        ubuntu:12.04                 bash                   17 seconds ago       Up 16 seconds                           webapp
     d7886598dbe2        crosbymichael/redis:latest   /redis-server --dir    33 minutes ago       Up 33 minutes       6379/tcp            redis,webapp/db
-    fd2645e2e2b5        busybox:latest               top                    10 days ago          Ghost                                   insane_ptolemy
-
-The last container is marked as a ``Ghost`` container. It is a container that was running when the docker daemon was restarted (upgraded, or ``-H`` settings changed). The container is still running, but as this docker daemon process is not able to manage it, you can't attach to it. To bring them out of ``Ghost`` Status, you need to use ``docker kill`` or ``docker restart``.
 
 ``docker ps`` will show only running containers by default.  To see all containers: ``docker ps -a``
 
@@ -856,6 +865,23 @@ The last container is marked as a ``Ghost`` container. It is a container that wa
 
     Pull an image or a repository from the registry
 
+Most of your images will be created on top of a base image from the
+<Docker Index>(https://index.docker.io).
+
+The Docker Index contains many pre-built images that you can ``pull`` and try 
+without needing to define and configure your own.
+
+To download a particular image, or set of images (i.e., a repository),
+use ``docker pull``:
+
+.. code-block:: bash
+
+    $ docker pull debian
+    # will pull all the images in the debian repository
+    $ docker pull debian:testing
+    # will pull only the image named debian:testing and any intermediate layers
+    # it is based on. (typically the empty `scratch` image, a MAINTAINERs layer,
+    # and the un-tared base.
 
 .. _cli_push:
 
@@ -868,6 +894,7 @@ The last container is marked as a ``Ghost`` container. It is a container that wa
 
     Push an image or a repository to the registry
 
+Use ``docker push`` to share your images on public or private registries.
 
 .. _cli_restart:
 
@@ -926,7 +953,7 @@ network communication.
 
 .. code-block:: bash
 
-    $ sudo docker rm `docker ps -a -q`
+    $ sudo docker rm $(docker ps -a -q)
 
 
 This command will delete all stopped containers. The command ``docker ps -a -q`` will return all
@@ -1022,7 +1049,8 @@ The ``docker run`` command first ``creates`` a writeable container layer over
 the specified image, and then ``starts`` it using the specified command. That
 is, ``docker run`` is equivalent to the API ``/containers/create`` then
 ``/containers/(id)/start``.
-Once the container is stopped it still exists and can be started back up.  See ``docker ps -a`` to view a list of all containers.
+A stopped container can be restarted with all its previous changes intact using 
+``docker start``. See ``docker ps -a`` to view a list of all containers.
 
 The ``docker run`` command can be used in combination with ``docker commit`` to
 :ref:`change the command that a container runs <cli_commit_examples>`.
@@ -1270,6 +1298,8 @@ This example shows 5 containers that might be set up to test a web application c
 Produces a tarred repository to the standard output stream.
 Contains all parent layers, and all tags + versions, or specified repo:tag.
 
+It is used to create a backup that can then be used with ``docker load``
+
 .. code-block:: bash
 
    $ sudo docker save busybox > busybox.tar
@@ -1297,6 +1327,9 @@ Contains all parent layers, and all tags + versions, or specified repo:tag.
      -s, --stars=0: Only displays with at least xxx stars
      -t, --trusted=false: Only show trusted builds
 
+See :ref:`searching_central_index` for more details on finding shared images
+from the commandline.
+
 .. _cli_start:
 
 ``start``
@@ -1339,6 +1372,9 @@ The main process inside the container will receive SIGTERM, and after a grace pe
 
       -f, --force=false: Force
 
+You can group your images together using names and
+tags, and then upload them to :ref:`working_with_the_repository`.
+
 .. _cli_top:
 
 ``top``