Add gists provided by Mary

This adds the example gists, provided by Mary Anthony,
also fixes a link to the old /terms/

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/run.md

@@ -16,15 +16,14 @@ parent = "mn_reference"
 </style>
 # Docker run reference
 
-**Docker runs processes in isolated containers**. When an operator
-executes `docker run`, she starts a process with its own file system,
-its own networking, and its own isolated process tree.  The
-[*Image*](/reference/glossary/#image) which starts the process may define
-defaults related to the binary to run, the networking to expose, and
-more, but `docker run` gives additional control to the operator who starts
-the container from the image. That's the main reason
-[*run*](/reference/commandline/run) has more options than any
-other `docker` command.
+Docker runs processes in isolated containers. A container is a process
+which runs on a host. The host may be local or remote. When an operator
+executes `docker run`, the container process that runs is isolated in
+that it has its own file system, its own networking, and its own
+isolated process tree separate from the host.
+
+This page details how to use the `docker run` command to define the
+container's resources at runtime.
 
 ## General form
 
@@ -32,27 +31,33 @@ The basic `docker run` command takes this form:
 
     $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...]
 
-To learn how to interpret the types of `[OPTIONS]`,
-see [*Option types*](/reference/commandline/cli/#option-types).
-
-The `run` options control the image's runtime behavior in a container. These
-settings affect:
+The `docker run` command must specify an [*IMAGE*](/reference/glossary/#image)
+to derive the container from. An image developer can define image
+defaults related to:
 
  * detached or foreground running
  * container identification
  * network settings
  * runtime constraints on CPU and memory
  * privileges and LXC configuration
- 
-An image developer may set defaults for these same settings when she creates the
-image using the `docker build` command. Operators can use the `run` options to override most of the
-defaults set by the developer. And, operators can override nearly all the defaults set by the Docker runtime itself.
 
-Finally, depending on your Docker system configuration, you may be required to
-preface each `docker` command with `sudo`. To avoid having to use `sudo` with
-the `docker` command, your system administrator can create a Unix group called
-`docker` and add users to it. For more information about this configuration,
-refer to the Docker installation documentation for your operating system.
+With the `docker run [OPTIONS]` an operator can add to or override the
+image defaults set by a developer. And, additionally, operators can
+override nearly all the defaults set by the Docker runtime itself. The
+operator's ability to override image and Docker runtime defaults is why
+[*run*](/reference/commandline/cli/run/) has more options than any
+other `docker` command.
+
+To learn how to interpret the types of `[OPTIONS]`, see [*Option
+types*](/reference/commandline/cli/#option-types).
+
+> **Note**: Depending on your Docker system configuration, you may be
+> required to preface the `docker run` command with `sudo`. To avoid
+> having to use `sudo` with the `docker` command, your system
+> administrator can create a Unix group called `docker` and add users to
+> it. For more information about this configuration, refer to the Docker
+> installation documentation for your operating system.
+
 
 ## Operator exclusive options
 
@@ -971,45 +976,59 @@ or two examples of how to pass more parameters to that ENTRYPOINT:
 
 ### EXPOSE (incoming ports)
 
-The Dockerfile doesn't give much control over networking, only providing
-the `EXPOSE` instruction to specify incoming ports that provide services.
 The following `run` command options work with container networking:
 
-    --expose=[]: Expose a port or a range of ports from the container,
-                in addition to ports exposed by the `EXPOSE` Dockerfile instruction
+    --expose=[]: Expose a port or a range of ports inside the container.
+                 These are additional to those exposed by the `EXPOSE` instruction
     -P=false   : Publish all exposed ports to the host interfaces
     -p=[]      : Publish a container᾿s port or a range of ports to the host
                    format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort
-                   Both hostPort and containerPort can be specified as a range of ports.
-                   When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
-                   When specifying a range for hostPort only, the containerPort must not be a range.  In this case the container port is published somewhere within the specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`)
+                   Both hostPort and containerPort can be specified as a
+                   range of ports. When specifying ranges for both, the
+                   number of container ports in the range must match the
+                   number of host ports in the range, for example:
+                       -p 1234-1236:1234-1236/tcp
+
+                   When specifying a range for hostPort only, the
+                   containerPort must not be a range.  In this case the
+                   container port is published somewhere within the
+                   specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`)
+
                    (use 'docker port' to see the actual mapping)
+
     --link=""  : Add link to another container (<name or id>:alias or <name or id>)
 
-As mentioned previously, `EXPOSE` (and `--expose`) makes ports available
-**in** a container for incoming connections. The port number on the
-inside of the container (where the service listens) does not need to be
-the same number as the port exposed on the outside of the container
-(where clients connect), so inside the container you might have an HTTP
-service listening on port 80 (and so you `EXPOSE 80` in the Dockerfile),
-but outside the container the port might be 42800.
-
-To help a new client container reach the server container's internal
-port operator `--expose`'d by the operator or `EXPOSE`'d by the
-developer, the operator has three choices: start the server container
-with `-P` or `-p,` or start the client container with `--link`.
-
-If the operator uses `-P` or `-p` then Docker will make the exposed port
-accessible on the host and the ports will be available to any client that can
-reach the host. When using `-P`, Docker will bind the exposed port to a random
-port on the host within an *ephemeral port range* defined by
-`/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host
-ports and the exposed ports, use `docker port`.
-
-If the operator uses `--link` when starting the new client container,
+With the exception of the `EXPOSE` directive, an image developer hasn't
+got much control over networking. The `EXPOSE` instruction defines the
+initial incoming ports that provide services. These ports are available
+to processes inside the container. An operator can use the `--expose`
+option to add to the exposed ports.
+
+To expose a container's internal port, an operator can start the
+container with the `-P` or `-p` flag. The exposed port is accessible on
+the host and the ports are available to any client that can reach the
+host.
+
+The `-P` option publishes all the ports to the host interfaces. Docker
+binds each exposed port to a random port on the host. The range of
+ports are within an *ephemeral port range* defined by
+`/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to
+explicitly map a single port or range of ports.
+
+The port number inside the container (where the service listens) does
+not need to match the port number exposed on the outside of the
+container (where clients connect). For example, inside the container an
+HTTP service is listening on port 80 (and so the image developer
+specifies `EXPOSE 80` in the Dockerfile). At runtime, the port might be
+bound to 42800 on the host. To find the mapping between the host ports
+and the exposed ports, use `docker port`.
+
+If the operator uses `--link` when starting a new client container,
 then the client container can access the exposed port via a private
-networking interface.  Docker will set some environment variables in the
-client container to help indicate which interface and port to use.
+networking interface. Docker will set some environment variables in the
+client container to help indicate which interface and port to use. For
+more information on linking, see [the guide on linking container
+together](/userguide/dockerlinks/)
 
 ### ENV (environment variables)