Merge pull request #3103 from metalivedev/1229-titleactions

Update "Use" titles to be action-oriented

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
+to containers. The ``docker0`` bridge interface is managed by Docker
-for this purpose. Thus, when the Docker daemon starts it :
+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 
+At runtime, a :ref:`specific kind of virtual
-given to each containers which is then bonded to the ``docker0`` bridge. 
+interface<vethxxxx-device>` is given to each containers which is then
-Each containers also receives a dedicated IP address from the same range 
+bonded to the ``docker0`` bridge.  Each containers also receives a
-as ``docker0``. The ``docker0`` IP address is then used as the default 
+dedicated IP address from the same range as ``docker0``. The
-gateway for the containers.
+``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
+Above, ``docker0`` acts as a bridge for the ``vethQCDY1N`` interface
-to the 52f811c5d3d6 container.
+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 
+Docker will try hard to find an IP range which is not used by the
-your own one using the ``-b=<bridgename>`` parameter.
+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 
+Under the hood, ``iptables`` is used by Docker to either accept or
-between containers.
+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 
+The ``vethXXXX`` interface is the host side of a point-to-point link
-host and the corresponding container, the other side of the link being
+between the host and the corresponding container, the other side of
-materialized by the container's ``eth0`` interface. This pair (host ``vethXXX`` and 
+the link being materialized by the container's ``eth0``
-container ``eth0``) are connected like a tube. Everything that comes in one side will
+interface. This pair (host ``vethXXX`` and container ``eth0``) are
-come out the other side.
+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
+All the plumbing is delegated to Linux network capabilities (check the
-command) and the namespaces infrastructure.
+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
+:title: Link Containers
-:description: How to create and use links and names
+: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
+From version 0.6.5 you are now able to ``name`` a container and
-container by referring to its name. This will create a parent -> child relationship
+``link`` it to another container by referring to its name. This will
-where the parent container can see selected information about its child.
+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
+You can now name your container by using the ``-name`` flag. If no
-will automatically generate a name. You can see this name using the ``docker ps`` command.
+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
+Links allow containers to discover and securely communicate with each
-flag ``-link name:alias``. Inter-container communication can be disabled with the daemon
+other by using the flag ``-link name:alias``. Inter-container
-flag ``-icc=false``. With this flag set to ``false``, Container A cannot access Container B
+communication can be disabled with the daemon flag
-unless explicitly allowed via a link. This is a huge win for securing your containers.
+``-icc=false``. With this flag set to ``false``, Container A cannot
-When two containers are linked together Docker creates a parent child relationship
+access Container B unless explicitly allowed via a link. This is a
-between the containers. The parent container will be able to access information via
+huge win for securing your containers.  When two containers are linked
-environment variables of the child such as name, exposed ports, IP and other selected
+together Docker creates a parent child relationship between the
-environment variables.
+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
+When linking two containers Docker will use the exposed ports of the
-a secure tunnel for the parent to access. If a database container only exposes port 8080
+container to create a secure tunnel for the parent to access. If a
-then the linked container will only be allowed to access port 8080 and nothing else if
+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,
+We can issue all the commands that you would expect using the name
-attach, using the name for our container. The name also allows us to link other containers
+``redis``; start, stop, attach, using the name for our container. The
-into this one.
+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
+Next, we can start a new web application that has a dependency on
-to connect both containers. If you noticed when running our Redis server we did not use
+Redis and apply a link to connect both containers. If you noticed when
-the ``-p`` flag to publish the Redis port to the host system. Redis exposed port 6379 and
+running our Redis server we did not use the ``-p`` flag to publish the
-this is all we need to establish a link.
+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``
+When you specified ``-link redis:db`` you are telling Docker to link
-into this new container with the alias ``db``. Environment variables are prefixed with the alias
+the container named ``redis`` into this new container with the alias
-so that the parent container can access network and environment information from the containers
+``db``. Environment variables are prefixed with the alias so that the
-that are linked into it.
+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
+If we inspect the environment variables of the second container, we
-about the child container.
+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
+Accessing the network information along with the environment of the
-us to easily connect to the Redis service on the specific IP and port in the environment.
+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