@@ -159,8 +159,12 @@ A Dockerfile is similar to a Makefile.

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

   ```

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

-  key-value pair by a space.

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

+  each key-value pair by a space. 

+  

+  Labels are additive including `LABEL`s in `FROM` images. As the system

+  encounters and then applies a new label, new `key`s override any previous

+  labels with identical keys.

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

@@ -290,20 +294,22 @@ A Dockerfile is similar to a Makefile.

 **ONBUILD**

   -- `ONBUILD [INSTRUCTION]`

-  The **ONBUILD** instruction adds a trigger instruction to the image, which is 

-  executed at a later time, when the image is used as the base for another

-  build. The trigger is executed in the context of the downstream build, as

-  if it had been inserted immediately after the **FROM** instruction in the

-  downstream Dockerfile.  Any build instruction can be registered as a

-  trigger.  This is useful if you are building an image to be

-  used as a base for building other images, for example an application build

-  environment or a daemon to be customized with a user-specific

-  configuration.  For example, if your image is a reusable python

-  application builder, it requires application source code to be

-  added in a particular directory, and might require a build script

-  to be called after that. You can't just call **ADD** and **RUN** now, because

-  you don't yet have access to the application source code, and it

-  is different for each application build.

+  The **ONBUILD** instruction adds a trigger instruction to an image. The

+  trigger is executed at a later time, when the image is used as the base for

+  another build. Docker executes the trigger in the context of the downstream

+  build, as if the trigger existed immediately after the **FROM** instruction in

+  the downstream Dockerfile.

+

+  You can register any build instruction as a trigger. A trigger is useful if

+  you are defining an image to use as a base for building other images. For

+  example, if you are defining an application build environment or a daemon that

+  is customized with a user-specific configuration.  

+  

+  Consider an image intended as a reusable python application builder. It must

+  add application source code to a particular directory, and might need a build

+  script called after that. You can't just call **ADD** and **RUN** now, because

+  you don't yet have access to the application source code, and it is different

+  for each application build.

   -- Providing application developers with a boilerplate Dockerfile to copy-paste

   into their application is inefficient, error-prone, and

@@ -22,7 +22,7 @@ Using an existing container's name or ID you can create a new image.

 **-c** , **--change**=[]

    Apply specified Dockerfile instructions while committing the image

-   Supported Dockerfile instructions: CMD, ENTRYPOINT, ENV, EXPOSE, ONBUILD, USER, VOLUME, WORKDIR

+   Supported Dockerfile instructions: ADD|CMD|ENTRYPOINT|ENV|EXPOSE|FROM|MAINTAINER|RUN|USER|LABEL|VOLUME|WORKDIR|COPY

 **--help**

   Print usage statement

@@ -106,10 +106,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 metadata on the container (e.g., --label=com.example.key=value)

+   Adds metadata to a container (e.g., --label=com.example.key=value)

 **--label-file**=[]

-   Read in a file of labels (EOL delimited)

+   Read labels from a file. Delimit each label with an EOL.

 **--link**=[]

    Add link to another container in the form of <name or id>:alias

@@ -13,7 +13,7 @@ URL|- [REPOSITORY[:TAG]]

 # OPTIONS

 **-c**, **--change**=[]

    Apply specified Dockerfile instructions while importing the image

-   Supported Dockerfile instructions: CMD, ENTRYPOINT, ENV, EXPOSE, ONBUILD, USER, VOLUME, WORKDIR

+   Supported Dockerfile instructions: `ADD`|`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`FROM`|`MAINTAINER`|`RUN`|`USER`|`LABEL`|`VOLUME`|`WORKDIR`|`COPY`

 # DESCRIPTION

 Create a new filesystem image from the contents of a tarball (`.tar`,

@@ -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 metadata in Docker' ]

+- ['userguide/labels-custom-metadata.md', 'User Guide', 'Apply custom metadata' ]

 - ['userguide/dockerrepos.md', 'User Guide', 'Working with Docker Hub' ]

 - ['userguide/level1.md', '**HIDDEN**' ]

 - ['userguide/level2.md', '**HIDDEN**' ]

@@ -352,6 +352,15 @@ key-value pair by an EOL.

     LABEL description="This text illustrates \

     that label-values can span multiple lines."

+Docker recommends combining labels in a single `LABEL` instruction where

+possible. Each `LABEL` instruction produces a new layer which can result in an

+inefficient image if you use many labels. This example results in four image

+layers. 

+    

+Labels are additive including `LABEL`s in `FROM` images. As the system

+encounters and then applies a new label, new `key`s override any previous labels

+with identical keys.    

+

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

 ## EXPOSE

@@ -750,8 +750,7 @@ If this behavior is undesired, set the 'p' option to false.

 The `--change` option will apply `Dockerfile` instructions to the image

 that is created.

-Supported `Dockerfile` instructions: `CMD`, `ENTRYPOINT`, `ENV`, `EXPOSE`,

-`ONBUILD`, `USER`, `VOLUME`, `WORKDIR`

+Supported `Dockerfile` instructions: `ADD`|`CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`FROM`|`MAINTAINER`|`RUN`|`USER`|`LABEL`|`VOLUME`|`WORKDIR`|`COPY`

 #### Commit a container

@@ -1906,22 +1905,23 @@ A label is a a `key=value` pair that applies metadata to a container. To label a

     $ sudo docker run -l my-label --label com.example.foo=bar ubuntu bash

-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 `my-label` key doesn't specify a value 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.

+The `key=value` must be unique to avoid overwriting the label value. If you

+specify labels with identical keys but different values, each subsequent value

+overwrites the previous. Docker uses 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;

+labels file in the current directory:

     $ sudo docker run --label-file ./labels ubuntu bash

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

+The label-file format is similar to the format for loading environment

+variables. (Unlike environment variables, labels are not visislbe to processes

+running inside a container.) The following example illustrates a label-file

+format:

     com.example.label1="a label"

@@ -1929,12 +1929,11 @@ The label-file format is similar to the format for loading environment variables

     com.example.label2=another\ label

     com.example.label3

-You can load multiple label-files by supplying the `--label-file` flag multiple

-times.

+You can load multiple label-files by supplying multiple  `--label-file` flags. 

-For additional information on working with labels, see

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

-the Docker 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,26 +1,27 @@

-page_title: Labels - custom metadata in Docker

+page_title: Apply custom metadata

 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 metadata in Docker

+# Apply custom metadata

-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

+You can apply metadata to your images, containers, or daemons via

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

 licensing information to an image or to identify a host.

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

+A label is a `<key>` / `<value>` pair. Docker stores the label values as

+*strings*. You can specify multiple labels but each `<key>` / `<value>` must be

+unique to avoid overwriting. If you specify the same `key` several times but with

+different values, newer labels overwrite previous labels. Docker uses

+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 are new in Docker 1.6.0

-### Naming your labels - namespaces

+## Label keys (namespaces)

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

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

+simple keys can conflict. For example, you can categorize your images by using a

+chip "architecture" label:

     LABEL architecture="amd64"

@@ -30,9 +31,8 @@ But a user can label images by building architectural style:

     LABEL architecture="Art Nouveau"

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

-notation. This notation has the following guidelines:

-

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

+notation. Use the following guidelines to name your keys:

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

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

@@ -49,19 +49,19 @@ notation. This notation has the following guidelines:

 - 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

+  users to add metadata to their containers and images without having to type

   cumbersome namespaces on the command-line.

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

+These are guidelines and 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

+## Store structured data in labels

-Label values can contain any data type as long as the value can be stored as a

-string. For example, consider this JSON:

+Label values can contain any data type that can be stored as a string. For

+example, consider this JSON:

     {

@@ -78,15 +78,13 @@ 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.

-

-If your tool needs to filter on nested properties, the tool itself should

-implement this.

+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. If your tool needs to filter on

+nested properties, the tool itself should implement this.

-### Adding labels to images; the `LABEL` instruction

+## Add labels to images; the `LABEL` instruction

 Adding labels to an image:

@@ -103,7 +101,7 @@ white space character:

     LABEL com.example.release-date="2015-02-12"

 The `LABEL` instruction supports setting multiple labels in a single instruction

-using this notation;

+using this notation:

     LABEL com.example.version="0.0.1-beta" com.example.release-date="2015-02-12"

@@ -114,10 +112,9 @@ Wrapping is allowed by using a backslash (`\`) as continuation marker:

           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.

+Docker recommends you add multiple labels in a single `LABEL` instruction. Using

+individual instructions for each label can result in an inefficient image. This

+is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer. 

 You can view the labels via the `docker inspect` command:

@@ -137,11 +134,10 @@ You can view the labels via the `docker inspect` command:

     {"Vendor":"ACME Incorporated","com.example.is-beta":"","com.example.version":"0.0.1-beta","com.example.release-date":"2015-02-12"}

+## Query labels

-### Querying labels

-

-Besides storing metadata, you can filter images and labels by label. To list all

-running containers that have a `com.example.is-beta` label:

+Besides storing metadata, you can filter images and containers by label. To list all

+running containers that the `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"

@@ -155,7 +151,7 @@ List all images with `vendor` `ACME`:

     $ docker images --filter "label=vendor=ACME"

-### Daemon labels

+## Daemon labels

     docker -d \