Merge pull request #15903 from charleswhchan/patch-1

Revise documentation for Docker LABEL.

docs/userguide/labels-custom-metadata.md

@@ -11,34 +11,35 @@ parent = "mn_use_docker"
 # Apply custom metadata
 
 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.
+labels. Labels serve a wide range of uses, such as adding notes or licensing
+information to an image, or to identify a host.
 
 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.
+*strings*. You can specify multiple labels but each `<key>` must be
+unique or the value will be overwritten. 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
 >containers and images are new in Docker 1.6.0
 
 ## Label keys (namespaces)
 
-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:
+Docker puts no hard restrictions on the `key` used for a label. However, using
+simple keys can easily lead to conflicts. For example, you have chosen to
+categorize your images by CPU architecture using "architecture" labels in
+your Dockerfiles:
 
     LABEL architecture="amd64"
 
     LABEL architecture="ARMv7"
 
-But a user can label images by building architectural style:
+Another user may apply the same label based on a building's "architecture":
 
     LABEL architecture="Art Nouveau"
 
-To prevent naming conflicts, Docker namespaces label keys using a reverse domain
-notation. Use the following guidelines to name your keys:
+To prevent naming conflicts, Docker recommends using namespaces to label keys
+using 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
@@ -59,15 +60,14 @@ notation. Use the following guidelines to name your keys:
   cumbersome namespaces on the command-line.
 
 
-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.
+These are simply guidelines and Docker does not *enforce* them. However, for
+the benefit of the community, you *should* use namespaces for your label keys.
 
 
 ## Store structured data in labels
 
-Label values can contain any data type that can be stored as a string. For
-example, consider this JSON:
+Label values can contain any data type as long as it can be represented as a
+string. For example, consider this JSON document:
 
 
     {
@@ -87,31 +87,31 @@ You can store this struct in a label by serializing it to a string first:
 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.
+nested properties, the tool itself needs to implement this functionality.
 
 
-## Add labels to images; the `LABEL` instruction
+## Add labels to images
 
-Adding labels to an image:
+To add labels to an image, use the `LABEL` instruction in your Dockerfile:
 
 
     LABEL [<namespace>.]<key>[=<value>] ...
 
-The `LABEL` instruction adds a label to your image, optionally setting its value.
+The `LABEL` instruction adds a label to your image, optionally with a value.
 Use surrounding quotes or backslashes for labels that contain
-white space character:
+white space characters in the `<value>`:
 
     LABEL vendor=ACME\ Incorporated
     LABEL com.example.version.is-beta
     LABEL com.example.version="0.0.1-beta"
     LABEL com.example.release-date="2015-02-12"
 
-The `LABEL` instruction supports setting multiple labels in a single instruction
-using this notation:
+The `LABEL` instruction also supports setting multiple `<key>` / `<value>` pairs
+in a single instruction:
 
     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:
+Long lines can be split up by using a backslash (`\`) as continuation marker:
 
     LABEL vendor=ACME\ Incorporated \
           com.example.is-beta \
@@ -120,7 +120,7 @@ Wrapping is allowed by using a backslash (`\`) as continuation marker:
 
 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. 
+is because each `LABEL` instruction in a Dockerfile produces a new IMAGE layer.
 
 You can view the labels via the `docker inspect` command:
 
@@ -147,16 +147,16 @@ You can view the labels via the `docker inspect` command:
 ## Query labels
 
 Besides storing metadata, you can filter images and containers by label. To list all
-running containers that the `com.example.is-beta` label:
+running containers that have 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"
 
-List all running containers with a `color` label of `blue`:
+List all running containers with the label `color` that have a value `blue`:
 
     $ docker ps --filter "label=color=blue"
 
-List all images with `vendor` `ACME`:
+List all images with the label `vendor` that have the value `ACME`:
 
     $ docker images --filter "label=vendor=ACME"