Merge pull request #6056 from ipbabble/master

Made fixes to man pages to remove some ambiguities and typos

contrib/man/md/docker-attach.1.md

@@ -9,10 +9,11 @@ docker-attach - Attach to a running container
 
 # DESCRIPTION
 If you **docker run** a container in detached mode (**-d**), you can reattach to
- the detached container with **docker attach** using the container's ID or name.
+the detached container with **docker attach** using the container's ID or name.
 
-You can detach from the container again (and leave it running) with `CTRL-c` (for
+You can detach from the container again (and leave it running) with `CTRL-q 
-a quiet exit) or `CTRL-\` to get a stacktrace of the Docker client when it quits.
+CTRL-q` (for a quiet exit), or `CTRL-c`  which will send a SIGKILL to the
+container, or `CTRL-\` to get a stacktrace of the Docker client when it quits.
 When you detach from a container the exit code will be returned to
 the client.
 

contrib/man/md/docker-build.1.md

@@ -34,8 +34,9 @@ as context.
 build process. The default is true.
 
 **-t**, **--tag**=*tag*
-   Tag to be applied to the resulting image on successful completion of
+   The name to be applied to the resulting image on successful completion of
-the build.
+the build. `tag` in this context means the entire image name including the 
+optional TAG after the ':'.
 
 **--no-cache**=*true*|*false*
    When set to true, do not use a cache when building the image. The
@@ -66,6 +67,40 @@ in the Dockerfile. Note: If you include a tar file (a good practice!), then
 Docker will automatically extract the contents of the tar file
 specified within the `ADD` instruction into the specified target.
 
+## Building an image and naming that image
+
+A good practice is to give a name to the image you are building. There are
+no hard rules here but it is best to give the names consideration. 
+
+The **-t**/**--tag** flag is used to rename an image. Here are some examples:
+
+Though it is not a good practice, image names can be arbtrary:
+
+    docker build -t myimage .
+
+A better approach is to provide a fully qualified and meaningful repository,
+name, and tag (where the tag in this context means the qualifier after 
+the ":"). In this example we build a JBoss image for the Fedora repository 
+and give it the version 1.0:
+
+    docker build -t fedora/jboss:1.0
+
+The next example is for the "whenry" user repository and uses Fedora and
+JBoss and gives it the version 2.1 :
+
+    docker build -t whenry/fedora-jboss:V2.1
+
+If you do not provide a version tag then Docker will assign `latest`:
+
+    docker build -t whenry/fedora-jboss
+
+When you list the images, the image above will have the tag `latest`.
+
+So renaming an image is arbitrary but consideration should be given to 
+a useful convention that makes sense for consumers and should also take
+into account Docker community conventions.
+
+
 ## Building an image using a URL
 
 This will clone the specified Github repository from the URL and use it

contrib/man/md/docker-run.1.md

@@ -64,6 +64,9 @@ the other shell to view a list of the running containers. You can reattach to a
 detached container with **docker attach**. If you choose to run a container in
 the detached mode, then you cannot use the **-rm** option.
 
+   When attached in the tty mode, you can detach from a running container without
+stopping the process by pressing the keys CTRL-P CTRL-Q.
+
 
 **--dns**=*IP-address*
    Set custom DNS servers. This option can be used to override the DNS
@@ -237,7 +240,7 @@ can override the working directory by using the **-w** option.
 ## Exposing log messages from the container to the host's log
 
 If you want messages that are logged in your container to show up in the host's
-syslog/journal then you should bind mount the /var/log directory as follows.
+syslog/journal then you should bind mount the /dev/log directory as follows.
 
     # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
 

contrib/man/md/docker-tag.1.md

@@ -9,11 +9,12 @@ docker-tag - Tag an image in the repository
 IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG]
 
 # DESCRIPTION
-This will tag an image in the repository.
+This will give a new alias to an image in the repository. This refers to the
+entire image name including the optional TAG after the ':'. 
 
 # "OPTIONS"
 **-f**, **--force**=*true*|*false*
-   When set to true, force the tag name. The default is *false*.
+   When set to true, force the alias. The default is *false*.
 
 **REGISTRYHOST**
    The hostname of the registry if required. This may also include the port
@@ -26,13 +27,16 @@ separated by a ':'
    The image name.
 
 **TAG**
-   The tag you are assigning to the image.
+   The tag you are assigning to the image.  Though this is arbitrary it is
+recommended to be used for a version to disinguish images with the same name.
+Note that here TAG is a part of the overall name or "tag".
 
 # EXAMPLES
 
-## Tagging an image
+## Giving an image a new alias
 
-Here is an example of tagging an image with the tag version1.0 :
+Here is an example of aliasing an image (e.g. 0e5574283393) as "httpd" and 
+tagging it into the "fedora" repository with "version1.0":
 
     docker tag 0e5574283393 fedora/httpd:version1.0