Merge pull request #624 from mstanleyjones/guidance-on-labels

Update info on labels

docs/reference/builder.md

@@ -708,23 +708,24 @@ backslashes as you would in command-line parsing. A few usage examples:
     LABEL description="This text illustrates \
     that label-values can span multiple lines."
 
-An image can have more than one label. To specify multiple labels,
+An image can have more than one label. You can specify multiple labels on a
-Docker recommends combining labels into a single `LABEL` instruction where
+single line. Prior to Docker 1.10, this decreased the size of the final image,
-possible. Each `LABEL` instruction produces a new layer which can result in an
+but this is no longer the case. You may still choose to specify multiple labels
-inefficient image if you use many labels. This example results in a single image
+in a single instruction, in one of the following two ways:
-layer.
 
-    LABEL multi.label1="value1" multi.label2="value2" other="value3"
+```none
+LABEL multi.label1="value1" multi.label2="value2" other="value3"
+```
 
-The above can also be written as:
+```none
+LABEL multi.label1="value1" \
+      multi.label2="value2" \
+      other="value3"
+```
 
-    LABEL multi.label1="value1" \
+Labels included in base or parent images (images in the `FROM` line) are
-          multi.label2="value2" \
+inherited by your image. If a label already exists but with a different value,
-          other="value3"
+the most-recently-applied value overrides any previously-set value.
-
-Labels are additive including `LABEL`s in `FROM` images. If Docker
-encounters a label/key that already exists, the new value overrides any previous
-labels with identical keys.
 
 To view an image's labels, use the `docker inspect` command.