Add labels documentation

Adds more documentation for labels and adds the label instruction to the
man-pages.

Also included is a document called "Labels - custom meta-data in Docker"
in the user-guide, this is still a work-in-progress I started to describe
the "namespaces" conventions, an example on storing structured data.

I ran a bit "out of steam" (writers block?) on that document, but kept
it in (for now), in case it still ends up useful.

The Remote API documentation changes will need to be moved to the
docker_remote_api_v1.18.md document when rebasing the whole PR.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Darren Shepherd <darren@rancher.com>

docs/man/Dockerfile.5.md

@@ -143,6 +143,18 @@ A Dockerfile is similar to a Makefile.
   **CMD** executes nothing at build time, but specifies the intended command for
   the image.
 
+**LABEL**
+ --**LABEL <key>[=<value>] [<key>[=<value>] ...]**
+
+ The **LABEL** instruction allows you to add meta-data to the image your 
+ Dockerfile is building. LABEL is specified as name value pairs. This data can
+ be retrieved using the `docker inspect` command.
+
+ The LABEL instruction allows for multiple labels to be set at one time. Like 
+ command line parsing, quotes and backslashes can be used to include spaces 
+ within values.
+
+
 **EXPOSE**
   -- `EXPOSE <port> [<port>...]`
   The **EXPOSE** instruction informs Docker that the container listens on the

docs/man/docker-create.1.md

@@ -24,6 +24,8 @@ docker-create - Create a new container
 [**--help**]
 [**-i**|**--interactive**[=*false*]]
 [**--ipc**[=*IPC*]]
+[**-l**|**--label**[=*[]*]]
+[**--label-file**[=*[]*]]
 [**--link**[=*[]*]]
 [**--lxc-conf**[=*[]*]]
 [**-m**|**--memory**[=*MEMORY*]]
@@ -102,6 +104,12 @@ IMAGE [COMMAND] [ARG...]
                                'container:<name|id>': reuses another container shared memory, semaphores and message queues
                                'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
 
+**-l**, **--label**=[]
+   Set meta data on the container (e.g., --label=com.example.key=value)
+
+**--label-file**=[]
+   Read in a line delimited file of labels
+
 **--link**=[]
    Add link to another container in the form of <name or id>:alias
 

docs/man/docker-images.1.md

@@ -34,7 +34,9 @@ versions.
    Show all images (by default filter out the intermediate image layers). The default is *false*.
 
 **-f**, **--filter**=[]
-   Provide filter values (i.e., 'dangling=true')
+   Provide filter values. Valid filters:
+                          dangling=true - unlabeled images with no children
+                          label=<key> or label=<key>=<value>
 
 **--help**
   Print usage statement

docs/man/docker-inspect.1.md

@@ -83,6 +83,11 @@ To get information on a container use it's ID or instance name:
             "Ghost": false
         },
         "Image": "df53773a4390e25936f9fd3739e0c0e60a62d024ea7b669282b27e65ae8458e6",
+        "Labels": {
+            "com.example.vendor": "Acme",
+            "com.example.license": "GPL",
+            "com.example.version": "1.0"
+        },
         "NetworkSettings": {
             "IPAddress": "172.17.0.2",
             "IPPrefixLen": 16,

docs/man/docker-ps.1.md

@@ -36,6 +36,7 @@ the running containers.
 **-f**, **--filter**=[]
    Provide filter values. Valid filters:
                           exited=<int> - containers with exit code of <int>
+                          label=<key> or label=<key>=<value>
                           status=(restarting|running|paused|exited)
                           name=<string> - container's name
                           id=<ID> - container's ID

docs/man/docker-run.1.md

@@ -25,6 +25,8 @@ docker-run - Run a command in a new container
 [**--help**]
 [**-i**|**--interactive**[=*false*]]
 [**--ipc**[=*IPC*]]
+[**-l**|**--label**[=*[]*]]
+[**--label-file**[=*[]*]]
 [**--link**[=*[]*]]
 [**--lxc-conf**[=*[]*]]
 [**-m**|**--memory**[=*MEMORY*]]
@@ -197,6 +199,12 @@ ENTRYPOINT.
                                'container:<name|id>': reuses another container shared memory, semaphores and message queues
                                'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
 
+**-l**, **--label**=[]
+   Set meta data on the container (e.g., --label=com.example.key=value)
+
+**--label-file**=[]
+   Read in a line delimited file of labels
+
 **--link**=[]
    Add link to another container in the form of <name or id>:alias