Updating with Sven's comments and other tweaks

Signed-off-by: Mary Anthony <mary@docker.com>

docs/man/Dockerfile.5.md

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

docs/man/docker-commit.1.md

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

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

docs/man/docker-import.1.md

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

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

docs/sources/reference/builder.md

@@ -347,6 +347,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

docs/sources/reference/commandline/cli.md

@@ -749,8 +749,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
 
@@ -1864,22 +1863,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"
 
@@ -1887,12 +1887,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
 

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

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