Documentation changes for labels

Signed-off-by: Darren Shepherd <darren@rancher.com>

docs/sources/reference/builder.md

@@ -329,26 +329,26 @@ default specified in `CMD`.
 > the intended command for the image.
 
 ## LABEL
+
     LABEL <key>=<value> <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 adds metadata to an image. A `LABEL` is a
+key-value pair. To include spaces within a `LABEL` value, use quotes and
+blackslashes as you would in command-line parsing.
+
+    LABEL "com.example.vendor"="ACME Incorporated"
+
+An image can have more than one label. To specify multiple labels, separate each
+key-value pair by an EOL.
 
     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"
-
-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."
 
+To view an image's labels, use the `docker inspect` command.
+
 ## EXPOSE
 
     EXPOSE <port> [<port>...]

docs/sources/reference/commandline/cli.md

@@ -814,7 +814,7 @@ 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)
+      -l, --label=[]             Set metadata 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
@@ -1688,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 the container (e.g., --label=com.example.key=value)
-      --label-file=[]            Read in a line delimited file of labels
+      -l, --label=[]             Set metadata on the container (e.g., --label=com.example.key=value)
+      --label-file=[]            Read in a file of labels (EOL delimited)
       --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,38 +1860,39 @@ An example of a file passed with `--env-file`
 
     $ sudo docker run --name console -t -i ubuntu bash
 
-This will create and run a new container with the container name being
-`console`.
+A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels:
 
     $ sudo docker run -l my-label --label 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 
-`--label` 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.
+The `my-label` key doesn't specify so the label defaults to an empty
+string(`""`). To add multiple labels, repeat the label flag (`-l` or
+`--label`).
 
-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;
+The `key=value` must be unique. If you specify the same key multiple times
+with different values, each subsequent value overwrites the previous. Docker
+applies the last `key=value` you supply.
+
+Use the `--label-file` flag to load multiple labels from a file. Delimit each
+label in the file with an EOL mark. The example below loads labels from a
+labels file in the current directory;
 
     $ sudo docker run --label-file ./labels ubuntu bash
 
-The format of the labels-file is similar to that used for loading environment
-variables (see `--label-file` above). An example of a file passed with `--label-file`;
+The label-file format is similar to the format for loading environment variables
+(see `--env-file` above). The following example illustrates a label-file format;
 
-    $ 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 
+You can load multiple label-files by supplying the `--label-file` flag multiple
 times.
 
 For additional information on working with labels, see
-[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in
-the user guide.
+[*Labels - custom metadata in Docker*](/userguide/labels-custom-metadata/) in
+the Docker User Guide.
 
     $ sudo docker run --link /redis:redis --name console ubuntu bash