Fix #1229. Update titles, fix some wrapping.

Make the Ambassador container explicit.
Apply Sven's suggestions.

docs/sources/use/ambassador_pattern_linking.rst

@@ -1,11 +1,11 @@
-:title: Ambassador pattern linking
+:title: Link via an Ambassador Container
 :description: Using the Ambassador pattern to abstract (network) services
 :keywords: Examples, Usage, links, docker, documentation, examples, names, name, container naming
 
 .. _ambassador_pattern_linking:
 
-Ambassador pattern linking
-==========================
+Link via an Ambassador Container
+================================
 
 Rather than hardcoding network links between a service consumer and provider, Docker
 encourages service portability.

docs/sources/use/baseimages.rst

@@ -1,10 +1,10 @@
-:title: Base Image Creation
+:title: Create a Base Image
 :description: How to create base images
 :keywords: Examples, Usage, base image, docker, documentation, examples
 
 .. _base_image_creation:
 
-Base Image Creation
+Create a Base Image
 ===================
 
 So you want to create your own :ref:`base_image_def`? Great!

docs/sources/use/basics.rst

@@ -1,10 +1,10 @@
-:title: Basic Commands
+:title: Learn Basic Commands
 :description: Common usage and commands
 :keywords: Examples, Usage, basic commands, docker, documentation, examples
 
 
-The Basics
-==========
+Learn Basic Commands
+====================
 
 Starting Docker
 ---------------

docs/sources/use/builder.rst

@@ -1,12 +1,12 @@
-:title: Dockerfiles for Images
+:title: Build Images (Dockerfile Reference)
 :description: Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image.
 :keywords: builder, docker, Dockerfile, automation, image creation
 
 .. _dockerbuilder:
 
-======================
-Dockerfiles for Images
-======================
+===================================
+Build Images (Dockerfile Reference)
+===================================
 
 **Docker can act as a builder** and read instructions from a text
 ``Dockerfile`` to automate the steps you would otherwise take manually

docs/sources/use/host_integration.rst

@@ -1,11 +1,11 @@
-:title: Host Integration
+:title: Automatically Start Containers
 :description: How to generate scripts for upstart, systemd, etc.
 :keywords: systemd, upstart, supervisor, docker, documentation, host integration
 
 
 
-Host Integration
-================
+Automatically Start Containers
+==============================
 
 You can use your Docker containers with process managers like ``upstart``,
 ``systemd`` and ``supervisor``.

docs/sources/use/index.rst

@@ -17,9 +17,9 @@ Contents:
    workingwithrepository
    baseimages
    port_redirection
-   puppet
    networking
    host_integration
    working_with_volumes
    working_with_links_names
    ambassador_pattern_linking
+   puppet

docs/sources/use/networking.rst

@@ -1,14 +1,14 @@
-:title: Docker networking
+:title: Configure Networking
 :description: Docker networking
 :keywords: network, networking, bridge, docker, documentation
 
 
-Networking
-==========
+Configure Networking
+====================
 
-Docker uses Linux bridge capabilities to provide network connectivity 
-to containers. The ``docker0`` bridge interface is managed by Docker itself
-for this purpose. Thus, when the Docker daemon starts it :
+Docker uses Linux bridge capabilities to provide network connectivity
+to containers. The ``docker0`` bridge interface is managed by Docker
+itself for this purpose. Thus, when the Docker daemon starts it :
 
 - creates the ``docker0`` bridge if not present
 - searches for an IP address range which doesn't overlap with an existing route
@@ -30,11 +30,12 @@ for this purpose. Thus, when the Docker daemon starts it :
 
 
 
-At runtime, a :ref:`specific kind of virtual interface<vethxxxx-device>` is 
-given to each containers which is then bonded to the ``docker0`` bridge. 
-Each containers also receives a dedicated IP address from the same range 
-as ``docker0``. The ``docker0`` IP address is then used as the default 
-gateway for the containers.
+At runtime, a :ref:`specific kind of virtual
+interface<vethxxxx-device>` is given to each containers which is then
+bonded to the ``docker0`` bridge.  Each containers also receives a
+dedicated IP address from the same range as ``docker0``. The
+``docker0`` IP address is then used as the default gateway for the
+containers.
 
 .. code-block:: bash
 
@@ -47,18 +48,19 @@ gateway for the containers.
     docker0		8000.fef213db5a66	no		vethQCDY1N
 
 
-Above, ``docker0`` acts as a bridge for the ``vethQCDY1N`` interface which is dedicated
-to the 52f811c5d3d6 container.
+Above, ``docker0`` acts as a bridge for the ``vethQCDY1N`` interface
+which is dedicated to the 52f811c5d3d6 container.
 
 
 How to use a specific IP address range
 ---------------------------------------
-Docker will try hard to find an IP range which is not used by the host. 
-Even if it works for most cases, it's not bullet-proof and sometimes you need 
-to have more control over the IP addressing scheme.
 
-For this purpose, Docker allows you to manage the ``docker0`` bridge or 
-your own one using the ``-b=<bridgename>`` parameter.
+Docker will try hard to find an IP range which is not used by the
+host.  Even if it works for most cases, it's not bullet-proof and
+sometimes you need to have more control over the IP addressing scheme.
+
+For this purpose, Docker allows you to manage the ``docker0`` bridge
+or your own one using the ``-b=<bridgename>`` parameter.
 
 In this scenario:
 
@@ -115,14 +117,15 @@ In this scenario:
     
 Container intercommunication
 -------------------------------
-Containers can communicate with each other according to the ``icc`` parameter 
-value of the Docker daemon.
+
+Containers can communicate with each other according to the ``icc``
+parameter value of the Docker daemon.
 
 - The default, ``-icc=true`` allows containers to communicate with each other.
 - ``-icc=false`` means containers are isolated from each other.
 
-Under the hood, ``iptables`` is used by Docker to either accept or drop communication 
-between containers.
+Under the hood, ``iptables`` is used by Docker to either accept or
+drop communication between containers.
 
 
 .. _vethxxxx-device:
@@ -131,17 +134,20 @@ What's about the vethXXXX device?
 -----------------------------------
 Well. Things get complicated here.
 
-The ``vethXXXX`` interface is the host side of a point-to-point link between the 
-host and the corresponding container, the other side of the link being
-materialized by the container's ``eth0`` interface. This pair (host ``vethXXX`` and 
-container ``eth0``) are connected like a tube. Everything that comes in one side will
-come out the other side.
+The ``vethXXXX`` interface is the host side of a point-to-point link
+between the host and the corresponding container, the other side of
+the link being materialized by the container's ``eth0``
+interface. This pair (host ``vethXXX`` and container ``eth0``) are
+connected like a tube. Everything that comes in one side will come out
+the other side.
 
-All the plumbing is delegated to Linux network capabilities (check the ip link
-command) and the namespaces infrastructure.
+All the plumbing is delegated to Linux network capabilities (check the
+ip link command) and the namespaces infrastructure.
 
 
 I want more
 ------------
-Jérôme Petazzoni has create ``pipework`` to connect together containers in 
-arbitrarily complex scenarios : https://github.com/jpetazzo/pipework
+
+Jérôme Petazzoni has create ``pipework`` to connect together
+containers in arbitrarily complex scenarios :
+https://github.com/jpetazzo/pipework

docs/sources/use/port_redirection.rst

@@ -1,12 +1,12 @@
-:title: Port redirection
+:title: Redirect Ports
 :description: usage about port redirection
 :keywords: Usage, basic port, docker, documentation, examples
 
 
 .. _port_redirection:
 
-Port redirection
-================
+Redirect Ports
+==============
 
 Interacting with a service is commonly done through a connection to a
 port. When this service runs inside a container, one can connect to

docs/sources/use/working_with_links_names.rst

@@ -1,15 +1,16 @@
-:title: Working with Links and Names
-:description: How to create and use links and names
+:title: Link Containers
+:description: How to create and use both links and names
 :keywords: Examples, Usage, links, linking, docker, documentation, examples, names, name, container naming
 
 .. _working_with_links_names:
 
-Working with Links and Names
-============================
+Link Containers
+===============
 
-From version 0.6.5 you are now able to ``name`` a container and ``link`` it to another
-container by referring to its name. This will create a parent -> child relationship
-where the parent container can see selected information about its child.
+From version 0.6.5 you are now able to ``name`` a container and
+``link`` it to another container by referring to its name. This will
+create a parent -> child relationship where the parent container can
+see selected information about its child.
 
 .. _run_name:
 
@@ -18,8 +19,9 @@ Container Naming
 
 .. versionadded:: v0.6.5
 
-You can now name your container by using the ``-name`` flag. If no name is provided, Docker
-will automatically generate a name. You can see this name using the ``docker ps`` command.
+You can now name your container by using the ``-name`` flag. If no
+name is provided, Docker will automatically generate a name. You can
+see this name using the ``docker ps`` command.
 
 .. code-block:: bash
 
@@ -38,18 +40,21 @@ Links: service discovery for docker
 
 .. versionadded:: v0.6.5
 
-Links allow containers to discover and securely communicate with each other by using the
-flag ``-link name:alias``. Inter-container communication can be disabled with the daemon
-flag ``-icc=false``. With this flag set to ``false``, Container A cannot access Container B
-unless explicitly allowed via a link. This is a huge win for securing your containers.
-When two containers are linked together Docker creates a parent child relationship
-between the containers. The parent container will be able to access information via
-environment variables of the child such as name, exposed ports, IP and other selected
-environment variables.
-
-When linking two containers Docker will use the exposed ports of the container to create
-a secure tunnel for the parent to access. If a database container only exposes port 8080
-then the linked container will only be allowed to access port 8080 and nothing else if
+Links allow containers to discover and securely communicate with each
+other by using the flag ``-link name:alias``. Inter-container
+communication can be disabled with the daemon flag
+``-icc=false``. With this flag set to ``false``, Container A cannot
+access Container B unless explicitly allowed via a link. This is a
+huge win for securing your containers.  When two containers are linked
+together Docker creates a parent child relationship between the
+containers. The parent container will be able to access information
+via environment variables of the child such as name, exposed ports, IP
+and other selected environment variables.
+
+When linking two containers Docker will use the exposed ports of the
+container to create a secure tunnel for the parent to access. If a
+database container only exposes port 8080 then the linked container
+will only be allowed to access port 8080 and nothing else if
 inter-container communication is set to false.
 
 For example, there is an image called ``crosbymichael/redis`` that exposes the
@@ -60,26 +65,28 @@ based on that image and run it as daemon.
 
     $ sudo docker run -d -name redis crosbymichael/redis
 
-We can issue all the commands that you would expect using the name ``redis``; start, stop,
-attach, using the name for our container. The name also allows us to link other containers
-into this one.
+We can issue all the commands that you would expect using the name
+``redis``; start, stop, attach, using the name for our container. The
+name also allows us to link other containers into this one.
 
-Next, we can start a new web application that has a dependency on Redis and apply a link
-to connect both containers. If you noticed when running our Redis server we did not use
-the ``-p`` flag to publish the Redis port to the host system. Redis exposed port 6379 and
-this is all we need to establish a link.
+Next, we can start a new web application that has a dependency on
+Redis and apply a link to connect both containers. If you noticed when
+running our Redis server we did not use the ``-p`` flag to publish the
+Redis port to the host system. Redis exposed port 6379 and this is all
+we need to establish a link.
 
 .. code-block:: bash
 
     $ sudo docker run -t -i -link redis:db -name webapp ubuntu bash
 
-When you specified ``-link redis:db`` you are telling Docker to link the container named ``redis``
-into this new container with the alias ``db``. Environment variables are prefixed with the alias
-so that the parent container can access network and environment information from the containers
-that are linked into it.
+When you specified ``-link redis:db`` you are telling Docker to link
+the container named ``redis`` into this new container with the alias
+``db``. Environment variables are prefixed with the alias so that the
+parent container can access network and environment information from
+the containers that are linked into it.
 
-If we inspect the environment variables of the second container, we would see all the information
-about the child container.
+If we inspect the environment variables of the second container, we
+would see all the information about the child container.
 
 .. code-block:: bash
 
@@ -101,10 +108,12 @@ about the child container.
     _=/usr/bin/env
     root@4c01db0b339c:/#
 
-Accessing the network information along with the environment of the child container allows
-us to easily connect to the Redis service on the specific IP and port in the environment.
+Accessing the network information along with the environment of the
+child container allows us to easily connect to the Redis service on
+the specific IP and port in the environment.
 
-Running ``docker ps`` shows the 2 containers, and the ``webapp/db`` alias name for the redis container.
+Running ``docker ps`` shows the 2 containers, and the ``webapp/db``
+alias name for the redis container.
 
 .. code-block:: bash
 

docs/sources/use/working_with_volumes.rst

@@ -1,11 +1,11 @@
-:title: Working with Volumes
+:title: Share Directories via Volumes
 :description: How to create and share volumes
 :keywords: Examples, Usage, volume, docker, documentation, examples
 
 .. _volume_def:
 
-Data Volume
-===========
+Share Directories via Volumes
+=============================
 
 .. versionadded:: v0.3.0
    Data volumes have been available since version 1 of the

docs/sources/use/workingwithrepository.rst

@@ -1,11 +1,11 @@
-:title: Working With Repositories
+:title: Share Images via Repositories
 :description: Repositories allow users to share images.
 :keywords: repo, repositories, usage, pull image, push image, image, documentation
 
 .. _working_with_the_repository:
 
-Working with Repositories
-=========================
+Share Images via Repositories
+=============================
 
 A *repository* is a hosted collection of tagged :ref:`images
 <image_def>` that together create the file system for a container. The