@@ -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

- be retrieved using the `docker inspect` command.

+  ```

+  LABEL "com.example.vendor"="ACME Incorporated"

+  ```

- 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.

+  An image can have more than one label. To specify multiple labels, separate each

+  key-value pair by a space.

+  To display an image's labels, use the `docker inspect` command.

 **EXPOSE**

   -- `EXPOSE <port> [<port>...]`

@@ -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

@@ -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:

-                          dangling=true - unlabeled images with no children

-                          label=<key> or label=<key>=<value>

+   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.

 **--help**

   Print usage statement

@@ -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

@@ -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**' ]

@@ -71,9 +71,8 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.

 ### What's new

-**New!**

-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.

+The build supports `LABEL` command. Use this to add metadata

+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`

@@ -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

-        container. It should be specified in the form `{"name":"value"[,"name2":"value2"]}`

+-   **Labels** - Adds a map of labels that to a container. To specify a map: `{"key":"value"[,"key2":"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

@@ -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

+    LABEL <key>=<value> <key>=<value> <key>=<value> ...

-    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"

+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.

-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.

+    LABEL "com.example.vendor"="ACME Incorporated"

-For example:

+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 text illustrates \

     that label-values can span multiple lines."

+To view an image's labels, use the `docker inspect` command.

+

 ## EXPOSE

     EXPOSE <port> [<port>...]

@@ -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)

-      --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

@@ -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

-`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`).

+

+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.

-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;

+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.

+For additional information on working with labels, see

+[*Labels - custom metadata in Docker*](/userguide/labels-custom-metadata/) in

+the Docker User Guide.

     $ sudo docker run --link /redis:redis --name console ubuntu bash

@@ -1,61 +1,67 @@

-page_title: Labels - custom meta-data in Docker

-page_description: Learn how to work with custom meta-data in Docker, using labels.

-page_keywords: Usage, user guide, labels, meta-data, docker, documentation, examples, annotating

+page_title: Labels - custom metadata in Docker

+page_description: Learn how to work with custom metadata in Docker, using labels.

+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

-labels. Meta-data can serve a wide range of uses ranging from adding notes or 

-licensing information to an image to identifying a host.

+You can add metadata to your images, containers, and daemons via

+labels. Metadata can serve a wide range of uses. Use them to add notes or

+licensing information to an image or to identify a host.

-Labels in Docker are implemented as `<key>` / `<value>` pairs and values are

-stored as *strings*.

+A label is a `<key>` / `<value>` pair. Docker stores the values 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

->containers and images in docker 1.6.0

+>**note:** Support for daemon-labels was added in Docker 1.4.1. Labels on

+>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,

-it's easy for labels to "conflict".

-

-For example, you're building a tool that categorizes your images in 

-architectures, doing so by using an "architecture" label;

+Docker puts no hard restrictions on the label `key` you. However, labels can

+conflict. For example, you can categorize your images by using a chip "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,

-using a reverse domain notation;

+To prevent such conflicts, Docker namespaces label keys using a reverse domain

+notation. This notation has the following guidelines:

+

+- All (third-party) tools should prefix their keys with the

+  reverse DNS notation of a domain controlled by the author. For

+  example, `com.example.some-label`.

-- All (third-party) tools should namespace (prefix) their labels with the 

-  reverse DNS notation of a domain controlled by the author of the tool. For 

-  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,

-> preventing to do so will likely result in conflicting usage of labels. 

-> If you're building a tool that uses labels, you *should* use namespaces

-> for your labels.

+These are guidelines and are not enforced. Docker does not *enforce* them.

+Failing following these guidelines can result in conflicting labels. If you're

+building a tool that uses labels, you *should* use namespaces for your label keys.

 ### 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 

-> data in labels, Docker does not treat this data any other way than a 'regular'

-> 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.

+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

-white space characters. Alternatively, backslashes can be used.

-

-Label values only support strings

-

+Use surrounding quotes or backslashes for labels that contain

+white space character:

     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 

-containers.

+### Querying labels

-List all running containers that have a `com.example.is-beta` label;

+Besides storing metadata, you can filter images and labels by label. To 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 set to "blue";

+List all running containers with a `color` label of `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