Add documentation on short-names

Once we settle on the wording for short-names in podman-pull, I will
add the same section to all of the podman commands that use pull.

Also ran through all man pages with a spell checker.

Signed-off-by: Daniel J Walsh <dwalsh@redhat.com>

14 files changed, 39 insertions, 30 deletions

diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index 9fc4ffb5b..1d6aa3d40 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -657,8 +657,8 @@ specified, `podman` will assume that the specified group name is also a
 suitable user name to use as the default setting for this option.
 
 **NOTE:** When this option is specified by a rootless user, the specified
-mappings are relative to the rootless usernamespace in the container, rather
-than being relative to the host as it would be when run rootful.
+mappings are relative to the rootless user namespace in the container, rather
+than being relative to the host as it would be when run rootfull.
 
 #### **\-\-userns-gid-map-group**=*group*
 
@@ -672,8 +672,8 @@ specified, `podman` will assume that the specified user name is also a
 suitable group name to use as the default setting for this option.
 
 **NOTE:** When this option is specified by a rootless user, the specified
-mappings are relative to the rootless usernamespace in the container, rather
-than being relative to the host as it would be when run rootful.
+mappings are relative to the rootless user namespace in the container, rather
+than being relative to the host as it would be when run rootfull.
 
 #### **\-\-uts**=*how*
 
diff --git a/docs/source/markdown/podman-completion.1.md b/docs/source/markdown/podman-completion.1.md
index 964f3264e..cff9c7878 100644
--- a/docs/source/markdown/podman-completion.1.md
+++ b/docs/source/markdown/podman-completion.1.md
@@ -41,7 +41,7 @@ If shell completion is not already enabled in the environment you will need to e
 To make it available for all zsh sessions run:
 `podman completion zsh -f "${fpath[1]}/_podman"`
 
-Once you reload the shell the autocompletion should be working.
+Once you reload the shell the auto-completion should be working.
 
 
 ### FISH
diff --git a/docs/source/markdown/podman-cp.1.md b/docs/source/markdown/podman-cp.1.md
index bafbbdf3b..f245ad1aa 100644
--- a/docs/source/markdown/podman-cp.1.md
+++ b/docs/source/markdown/podman-cp.1.md
@@ -31,7 +31,7 @@ Assuming a path separator of /, a first argument of **src_path** and second argu
   - **dest_path** exists and is a file
     - the destination is overwritten with the source file's contents
   - **dest_path** exists and is a directory
-    - the file is copied into this directory using the basename from **src_path**
+    - the file is copied into this directory using the base name from **src_path**
 
 **src_path** specifies a directory
   - **dest_path** does not exist
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index bd2aab4c2..e4631c319 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -87,7 +87,7 @@ Attach to STDIN, STDOUT or STDERR.
 In foreground mode (the default when **-d**
 is not specified), **podman run** can start the process in the container
 and attach the console to the process's standard input, output, and standard
-error. It can even pretend to be a TTY (this is what most commandline
+error. It can even pretend to be a TTY (this is what most command line
 executables expect) and pass along signals. The **-a** option can be set for
 each of stdin, stdout, and stderr.
 
@@ -997,8 +997,8 @@ option conflicts with the **\-\-userns** and **\-\-subuidname** options. This
 option provides a way to map host UIDs to container UIDs. It can be passed
 several times to map different ranges.
 
-The _from_uid_ value is based upon the user running the command, either rootful or rootless users.
-* rootful user:  *container_uid*:*host_uid*:*amount*
+The _from_uid_ value is based upon the user running the command, either rootfull or rootless users.
+* rootfull user:  *container_uid*:*host_uid*:*amount*
 * rootless user: *container_uid*:*intermediate_uid*:*amount*
 
 When **podman create** is called by a privileged user, the option **\-\-uidmap**
@@ -1108,7 +1108,7 @@ Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman
 bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman
 container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume
 in the host to the container. If no such named volume exists, Podman will
-create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>  (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.)
+create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>  (Note when using the remote client, the volumes will be mounted from the remote server, not necessarily the client machine.)
 
 The _options_ is a comma-separated list and can be:
 
diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md
index 1d427d35b..7dccc5c1f 100644
--- a/docs/source/markdown/podman-generate-systemd.1.md
+++ b/docs/source/markdown/podman-generate-systemd.1.md
@@ -236,7 +236,7 @@ bb310a0780ae  docker.io/library/alpine:latest  /bin/sh  3 minutes ago  Created
 [**podman**(1)](podman.1.md), [**podman-container**(1)](podman-container.1.md), **systemctl**(1), **systemd.unit**(5), **systemd.service**(5), **conmon**(8).
 
 ## HISTORY
-April 2020, Updated details and added usecase to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com)
+April 2020, Updated details and added use case to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com)
 
 August 2019, Updated with pod support by Valentin Rothberg (rothberg at redhat dot com)
 
diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md
index 946f959bf..8947967aa 100644
--- a/docs/source/markdown/podman-machine-init.1.md
+++ b/docs/source/markdown/podman-machine-init.1.md
@@ -10,7 +10,7 @@ podman\-machine\-init - Initialize a new virtual machine
 
 Initialize a new virtual machine for Podman.
 
-Podman on MacOS requires a virtual machine. This is because containers are Linux -
+Podman on macOS requires a virtual machine. This is because containers are Linux -
 containers do not run on any other OS because containers' core functionality are
 tied to the Linux kernel.
 
diff --git a/docs/source/markdown/podman-machine-start.1.md b/docs/source/markdown/podman-machine-start.1.md
index b430f51eb..b21bbd65c 100644
--- a/docs/source/markdown/podman-machine-start.1.md
+++ b/docs/source/markdown/podman-machine-start.1.md
@@ -10,7 +10,7 @@ podman\-machine\-start - Start a virtual machine
 
 Starts a virtual machine for Podman.
 
-Podman on MacOS requires a virtual machine. This is because containers are Linux -
+Podman on macOS requires a virtual machine. This is because containers are Linux -
 containers do not run on any other OS because containers' core functionality are
 tied to the Linux kernel.
 
diff --git a/docs/source/markdown/podman-machine-stop.1.md b/docs/source/markdown/podman-machine-stop.1.md
index 33c67f70b..e2037144c 100644
--- a/docs/source/markdown/podman-machine-stop.1.md
+++ b/docs/source/markdown/podman-machine-stop.1.md
@@ -10,7 +10,7 @@ podman\-machine\-stop - Stop a virtual machine
 
 Stops a virtual machine.
 
-Podman on MacOS requires a virtual machine. This is because containers are Linux -
+Podman on macOS requires a virtual machine. This is because containers are Linux -
 containers do not run on any other OS because containers' core functionality are
 tied to the Linux kernel.
 
diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md
index 693f42fe3..40f69c0ba 100644
--- a/docs/source/markdown/podman-machine.1.md
+++ b/docs/source/markdown/podman-machine.1.md
@@ -7,7 +7,7 @@ podman\-machine - Manage Podman's virtual machine
 **podman machine** *subcommand*
 
 ## DESCRIPTION
-`podman machine` is a set of subcommands that manage Podman's virtual machine on MacOS.
+`podman machine` is a set of subcommands that manage Podman's virtual machine on macOS.
 
 ## SUBCOMMANDS
 
diff --git a/docs/source/markdown/podman-network-reload.1.md b/docs/source/markdown/podman-network-reload.1.md
index a4204a397..8f88585f2 100644
--- a/docs/source/markdown/podman-network-reload.1.md
+++ b/docs/source/markdown/podman-network-reload.1.md
@@ -9,7 +9,7 @@ podman\-network\-reload - Reload network configuration for containers
 ## DESCRIPTION
 Reload one or more container network configurations.
 
-Rootful Podman relies on iptables rules in order to provide network connectivity. If the iptables rules are deleted,
+Rootfull Podman relies on iptables rules in order to provide network connectivity. If the iptables rules are deleted,
 this happens for example with `firewall-cmd --reload`, the container loses network connectivity. This command restores
 the network connectivity.
 
diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index 6f3d7f1ca..701c0edf6 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -82,7 +82,7 @@ Assign a name to the pod.
 #### **\-\-network**=*mode*, **\-\-net**
 
 Set network mode for the pod. Supported values are
-- **bridge**: Create a network stack on the default bridge. This is the default for rootful containers.
+- **bridge**: Create a network stack on the default bridge. This is the default for rootfull containers.
 - **host**: Do not create a network namespace, all containers in the pod will use the host's network. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
 - Comma-separated list of the names of CNI networks the pod should join.
 - **slirp4netns[:OPTIONS,...]**: use slirp4netns to create a user network stack.  This is the default for rootless containers.  It is possible to specify these additional options:
diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md
index 79563fb57..2e038fd70 100644
--- a/docs/source/markdown/podman-pull.1.md
+++ b/docs/source/markdown/podman-pull.1.md
@@ -13,13 +13,8 @@ podman\-pull - Pull an image from a registry
 **podman image pull** [*options*] [*transport*]*name*[:*tag*|@*digest*]
 
 ## DESCRIPTION
-Copies an image from a registry onto the local machine. **podman pull** pulls an
-image from Docker Hub if a registry is not specified in the command line argument.
-If an image tag is not specified, **podman pull** defaults to the image with the
-**latest** tag (if it exists) and pulls it. After the image is pulled, podman will
-print the full image ID.  **podman pull** can also pull an image
-using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull
-images from archives and local storage using different transports.
+Copies an image from a registry onto the local machine. The **podman pull** command pulls an
+image.  If the image reference in the command line argument does not contain a registry, it is referred to as a`short-name` reference. If the image is a 'short-name' reference, Podman will prompt the user for the specific container registry to pull the image from, if an alias for the short-name has not been specified in the short-name-aliases.conf.  If an image tag is not specified, **podman pull** defaults to the image with the **latest** tag (if it exists) and pulls it. After the image is pulled, podman will print the full image ID.  **podman pull** can also pull an image using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull images from archives and local storage using different transports.
 
 ## Image storage
 Images are stored in local image storage.
@@ -201,9 +196,23 @@ Storing signatures
 
 ## FILES
 
+**short-name-aliases.conf** (`/var/cache/containers/short-name-aliases.conf`, `$HOME/.cache/containers/short-name-aliases.conf`)
+
+When users specify images that do not include the container registry where the
+image is stored, this is called a short name. The use of unqualified-search registries entails an ambiguity as it is unclear from which registry a given image, referenced by a short name, may be pulled from.
+
+Using short names is subject to the risk of hitting squatted registry namespaces. If the unqualified-search registries are set to ["public-registry.com",  "my-private-registry.com"] an attacker may take over a namespace of `public-registry.com` such that an image may be pulled from `public-registry.com` instead of the intended source `my-private-registry.com`.
+
+While it is highly recommended to always use fully-qualified image references, existing deployments using short names may not be easily changed. To circumvent the aforementioned ambiguity, so called short-name aliases can be configured that point to a fully-qualified image reference. Distributions often ship a default shortnames.conf expansion file in /etc/containers/registries.conf.d/ directory. Administrators can use this directory to add their own local short-name expansion files.
+
+When pulling an image, if the user does not specify the complete registry, container engines attempt to expand the short-name into a full name. If the command is executed with a tty, the user will be prompted to select a registry from the
+default list unqualified registries defined in registries.conf. The user's selection is then stored in a cache file to be used in all future short-name expansions. Rootfull short-names are stored in /var/cache/containers/short-name-aliases.conf. Rootless short-names are stored in the $HOME/.cache/containers/short-name-aliases.conf file.
+
+For more information on short-names, see `containers-registries.conf(5)`
+
 **registries.conf** (`/etc/containers/registries.conf`)
 
-	registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
+registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
 
 NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`.
 
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 0c412c2a6..3270394ac 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -150,7 +150,7 @@ Default is **enabled**.
 The **enabled** option will create a new cgroup under the cgroup-parent.
 The **disabled** option will force the container to not create CGroups, and thus conflicts with CGroup options (**\-\-cgroupns** and **\-\-cgroup-parent**).
 The **no-conmon** option disables a new CGroup only for the **conmon** process.
-The **split** option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **\-\-cgroup-parent** with **split**.
+The **split** option splits the current CGroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **\-\-cgroup-parent** with **split**.
 
 #### **\-\-cgroup-parent**=*path*
 
@@ -1075,8 +1075,8 @@ option conflicts with the **\-\-userns** and **\-\-subuidname** options. This
 option provides a way to map host UIDs to container UIDs. It can be passed
 several times to map different ranges.
 
-The _from_uid_ value is based upon the user running the command, either rootful or rootless users.
-* rootful user:  *container_uid*:*host_uid*:*amount*
+The _from_uid_ value is based upon the user running the command, either rootfull or rootless users.
+* rootfull user:  *container_uid*:*host_uid*:*amount*
 * rootless user: *container_uid*:*intermediate_uid*:*amount*
 
 When **podman run** is called by a privileged user, the option **\-\-uidmap**
@@ -1183,7 +1183,7 @@ Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman
 bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman
 container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume
 in the host to the container. If no such named volume exists, Podman will
-create one. (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.)
+create one. (Note when using the remote client, the volumes will be mounted from the remote server, not necessarily the client machine.)
 
 The _options_ is a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>
 
diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md
index 5ad4eff5b..fddcece60 100644
--- a/docs/source/markdown/podman-system-service.1.md
+++ b/docs/source/markdown/podman-system-service.1.md
@@ -9,7 +9,7 @@ podman\-system\-service - Run an API service
 ## DESCRIPTION
 The **podman system service** command creates a listening service that will answer API calls for Podman.  You may
 optionally provide an endpoint for the API in URI form.  For example, *unix:///tmp/foobar.sock* or *tcp:localhost:8080*.
-If no endpoint is provided, defaults will be used.  The default endpoint for a rootful
+If no endpoint is provided, defaults will be used.  The default endpoint for a rootfull
 service is *unix:///run/podman/podman.sock* and rootless is *unix://$XDG_RUNTIME_DIR/podman/podman.sock* (for
 example *unix:///run/user/1000/podman/podman.sock*)