Merge component 'cli' from git@github.com:docker/cli master

components/cli/docs/reference/commandline/image_prune.md

@@ -95,6 +95,19 @@ which removes images with the specified labels. The other
 format is the `label!=...` (`label!=<key>` or `label!=<key>=<value>`), which removes
 images without the specified labels.
 
+> **Predicting what will be removed**
+>
+> If you are using positive filtering (testing for the existence of a label or
+> that a label has a specific value), you can use `docker image ls` with the
+> same filtering syntax to see which images match your filter.
+>
+> However, if you are using negative filtering (testing for the absence of a
+> label or that a label does *not* have a specific value), this type of filter
+> does not work with `docker image ls` so you cannot easily predict which images
+> will be removed. In addition, the confirmation prompt for `docker image prune`
+> always warns that *all* dangling images will be removed, even if you are using
+> `--filter`.
+
 The following removes images created before `2017-01-04T00:00:00`:
 
 ```bash
@@ -162,6 +175,35 @@ alpine              latest              88e169ea8f46        8 days ago
 busybox             latest              e02e811dd08f        2 months ago         1.09 MB
 ```
 
+The following example removes images with the label `deprecated`:
+
+```bash
+$ docker image prune --filter="label=deprecated"
+```
+
+The following example removes images with the label `maintainer` set to `john`:
+
+```bash
+$ docker image prune --filter="label=maintainer=john"
+```
+
+This example removes images which have no `maintainer` label:
+
+```bash
+$ docker image prune --filter="label!=maintainer"
+```
+
+This example removes images which have a maintainer label not set to `john`:
+
+```bash
+$ docker image prune --filter="label!=maintainer=john"
+```
+
+> **Note**: You are prompted for confirmation before the `prune` removes
+> anything, but you are not shown a list of what will potentially be removed.
+> In addition, `docker image ls` does not support negative filtering, so it
+> difficult to predict what images will actually be removed.
+
 ## Related commands
 
 * [system df](system_df.md)

components/cli/docs/reference/commandline/service_create.md

@@ -766,18 +766,14 @@ The options you can specify are:
 </tr>
 </thead>
 <tr>
-  <td>published and target port </td>
-  <td><tt></tt></td>
-  <td><tt></tt></td>
-  <td></td>
-</tr>
-<tr>
-  <td>protocol</td>
+  <td>published and target port</td>
   <td><tt>--publish 8080:80</tt></td>
   <td><tt>--publish published=8080,target=80</tt></td>
   <td><p>
-    The port to publish the service to on the routing mesh or directly on
-    the node, and the target port on the container.
+    The target port within the container and the port to map it to on the
+    nodes, using the routing mesh (<tt>ingress</tt>) or host-level networking.
+    More options are available, later in this table. The key-value syntax is
+    preferred, because it is somewhat self-documenting.
   </p></td>
 </tr>
 <tr>
@@ -785,8 +781,8 @@ The options you can specify are:
   <td>Not possible to set using short syntax.</td>
   <td><tt>--publish published=8080,target=80,mode=host</tt></td>
   <td><p>
-    The mode to use for binding the port, either `ingress` or `host`. Defaults
-    to `ingress` to use the routing mesh.
+    The mode to use for binding the port, either <tt>ingress</tt> or <tt>host</tt>.
+    Defaults to <tt>ingress</tt> to use the routing mesh.
   </p></td>
 </tr>
 <tr>
@@ -794,13 +790,14 @@ The options you can specify are:
   <td><tt>--publish 8080:80/tcp</tt></td>
   <td><tt>--publish published=8080,target=80,protocol=tcp</tt></td>
   <td><p>
-    The protocol to use, either `tcp` or `udp`. Defaults to `tcp`. To bind a
-    port for both protocols, specify the `-p` or `--publish` flag twice.
+    The protocol to use, either <tt>tcp</tt> or <tt>udp</tt> Defaults to
+    <tt>tcp</tt>. To bind a port for both protocols, specify the <tt>-p</tt> or
+    <tt>--publish</tt> flag twice.
   </p></td>
 </tr>
 </table>
 
-When you publish a service port using `ingres` mode, the swarm routing mesh
+When you publish a service port using `ingress` mode, the swarm routing mesh
 makes the service accessible at the published port on every node regardless if
 there is a task for the service running on the node. If you use `host` mode,
 the port is only bound on nodes where the service is running, and a given port
@@ -904,9 +901,9 @@ x3ti0erg11rjpg64m75kej2mz-hosttempl
 
 ### Specify isolation mode (Windows)
 
-By default, tasks scheduled on Windows nodes are run using the default isolation mode 
-configured for this particular node. To force a specific isolation mode, you can use 
-the `--isolation` flag: 
+By default, tasks scheduled on Windows nodes are run using the default isolation mode
+configured for this particular node. To force a specific isolation mode, you can use
+the `--isolation` flag:
 
 ```bash
 $ docker service create --name myservice --isolation=process microsoft/nanoserver