Improve the way we deliver Examples in command line. (Add descriptive titles)

Signed-off-by: Jian Zhang <zhangjian.fnst@cn.fujitsu.com>

docs/reference/commandline/build.md

@@ -128,6 +128,8 @@ See also:
 
 ## Examples
 
+### Build with PATH
+
     $ docker build .
     Uploading context 10240 bytes
     Step 1 : FROM busybox
@@ -168,6 +170,31 @@ The transfer of context from the local machine to the Docker daemon is what the
 If you wish to keep the intermediate containers after the build is complete,
 you must use `--rm=false`. This does not affect the build cache.
 
+### Build with URL
+
+    $ docker build github.com/creack/docker-firefox
+
+This will clone the GitHub repository and use the cloned repository as context.
+The Dockerfile at the root of the repository is used as Dockerfile. Note that
+you can specify an arbitrary Git repository by using the `git://` or `git@`
+schema.
+
+### Build with -
+
+    $ docker build - < Dockerfile
+
+This will read a Dockerfile from `STDIN` without context. Due to the lack of a
+context, no contents of any local directory will be sent to the Docker daemon.
+Since there is no context, a Dockerfile `ADD` only works if it refers to a
+remote URL.
+
+    $ docker build - < context.tar.gz
+
+This will build an image for a compressed context read from `STDIN`.  Supported
+formats are: bzip2, gzip and xz.
+
+### Usage of .dockerignore
+
     $ docker build .
     Uploading context 18.829 MB
     Uploading context
@@ -193,29 +220,14 @@ directory from the context. Its effect can be seen in the changed size of the
 uploaded context. The builder reference contains detailed information on
 [creating a .dockerignore file](../builder.md#dockerignore-file)
 
+### Tag image (-t)
+
     $ docker build -t vieux/apache:2.0 .
 
 This will build like the previous example, but it will then tag the resulting
 image. The repository name will be `vieux/apache` and the tag will be `2.0`
 
-    $ docker build - < Dockerfile
-
-This will read a Dockerfile from `STDIN` without context. Due to the lack of a
-context, no contents of any local directory will be sent to the Docker daemon.
-Since there is no context, a Dockerfile `ADD` only works if it refers to a
-remote URL.
-
-    $ docker build - < context.tar.gz
-
-This will build an image for a compressed context read from `STDIN`.  Supported
-formats are: bzip2, gzip and xz.
-
-    $ docker build github.com/creack/docker-firefox
-
-This will clone the GitHub repository and use the cloned repository as context.
-The Dockerfile at the root of the repository is used as Dockerfile. Note that
-you can specify an arbitrary Git repository by using the `git://` or `git@`
-schema.
+### Specify Dockerfile (-f)
 
     $ docker build -f Dockerfile.debug .
 
@@ -248,14 +260,20 @@ the command line.
 > repeatable builds on remote Docker hosts. This is also the reason why
 > `ADD ../file` will not work.
 
+### Optional parent cgroup (--cgroup-parent)
+
 When `docker build` is run with the `--cgroup-parent` option the containers
 used in the build will be run with the [corresponding `docker run`
 flag](../run.md#specifying-custom-cgroups).
 
+### Set ulimits in container (--ulimit)
+
 Using the `--ulimit` option with `docker build` will cause each build step's
 container to be started using those [`--ulimit`
 flag values](../run.md#setting-ulimits-in-a-container).
 
+### Set build-time variables (--build-arg)
+
 You can use `ENV` instructions in a Dockerfile to define variable
 values. These values persist in the built image. However, often
 persistence is not what you want. Users want to specify variables differently
@@ -263,7 +281,7 @@ depending on which host they build an image on.
 
 A good example is `http_proxy` or source versions for pulling intermediate
 files. The `ARG` instruction lets Dockerfile authors define values that users
-can set at build-time using the  `---build-arg` flag:
+can set at build-time using the  `--build-arg` flag:
 
     $ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .
 

docs/reference/commandline/run.md

@@ -92,6 +92,8 @@ and linking containers.
 
 ## Examples
 
+### Assign name and allocate psuedo-TTY (--name, -it)
+
     $ docker run --name test -it debian
     root@d6c0fe130dba:/# exit 13
     $ echo $?
@@ -106,6 +108,8 @@ In the example, the `bash` shell is quit by entering
 `exit 13`. This exit code is passed on to the caller of
 `docker run`, and is recorded in the `test` container's metadata.
 
+### Capture container ID (--cidfile)
+
     $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
 
 This will create a container and print `test` to the console. The `cidfile`
@@ -113,6 +117,8 @@ flag makes Docker attempt to create a new file and write the container ID to it.
 If the file exists already, Docker will return an error. Docker will close this
 file when `docker run` exits.
 
+### Full container capabilities (--privileged)
+
     $ docker run -t -i --rm ubuntu bash
     root@bc338942ef20:/# mount -t tmpfs none /mnt
     mount: permission denied
@@ -132,11 +138,15 @@ lifts all the limitations enforced by the `device` cgroup controller. In other
 words, the container can then do almost everything that the host can do. This
 flag exists to allow special use-cases, like running Docker within Docker.
 
+### Set working directory (-w)
+
     $ docker  run -w /path/to/dir/ -i -t  ubuntu pwd
 
 The `-w` lets the command being executed inside directory given, here
 `/path/to/dir/`. If the path does not exists it is created inside the container.
 
+### Mount volume (-v, --read-only)
+
     $ docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
 
 The `-v` flag mounts the current working directory into the container. The `-w`
@@ -166,6 +176,8 @@ binary (such as that provided by [https://get.docker.com](
 https://get.docker.com)), you give the container the full access to create and
 manipulate the host's Docker daemon.
 
+### Publish or expose port (-p, --expose)
+
     $ docker run -p 127.0.0.1:80:8080 ubuntu bash
 
 This binds port `8080` of the container to port `80` on `127.0.0.1` of
@@ -179,6 +191,8 @@ publishing the port to the host system's interfaces. The [Docker User
 Guide](../../userguide/dockerlinks.md) explains in detail how to manipulate
 ports in Docker.
 
+### Set environment variables (-e, --env, --env-file)
+
     $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
 
 This sets environmental variables in the container. For illustration all three
@@ -247,7 +261,9 @@ An example of a file passed with `--env-file`
     123qwe=bar
     org.spring.config=something
 
-A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels:
+### Set metadata on container (-l, --label, --label-file)
+
+A label is a `key=value` pair that applies metadata to a container. To label a container with two labels:
 
     $ docker run -l my-label --label com.example.foo=bar ubuntu bash
 
@@ -281,6 +297,8 @@ For additional information on working with labels, see [*Labels - custom
 metadata in Docker*](../../userguide/labels-custom-metadata.md) in the Docker User
 Guide.
 
+### Add link to another container (--link)
+
     $ docker run --link /redis:redis --name console ubuntu bash
 
 The `--link` flag will link the container named `/redis` into the newly
@@ -295,6 +313,8 @@ example as:
 The `--name` flag will assign the name `console` to the newly created
 container.
 
+### Mount volumes from container (--volumes-from)
+
     $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
 
 The `--volumes-from` flag mounts all the defined volumes from the referenced
@@ -317,6 +337,8 @@ content label. Shared volume labels allow all containers to read/write content.
 The `Z` option tells Docker to label the content with a private unshared label.
 Only the current container can use a private volume.
 
+### Attach to STDIN/STDOUT/STDERR (-a)
+
 The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT`
 or `STDERR`. This makes it possible to manipulate the output and input as
 needed.
@@ -340,6 +362,8 @@ logs could be retrieved using `docker logs`. This is
 useful if you need to pipe a file or something else into a container and
 retrieve the container's ID once the container has finished running.
 
+### Add host device to container (--device)
+
     $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo}
     brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
     brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
@@ -375,38 +399,7 @@ flag:
 > that may be removed should not be added to untrusted containers with
 > `--device`.
 
-**A complete example:**
-
-    $ docker run -d --name static static-web-files sh
-    $ docker run -d --expose=8098 --name riak riakserver
-    $ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
-    $ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver
-    $ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
-
-This example shows five containers that might be set up to test a web
-application change:
-
-1. Start a pre-prepared volume image `static-web-files` (in the background)
-   that has CSS, image and static HTML in it, (with a `VOLUME` instruction in
-   the Dockerfile to allow the web server to use those files);
-2. Start a pre-prepared `riakserver` image, give the container name `riak` and
-   expose port `8098` to any containers that link to it;
-3. Start the `appserver` image, restricting its memory usage to 100MB, setting
-   two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the
-   current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`;
-4. Start the `webserver`, mapping port `443` in the container to port `1443` on
-   the Docker server, setting the DNS server to `10.0.0.1` and DNS search
-   domain to `dev.org`, creating a volume to put the log files into (so we can
-   access it from another container), then importing the files from the volume
-   exposed by the `static` container, and linking to all exposed ports from
-   `riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its
-   consistent with the pre-generated SSL certificate;
-5. Finally, we create a container that runs `tail -f access.log` using the logs
-   volume from the `web` container, setting the workdir to `/var/log/httpd`. The
-   `--rm` option means that when the container exits, the container's layer is
-   removed.
-
-## Restart policies
+### Restart policies (--restart)
 
 Use Docker's `--restart` to specify a container's *restart policy*. A restart
 policy controls whether the Docker daemon restarts a container after exit.
@@ -468,7 +461,7 @@ More detailed information on restart policies can be found in the
 [Restart Policies (--restart)](../run.md#restart-policies-restart)
 section of the Docker run reference page.
 
-## Adding entries to a container hosts file
+### Add entries to container hosts file (--add-host)
 
 You can add other hosts into a container's `/etc/hosts` file by using one or
 more `--add-host` flags. This example adds a static address for a host named
@@ -499,7 +492,7 @@ For IPv6 use the `-6` flag instead of the `-4` flag. For other network
 devices, replace `eth0` with the correct device name (for example `docker0`
 for the bridge device).
 
-### Setting ulimits in a container
+### Set ulimits in container (--ulimit)
 
 Since setting `ulimit` settings in a container requires extra privileges not
 available in the default container, you can set these using the `--ulimit` flag.
@@ -519,13 +512,12 @@ available in the default container, you can set these using the `--ulimit` flag.
 The values are sent to the appropriate `syscall` as they are set.
 Docker doesn't perform any byte conversion. Take this into account when setting the values.
 
-#### For `nproc` usage:
+#### For `nproc` usage
 
 Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the
 maximum number of processes available to a user, not to a container.  For example, start four
 containers with `daemon` user:
 
-
     docker run -d -u daemon --ulimit nproc=3 busybox top
     docker run -d -u daemon --ulimit nproc=3 busybox top
     docker run -d -u daemon --ulimit nproc=3 busybox top
@@ -535,8 +527,39 @@ The 4th container fails and reports "[8] System error: resource temporarily unav
 This fails because the caller set `nproc=3` resulting in the first three containers using up
 the three processes quota set for the `daemon` user.
 
-### Stopping a container with a specific signal
+### Stop container with signal (--stop-signal)
 
 The `--stop-signal` flag sets the system call signal that will be sent to the container to exit.
 This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
 or a signal name in the format SIGNAME, for instance SIGKILL.
+
+### A complete example
+
+    $ docker run -d --name static static-web-files sh
+    $ docker run -d --expose=8098 --name riak riakserver
+    $ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
+    $ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver
+    $ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
+
+This example shows five containers that might be set up to test a web
+application change:
+
+1. Start a pre-prepared volume image `static-web-files` (in the background)
+   that has CSS, image and static HTML in it, (with a `VOLUME` instruction in
+   the Dockerfile to allow the web server to use those files);
+2. Start a pre-prepared `riakserver` image, give the container name `riak` and
+   expose port `8098` to any containers that link to it;
+3. Start the `appserver` image, restricting its memory usage to 100MB, setting
+   two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the
+   current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`;
+4. Start the `webserver`, mapping port `443` in the container to port `1443` on
+   the Docker server, setting the DNS server to `10.0.0.1` and DNS search
+   domain to `dev.org`, creating a volume to put the log files into (so we can
+   access it from another container), then importing the files from the volume
+   exposed by the `static` container, and linking to all exposed ports from
+   `riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its
+   consistent with the pre-generated SSL certificate;
+5. Finally, we create a container that runs `tail -f access.log` using the logs
+   volume from the `web` container, setting the workdir to `/var/log/httpd`. The
+   `--rm` option means that when the container exits, the container's layer is
+   removed.