Add labels documentation

Adds more documentation for labels and adds the label instruction to the
man-pages.

Also included is a document called "Labels - custom meta-data in Docker"
in the user-guide, this is still a work-in-progress I started to describe
the "namespaces" conventions, an example on storing structured data.

I ran a bit "out of steam" (writers block?) on that document, but kept
it in (for now), in case it still ends up useful.

The Remote API documentation changes will need to be moved to the
docker_remote_api_v1.18.md document when rebasing the whole PR.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Darren Shepherd <darren@rancher.com>
Upstream-commit: 7d89e66dac59999ae2f07970b273e227fdf73ea7
Component: engine

components/engine/docs/sources/reference/api/docker_remote_api.md

@@ -75,7 +75,7 @@ This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
 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.
 
-`LABEL "Vendor"="ACME Incorporated"`
+`LABEL "com.example.vendor"="ACME Incorporated"`
 
 **New!**
 `POST /containers/(id)/attach` and `POST /exec/(id)/start`

components/engine/docs/sources/reference/api/docker_remote_api_v1.17.md

@@ -130,9 +130,9 @@ Create a container
              "Entrypoint": "",
              "Image": "ubuntu",
              "Labels": {
-                     "Vendor": "Acme",
-                     "License": "GPL",
-                     "Version": "1.0"
+                     "com.example.vendor": "Acme",
+                     "com.example.license": "GPL",
+                     "com.example.version": "1.0"
              },
              "Volumes": {
                      "/tmp": {}
@@ -194,7 +194,8 @@ 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 list of labels that will applied 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"]}`
 -   **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
@@ -304,11 +305,11 @@ Return low-level information on the container `id`
 			"ExposedPorts": null,
 			"Hostname": "ba033ac44011",
 			"Image": "ubuntu",
-                        "Labels": {
-                                "Vendor": "Acme",
-                                "License": "GPL",
-                                "Version": "1.0"
-                        },
+			"Labels": {
+				"com.example.vendor": "Acme",
+				"com.example.license": "GPL",
+				"com.example.version": "1.0"
+			},
 			"MacAddress": "",
 			"Memory": 0,
 			"MemorySwap": 0,
@@ -1181,9 +1182,9 @@ Return low-level information on the image `name`
                              "Dns": null,
                              "Image": "ubuntu",
                              "Labels": {
-                                    "Vendor": "Acme",
-                                    "License": "GPL",
-                                    "Version": "1.0"
+                                 "com.example.vendor": "Acme",
+                                 "com.example.license": "GPL",
+                                 "com.example.version": "1.0"
                              },
                              "Volumes": null,
                              "VolumesFrom": "",