updating docs for EXPOSE option on run command; fixes #16634

Signed-off-by: Mike Brown <brownwm@us.ibm.com>

docs/reference/builder.md

@@ -484,17 +484,15 @@ To view an image's labels, use the `docker inspect` command.
 
     EXPOSE <port> [<port>...]
 
-The `EXPOSE` instructions informs Docker that the container will listen on the
+The `EXPOSE` instruction informs Docker that the container listens on the
-specified network ports at runtime. Docker uses this information to interconnect
+specified network ports at runtime. `EXPOSE` does not make the ports of the
-containers using links (see the [Docker User
+container accessible to the host. To do that, you must use either the `-p` flag
-Guide](../userguide/dockerlinks.md) and to determine which ports to expose to the
+to publish a range of ports or the `-P` flag to publish all of the exposed ports.
-host when [using the -P flag](run.md#expose-incoming-ports).
+You can expose one port number and publish it externally under another number.
-
+ 
-> **Note**:
+Docker uses exposed and published ports to interconnect containers using links
-> `EXPOSE` doesn't define which ports can be exposed to the host or make ports
+(see [Linking containers together](../userguide/dockerlinks.md))
-> accessible from the host by default. To expose ports to the host, at runtime,
+and to set up port redirection on the host system when [using the -P flag](run.md#expose-incoming-ports).
-> [use the `-p` flag](../userguide/dockerlinks.md) or
-> [the -P flag](run.md#expose-incoming-ports).
 
 ## ENV
 

man/Dockerfile.5.md

@@ -185,7 +185,7 @@ A Dockerfile is similar to a Makefile.
   -- `EXPOSE <port> [<port>...]`
   The **EXPOSE** instruction informs Docker that the container listens on the
   specified network ports at runtime. Docker uses this information to
-  interconnect containers using links, and to set up port redirection on the host
+  interconnect containers using links and to set up port redirection on the host
   system.
 
 **ENV**

man/docker-run.1.md

@@ -223,7 +223,10 @@ ENTRYPOINT.
    Read in a line delimited file of environment variables
 
 **--expose**=[]
-   Expose a port, or a range of ports (e.g. --expose=3300-3310), from the container without publishing it to your host
+   Expose a port, or a range of ports (e.g. --expose=3300-3310) informs Docker
+that the container listens on the specified network ports at runtime. Docker
+uses this information to interconnect containers using links and to set up port
+redirection on the host system.
 
 **--group-add**=[]
    Add additional groups to run as