man pages - consistency fixes

podman-generate and -play had the wrong NAMEs.

podman-restart and -volume-prune the wrong SYNOPSIS.

All the rest are varying degrees of minor:

  - missing a space between the NAME and description
  - multi-line SYNOPSIS that could be collapsed into one
  - use of UPPER CASE in synopsis instead of *asterisks*
  - improper use of **double asterisks** for options
  - varlink and version were transposed in podman-1
  - fixed inconsistencies between the description in
    the man page and that in the parent manpage. These
    are too numerous for me to fix all.

Added: script that could be used in CI to prevent future
such inconsistencies. It cannot be enabled yet because
there are still 35+ inconsistencies in need of cleaning.

This will be difficult to review on github. I suggest
pulling the PR and running 'git log -1 -p | cdif | less'

'cdif' is a handy tool for colorizing individual diffs between
lines:

   http://kaz-utashiro.github.io/cdif/

There are other such tools; use your favorite. Comparing
without visual highlights may be painful.

I also encourage you to run hack/man-page-checker and suggest
more fixes for the problems it's finding.

Signed-off-by: Ed Santiago <santiago@redhat.com>

29 files changed, 169 insertions, 76 deletions

diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index 3d51a5319..42fa9a359 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -1,7 +1,7 @@
 % podman-build(1)
 
 ## NAME
-podman\-build - Build a container image using a Dockerfile.
+podman\-build - Build a container image using a Dockerfile
 
 ## SYNOPSIS
 **podman build** [*options*] *context*
diff --git a/docs/podman-container-exists.1.md b/docs/podman-container-exists.1.md
index 76701e2c2..8feb736f8 100644
--- a/docs/podman-container-exists.1.md
+++ b/docs/podman-container-exists.1.md
@@ -2,12 +2,10 @@
 % Brent Baude
 % November 2018
 # NAME
-podman-container-exists- Check if a container exists in local storage
+podman-container-exists - Check if a container exists in local storage
 
 # SYNOPSIS
-**podman container exists**
-[**-h**|**--help**]
-CONTAINER
+**podman container exists** [*-h*|*--help*] *container*
 
 # DESCRIPTION
 **podman container exists** checks if a container exists in local storage. The **ID** or **Name**
diff --git a/docs/podman-container-prune.1.md b/docs/podman-container-prune.1.md
index 1f3ef1d41..194dd3dae 100644
--- a/docs/podman-container-prune.1.md
+++ b/docs/podman-container-prune.1.md
@@ -5,8 +5,7 @@
 podman-container-prune - Remove all stopped containers
 
 # SYNOPSIS
-**podman container prune**
-[**-h**|**--help**]
+**podman container prune** [*-h*|*--help*]
 
 # DESCRIPTION
 **podman container prune** removes all stopped containers from local storage.
diff --git a/docs/podman-cp.1.md b/docs/podman-cp.1.md
index 7774542e8..44612003d 100644
--- a/docs/podman-cp.1.md
+++ b/docs/podman-cp.1.md
@@ -4,12 +4,12 @@
 podman\-cp - Copy files/folders between a container and the local filesystem
 
 ## SYNOPSIS
-**podman cp [CONTAINER:]SRC_PATH [CONTAINER:]DEST_PATH**
+**podman cp** [*container*:]*src_path* [*container*:]*dest_path*
 
 ## DESCRIPTION
-Copies the contents of **SRC_PATH** to the **DEST_PATH**. You can copy from the containers's filesystem to the local machine or the reverse, from the local filesystem to the container.
+Copies the contents of **src_path** to the **dest_path**. You can copy from the containers's filesystem to the local machine or the reverse, from the local filesystem to the container.
 
-The CONTAINER can be a running or stopped container. The **SRC_PATH** or **DEST_PATH** can be a file or directory.
+The CONTAINER can be a running or stopped container. The **src_path** or **dest_path** can be a file or directory.
 
 The **podman cp** command assumes container paths are relative to the container's / (root) directory.
 
@@ -20,36 +20,36 @@ The command sees **compassionate_darwin:/tmp/foo/myfile.txt** and **compassionat
 Local machine paths can be an absolute or relative value.
 The command interprets a local machine's relative paths as relative to the current working directory where **podman cp** is run.
 
-Assuming a path separator of /, a first argument of **SRC_PATH** and second argument of **DEST_PATH**, the behavior is as follows:
+Assuming a path separator of /, a first argument of **src_path** and second argument of **dest_path**, the behavior is as follows:
 
-**SRC_PATH** specifies a file
-  - **DEST_PATH** does not exist
-	- the file is saved to a file created at **DEST_PATH**
-  - **DEST_PATH** does not exist and ends with /
-	- **DEST_PATH** is created as a directory and the file is copied into this directory using the basename from **SRC_PATH**
-  - **DEST_PATH** exists and is a file
+**src_path** specifies a file
+  - **dest_path** does not exist
+	- the file is saved to a file created at **dest_path**
+  - **dest_path** does not exist and ends with /
+	- **dest_path** is created as a directory and the file is copied into this directory using the basename from **src_path**
+  - **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**
+  - **dest_path** exists and is a directory
+	- the file is copied into this directory using the basename from **src_path**
 
-**SRC_PATH** specifies a directory
-  - **DEST_PATH** does not exist
-	- **DEST_PATH** is created as a directory and the contents of the source directory are copied into this directory
-  - **DEST_PATH** exists and is a file
+**src_path** specifies a directory
+  - **dest_path** does not exist
+	- **dest_path** is created as a directory and the contents of the source directory are copied into this directory
+  - **dest_path** exists and is a file
 	- Error condition: cannot copy a directory to a file
-  - **DEST_PATH** exists and is a directory
-	- **SRC_PATH** ends with /
+  - **dest_path** exists and is a directory
+	- **src_path** ends with /
 		- the source directory is copied into this directory
-	- **SRC_PATH** ends with /. (that is: slash followed by dot)
+	- **src_path** ends with /. (that is: slash followed by dot)
 		- the content of the source directory is copied into this directory
 
-The command requires **SRC_PATH** and **DEST_PATH** to exist according to the above rules.
+The command requires **src_path** and **dest_path** to exist according to the above rules.
 
-If **SRC_PATH** is local and is a symbolic link, the symbolic target, is copied by default.
+If **src_path** is local and is a symbolic link, the symbolic target, is copied by default.
 
 A colon (:) is used as a delimiter between CONTAINER and its path.
 
-You can also use : when specifying paths to a **SRC_PATH** or **DEST_PATH** on a local machine, for example, `file:name.txt`.
+You can also use : when specifying paths to a **src_path** or **dest_path** on a local machine, for example, `file:name.txt`.
 
 If you use a : in a local machine path, you must be explicit with a relative or absolute path, for example:
 	`/path/to/file:name.txt` or `./file:name.txt`
diff --git a/docs/podman-events.1.md b/docs/podman-events.1.md
index b4ebe7649..3463d2aaa 100644
--- a/docs/podman-events.1.md
+++ b/docs/podman-events.1.md
@@ -1,7 +1,7 @@
 % podman-events(1)
 
 ## NAME
-podman\-events- Monitor Podman events
+podman\-events - Monitor Podman events
 
 ## SYNOPSIS
 **podman events** [*options*]
diff --git a/docs/podman-export.1.md b/docs/podman-export.1.md
index a8810f534..d0e365056 100644
--- a/docs/podman-export.1.md
+++ b/docs/podman-export.1.md
@@ -1,7 +1,7 @@
 % podman-export(1)
 
 ## NAME
-podman\-export - Export container's filesystem contents as a tar archive
+podman\-export - Export a container's filesystem contents as a tar archive
 
 ## SYNOPSIS
 **podman export** [*options*] *container*
diff --git a/docs/podman-generate-kube.1.md b/docs/podman-generate-kube.1.md
index d4bed8ab1..b6fa78606 100644
--- a/docs/podman-generate-kube.1.md
+++ b/docs/podman-generate-kube.1.md
@@ -5,10 +5,7 @@
 podman-generate-kube - Generate Kubernetes YAML
 
 # SYNOPSIS
-**podman generate kube **
-[**-h**|**--help**]
-[**-s**][**--service**]
-CONTAINER|POD
+**podman generate kube** [*-s*][*--service*] *container* | *pod*
 
 # DESCRIPTION
 **podman generate kube** will generate Kubernetes Pod YAML (v1 specification) from a podman container or pod. Whether
diff --git a/docs/podman-generate.1.md b/docs/podman-generate.1.md
index 66afacd0b..d1736f38e 100644
--- a/docs/podman-generate.1.md
+++ b/docs/podman-generate.1.md
@@ -1,7 +1,7 @@
 % podman-generate(1)
 
 ## NAME
-podman\-container - generate structured data based for a containers and pods
+podman\-generate - Generate structured data based for a containers and pods
 
 ## SYNOPSIS
 **podman generate** *subcommand*
diff --git a/docs/podman-healthcheck-run.1.md b/docs/podman-healthcheck-run.1.md
index 8cecb8eaa..e19c6250c 100644
--- a/docs/podman-healthcheck-run.1.md
+++ b/docs/podman-healthcheck-run.1.md
@@ -1,7 +1,7 @@
 % podman-healthcheck-run(1)
 
 ## NAME
-podman\-healthcheck\-run- Run a container healthcheck
+podman\-healthcheck\-run - Run a container healthcheck
 
 ## SYNOPSIS
 **podman healthcheck run** [*options*] *container*
diff --git a/docs/podman-healthcheck.1.md b/docs/podman-healthcheck.1.md
index 68d403231..91c3e4345 100644
--- a/docs/podman-healthcheck.1.md
+++ b/docs/podman-healthcheck.1.md
@@ -1,7 +1,7 @@
 % podman-healthcheck(1)
 
 ## NAME
-podman\-healthcheck- Manage healthchecks for containers
+podman\-healthcheck - Manage healthchecks for containers
 
 ## SYNOPSIS
 **podman healthcheck** *subcommand*
diff --git a/docs/podman-history.1.md b/docs/podman-history.1.md
index bca8cb1d2..8335428a8 100644
--- a/docs/podman-history.1.md
+++ b/docs/podman-history.1.md
@@ -1,7 +1,7 @@
 % podman-history(1)
 
 ## NAME
-podman\-history - Shows the history of an image
+podman\-history - Show the history of an image
 
 ## SYNOPSIS
 **podman history** [*options*] *image*[:*tag*|@*digest*]
diff --git a/docs/podman-image-exists.1.md b/docs/podman-image-exists.1.md
index e04c23721..1dc264a6b 100644
--- a/docs/podman-image-exists.1.md
+++ b/docs/podman-image-exists.1.md
@@ -2,12 +2,10 @@
 % Brent Baude
 % November 2018
 # NAME
-podman-image-exists- Check if an image exists in local storage
+podman-image-exists - Check if an image exists in local storage
 
 # SYNOPSIS
-**podman image exists**
-[**-h**|**--help**]
-IMAGE
+**podman image exists** [*-h*|*--help*] *image*
 
 # DESCRIPTION
 **podman image exists** checks if an image exists in local storage. The **ID** or **Name**
diff --git a/docs/podman-image-prune.1.md b/docs/podman-image-prune.1.md
index df912c380..7d5fd2fc8 100644
--- a/docs/podman-image-prune.1.md
+++ b/docs/podman-image-prune.1.md
@@ -5,9 +5,7 @@
 podman-image-prune - Remove all unused images
 
 # SYNOPSIS
-**podman image prune**
-[**-a**|**--all**]
-[**-h**|**--help**]
+**podman image prune** [*-a*|*--all*] [*-h*|*--help*]
 
 # DESCRIPTION
 **podman image prune** removes all dangling images from local storage. With the `all` option,
diff --git a/docs/podman-image-sign.1.md b/docs/podman-image-sign.1.md
index 232bc87fe..804ee03db 100644
--- a/docs/podman-image-sign.1.md
+++ b/docs/podman-image-sign.1.md
@@ -1,7 +1,7 @@
 % podman-image-sign(1)
 
 # NAME
-podman-image-sign- Create a signature for an image
+podman-image-sign - Create a signature for an image
 
 # SYNOPSIS
 **podman image sign**
diff --git a/docs/podman-image-tree.1.md b/docs/podman-image-tree.1.md
index 014499d6a..acd5ffcbf 100644
--- a/docs/podman-image-tree.1.md
+++ b/docs/podman-image-tree.1.md
@@ -4,7 +4,7 @@
 podman\-image\-tree - Prints layer hierarchy of an image in a tree format
 
 ## SYNOPSIS
-**podman image tree** [*image*:*tag*]**|**[*image-id*]
+**podman image tree** [*image*:*tag*]|[*image-id*]
 [**--help**|**-h**]
 
 ## DESCRIPTION
diff --git a/docs/podman-image-trust.1.md b/docs/podman-image-trust.1.md
index 819035040..f96a7996f 100644
--- a/docs/podman-image-trust.1.md
+++ b/docs/podman-image-trust.1.md
@@ -1,11 +1,11 @@
 % podman-image-trust "1"
 
 # NAME
-podman\-trust - Manage container registry image trust policy
+podman\-image\-trust - Manage container registry image trust policy
 
 
 # SYNOPSIS
-**podman image trust set|show**
+**podman image trust** set|show
 [**-h**|**--help**]
 [**-j**|**--json**]
 [**--raw**]
diff --git a/docs/podman-image.1.md b/docs/podman-image.1.md
index 333a75b69..01cf08d62 100644
--- a/docs/podman-image.1.md
+++ b/docs/podman-image.1.md
@@ -14,13 +14,13 @@ The image command allows you to manage images
 | Command  | Man Page                                        | Description                                                                 |
 | -------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
 | build    | [podman-build(1)](podman-build.1.md)            | Build a container using a Dockerfile.                                       |
-| exists   | [podman-image-exists(1)](podman-image-exists.1.md) | Check if a image exists in local storage.                                |
+| exists   | [podman-image-exists(1)](podman-image-exists.1.md) | Check if an image exists in local storage.                               |
 | history  | [podman-history(1)](podman-history.1.md)        | Show the history of an image.                                               |
 | import   | [podman-import(1)](podman-import.1.md)          | Import a tarball and save it as a filesystem image.                         |
 | inspect  | [podman-inspect(1)](podman-inspect.1.md)        | Display a image or image's configuration.                                   |
 | list     | [podman-images(1)](podman-images.1.md)          | List the container images on the system.(alias ls)                          |
 | load     | [podman-load(1)](podman-load.1.md)              | Load an image from the docker archive.                                      |
-| prune    | [podman-image-prune(1)](podman-image-prune.1.md)| Removed all unused images from the local store.                             |
+| prune    | [podman-image-prune(1)](podman-image-prune.1.md)| Remove all unused images from the local store.                              |
 | pull     | [podman-pull(1)](podman-pull.1.md)              | Pull an image from a registry.                                              |
 | push     | [podman-push(1)](podman-push.1.md)              | Push an image from local storage to elsewhere.                              |
 | rm       | [podman-rmi(1)](podman-rmi.1.md)                | Removes one or more locally stored images.                                  |
diff --git a/docs/podman-play-kube.1.md b/docs/podman-play-kube.1.md
index 2264f7a88..a9af961cd 100644
--- a/docs/podman-play-kube.1.md
+++ b/docs/podman-play-kube.1.md
@@ -5,7 +5,7 @@
 podman-play-kube - Create pods and containers based on Kubernetes YAML
 
 # SYNOPSIS
-**podman play kube **
+**podman play kube**
 [**-h**|**--help**]
 [**--authfile**]
 [**--cert-dir**]
diff --git a/docs/podman-play.1.md b/docs/podman-play.1.md
index 6d2a7beba..f0bf8ea41 100644
--- a/docs/podman-play.1.md
+++ b/docs/podman-play.1.md
@@ -1,7 +1,7 @@
 % podman-play(1)
 
 ## NAME
-podman\-container - play pods and containers based on a structured input file
+podman\-play - Play pods and containers based on a structured input file
 
 ## SYNOPSIS
 **podman play** *subcommand*
diff --git a/docs/podman-pod-exists.1.md b/docs/podman-pod-exists.1.md
index 8fb2fc90e..da3947511 100644
--- a/docs/podman-pod-exists.1.md
+++ b/docs/podman-pod-exists.1.md
@@ -2,12 +2,10 @@
 % Brent Baude
 % December 2018
 # NAME
-podman-pod-exists- Check if a pod exists in local storage
+podman-pod-exists - Check if a pod exists in local storage
 
 # SYNOPSIS
-**podman pod exists**
-[**-h**|**--help**]
-POD
+**podman pod exists** [*-h*|*--help*] *pod*
 
 # DESCRIPTION
 **podman pod exists** checks if a pod exists in local storage. The **ID** or **Name**
diff --git a/docs/podman-pod-top.1.md b/docs/podman-pod-top.1.md
index a77ca2b37..b235a70ad 100644
--- a/docs/podman-pod-top.1.md
+++ b/docs/podman-pod-top.1.md
@@ -4,7 +4,7 @@
 podman\-pod\-top - Display the running processes of containers in a pod
 
 ## SYNOPSIS
-**podman top** [*options*] *pod* [*format-descriptors*]
+**podman pod top** [*options*] *pod* [*format-descriptors*]
 
 ## DESCRIPTION
 Display the running process of containers in a pod. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process.
diff --git a/docs/podman-pod.1.md b/docs/podman-pod.1.md
index 8f8403a40..1846d0411 100644
--- a/docs/podman-pod.1.md
+++ b/docs/podman-pod.1.md
@@ -19,7 +19,7 @@ podman pod is a set of subcommands that manage pods, or groups of containers.
 | kill    | [podman-pod-kill(1)](podman-pod-kill.1.md)        | Kill the main process of each container in pod.                                |
 | pause   | [podman-pod-pause(1)](podman-pod-pause.1.md)      | Pause one or more pods.                                                        |
 | ps      | [podman-pod-ps(1)](podman-pod-ps.1.md)            | Prints out information about pods.                                             |
-| restart | [podman-pod-restart(1)](podman-pod-restart.1.md)  | Restart one or mode pods.                                                      |
+| restart | [podman-pod-restart(1)](podman-pod-restart.1.md)  | Restart one or more pods.                                                      |
 | rm      | [podman-pod-rm(1)](podman-pod-rm.1.md)            | Remove one or more pods.                                                       |
 | start   | [podman-pod-start(1)](podman-pod-start.1.md)      | Start one or more pods.                                                        |
 | stats   | [podman-pod-stats(1)](podman-pod-stats.1.md)      | Display live stream resource usage stats for containers in one or more pods.   |
diff --git a/docs/podman-push.1.md b/docs/podman-push.1.md
index 3ce156010..bb17c7e03 100644
--- a/docs/podman-push.1.md
+++ b/docs/podman-push.1.md
@@ -4,7 +4,7 @@
 podman\-push - Push an image from local storage to elsewhere
 
 ## SYNOPSIS
-**podman push** [*options*] **image** [**destination**]
+**podman push** [*options*] *image* [*destination*]
 
 ## DESCRIPTION
 Pushes an image from local storage to a specified destination.
diff --git a/docs/podman-restart.1.md b/docs/podman-restart.1.md
index dd28e34c7..a20eee243 100644
--- a/docs/podman-restart.1.md
+++ b/docs/podman-restart.1.md
@@ -1,10 +1,10 @@
 % podman-restart(1)
 
 ## NAME
-podman\-restart - Restart a container
+podman\-restart - Restart one or more containers
 
 ## SYNOPSIS
-**podman attach** [*options*] *container* ...
+**podman restart** [*options*] *container* ...
 
 ## DESCRIPTION
 The restart command allows containers to be restarted using their ID or name.
diff --git a/docs/podman-volume-inspect.1.md b/docs/podman-volume-inspect.1.md
index 6d5b184ee..c22c80bb7 100644
--- a/docs/podman-volume-inspect.1.md
+++ b/docs/podman-volume-inspect.1.md
@@ -4,7 +4,7 @@
 podman\-volume\-inspect - Inspect one or more volumes
 
 ## SYNOPSIS
-**podman volume inspect** [*options*]
+**podman volume inspect** [*options*] *volume*...
 
 ## DESCRIPTION
 
diff --git a/docs/podman-volume-prune.1.md b/docs/podman-volume-prune.1.md
index a06bb2fa4..437cad4e5 100644
--- a/docs/podman-volume-prune.1.md
+++ b/docs/podman-volume-prune.1.md
@@ -4,7 +4,7 @@
 podman\-volume\-prune - Remove all unused volumes
 
 ## SYNOPSIS
-**podman volume rm** [*options*]
+**podman volume prune** [*options*]
 
 ## DESCRIPTION
 
diff --git a/docs/podman-wait.1.md b/docs/podman-wait.1.md
index 672316eef..2d145527b 100644
--- a/docs/podman-wait.1.md
+++ b/docs/podman-wait.1.md
@@ -1,7 +1,7 @@
 % podman-wait "1"
 
 ## NAME
-podman\-wait - Waits on one or more containers to stop and prints exit code
+podman\-wait - Wait on one or more containers to stop and print their exit codes
 
 ## SYNOPSIS
 **podman wait** [*options*] *container*
diff --git a/docs/podman.1.md b/docs/podman.1.md
index c4dc168c7..b808a7fa5 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -131,9 +131,9 @@ the exit codes follow the `chroot` standard, see below:
 | Command                                   | Description                                                                    |
 | ----------------------------------------- | ------------------------------------------------------------------------------ |
 | [podman-attach(1)](podman-attach.1.md)    | Attach to a running container.                                                 |
-| [podman-build(1)](podman-build.1.md)      | Build a container using a Dockerfile.                                          |
+| [podman-build(1)](podman-build.1.md)      | Build a container image using a Dockerfile.                                    |
 | [podman-commit(1)](podman-commit.1.md)    | Create new image based on the changed container.                               |
-| [podman-container(1)](podman-container.1.md)    | Manage Containers.                                                       |
+| [podman-container(1)](podman-container.1.md)    | Manage containers.                                                       |
 | [podman-cp(1)](podman-cp.1.md)            | Copy files/folders between a container and the local filesystem.               |
 | [podman-create(1)](podman-create.1.md)    | Create a new container.                                                        |
 | [podman-diff(1)](podman-diff.1.md)        | Inspect changes on a container or image's filesystem.                          |
@@ -143,13 +143,13 @@ the exit codes follow the `chroot` standard, see below:
 | [podman-generate(1)](podman-generate.1.md)| Generate structured data based for a containers and pods.                      |
 | [podman-healthcheck(1)](podman-healthcheck.1.md)| Manage healthchecks for containers                                       |
 | [podman-history(1)](podman-history.1.md)  | Show the history of an image.                                                  |
-| [podman-image(1)](podman-image.1.md)      | Manage Images.                                                                 |
+| [podman-image(1)](podman-image.1.md)      | Manage images.                                                                 |
 | [podman-images(1)](podman-images.1.md)    | List images in local storage.                                                  |
 | [podman-import(1)](podman-import.1.md)    | Import a tarball and save it as a filesystem image.                            |
 | [podman-info(1)](podman-info.1.md)        | Displays Podman related system information.                                    |
 | [podman-inspect(1)](podman-inspect.1.md)  | Display a container or image's configuration.                                  |
 | [podman-kill(1)](podman-kill.1.md)        | Kill the main process in one or more containers.                               |
-| [podman-load(1)](podman-load.1.md)        | Load an image from the docker archive.                                         |
+| [podman-load(1)](podman-load.1.md)        | Load an image from a container image archive into container storage.           |
 | [podman-login(1)](podman-login.1.md)      | Login to a container registry.                                                 |
 | [podman-logout(1)](podman-logout.1.md)    | Logout of a container registry.                                                |
 | [podman-logs(1)](podman-logs.1.md)        | Display the logs of a container.                                               |
@@ -157,17 +157,17 @@ the exit codes follow the `chroot` standard, see below:
 | [podman-pause(1)](podman-pause.1.md)      | Pause one or more containers.                                                  |
 | [podman-play(1)](podman-play.1.md)        | Play pods and containers based on a structured input file.                     |
 | [podman-pod(1)](podman-pod.1.md)          | Management tool for groups of containers, called pods.                         |
-| [podman-port(1)](podman-port.1.md)        | List port mappings for the container.                                          |
+| [podman-port(1)](podman-port.1.md)        | List port mappings for a container.                                            |
 | [podman-ps(1)](podman-ps.1.md)            | Prints out information about containers.                                       |
 | [podman-pull(1)](podman-pull.1.md)        | Pull an image from a registry.                                                 |
 | [podman-push(1)](podman-push.1.md)        | Push an image from local storage to elsewhere.                                 |
 | [podman-restart(1)](podman-restart.1.md)  | Restart one or more containers.                                                |
 | [podman-rm(1)](podman-rm.1.md)            | Remove one or more containers.                                                 |
 | [podman-rmi(1)](podman-rmi.1.md)          | Removes one or more locally stored images.                                     |
-| [podman-run(1)](podman-run.1.md)          | Run a command in a container.                                                  |
-| [podman-save(1)](podman-save.1.md)        | Save an image to docker-archive or oci.                                        |
+| [podman-run(1)](podman-run.1.md)          | Run a command in a new container.                                              |
+| [podman-save(1)](podman-save.1.md)        | Save an image to a container archive.                                          |
 | [podman-search(1)](podman-search.1.md)    | Search a registry for an image.                                                |
-| [podman-start(1)](podman-start.1.md)      | Starts one or more containers.                                                 |
+| [podman-start(1)](podman-start.1.md)      | Start one or more containers.                                                  |
 | [podman-stats(1)](podman-stats.1.md)      | Display a live stream of one or more container's resource usage statistics.    |
 | [podman-stop(1)](podman-stop.1.md)        | Stop one or more running containers.                                           |
 | [podman-system(1)](podman-system.1.md)    | Manage podman.                                                                 |
@@ -175,8 +175,8 @@ the exit codes follow the `chroot` standard, see below:
 | [podman-top(1)](podman-top.1.md)          | Display the running processes of a container.                                  |
 | [podman-umount(1)](podman-umount.1.md)    | Unmount a working container's root filesystem.                                 |
 | [podman-unpause(1)](podman-unpause.1.md)  | Unpause one or more containers.                                                |
-| [podman-varlink(1)](podman-varlink.1.md)  | Display the Podman version information.                                        |
-| [podman-version(1)](podman-version.1.md)  | Runs the varlink backend interface.                                            |
+| [podman-version(1)](podman-varlink.1.md)  | Runs the varlink backend interface.                                            |
+| [podman-varlink(1)](podman-version.1.md)  | Display the Podman version information.                                        |
 | [podman-volume(1)](podman-volume.1.md)    | Manage Volumes.                                                                |
 | [podman-wait(1)](podman-wait.1.md)        | Wait on one or more containers to stop and print their exit codes.             |
 
diff --git a/hack/man-page-checker b/hack/man-page-checker
new file mode 100755
index 000000000..8e9b5a50d
--- /dev/null
+++ b/hack/man-page-checker
@@ -0,0 +1,105 @@
+#!/bin/bash
+#
+# man-page-name-checker - validate and cross-reference man page names
+#
+# FIXME as of 2019-03-20 there are still four files with inconsistent names:
+#
+#    podman-logs.1.md         NAME= podman-container-logs
+#    podman-info.1.md         NAME= podman-system-info
+#    podman-rm.1.md           NAME= podman-container-rm
+#    podman-rmi.1.md          NAME= podman-image-rm
+#
+# If those four get renamed (with suitable symlink fixes), this script
+# can be enabled in CI to prevent future inconsistencies.
+#
+
+die() {
+    echo "$(basename $0): $*" >&2
+    exit 1
+}
+
+cd $(dirname $0)/../docs || die "Please run me from top-level libpod dir"
+
+rc=0
+
+for md in *.1.md;do
+    # Read the first line after '# NAME' (or '## NAME'). (FIXME: # and ##
+    #               are not the same; should we stick to one convention?)
+    # There may be more than one name, e.g. podman-info.1.md has
+    # podman-system-info then another line with podman-info. We
+    # care only about the first.
+    name=$(egrep -A1 '^#* NAME' $md|tail -1|awk '{print $1}' | tr -d \\\\)
+
+    if [ "$name" != "$(basename $md .1.md)" ]; then
+        printf "%-32s  NAME= %s\n" $md $name
+        rc=1
+    fi
+done
+
+# Pass 2: compare descriptions.
+#
+# Make sure the descriptive text in podman-foo.1.md matches the one
+# in the table in podman.1.md.
+for md in *.1.md;do
+    desc=$(egrep -A1 '^#* NAME' $md|tail -1|sed -e 's/^podman[^ ]\+ - //')
+
+    # podman.1.md has a two-column table; podman-*.1.md all have three.
+    parent=$(echo $md | sed -e 's/^\(.*\)-.*$/\1.1.md/')
+    x=3
+    if expr -- "$parent" : ".*-" >/dev/null; then
+        x=4
+    fi
+
+    # Find the descriptive text in the parent man page.
+    # Strip off the final period; let's not warn about such minutia.
+    parent_desc=$(grep $md $parent | awk -F'|' "{print \$$x}" | sed -e 's/^ \+//' -e 's/ \+$//' -e 's/\.$//')
+
+    if [ "$desc" != "$parent_desc" ]; then
+        echo
+        printf "  %-32s = '%s'\n" $md "$desc"
+        printf "  %-32s = '%s'\n" $parent "$parent_desc"
+        rc=1
+    fi
+done
+
+# Pass 3: compare synopses.
+#
+# Make sure the SYNOPSIS line in podman-foo.1.md reads '**podman foo** ...'
+for md in *.1.md;do
+    # FIXME: several pages have a multi-line form of SYNOPSIS in which
+    #        many or all flags are enumerated. Some of these are trivial
+    #        and really should be made into one line (podman-container-exists,
+    #        container-prune, others); some are more complicated and I
+    #        would still like to see them one-lined (container-runlabel,
+    #        image-trust) but I'm not 100% comfortable doing so myself.
+    #        To view those:
+    #           $ less $(for i in docs/*.1.md;do x=$(grep -A2 '^#* SYNOPSIS' $i|tail -1); if [ -n "$x" ]; then echo $i;fi;done)
+    #
+    synopsis=$(egrep -A1 '^#* SYNOPSIS' $md|tail -1)
+
+    # Command name must be bracketed by double asterisks; options and
+    # arguments are bracketed by single ones.
+    #   E.g. '**podman volume inspect** [*options*] *volume*...'
+    # Get the command name, and confirm that it matches the md file name.
+    cmd=$(echo "$synopsis" | sed -e 's/\(.*\)\*\*.*/\1/' | tr -d \* | tr ' ' '-')
+    if [ "$md" != "$cmd.1.md" ]; then
+        printf "  %-32s SYNOPSIS = %s\n" $md "$cmd"
+        rc=1
+    fi
+
+    # The convention is to use UPPER CASE in 'podman foo --help',
+    # but *lower case bracketed by asterisks* in the man page
+    if expr "$synopsis" : ".*[A-Z]" >/dev/null; then
+        printf "  %-32s UPPER-CASE '%s'\n" $md "$synopsis"
+        rc=1
+    fi
+
+    # (for debugging, and getting a sense of standard conventions)
+    #printf "  %-32s ------ '%s'\n" $md "$synopsis"
+
+    # FIXME: some day: run ./bin/podman "args", extract Usage,
+    #      strip off [flags] and [options], then compare arguments
+done
+
+
+exit $rc