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/sources/reference/builder.md

@@ -331,13 +331,23 @@ default specified in `CMD`.
 ## LABEL
    LABEL <key>=<value> <key>=<value> <key>=<value> ...
 
- --The `LABEL` instruction allows you to describe the image your `Dockerfile`
-is building. `LABEL` is specified as name value pairs. This data can
+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
 
+    LABEL com.example.label-without-value
+    LABEL com.example.label-with-value="foo"
+    LABEL version="1.0"
+    LABEL description="This my ACME image" vendor="ACME Products"
 
-    LABEL Description="This image is used to start the foobar executable" Vendor="ACME Products"
-    LABEL Version="1.0"
+As illustrated above, 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.
+
+For example:
+
+    LABEL description="This text illustrates \
+    that label-values can span multiple lines."
 
 ## EXPOSE
 

docs/sources/reference/commandline/cli.md

@@ -814,6 +814,8 @@ Creates a new container.
       -h, --hostname=""          Container host name
       -i, --interactive=false    Keep STDIN open even if not attached
       --ipc=""                   IPC namespace to use
+      -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
       --lxc-conf=[]              Add custom lxc options
       -m, --memory=""            Memory limit
@@ -1166,6 +1168,7 @@ than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "b
 
 Current filters:
  * dangling (boolean - true or false)
+ * label (`label=<key>` or `label=<key>=<value>`)
 
 ##### Untagged images
 
@@ -1685,8 +1688,8 @@ removed before the image is removed.
       --link=[]                  Add link to another container
       --lxc-conf=[]              Add custom lxc options
       -m, --memory=""            Memory limit
-      -l, --label=[]             Set meta data on a container, for example com.example.key=value
-      -label-file=[]             Read in a line delimited file of labels
+      -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
       --mac-address=""           Container MAC address (e.g. 92:d0:c6:0a:29:33)
       --memory-swap=""           Total memory (memory + swap), '-1' to disable swap
       --name=""                  Assign a name to the container
@@ -1860,6 +1863,36 @@ An example of a file passed with `--env-file`
 This will create and run a new container with the container name being
 `console`.
 
+    $ sudo docker run -l my-label --env com.example.foo=bar ubuntu bash
+
+This sets two labels on the container. Label "my-label" doesn't have a value
+specified and will default to "" (empty string) for its value. Both `-l` and 
+`--env` can be repeated to add more labels. Label names are unique; if the same 
+label is specified multiple times, latter values overwrite the previous value.
+
+Labels can also be loaded from a line delimited file of labels using the 
+`--label-file` flag. The example below will load labels from a file named `labels`
+in the current directory;
+
+    $ sudo docker run --env-file ./labels ubuntu bash
+
+The format of the labels-file is similar to that used for loading environment
+variables (see `--env-file` above). An example of a file passed with `--env-file`;
+
+    $ cat ./labels
+    com.example.label1="a label"
+
+    # this is a comment
+    com.example.label2=another\ label
+    com.example.label3
+
+Multiple label-files can be loaded by providing the `--label-file` multiple 
+times.
+
+For additional information on working with labels, see 
+[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in
+the user guide.
+
     $ sudo docker run --link /redis:redis --name console ubuntu bash
 
 The `--link` flag will link the container named `/redis` into the newly