Documentation changes for labels

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

docs/man/Dockerfile.5.md

@@ -144,16 +144,19 @@ A Dockerfile is similar to a Makefile.
   the image.
 
 **LABEL**
- --**LABEL <key>[=<value>] [<key>[=<value>] ...]**
+  -- `LABEL <key>[=<value>] [<key>[=<value>] ...]`
+  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.
 
- 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
+  LABEL "com.example.vendor"="ACME Incorporated"
- be retrieved using the `docker inspect` command.
+  ```
 
- The LABEL instruction allows for multiple labels to be set at one time. Like 
+  An image can have more than one label. To specify multiple labels, separate each
- command line parsing, quotes and backslashes can be used to include spaces 
+  key-value pair by a space.
- within values.
 
+  To display an image's labels, use the `docker inspect` command.
 
 **EXPOSE**
   -- `EXPOSE <port> [<port>...]`

docs/man/docker-create.1.md

@@ -105,10 +105,10 @@ IMAGE [COMMAND] [ARG...]
                                '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)
+   Set metadata on the container (e.g., --label=com.example.key=value)
 
 **--label-file**=[]
-   Read in a line delimited file of labels
+   Read in a file of labels (EOL delimited)
 
 **--link**=[]
    Add link to another container in the form of <name or id>:alias

docs/man/docker-images.1.md

@@ -34,9 +34,7 @@ versions.
    Show all images (by default filter out the intermediate image layers). The default is *false*.
 
 **-f**, **--filter**=[]
-   Provide filter values. Valid filters:
+   Filters the output. The dangling=true filter finds unused images. While label=com.foo=amd64 filters for images with a com.foo value of amd64. The label=com.foo filter finds images with the label com.foo of any value.
-                          dangling=true - unlabeled images with no children
-                          label=<key> or label=<key>=<value>
 
 **--help**
   Print usage statement

docs/man/docker-run.1.md

@@ -200,7 +200,7 @@ ENTRYPOINT.
                                '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)
+   Set metadata on the container (e.g., --label com.example.key=value)
 
 **--label-file**=[]
    Read in a line delimited file of labels

docs/mkdocs.yml

@@ -59,7 +59,7 @@ pages:
 - ['userguide/dockerimages.md', 'User Guide', 'Working with Docker Images' ]
 - ['userguide/dockerlinks.md', 'User Guide', 'Linking containers together' ]
 - ['userguide/dockervolumes.md', 'User Guide', 'Managing data in containers' ]
-- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom meta-data in Docker' ]
+- ['userguide/labels-custom-metadata.md', 'User Guide', 'Labels - custom metadata in Docker' ]
 - ['userguide/dockerrepos.md', 'User Guide', 'Working with Docker Hub' ]
 - ['userguide/level1.md', '**HIDDEN**' ]
 - ['userguide/level2.md', '**HIDDEN**' ]

docs/sources/reference/api/docker_remote_api.md

@@ -71,9 +71,8 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
 
 ### What's new
 
-**New!**
+The build supports `LABEL` command. Use this to add metadata
-Build now has support for `LABEL` command which can be used to add user data
+to an image. For example you could add data describing the content of an image.
-to an image.  For example you could add data describing the content of an image.
 
 `LABEL "com.example.vendor"="ACME Incorporated"`
 
@@ -91,7 +90,7 @@ You can set labels on container create describing the container.
 `GET /containers/json`
 
 **New!**
-This endpoint now returns the labels associated with each container (`Labels`).
+The endpoint returns the labels associated with the containers (`Labels`).
 
 `GET /containers/(id)/json`
 

docs/sources/reference/api/docker_remote_api_v1.18.md

@@ -195,8 +195,7 @@ Json Parameters:
 -   **OpenStdin** - Boolean value, opens stdin,
 -   **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects.
 -   **Env** - A list of environment variables in the form of `VAR=value`
--   **Labels** - A map of labels and their values that will be added to the
+-   **Labels** - Adds a map of labels that to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
-        container. It should be specified in the form `{"name":"value"[,"name2":"value2"]}`
 -   **Cmd** - Command to run specified as a string or an array of strings.
 -   **Entrypoint** - Set the entrypoint for the container a a string or an array
       of strings

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 
+    LABEL <key>=<value> <key>=<value> <key>=<value> ...
-`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

@@ -791,7 +791,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
@@ -1665,8 +1665,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)
+      -l, --label=[]             Set metadata on the container (e.g., --label=com.example.key=value)
-      --label-file=[]            Read in a line delimited file of labels
+      --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
@@ -1837,38 +1837,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
+A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels:
-`console`.
 
     $ 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
+The `my-label` key doesn't specify so the label defaults to an empty
-specified and will default to "" (empty string) for its value. Both `-l` and 
+string(`""`). To add multiple labels, repeat the label flag (`-l` or
-`--label` can be repeated to add more labels. Label names are unique; if the same
+`--label`).
-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 
+The `key=value` must be unique. If you specify the same key multiple times
-`--label-file` flag. The example below will load labels from a file named `labels`
+with different values, each subsequent value overwrites the previous. Docker
-in the current directory;
+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
+The label-file format is similar to the format for loading environment variables
-variables (see `--label-file` above). An example of a file passed with `--label-file`;
+(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 
+For additional information on working with labels, see
-[*Labels - custom meta-data in Docker*](/userguide/labels-custom-metadata/) in
+[*Labels - custom metadata in Docker*](/userguide/labels-custom-metadata/) in
-the user guide.
+the Docker User Guide.
 
     $ sudo docker run --link /redis:redis --name console ubuntu bash
 

docs/sources/userguide/labels-custom-metadata.md

@@ -1,61 +1,67 @@
-page_title: Labels - custom meta-data in Docker
+page_title: Labels - custom metadata in Docker
-page_description: Learn how to work with custom meta-data in Docker, using labels.
+page_description: Learn how to work with custom metadata in Docker, using labels.
-page_keywords: Usage, user guide, labels, meta-data, docker, documentation, examples, annotating
+page_keywords: Usage, user guide, labels, metadata, docker, documentation, examples, annotating
 
-## Labels - custom meta-data in Docker
+## Labels - custom metadata in Docker
 
-Docker enables you to add meta-data to your images, containers, and daemons via
+You can add metadata to your images, containers, and daemons via
-labels. Meta-data can serve a wide range of uses ranging from adding notes or 
+labels. Metadata can serve a wide range of uses. Use them to add notes or
-licensing information to an image to identifying a host.
+licensing information to an image or to identify a host.
 
-Labels in Docker are implemented as `<key>` / `<value>` pairs and values are
+A label is a `<key>` / `<value>` pair. Docker stores the values as *strings*.
-stored as *strings*.
+You can specify multiple labels but each `<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.
 
->**note:** Support for daemon-labels was added in docker 1.4.1, labels on
+>**note:** Support for daemon-labels was added in Docker 1.4.1. Labels on
->containers and images in docker 1.6.0
+>containers and images are new in Docker 1.6.0
 
 ### Naming your labels - namespaces
 
-Docker puts no hard restrictions on the names you pick for your labels, however,
+Docker puts no hard restrictions on the label `key` you. However, labels can
-it's easy for labels to "conflict".
+conflict. For example, you can categorize your images by using a chip "architecture"
-
+label:
-For example, you're building a tool that categorizes your images in 
-architectures, doing so by using an "architecture" label;
 
     LABEL architecture="amd64"
 
     LABEL architecture="ARMv7"
 
-But a user decided to label images by Architectural style
+But a user can label images by building architectural style:
 
     LABEL architecture="Art Nouveau"
 
-To prevent such conflicts, Docker uses the convention to namespace label-names,
+To prevent such conflicts, Docker namespaces label keys using a reverse domain
-using a reverse domain notation;
+notation. This notation has the following guidelines:
 
 
-- All (third-party) tools should namespace (prefix) their labels with the 
+- All (third-party) tools should prefix their keys with the
-  reverse DNS notation of a domain controlled by the author of the tool. For 
+  reverse DNS notation of a domain controlled by the author. For
-  example, "com.example.some-label".
+  example, `com.example.some-label`.
-- Namespaced labels should only consist of lower-cased alphanumeric characters,
+
-  dots and dashes (in short, `[a-z0-9-.]`), should start *and* end with an alpha
-  numeric character, and may not contain consecutive dots or dashes.
 - The `com.docker.*`, `io.docker.*` and `com.dockerproject.*` namespaces are
   reserved for Docker's internal use.
-- Labels *without* namespace (dots) are reserved for CLI use. This allows end-
+
-  users to add meta-data to their containers and images, without having to type 
+- Keys should only consist of lower-cased alphanumeric characters,
+  dots and dashes (for example, `[a-z0-9-.]`)
+
+- Keys should start *and* end with an alpha numeric character
+
+- Keys may not contain consecutive dots or dashes.
+
+- Keys *without* namespace (dots) are reserved for CLI use. This allows end-
+  users to add metadata to their containers and images, without having to type
   cumbersome namespaces on the command-line.
 
 
-> **Note:** Even though Docker does not *enforce* you to use namespaces,
+These are guidelines and are not enforced. Docker does not *enforce* them.
-> preventing to do so will likely result in conflicting usage of labels. 
+Failing following these guidelines can result in conflicting labels. If you're
-> If you're building a tool that uses labels, you *should* use namespaces
+building a tool that uses labels, you *should* use namespaces for your label keys.
-> for your labels.
 
 
 ### Storing structured data in labels
 
-Labels can store any type of data, as long as its stored as a string. 
+Label values can contain any data type as long as the value can be stored as a
+string. For example, consider this JSON:
 
 
     {
@@ -68,31 +74,28 @@ Labels can store any type of data, as long as its stored as a string.
         "aNestedArray": ["a", "b", "c"]
     }
 
-Which can be stored in a label by serializing it to a string first;
+You can store this struct in a label by serializing it to a string first:
 
     LABEL com.example.image-specs="{\"Description\":\"A containerized foobar\",\"Usage\":\"docker run --rm example\\/foobar [args]\",\"License\":\"GPL\",\"Version\":\"0.0.1-beta\",\"aBoolean\":true,\"aNumber\":0.01234,\"aNestedArray\":[\"a\",\"b\",\"c\"]}"
 
+While it is *possible* to store structured data in label values, Docker treats this
+data as a 'regular' string. This means that Docker doesn't offer ways to query
+(filter) based on nested properties.
 
-> **Note:** Although the example above shows it's *possible* to store structured 
+If your tool needs to filter on nested properties, the tool itself should
-> data in labels, Docker does not treat this data any other way than a 'regular'
+implement this.
-> string. This means that Docker doesn't offer ways to query (filter) based on 
-> nested properties. If your tool needs to filter on nested properties, the 
-> tool itself should implement this.
 
 
 ### Adding labels to images; the `LABEL` instruction
 
-Adding labels to your 
+Adding labels to an image:
 
 
-    LABEL [<namespace>.]<name>[=<value>] ...
+    LABEL [<namespace>.]<key>[=<value>] ...
 
 The `LABEL` instruction adds a label to your image, optionally setting its value.
-Quotes surrounding name and value are optional, but required if they contain
+Use surrounding quotes or backslashes for labels that contain
-white space characters. Alternatively, backslashes can be used.
+white space character:
-
-Label values only support strings
-
 
     LABEL vendor=ACME\ Incorporated
     LABEL com.example.version.is-beta
@@ -104,15 +107,19 @@ using this notation;
 
     LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"
 
-Wrapping is allowed by using a backslash (`\`) as continuation marker;
+Wrapping is allowed by using a backslash (`\`) as continuation marker:
 
     LABEL vendor=ACME\ Incorporated \
           com.example.is-beta \
           com.example.version="0.0.1-beta" \
           com.example.release-date="2015-02-12"
 
+Docker recommends combining labels in a single `LABEL` instruction instead of
+using a `LABEL` instruction for each label. Each instruction in a Dockerfile
+produces a new layer that can result in an inefficient image if you use many
+labels.
 
-You can view the labels via `docker inspect`
+You can view the labels via the `docker inspect` command:
 
     $ docker inspect 4fa6e0f0c678
 
@@ -129,27 +136,21 @@ You can view the labels via `docker inspect`
 
     {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}
 
-> **note:** We recommend combining labels in a single `LABEl` instruction in
+
-> stead of using a `LABEL` instruction for each label. Each instruction in a
-> Dockerfile produces a new layer, which can result in an inefficient image if
-> many labels are used.
 
 ### Querying labels
 
-Besides storing meta-data, labels can be used to filter your images and 
+Besides storing metadata, you can filter images and labels by label. To list all
-containers.
+running containers that have a `com.example.is-beta` label:
-
-List all running containers that have a `com.example.is-beta` label;
 
     # List all running containers that have a `com.example.is-beta` label
     $ docker ps --filter "label=com.example.is-beta"
 
-
+List all running containers with a `color` label of `blue`:
-List all running containers with a "color" label set to "blue";
 
     $ docker ps --filter "label=color=blue"
 
-List all images with "vendor" "ACME"
+List all images with `vendor` `ACME`:
 
     $ docker images --filter "label=vendor=ACME"
 
@@ -157,7 +158,6 @@ List all images with "vendor" "ACME"
 ### Daemon labels
 
 
-
     docker -d \
       --dns 8.8.8.8 \
       --dns 8.8.4.4 \
@@ -165,7 +165,7 @@ List all images with "vendor" "ACME"
       --label com.example.environment="production" \
       --label com.example.storage="ssd"
 
-And can be seen as part of the `docker info` output for the daemon;
+These labels appear as part of the `docker info` output for the daemon:
 
     docker -D info
     Containers: 12