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>

1 files changed, 10 insertions, 10 deletions

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.             |