docs: Follow man-pages(7) suggestions for SYNOPSIS

man-pages(7) has [1]:

> For commands, this shows the syntax of the command and its arguments
> (including options); boldface is used for as-is text and italics are
> used to indicate replaceable arguments. Brackets ([]) surround
> optional arguments, vertical bars (|) separate choices, and ellipses
> (...) can be repeated.

I've adjusted our SYNOPSIS entries to match that formatting, and
generally tried to make them more consistent with the precedent set by
the man-pages project.  Outside of the SYNOPSIS entry, I prefer using
backticks for literals, although in some places I've left the **
bolding to keep things visually similar to a nearby SYNOPSIS entry.

[1]: http://man7.org/linux/man-pages/man7/man-pages.7.html

Signed-off-by: W. Trevor King <wking@tremily.us>

Closes: #1027
Approved by: rhatdan

43 files changed, 111 insertions, 147 deletions

diff --git a/docs/podman-attach.1.md b/docs/podman-attach.1.md
index df13e7118..f56bde9e1 100644
--- a/docs/podman-attach.1.md
+++ b/docs/podman-attach.1.md
@@ -4,7 +4,7 @@
 podman\-attach - Attach to a running container
 
 ## SYNOPSIS
-**podman attach [OPTIONS] CONTAINER**
+**podman attach** [*options*] *container*
 
 ## DESCRIPTION
 The attach command allows you to attach to a running container using the container's ID
diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md
index 862ba3490..8d1ed9abd 100644
--- a/docs/podman-build.1.md
+++ b/docs/podman-build.1.md
@@ -4,7 +4,7 @@
 podman\-build - Build a container image using a Dockerfile.
 
 ## SYNOPSIS
-**podman** **build** [*options* [...]] **context**
+**podman build** [*options*] *context*
 
 ## DESCRIPTION
 **podman build** Builds an image using instructions from one or more Dockerfiles and a specified build context directory.
diff --git a/docs/podman-commit.1.md b/docs/podman-commit.1.md
index 781620e6c..4770eef09 100644
--- a/docs/podman-commit.1.md
+++ b/docs/podman-commit.1.md
@@ -4,18 +4,18 @@
 podman\-commit - Create new image based on the changed container
 
 ## SYNOPSIS
-**podman commit** [*options* [...]] CONTAINER IMAGE
+**podman commit** [*options*] *container* *image*
 
 ## DESCRIPTION
-**podman commit** creates an image based on a changed container. The author of the
-image can be set using the **--author** flag. Various image instructions can be
-configured with the **--change** flag and a commit message can be set using the
-**--message** flag. The container and its processes are paused while the image is
+`podman commit` creates an image based on a changed container. The author of the
+image can be set using the `--author` flag. Various image instructions can be
+configured with the `--change` flag and a commit message can be set using the
+`--message` flag. The container and its processes are paused while the image is
 committed. This minimizes the likelihood of data corruption when creating the new
-image. If this is not desired, the **--pause** flag can be set to false. When the commit
+image. If this is not desired, the `--pause` flag can be set to false. When the commit
 is complete, podman will print out the ID of the new image.
 
-If *imageName* does not begin with a registry name component, *localhost* will be added to the name.
+If *image* does not begin with a registry name component, `localhost` will be added to the name.
 
 ## OPTIONS
 
diff --git a/docs/podman-container-cleanup.1.md b/docs/podman-container-cleanup.1.md
index 50054afe2..5002e7142 100644
--- a/docs/podman-container-cleanup.1.md
+++ b/docs/podman-container-cleanup.1.md
@@ -4,7 +4,7 @@
 podman\-container\-cleanup - Cleanup Container storage and networks
 
 ## SYNOPSIS
-**podman container cleanup [OPTIONS] CONTAINER**
+**podman container cleanup** [*options*] *container*
 
 ## DESCRIPTION
 `podman container cleanup` cleans up exited containers by removing all mountpoints and network configuration from the host.  The container name or ID can be used.  The cleanup command does not remove the containers.  Running containers will not be cleaned up.
diff --git a/docs/podman-container.1.md b/docs/podman-container.1.md
index 71ee9489f..57495d3ba 100644
--- a/docs/podman-container.1.md
+++ b/docs/podman-container.1.md
@@ -4,7 +4,7 @@
 podman\-container - Manage containers
 
 ## SYNOPSIS
-**podman container SUBCOMMAND [OPTIONS]
+**podman container** *subcommand*
 
 ## DESCRIPTION
 The container command allows you to manage containers
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index e22efe4f3..9631655c1 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -4,14 +4,14 @@
 podman\-create - Create a new container
 
 ## SYNOPSIS
-**podman create** [*options* [...]] IMAGE [COMMAND] [ARG...]
+**podman create** [*options*] *image* [*command* [*arg* ...]]
 
 ## DESCRIPTION
 
 Creates a writable container layer over the specified image and prepares it for
 running the specified command. The container ID is then printed to STDOUT. This
 is similar to **podman run -d** except the container is never started. You can
-then use the **podman start <container_id>** command to start the container at
+then use the **podman start** *container* command to start the container at
 any point.
 
 The initial status of the container created with **podman create** is 'created'.
diff --git a/docs/podman-diff.1.md b/docs/podman-diff.1.md
index 427843d08..eae3521f5 100644
--- a/docs/podman-diff.1.md
+++ b/docs/podman-diff.1.md
@@ -4,7 +4,7 @@
 podman\-diff - Inspect changes on a container or image's filesystem
 
 ## SYNOPSIS
-**podman** **diff** [*options* [...]] NAME
+**podman diff** [*options*] *name*
 
 ## DESCRIPTION
 Displays changes on a container or image's filesystem.  The container or image will be compared to its parent layer
diff --git a/docs/podman-exec.1.md b/docs/podman-exec.1.md
index ec87eef84..910b68339 100644
--- a/docs/podman-exec.1.md
+++ b/docs/podman-exec.1.md
@@ -4,10 +4,7 @@
 podman\-exec - Execute a command in a running container
 
 ## SYNOPSIS
-**podman exec**
-**CONTAINER**
-[COMMAND] [ARG...]
-[**--help**|**-h**]
+**podman exec** *container* [*options*] [*command* [*arg* ...]]
 
 ## DESCRIPTION
 **podman exec** executes a command in a running container.
diff --git a/docs/podman-export.1.md b/docs/podman-export.1.md
index 92811b43e..6029beeb5 100644
--- a/docs/podman-export.1.md
+++ b/docs/podman-export.1.md
@@ -4,15 +4,12 @@
 podman export - Export container's filesystem contents as a tar archive
 
 ## SYNOPSIS
-**podman export**
-**CONTAINER**
-[**--output**|**-o**]
-[**--help**|**-h**]
+**podman export** [*options*] *container*
 
 ## DESCRIPTION
 **podman export** exports the filesystem of a container and saves it as a tarball
 on the local machine. **podman export** writes to STDOUT by default and can be
-redirected to a file using the **output flag**.
+redirected to a file using the `--output` flag.
 Note: `:` is a restricted character and cannot be part of the file name.
 
 **podman [GLOBAL OPTIONS]**
@@ -27,6 +24,10 @@ Note: `:` is a restricted character and cannot be part of the file name.
 
 Write to a file, default is STDOUT
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-history.1.md b/docs/podman-history.1.md
index 838994677..5b911a67f 100644
--- a/docs/podman-history.1.md
+++ b/docs/podman-history.1.md
@@ -4,13 +4,7 @@
 podman\-history - Shows the history of an image
 
 ## SYNOPSIS
-**podman history**
-**IMAGE[:TAG|DIGEST]**
-[**--human**|**-H**]
-[**--no-trunc**]
-[**--quiet**|**-q**]
-[**--format**]
-[**--help**|**-h**]
+**podman history** [*options*] *image*[:*tag*|@*digest*]
 
 ## DESCRIPTION
 **podman history** displays the history of an image by printing out information
@@ -31,12 +25,6 @@ Valid placeholders for the Go template are listed below:
 | .Size           | Size of layer on disk                                                         |
 | .Comment        | Comment for the layer                                                         |
 
-**podman [GLOBAL OPTIONS]**
-
-**podman history [GLOBAL OPTIONS]**
-
-**podman history [OPTIONS] IMAGE[:TAG|DIGEST]**
-
 ## OPTIONS
 
 **--human, -H**
@@ -55,6 +43,9 @@ Print the numeric IDs only
 
 Alter the output for a format like 'json' or a Go template.
 
+**--help**, **-h**
+
+Print usage statement
 
 ## EXAMPLES
 
diff --git a/docs/podman-image.1.md b/docs/podman-image.1.md
index d48e2ca83..64a798fda 100644
--- a/docs/podman-image.1.md
+++ b/docs/podman-image.1.md
@@ -4,7 +4,7 @@
 podman\-image - Manage images
 
 ## SYNOPSIS
-**podman image SUBCOMMAND [OPTIONS]
+**podman image** *subcommand*
 
 ## DESCRIPTION
 The image command allows you to manage images
diff --git a/docs/podman-images.1.md b/docs/podman-images.1.md
index 730ef4e3c..474226b9c 100644
--- a/docs/podman-images.1.md
+++ b/docs/podman-images.1.md
@@ -4,7 +4,7 @@
 podman\-images - List images in local storage
 
 ## SYNOPSIS
-**podman** **images** [*options* [...]]
+**podman** **images** [*options*]
 
 ## DESCRIPTION
 Displays locally stored images, their names, and their IDs.
diff --git a/docs/podman-import.1.md b/docs/podman-import.1.md
index 053a41538..70b382a63 100644
--- a/docs/podman-import.1.md
+++ b/docs/podman-import.1.md
@@ -4,12 +4,7 @@
 podman\-import - Import a tarball and save it as a filesystem image
 
 ## SYNOPSIS
-**podman import**
-**TARBALL**
-[**--change**|**-c**]
-[**--message**|**-m**]
-[**--help**|**-h**]
-[**-verbose**]
+**podman import** [*options*] *path*
 
 ## DESCRIPTION
 **podman import** imports a tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz)
@@ -18,12 +13,6 @@ Various image instructions can be configured with the **--change** flag and
 a commit message can be set using the **--message** flag.
 Note: `:` is a restricted character and cannot be part of the file name.
 
-**podman [GLOBAL OPTIONS]**
-
-**podman import [GLOBAL OPTIONS]**
-
-**podman import [OPTIONS] CONTAINER**
-
 ## OPTIONS
 
 **--change, -c**
@@ -40,6 +29,14 @@ Set commit message for imported image
 
 Shows progress on the import
 
+**-verbose**
+
+Print additional debugging information
+
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-info.1.md b/docs/podman-info.1.md
index 7ab9cd7a7..ccd7ff315 100644
--- a/docs/podman-info.1.md
+++ b/docs/podman-info.1.md
@@ -5,7 +5,7 @@ podman\-info - Display system information
 
 
 ## SYNOPSIS
-**podman** **info** [*options* [...]]
+**podman info** [*options*]
 
 
 ## DESCRIPTION
diff --git a/docs/podman-inspect.1.md b/docs/podman-inspect.1.md
index a814862a5..47a189e39 100644
--- a/docs/podman-inspect.1.md
+++ b/docs/podman-inspect.1.md
@@ -4,7 +4,7 @@
 podman\-inspect - Display a container or image's configuration
 
 ## SYNOPSIS
-**podman** **inspect** [*options* [...]] name [...]
+**podman inspect** [*options*] *name* ...
 
 ## DESCRIPTION
 This displays the low-level information on containers and images identified by name or ID. By default, this will render
diff --git a/docs/podman-kill.1.md b/docs/podman-kill.1.md
index 73bd658f5..115edc564 100644
--- a/docs/podman-kill.1.md
+++ b/docs/podman-kill.1.md
@@ -4,7 +4,7 @@
 podman\-kill - Kills one or more containers with a signal
 
 ## SYNOPSIS
-**podman kill [OPTIONS] CONTAINER [...]**
+**podman kill** [*options*] *container* ...
 
 ## DESCRIPTION
 The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal.
diff --git a/docs/podman-load.1.md b/docs/podman-load.1.md
index 6036353a2..a3299508e 100644
--- a/docs/podman-load.1.md
+++ b/docs/podman-load.1.md
@@ -4,11 +4,7 @@
 podman\-load - Load an image from docker archive
 
 ## SYNOPSIS
-**podman load**
-**NAME[:TAG|@DIGEST]**
-[**--input**|**-i**]
-[**--quiet**|**-q**]
-[**--help**|**-h**]
+**podman load** *name*[:*tag*|@*digest*]
 
 ## DESCRIPTION
 **podman load** copies an image from either **docker-archive** or **oci-archive** stored
@@ -38,6 +34,10 @@ Pathname of a signature policy file to use.  It is not recommended that this
 option be used, as the default behavior of using the system-wide default policy
 (frequently */etc/containers/policy.json*) is most often preferred
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-login.1.md b/docs/podman-login.1.md
index 6f0b8175b..27b47d9fd 100644
--- a/docs/podman-login.1.md
+++ b/docs/podman-login.1.md
@@ -4,12 +4,7 @@
 podman\-login - Login to a container registry
 
 ## SYNOPSIS
-**podman login**
-[**--help**|**-h**]
-[**--authfile**]
-[**--user**|**-u**]
-[**--password**|**-p**]
-**REGISTRY**
+**podman login** [*options*] *registry*
 
 ## DESCRIPTION
 **podman login** logs into a specified registry server with the correct username
@@ -47,6 +42,10 @@ Default certificates directory is _/etc/containers/certs.d_.
 
 Require HTTPS and verify certificates when contacting registries (default: true)
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-logout.1.md b/docs/podman-logout.1.md
index 7d8449915..e0c82b9ef 100644
--- a/docs/podman-logout.1.md
+++ b/docs/podman-logout.1.md
@@ -4,11 +4,7 @@
 podman\-logout - Logout of a container registry
 
 ## SYNOPSIS
-**podman logout**
-[**--help**|**-h**]
-[**--authfile**]
-[**--all**|**-a**]
-**REGISTRY**
+**podman logout** [*options*] *registry*
 
 ## DESCRIPTION
 **podman logout** logs out of a specified registry server by deleting the cached credentials
@@ -32,6 +28,10 @@ Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth
 
 Remove the cached credentials for all registries in the auth file
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-logs.1.md b/docs/podman-logs.1.md
index 63820ed6f..59fba69a1 100644
--- a/docs/podman-logs.1.md
+++ b/docs/podman-logs.1.md
@@ -4,7 +4,7 @@
 podman\-logs - Fetch the logs of a container
 
 ## SYNOPSIS
-**podman** **logs** [*options* [...]] container
+**podman** **logs** [*options*] *container*
 
 ## DESCRIPTION
 The podman logs command batch-retrieves whatever logs are present for a container at the time of execution.
diff --git a/docs/podman-mount.1.md b/docs/podman-mount.1.md
index 04210f087..6af618012 100644
--- a/docs/podman-mount.1.md
+++ b/docs/podman-mount.1.md
@@ -4,9 +4,7 @@
 podman\-mount - Mount the specifed working containers' root filesystem
 
 ## SYNOPSIS
-**podman** **mount**
-
-**podman** **mount** **containerID [...]**
+**podman** **mount** [*container* ...]
 
 ## DESCRIPTION
 Mounts the specified containers' root file system in a location which can be
diff --git a/docs/podman-pause.1.md b/docs/podman-pause.1.md
index bf52fac98..e37ac343a 100644
--- a/docs/podman-pause.1.md
+++ b/docs/podman-pause.1.md
@@ -4,7 +4,7 @@
 podman\-pause - Pause one or more containers
 
 ## SYNOPSIS
-**podman pause [OPTIONS] CONTAINER [...]**
+**podman pause** [*options*] *container* ...
 
 ## DESCRIPTION
 Pauses all the processes in one or more containers.  You may use container IDs or names as input.
diff --git a/docs/podman-port.1.md b/docs/podman-port.1.md
index 9dadd3865..a9fd903af 100644
--- a/docs/podman-port.1.md
+++ b/docs/podman-port.1.md
@@ -4,10 +4,10 @@
 podman\-port - List port mappings for a container
 
 ## SYNOPSIS
-**podman port [OPTIONS] CONTAINER [PRIVATE_PORT[/PROTO]]**
+**podman port** [*options*] *container* [*private-port*[/*proto*]]
 
 ## DESCRIPTION
-List port mappings for the CONTAINER, or lookup the public-facing port that is NAT-ed to the PRIVATE_PORT
+List port mappings for the *container* or lookup the public-facing port that is NAT-ed to the *private-port*.
 
 ## OPTIONS
 
diff --git a/docs/podman-ps.1.md b/docs/podman-ps.1.md
index f708c7d74..0ec39f5ac 100644
--- a/docs/podman-ps.1.md
+++ b/docs/podman-ps.1.md
@@ -4,12 +4,7 @@
 podman\-ps - Prints out information about containers
 
 ## SYNOPSIS
-**podman ps**
-[**--all**|**-a**]
-[**--no-trunc**]
-[**--quiet**|**-q**]
-[**--format**]
-[**--help**|**-h**]
+**podman ps** [*options*]
 
 ## DESCRIPTION
 **podman ps** lists the running containers on the system. Use the **--all** flag to view
@@ -23,12 +18,6 @@ all the containers information.  By default it lists:
  * port mappings the container is using
  * alternative names for the container
 
-**podman [GLOBAL OPTIONS]**
-
-**podman ps [GLOBAL OPTIONS]**
-
-**podman ps [OPTIONS]**
-
 ## OPTIONS
 
 **--all, -a**
@@ -103,6 +92,10 @@ Valid filters are listed below:
 | since           | [ID] or [Name] Containers created since this container              |
 | volume          | [VolumeName] or [MountpointDestination] Volume mounted in container |
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-pull.1.md b/docs/podman-pull.1.md
index 0061dfc70..a0f516068 100644
--- a/docs/podman-pull.1.md
+++ b/docs/podman-pull.1.md
@@ -4,9 +4,7 @@
 podman\-pull - Pull an image from a registry
 
 ## SYNOPSIS
-**podman pull**
-**NAME[:TAG|@DIGEST]**
-[**--help**|**-h**]
+**podman pull** [*options*] *name*[:*tag*|@*digest*]
 
 ## DESCRIPTION
 Copies an image from a registry onto the local machine. **podman pull** pulls an
@@ -14,7 +12,7 @@ image from Docker Hub if a registry is not specified in the command line argumen
 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
+using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull
 images from archives and local storage using different transports.
 
 ## imageID
@@ -45,12 +43,6 @@ Image stored in local container/storage
   **ostree:**_image_[**@**_/absolute/repo/path_]
   An image in local OSTree repository.  _/absolute/repo/path_ defaults to _/ostree/repo_.
 
-**podman [GLOBAL OPTIONS]**
-
-**podman pull [GLOBAL OPTIONS]**
-
-**podman pull NAME[:TAG|@DIGEST]**
-
 ## OPTIONS
 
 **--authfile**
@@ -85,6 +77,10 @@ Require HTTPS and verify certificates when contacting registries (default: true)
 then tls verification will be used, If set to false then tls verification will not be used. If not specified
 tls verification will be used unless the target registry is listed as an insecure registry in registries.conf.
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-push.1.md b/docs/podman-push.1.md
index ff6bbc854..8fc42bbf4 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* [...]] **imageID** [**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 653ccbf63..770c4f18e 100644
--- a/docs/podman-restart.1.md
+++ b/docs/podman-restart.1.md
@@ -4,7 +4,7 @@
 podman\-restart - Restart a container
 
 ## SYNOPSIS
-**podman attach [OPTIONS] CONTAINER [CONTAINER...]**
+**podman attach** [*options*] *container* ...
 
 ## DESCRIPTION
 The restart command allows containers to be restarted using their ID or name.
diff --git a/docs/podman-rm.1.md b/docs/podman-rm.1.md
index a3d1ec03c..5f542906d 100644
--- a/docs/podman-rm.1.md
+++ b/docs/podman-rm.1.md
@@ -4,10 +4,10 @@
 podman\-rm - Remove one or more containers
 
 ## SYNOPSIS
-**podman** **rm** [*options* [...]] container
+**podman rm** [*options*] *container*
 
 ## DESCRIPTION
-podman rm will remove one or more containers from the host.  The container name or ID can be used.  This does not remove images.  Running containers will not be removed without the -f option
+**podman rm** will remove one or more containers from the host.  The container name or ID can be used.  This does not remove images.  Running containers will not be removed without the `-f` option
 
 ## OPTIONS
 
diff --git a/docs/podman-rmi.1.md b/docs/podman-rmi.1.md
index f96ba5918..0d24ac27b 100644
--- a/docs/podman-rmi.1.md
+++ b/docs/podman-rmi.1.md
@@ -4,7 +4,7 @@
 podman\-rmi - Removes one or more images
 
 ## SYNOPSIS
-**podman** **rmi** **imageID [...]**
+**podman rmi** *image* ...
 
 ## DESCRIPTION
 Removes one or more locally stored images.
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index dfcbf7341..10b5d9e16 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -4,7 +4,7 @@
 podman\-run - Run a command in a new container
 
 ## SYNOPSIS
-**podman run** [*options* [...]] IMAGE [COMMAND] [ARG...]
+**podman run** [*options*] *image* [*command* [*arg* ...]]
 
 ## DESCRIPTION
 
diff --git a/docs/podman-save.1.md b/docs/podman-save.1.md
index a066d66da..afe69539e 100644
--- a/docs/podman-save.1.md
+++ b/docs/podman-save.1.md
@@ -4,12 +4,7 @@
 podman\-save - Save an image to docker-archive or oci-archive
 
 ## SYNOPSIS
-**podman save**
-**NAME[:TAG]**
-[**--quiet**|**-q**]
-[**--format**]
-[**--output**|**-o**]
-[**--help**|**-h**]
+**podman save** [*options*] *name*[:*tag*]
 
 ## DESCRIPTION
 **podman save** saves an image to either **docker-archive**, **oci-archive**, **oci-dir** (directory
@@ -48,6 +43,10 @@ Save image to **oci-archive**, **oci-dir** (directory with oci manifest type), o
 
 Suppress the output
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-search.1.md b/docs/podman-search.1.md
index 00900fcec..03267f15d 100644
--- a/docs/podman-search.1.md
+++ b/docs/podman-search.1.md
@@ -4,14 +4,7 @@
 podman\-search - Search a registry for an image
 
 ## SYNOPSIS
-**podman search**
-**TERM**
-[**--filter**|**-f**]
-[**--format**]
-[**--limit**]
-[**--no-trunc**]
-[**--registry**]
-[**--help**|**-h**]
+**podman search** [*options*] *term*
 
 ## DESCRIPTION
 **podman search** searches a registry or a list of registries for a matching image.
@@ -78,6 +71,10 @@ then tls verification will be used. If set to false then tls verification will n
 default registries will be searched through (in /etc/containers/registries.conf), and tls will be skipped if a default
 registry is listed in the insecure registries.
 
+**--help**, **-h**
+
+Print usage statement
+
 ## EXAMPLES
 
 ```
diff --git a/docs/podman-start.1.md b/docs/podman-start.1.md
index f38ed3d47..8f66c3a60 100644
--- a/docs/podman-start.1.md
+++ b/docs/podman-start.1.md
@@ -4,7 +4,7 @@
 podman\-start - Start one or more containers
 
 ## SYNOPSIS
-**podman start [OPTIONS] CONTAINER [...]**
+**podman start** [*options*] *container* ...
 
 ## DESCRIPTION
 Start one or more containers.  You may use container IDs or names as input.  The *attach* and *interactive*
diff --git a/docs/podman-stats.1.md b/docs/podman-stats.1.md
index 245384e02..8fc765326 100644
--- a/docs/podman-stats.1.md
+++ b/docs/podman-stats.1.md
@@ -4,7 +4,7 @@
 podman\-stats - Display a live stream of 1 or more containers' resource usage statistics
 
 ## SYNOPSIS
-**podman** **stats** [*options* [...]] [container]
+**podman stats** [*options*] [*container*]
 
 ## DESCRIPTION
 Display a live stream of one or more containers' resource usage statistics
diff --git a/docs/podman-stop.1.md b/docs/podman-stop.1.md
index 986a8e15d..98f74f269 100644
--- a/docs/podman-stop.1.md
+++ b/docs/podman-stop.1.md
@@ -4,7 +4,7 @@
 podman\-stop - Stop one or more containers
 
 ## SYNOPSIS
-**podman stop [OPTIONS] CONTAINER [...]**
+**podman stop** [*options*] *container* ...
 
 ## DESCRIPTION
 Stops one or more containers.  You may use container IDs or names as input. The **--timeout** switch
diff --git a/docs/podman-tag.1.md b/docs/podman-tag.1.md
index fe7945721..ef4a2a0f6 100644
--- a/docs/podman-tag.1.md
+++ b/docs/podman-tag.1.md
@@ -4,14 +4,19 @@
 podman\-tag - Add an additional name to a local image
 
 ## SYNOPSIS
-**podman [GLOBAL OPTIONS] tag IMAGE[:TAG] TARGET_NAME[:TAG]**
+**podman tag** *image*[:*tag*] *target-name*[:*tag*]
 [**--help**|**-h**]
 
 ## DESCRIPTION
 Assigns a new alias to an image.  An alias refers to the entire image name, including the optional
-**TAG** after the ':' If you do not provide a :TAG, podman will assume a :TAG of "latest" for both
-the IMAGE and the TARGET_NAME.
+*tag* after the `:`.  If you do not provide *tag*, podman will default to `latest` for both
+the *image* and the *target-name*.
 
+## OPTIONS
+
+**--help**, **-h**
+
+Print usage statement
 
 ## EXAMPLES
 
diff --git a/docs/podman-top.1.md b/docs/podman-top.1.md
index 9e7647079..a9abd8baf 100644
--- a/docs/podman-top.1.md
+++ b/docs/podman-top.1.md
@@ -4,13 +4,10 @@
 podman\-top - Display the running processes of a container
 
 ## SYNOPSIS
-**podman top**
-[**--help**|**-h**]
+**podman top** [*options*] *container* [*ps-options*]
 
 ## DESCRIPTION
-Display the running process of the container. ps-OPTION can be any of the options you would pass to a Linux ps command
-
-**podman [GLOBAL OPTIONS] top [OPTIONS]**
+Display the running process of the container. *ps-options* can be any of the options you would pass to `ps(1)`.
 
 ## OPTIONS
 
diff --git a/docs/podman-umount.1.md b/docs/podman-umount.1.md
index 2fe3da443..c13781dbf 100644
--- a/docs/podman-umount.1.md
+++ b/docs/podman-umount.1.md
@@ -4,7 +4,7 @@
 podman\-umount - Unmount the specified working containers' root file system.
 
 ## SYNOPSIS
-**podman** **umount** **containerID [...]**
+**podman umount** *container* ...
 
 ## DESCRIPTION
 Unmounts the specified containers' root file system.
diff --git a/docs/podman-unpause.1.md b/docs/podman-unpause.1.md
index c843ba4d8..9404e7648 100644
--- a/docs/podman-unpause.1.md
+++ b/docs/podman-unpause.1.md
@@ -4,7 +4,7 @@
 podman\-unpause - Unpause one or more containers
 
 ## SYNOPSIS
-**podman unpause [OPTIONS] CONTAINER [...]**
+**podman unpause** [*options*] *container* ...
 
 ## DESCRIPTION
 Unpauses the processes in one or more containers.  You may use container IDs or names as input.
diff --git a/docs/podman-varlink.1.md b/docs/podman-varlink.1.md
index 7d6c481e5..1e63ddec3 100644
--- a/docs/podman-varlink.1.md
+++ b/docs/podman-varlink.1.md
@@ -4,16 +4,12 @@
 podman\-varlink - Runs the varlink backend interface
 
 ## SYNOPSIS
-**podman varlink** [OPTIONS]
-[**--help**|**-h**]
-VARLINK_URI
+**podman varlink** [*options*] *uri*
 
 ## DESCRIPTION
-Starts the varlink service that allows varlink clients to interact with podman.  This should generally be done
+Starts the varlink service listening on *uri* that allows varlink clients to interact with podman.  This should generally be done
 with systemd.  See _Configuration_ below.
 
-**podman [GLOBAL OPTIONS] [OPTIONS] varlink VARLINK_URI**
-
 ## GLOBAL OPTIONS
 
 **--help, -h**
diff --git a/docs/podman-version.1.md b/docs/podman-version.1.md
index 2f4e9ba33..f1a1505d9 100644
--- a/docs/podman-version.1.md
+++ b/docs/podman-version.1.md
@@ -4,16 +4,17 @@
 podman\-version - Display the PODMAN Version Information
 
 ## SYNOPSIS
-**podman version**
-[**--help**|**-h**]
+**podman version** [*options*]
 
 ## DESCRIPTION
 Shows the the following information: Version, Go Version, Git Commit, Build Time,
 OS, and Architecture.
 
-**podman [GLOBAL OPTIONS]**
+## OPTIONS
 
-**podman version**
+**--help**, **-h**
+
+Print usage statement
 
 ## SEE ALSO
 podman(1), crio(8)
diff --git a/docs/podman-wait.1.md b/docs/podman-wait.1.md
index 085472a0c..3868928dd 100644
--- a/docs/podman-wait.1.md
+++ b/docs/podman-wait.1.md
@@ -4,17 +4,14 @@
 podman\-wait - Waits on one or more containers to stop and prints exit code
 
 ## SYNOPSIS
-**podman wait**
-[**--help**|**-h**]
+**podman wait** [*options*] *container*
 
 ## DESCRIPTION
 Waits on one or more containers to stop.  The container can be referred to by its
 name or ID.  In the case of multiple containers, podman will wait on each consecutively.
 After the container stops, the container's return code is printed.
 
-**podman [GLOBAL OPTIONS] wait **
-
-## GLOBAL OPTIONS
+## OPTIONS
 
 **--help, -h**
 
diff --git a/docs/podman.1.md b/docs/podman.1.md
index 6ce5283cf..bb84037a0 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -4,7 +4,7 @@
 podman - Simple management tool for containers and images
 
 ## SYNOPSIS
-**podman** [*options*] COMMAND
+**podman** [*options*] *command*
 
 # DESCRIPTION
 podman is a simple client only tool to help with debugging issues when daemons