man page checker: enforce stricter options format

Followup to #14906, in which a nonexistent option was found
in a man page. The xref script was designed to catch that,
but I was too lax in my parsing: the option was documented
using wrong syntax, and the script didn't catch it.

Solution: do not allow *any* unrecognized cruft in the
option description lines. And fix all improperly-written
entries to conform to the rule:

    **--option**=*value(s)*

Two asterisks around option, which must have two dashes. One
asterisk around value(s).

This is going to cause headaches for some people adding new
options, but I don't think I can fix that: there are many
factors that make an unparseable line. Adding 'hint' code
would make the script even more complex than it is. I have
to assume that our contributors are smart enough to look
at surrounding context and figure out the right way to
specify options.

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

29 files changed, 182 insertions, 141 deletions

diff --git a/docs/MANPAGE_SYNTAX.md b/docs/MANPAGE_SYNTAX.md
index 7fff167ba..60bffdace 100644
--- a/docs/MANPAGE_SYNTAX.md
+++ b/docs/MANPAGE_SYNTAX.md
@@ -60,15 +60,15 @@ Example sentence: Use **[podman-generate-systemd --new](./source/markdown/podman
 
 #### **--version**, **-v**
 
-OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front. If the arguments behind the OPTION are boolean, it is not shown behind the OPTION itself. The default boolean argument is shown in the same way normal default arguments are displayed.\
+OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front. If OPTION is boolean, *true/false* are not enumerated. The default boolean argument is shown in the same way normal default arguments are displayed.\
 Example: The default is **false**.\
 *IMPORTANT: This OPTION is not available with the remote Podman client.*
 
 #### **--exit**
 
-An example of an OPTION that has only one possible structure. Thus, it cannot be executed by the extension **-e**.
+An example of a boolean OPTION that is only available in long form.
 
-#### **--answer**=, **-a**=**active** | *disable*
+#### **--answer**, **-a**=**active** | *disable*
 
 The **--answer** OPTION above is an example of an OPTION that accepts two possible arguments as inputs. If a default argument is selected when the OPTION is not used in the command, it is shown in **bold**. If the OPTION is used, it must include an argument afterward. It must always be ensured that the standard argument is in the first position after the OPTION. In this example, there are two different ways to execute the command. Both possible OPTIONS have to be shown with the arguments following them.\
 The default value is shown as **active**.
diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md
index bf710022e..ba7081ff5 100644
--- a/docs/source/markdown/podman-build.1.md
+++ b/docs/source/markdown/podman-build.1.md
@@ -259,7 +259,7 @@ keys and/or certificates. Decryption will be tried with all keys. If the key is
 protected by a passphrase, it is required to be passed in the argument and
 omitted otherwise.
 
-#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
+#### **--device**=*host-device[:container-device][:permissions]*
 
 Add a host device to the container. Optional *permissions* parameter
 can be used to specify device permissions, it is combination of
@@ -267,13 +267,13 @@ can be used to specify device permissions, it is combination of
 
 Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
 
-Note: if _host_device_ is a symbolic link then it will be resolved first.
+Note: if *host-device* is a symbolic link then it will be resolved first.
 The container will only store the major and minor numbers of the host device.
 
 Note: if the user only has access rights via a group, accessing the device
 from inside a rootless container will fail. The **[crun(1)](https://github.com/containers/crun/tree/main/crun.1.md)** runtime offers a
 workaround for this by adding the option
-#### **--annotation run.oci.keep_original_groups=1**.
+**--annotation run.oci.keep_original_groups=1**.
 
 #### **--disable-compression**, **-D**
 
@@ -311,7 +311,7 @@ Set custom DNS options to be used during the build.
 
 Set custom DNS search domains to be used during the build.
 
-#### **--env** *env[=value]*
+#### **--env**=*env[=value]*
 
 Add a value (e.g. env=*value*) to the built image.  Can be used multiple times.
 If neither `=` nor a `*value*` are specified, but *env* is set in the current
@@ -430,7 +430,7 @@ specified file instead of to standard output and standard error.
 This option is not supported on the remote client, including Mac and Windows
 (excluding WSL2) machines.
 
-#### **--logsplit** *bool-value*
+#### **--logsplit**=*bool-value*
 
 If `--logfile` and `--platform` are specified, the `--logsplit` option allows
 end-users to split the log file for each platform into different files in the
@@ -438,7 +438,7 @@ following format: `${logfile}_${platform-os}_${platform-arch}`.
 This option is not supported on the remote client, including Mac and Windows
 (excluding WSL2) machines.
 
-#### **--manifest** "manifest"
+#### **--manifest**=*manifest*
 
 Name of the manifest list to which the image will be added. Creates the manifest list
 if it does not exist. This option is useful for building multi architecture images.
@@ -507,7 +507,7 @@ Set the OS of the image to be built, and that of the base image to be pulled,
 if the build uses one, instead of using the current operating system of the
 build host.
 
-#### **--os-feature** *feature*
+#### **--os-feature**=*feature*
 
 Set the name of a required operating system *feature* for the image which will
 be built.  By default, if the image is not based on *scratch*, the base image's
@@ -517,7 +517,7 @@ is typically only meaningful when the image's OS is Windows.
 If *feature* has a trailing `-`, then the *feature* is removed from the set of
 required features which will be listed in the image.
 
-#### **--os-version** *version*
+#### **--os-version**=*version*
 
 Set the exact required operating system *version* for the image which will be
 built.  By default, if the image is not based on *scratch*, the base image's
@@ -525,7 +525,7 @@ required OS version is kept, if the base image specified one.  This option is
 typically only meaningful when the image's OS is Windows, and is typically set in
 Windows base images, so using this option is usually unnecessary.
 
-#### **--output**, **-o**=""
+#### **--output**, **-o**=*output-opts*
 
 Output destination (format: type=local,dest=path)
 
@@ -553,9 +553,9 @@ that the PID namespace in which `podman` itself is being run should be reused,
 or it can be the path to a PID namespace which is already in use by another
 process.
 
-#### **--platform**="OS/ARCH[/VARIANT][,...]"
+#### **--platform**=*os/arch[/variant][,...]*
 
-Set the OS/ARCH of the built image (and its base image, if your build uses one)
+Set the *os/arch* of the built image (and its base image, if your build uses one)
 to the provided value instead of using the current operating system and
 architecture of the host (for example `linux/arm`). If `--platform` is set,
 then the values of the `--arch`, `--os`, and `--variant` options will be
@@ -566,8 +566,8 @@ comma-separated list of values as its argument.  When more than one platform is
 specified, the `--manifest` option should be used instead of the `--tag`
 option.
 
-OS/ARCH pairs are those used by the Go Programming Language.  In several cases
-the ARCH value for a platform differs from one produced by other tools such as
+Os/arch pairs are those used by the Go Programming Language.  In several cases
+the *arch* value for a platform differs from one produced by other tools such as
 the `arch` command.  Valid OS and architecture name combinations are listed as
 values for $GOOS and $GOARCH at https://golang.org/doc/install/source#environment,
 and can also be found by running `go tool dist list`.
@@ -576,7 +576,7 @@ While `podman build` is happy to use base images and build images for any
 platform that exists, `RUN` instructions will not be able to succeed without
 the help of emulation provided by packages like `qemu-user-static`.
 
-#### **--pull**=**always**|**missing**|**never**|**newer**
+#### **--pull**=*policy*
 
 Pull image policy. The default is **always**.
 
@@ -655,7 +655,7 @@ layers are not squashed.
 Squash all of the new image's layers (including those inherited from a base
 image) into a single new layer.
 
-#### **--ssh**=*default|id[=socket>|[,]*
+#### **--ssh**=*default* | *id[=socket>*
 
 SSH agent socket or keys to expose to the build.
 The socket path can be left empty to use the value of `default=$SSH_AUTH_SOCK`
@@ -683,7 +683,7 @@ Set the target build stage to build.  When building a Containerfile with
 multiple build stages, --target can be used to specify an intermediate build
 stage by name as the final stage for the resulting image. Commands after the target stage will be skipped.
 
-#### **--timestamp** *seconds*
+#### **--timestamp**=*seconds*
 
 Set the create timestamp to seconds since epoch to allow for deterministic
 builds (defaults to current time). By default, the created timestamp is changed
@@ -699,7 +699,7 @@ timestamp.
 Require HTTPS and verify certificates when talking to container registries
 (defaults to true). (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
 
-#### **--ulimit**=*type*=*soft-limit*[:*hard-limit*]
+#### **--ulimit**=*type=soft-limit[:hard-limit]*
 
 Specifies resource limits to apply to processes launched when processing `RUN`
 instructions. This option can be specified multiple times.  Recognized resource
@@ -720,7 +720,7 @@ types include:
   "sigpending": maximum number of pending signals (ulimit -i)
   "stack": maximum stack size (ulimit -s)
 
-#### **--unsetenv** *env*
+#### **--unsetenv**=*env*
 
 Unset environment variables from the final image.
 
@@ -814,19 +814,20 @@ that the UTS namespace in which `podman` itself is being run should be reused,
 or it can be the path to a UTS namespace which is already in use by another
 process.
 
-#### **--variant**=""
+#### **--variant**=*variant*
 
 Set the architecture variant of the image to be built, and that of the base
 image to be pulled, if the build uses one, to the provided value instead of
 using the architecture variant of the build host.
 
-#### **--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*]
+#### **--volume**, **-v**=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*
 
-   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. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
+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. (This option is not available with the remote Podman client,
+including Mac and Windows (excluding WSL2) machines)
 
-   The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>
+The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup>
 
    * [rw|ro]
    * [z|Z|O]
diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md
index 3df931254..b7b52e3a7 100644
--- a/docs/source/markdown/podman-commit.1.md
+++ b/docs/source/markdown/podman-commit.1.md
@@ -36,7 +36,7 @@ Apply the following possible instructions to the created image:
 
 Can be set multiple times.
 
-#### **--format**, **-f** =**oci** | *docker*
+#### **--format**, **-f**=**oci** | *docker*
 
 Set the format of the image manifest and metadata.  The currently supported formats are **oci** and *docker*.\
 The default is **oci**.
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index a6ba69d6a..67bb573e2 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -243,7 +243,7 @@ this can result in the following division of CPU shares:
 
 Number of CPUs. The default is *0.0* which means no limit. This is shorthand
 for **--cpu-period** and **--cpu-quota**, so you may only set either
-#### **--cpus** or **--cpu-period** and **--cpu-quota**.
+**--cpus** or **--cpu-period** and **--cpu-quota**.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
@@ -261,7 +261,7 @@ If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1`
 then processes in your container will only use memory from the first
 two memory nodes.
 
-#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
+#### **--device**=*host-device[:container-device][:permissions]*
 
 Add a host device to the container. Optional *permissions* parameter
 can be used to specify device permissions, it is combination of
@@ -269,7 +269,7 @@ can be used to specify device permissions, it is combination of
 
 Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
 
-Note: if _host_device_ is a symbolic link then it will be resolved first.
+Note: if *host-device* is a symbolic link then it will be resolved first.
 The container will only store the major and minor numbers of the host device.
 
 Note: if the user only has access rights via a group, accessing the device
@@ -280,7 +280,7 @@ Podman may load kernel modules required for using the specified
 device. The devices that podman will load modules when necessary are:
 /dev/fuse.
 
-#### **--device-cgroup-rule**="type major:minor mode"
+#### **--device-cgroup-rule**=*"type major:minor mode"*
 
 Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt):
        - type: a (all), c (char), or b (block);
@@ -376,7 +376,7 @@ __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
 
 Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
 
-#### **--group-add**=*group|keep-groups*
+#### **--group-add**=*group* | *keep-groups*
 
 Assign additional groups to the primary user running within the container process.
 
@@ -419,7 +419,7 @@ value can be expressed in a time format such as `1m22s`. The default value is `3
 
 Print usage statement
 
-#### **--hostname**=*name*, **-h**
+#### **--hostname**, **-h**=*name*
 
 Container host name
 
@@ -450,7 +450,7 @@ container:
 
 Defaults to `true`
 
-#### **--image-volume**=*bind|tmpfs|ignore*
+#### **--image-volume**=**bind** | *tmpfs* | *ignore*
 
 Tells Podman how to handle the builtin image volumes. Default is **bind**.
 
@@ -465,8 +465,9 @@ Run an init inside the container that forwards signals and reaps processes.
 The container-init binary is mounted at `/run/podman-init`.
 Mounting over `/run` will hence break container execution.
 
-#### **--init-ctr**=*type* (pods only)
+#### **--init-ctr**=*type*
 
+(Pods only).
 When using pods, create an init style container, which is run after the infra container is started
 but before regular pod containers are started.  Init containers are useful for running
 setup operations for the pod's applications.
@@ -531,7 +532,7 @@ Read in a line delimited file of labels
 
 Not implemented
 
-#### **--log-driver**="*k8s-file*"
+#### **--log-driver**=*driver*
 
 Logging driver for the container. Currently available options are *k8s-file*, *journald*, *none* and *passthrough*, with *json-file* aliased to *k8s-file* for scripting compatibility.
 
@@ -544,7 +545,7 @@ The *passthrough* driver passes down the standard streams (stdin, stdout, stderr
 container.  It is not allowed with the remote Podman client, including Mac and Windows (excluding WSL2) machines, and on a tty, since it is
 vulnerable to attacks via TIOCSTI.
 
-#### **--log-opt**=*name*=*value*
+#### **--log-opt**=*name=value*
 
 Set custom logging configuration. The following *name*s are supported:
 
@@ -828,11 +829,11 @@ container.
 
 Rootless containers cannot have more privileges than the account that launched them.
 
-#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_]
+#### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]*
 
 Publish a container's port, or range of ports, to the host.
 
-Both hostPort and containerPort can be specified as a range of ports.
+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.
 
@@ -868,7 +869,7 @@ 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 `podman port`.
 
-#### **--pull**=**always**|**missing**|**never**|**newer**
+#### **--pull**=*policy*
 
 Pull image policy. The default is **missing**.
 
@@ -897,7 +898,7 @@ If container is running in --read-only mode, then mount a read-write tmpfs on /r
 
 If another container with the same name already exists, replace and remove it. The default is **false**.
 
-#### **--requires**=**container**
+#### **--requires**=*container*
 
 Specify one or more requirements.
 A requirement is a dependency container that will be started before this container.
@@ -940,7 +941,7 @@ directory will be the lower, and the container storage directory will be the
 upper. Modifications to the mount point are destroyed when the container
 finishes executing, similar to a tmpfs mount point being unmounted.
 
-#### **--sdnotify**=**container**|**conmon**|**ignore**
+#### **--sdnotify**=**container** | *conmon* | *ignore*
 
 Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify.
 
@@ -957,7 +958,7 @@ Specify the policy to select the seccomp profile. If set to *image*, Podman will
 
 Note that this feature is experimental and may change in the future.
 
-#### **--secret**=*secret*[,opt=opt ...]
+#### **--secret**=*secret[,opt=opt ...]*
 
 Give the container access to a secret. Can be specified multiple times.
 
@@ -1052,7 +1053,7 @@ Network Namespace - current sysctls allowed:
 
 Note: if you use the --network=host option these sysctls will not be allowed.
 
-#### **--systemd**=*true|false|always*
+#### **--systemd**=*true* | *false* | *always*
 
 Run container in systemd mode. The default is *true*.
 
@@ -1120,7 +1121,7 @@ standard input.
 Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones.
 Remote connections use local containers.conf for defaults
 
-#### **--uidmap**=*container_uid*:*from_uid*:*amount*
+#### **--uidmap**=*container_uid:from_uid:amount*
 
 Run the container in a new user namespace using the supplied UID mapping. This
 option conflicts with the **--userns** and **--subuidname** options. This
@@ -1215,7 +1216,7 @@ Unset default environment variables for the container. Default environment
 variables include variables provided natively by Podman, environment variables
 configured by the image, and environment variables from containers.conf.
 
-#### **--unsetenv-all**=*true|false*
+#### **--unsetenv-all**
 
 Unset all default environment variables for the container. Default environment
 variables include variables provided natively by Podman, environment variables
@@ -1285,7 +1286,7 @@ Set the UTS namespace mode for the container. The following values are supported
 #### **--variant**=*VARIANT*
 Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7.
 
-#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
+#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*
 
 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
@@ -1455,7 +1456,7 @@ Note: if the user only has access rights via a group, accessing the volume
 from inside a rootless container will fail. Use the `--group-add keep-groups`
 flag to pass the user's supplementary group access into the container.
 
-#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]]
+#### **--volumes-from**=*CONTAINER[:OPTIONS]]*
 
 Mount volumes from the specified container(s). Used to share volumes between
 containers. The *options* is a comma-separated list with the following available elements:
diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md
index 9b8aa5b80..bd7bc711c 100644
--- a/docs/source/markdown/podman-generate-kube.1.md
+++ b/docs/source/markdown/podman-generate-kube.1.md
@@ -30,7 +30,7 @@ Note that the generated Kubernetes YAML file can be used to re-run the deploymen
 
 ## OPTIONS
 
-#### **--filename**, **-f**=**filename**
+#### **--filename**, **-f**=*filename*
 
 Output to the given file, instead of STDOUT. If the file already exists, `generate kube` will refuse to replace it and return an error.
 
diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md
index 3d63c83c0..50881a509 100644
--- a/docs/source/markdown/podman-generate-systemd.1.md
+++ b/docs/source/markdown/podman-generate-systemd.1.md
@@ -83,11 +83,11 @@ Takes a value in seconds.
 
 Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is *-*.
 
-#### **--start-timeout** =*value*
+#### **--start-timeout**=*value*
 
 Override the default start timeout for the container with the given value in seconds.
 
-#### **--stop-timeout** =*value*
+#### **--stop-timeout**=*value*
 
 Override the default stop timeout for the container with the given value in seconds.
 
diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md
index 66d492922..4e80bdcf5 100644
--- a/docs/source/markdown/podman-image-trust.1.md
+++ b/docs/source/markdown/podman-image-trust.1.md
@@ -42,12 +42,12 @@ Trust may be updated using the command **podman image trust set** for an existin
 
 ### set OPTIONS
 
-#### **--pubkeysfile**=*KEY1*, **-f**
+#### **--pubkeysfile**, **-f**=*KEY1*
   A path to an exported public key on the local system. Key paths
   will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to
   require an image be signed by multiple keys.  The **--pubkeysfile** option is required for the **signedBy** type.
 
-#### **--type**=*value*, **-t**
+#### **--type**, **-t**=*value*
   The trust type for this policy entry.
   Accepted values:
     **signedBy** (default): Require signatures with corresponding list of
diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md
index e28df840d..923b22f1b 100644
--- a/docs/source/markdown/podman-images.1.md
+++ b/docs/source/markdown/podman-images.1.md
@@ -23,7 +23,7 @@ Show all images (by default filter out the intermediate image layers). The defau
 
 Show image digests
 
-#### **--filter**=*filter*, **-f**
+#### **--filter**, **-f**=*filter*
 
 Provide filter values.
 
@@ -100,9 +100,9 @@ Omit the table headings from the listing of images.
 
 Lists only the image IDs.
 
-#### **--sort**=*sort*=*created*
+#### **--sort**=*sort*
 
-Sort by created, id, repository, size or tag (default: created)
+Sort by *created*, *id*, *repository*, *size* or *tag* (default: **created**)
 
 ## EXAMPLE
 
diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md
index bfe0291de..4002f5255 100644
--- a/docs/source/markdown/podman-import.1.md
+++ b/docs/source/markdown/podman-import.1.md
@@ -23,7 +23,7 @@ Note: `:` is a restricted character and cannot be part of the file name.
 
 Set architecture of the imported image.
 
-#### **--change**=*instruction*, **-c**
+#### **--change**, **-c**=*instruction*
 
 Apply the following possible instructions to the created image:
 **CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR**
diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md
index 28e4f3291..347d8d27b 100644
--- a/docs/source/markdown/podman-info.1.md
+++ b/docs/source/markdown/podman-info.1.md
@@ -19,7 +19,7 @@ Displays information pertinent to the host, current storage stats, configured co
 
 Show additional information
 
-#### **--format**=*format*, **-f**
+#### **--format**, **-f**=*format*
 
 Change output format to "json" or a Go template.
 
diff --git a/docs/source/markdown/podman-kube-play.1.md b/docs/source/markdown/podman-kube-play.1.md
index 37d2069e0..ee68380e6 100644
--- a/docs/source/markdown/podman-kube-play.1.md
+++ b/docs/source/markdown/podman-kube-play.1.md
@@ -159,11 +159,11 @@ Print usage statement
 Assign a static ip address to the pod. This option can be specified several times when kube play creates more than one pod.
 Note: When joining multiple networks you should use the **--network name:ip=\<ip\>** syntax.
 
-#### **--log-driver**=driver
+#### **--log-driver**=*driver*
 
 Set logging driver for all created containers.
 
-#### **--log-opt**=*name*=*value*
+#### **--log-opt**=*name=value*
 
 Set custom logging configuration. The following *name*s are supported:
 
diff --git a/docs/source/markdown/podman-machine-info.1.md b/docs/source/markdown/podman-machine-info.1.md
index 33c207d32..926d3d8b3 100644
--- a/docs/source/markdown/podman-machine-info.1.md
+++ b/docs/source/markdown/podman-machine-info.1.md
@@ -13,7 +13,7 @@ Rootless only, as all `podman machine` commands can be only be used with rootles
 
 ## OPTIONS
 
-#### **--format**=*format*, **-f**
+#### **--format**, **-f**=*format*
 
 Change output format to "json" or a Go template.
 
diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md
index 21c98b2c7..07273a111 100644
--- a/docs/source/markdown/podman-machine-init.1.md
+++ b/docs/source/markdown/podman-machine-init.1.md
@@ -62,7 +62,7 @@ Memory (in MB).
 
 Start the virtual machine immediately after it has been initialized.
 
-#### **--rootful**=*true|false*
+#### **--rootful**
 
 Whether this machine should prefer rootful (`true`) or rootless (`false`)
 container execution. This option will also determine the remote connection default
diff --git a/docs/source/markdown/podman-machine-set.1.md b/docs/source/markdown/podman-machine-set.1.md
index 1daf97a61..52338cedb 100644
--- a/docs/source/markdown/podman-machine-set.1.md
+++ b/docs/source/markdown/podman-machine-set.1.md
@@ -33,7 +33,7 @@ Print usage statement.
 Memory (in MB).
 Only supported for QEMU machines.
 
-#### **--rootful**=*true|false*
+#### **--rootful**
 
 Whether this machine should prefer rootful (`true`) or rootless (`false`)
 container execution. This option will also update the current podman
diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md
index 40f841bf8..5aa7f8341 100644
--- a/docs/source/markdown/podman-manifest-add.1.md
+++ b/docs/source/markdown/podman-manifest-add.1.md
@@ -22,7 +22,7 @@ index, add all of the contents to the local list.  By default, only one image
 from such a list or index will be added to the list or index.  Combining
 *--all* with any of the other options described below is NOT recommended.
 
-#### **--annotation** *annotation=value*
+#### **--annotation**=*annotation=value*
 
 Set an annotation on the entry for the newly-added image.
 
diff --git a/docs/source/markdown/podman-manifest-annotate.1.md b/docs/source/markdown/podman-manifest-annotate.1.md
index 2b8b70aa4..36c35c7c8 100644
--- a/docs/source/markdown/podman-manifest-annotate.1.md
+++ b/docs/source/markdown/podman-manifest-annotate.1.md
@@ -12,7 +12,7 @@ Adds or updates information about an image included in a manifest list or image
 
 ## OPTIONS
 
-#### **--annotation** *annotation=value*
+#### **--annotation**=*annotation=value*
 
 Set an annotation on the entry for the specified image.
 
diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md
index 1d89b12e3..3587ac2a8 100644
--- a/docs/source/markdown/podman-network-create.1.md
+++ b/docs/source/markdown/podman-network-create.1.md
@@ -67,7 +67,7 @@ Enable IPv6 (Dual Stack) networking. If not subnets are given it will allocate a
 
 Set metadata for a network (e.g., --label mykey=value).
 
-#### **--opt**=*option*, **-o**
+#### **--opt**, **-o**=*option*
 
 Set driver specific options.
 
diff --git a/docs/source/markdown/podman-pod-clone.1.md b/docs/source/markdown/podman-pod-clone.1.md
index d90d1efb9..49084386c 100644
--- a/docs/source/markdown/podman-pod-clone.1.md
+++ b/docs/source/markdown/podman-pod-clone.1.md
@@ -27,7 +27,7 @@ CPUs in which to allow execution (0-3, 0,1). If none are specified, the original
 
 Remove the original pod that we are cloning once used to mimic the configuration.
 
-#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
+#### **--device**=*host-device[:container-device][:permissions]*
 
 Add a host device to the pod. Optional *permissions* parameter
 can be used to specify device permissions. It is a combination of
@@ -56,7 +56,7 @@ GID map for the user namespace. Using this flag will run all containers in the p
 
 Print usage statement.
 
-#### **--hostname**=name
+#### **--hostname**=*name*
 
 Set a hostname to the pod.
 
@@ -72,7 +72,7 @@ Write the pid of the infra container's **conmon** process to a file. As **conmon
 
 The name that will be used for the pod's infra container.
 
-#### **--label**=*label*, **-l**
+#### **--label**, **-l**=*label*
 
 Add metadata to a pod (e.g., --label com.example.key=value).
 
@@ -153,7 +153,7 @@ Name for GID map from the `/etc/subgid` file. Using this flag will run the conta
 
 Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`.
 
-#### **--sysctl**=_name_=_value_
+#### **--sysctl**=*name=value*
 
 Configure namespace kernel parameters for all containers in the new pod.
 
@@ -175,7 +175,7 @@ For the network namespace, only sysctls beginning with net.\* are allowed.
 
 Note: if the network namespace is not shared within the pod, these sysctls are not allowed.
 
-#### **--uidmap**=*container_uid*:*from_uid*:*amount*
+#### **--uidmap**=*container_uid:from_uid:amount*
 
 Run all containers in the pod in a new user namespace using the supplied mapping. This
 option conflicts with the **--userns** and **--subuidname** options. This
@@ -220,7 +220,7 @@ Set the UTS namespace mode for the pod. The following values are supported:
 - **ns:[path]**: run the pod in the given existing UTS namespace.
 
 
-#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
+#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*
 
 Create a bind mount. If ` -v /HOST-DIR:/CONTAINER-DIR` is specified, Podman
 bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman
@@ -381,7 +381,7 @@ change propagation properties of source mount. Say `/` is source mount for
 Note: if the user only has access rights via a group, accessing the volume
 from inside a rootless pod will fail.
 
-#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]]
+#### **--volumes-from**=*container[:options]]*
 
 Mount volumes from the specified container(s). Used to share volumes between
 containers and pods. The *options* is a comma-separated list with the following available elements:
diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index f7bdb623a..de9a34bfa 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -25,7 +25,7 @@ for it. The name is useful any place you need to identify a pod.
 
 ## OPTIONS
 
-#### **--add-host**=_host_:_ip_
+#### **--add-host**=*host:ip*
 
 Add a custom host-to-IP mapping (host:ip)
 
@@ -52,7 +52,7 @@ Examples of the List Format:
 0-4,9           # bits 0, 1, 2, 3, 4, and 9 set
 0-2,7,12-14     # bits 0, 1, 2, 7, 12, 13, and 14 set
 
-#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
+#### **--device**=*host-device[:container-device][:permissions]*
 
 Add a host device to the pod. Optional *permissions* parameter
 can be used to specify device permissions. It is a combination of
@@ -60,7 +60,7 @@ can be used to specify device permissions. It is a combination of
 
 Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
 
-Note: if _host_device_ is a symbolic link then it will be resolved first.
+Note: if *host-device* is a symbolic link then it will be resolved first.
 The pod will only store the major and minor numbers of the host device.
 
 Note: the pod implements devices by storing the initial configuration passed by the user and recreating the device on each container added to the pod.
@@ -102,7 +102,7 @@ GID map for the user namespace. Using this flag will run the container with user
 
 Print usage statement.
 
-#### **--hostname**=name
+#### **--hostname**=*name*
 
 Set a hostname to the pod
 
@@ -144,7 +144,7 @@ The address must be within the network's IPv6 address pool.
 
 To specify multiple static IPv6 addresses per pod, set multiple networks using the **--network** option with a static IPv6 address specified for each using the `ip6` mode for that option.
 
-#### **--label**=*label*, **-l**
+#### **--label**, **-l**=*label*
 
 Add metadata to a pod (e.g., --label com.example.key=value).
 
@@ -175,7 +175,7 @@ not limited. The actual limit may be rounded up to a multiple of the operating
 system's page size (the value would be very large, that's millions of trillions).
 
 
-#### **--name**=*name*, **-n**
+#### **--name**, **-n**=*name*
 
 Assign a name to the pod.
 
@@ -237,11 +237,11 @@ Set the PID mode for the pod. The default is to create a private PID namespace f
 
 Write the pod ID to the file.
 
-#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_]
+#### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]*
 
 Publish a container's port, or range of ports, within this pod to the host.
 
-Both hostPort and containerPort can be specified as a range of ports.
+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.
 
@@ -323,7 +323,7 @@ Name for GID map from the `/etc/subgid` file. Using this flag will run the conta
 Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`.
 
 
-#### **--sysctl**=_name_=_value_
+#### **--sysctl**=*name=value*
 
 Configure namespace kernel parameters for all containers in the pod.
 
@@ -345,7 +345,7 @@ For the network namespace, only sysctls beginning with net.\* are allowed.
 
 Note: if the network namespace is not shared within the pod, these sysctls are not allowed.
 
-#### **--uidmap**=*container_uid*:*from_uid*:*amount*
+#### **--uidmap**=*container_uid:from_uid:amount*
 
 Run the container in a new user namespace using the supplied mapping. This
 option conflicts with the **--userns** and **--subuidname** options. This
@@ -389,7 +389,7 @@ Set the UTS namespace mode for the pod. The following values are supported:
 - **private**: create a new namespace for the pod (default).
 - **ns:[path]**: run the pod in the given existing UTS namespace.
 
-#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
+#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*
 
 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
@@ -548,7 +548,7 @@ change propagation properties of source mount. Say `/` is source mount for
 Note: if the user only has access rights via a group, accessing the volume
 from inside a rootless pod will fail.
 
-#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]]
+#### **--volumes-from**=*container[:options]]*
 
 Mount volumes from the specified container(s). Used to share volumes between
 containers and pods. The *options* is a comma-separated list with the following available elements:
diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md
index 3105ebaab..d0a165b05 100644
--- a/docs/source/markdown/podman-pod-inspect.1.md
+++ b/docs/source/markdown/podman-pod-inspect.1.md
@@ -12,7 +12,7 @@ that belong to the pod.
 
 ## OPTIONS
 
-#### **--format**=*format*, **-f**
+#### **--format**, **-f**=*format*
 
 Change the default output format.  This can be of a supported type like 'json'
 or a Go template.
diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md
index 25c1e024a..3cda982ac 100644
--- a/docs/source/markdown/podman-push.1.md
+++ b/docs/source/markdown/podman-push.1.md
@@ -65,7 +65,7 @@ Please refer to containers-certs.d(5) for details. (This option is not available
 Compress tarball image layers when pushing to a directory using the 'dir' transport. (default is same compression type, compressed or uncompressed, as source)
 Note: This flag can only be set when using the **dir** transport
 
-#### **--compression-format** *COMPRESSION*
+#### **--compression-format**=**gzip** | *zstd* | *zstd:chunked*
 
 Specifies the compression format to use.  Supported values are: `gzip`, `zstd` and `zstd:chunked`.  The default is `gzip`.
 
@@ -75,7 +75,7 @@ The [username[:password]] to use to authenticate with the registry if required.
 If one or both values are not supplied, a command line prompt will appear and the
 value can be entered.  The password is entered without echo.
 
-#### **--digestfile** *Digestfile*
+#### **--digestfile**=*Digestfile*
 
 After copying the image, write the digest of the resulting image to the file.  (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
 
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 9561d65bf..4566a73d0 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -83,14 +83,14 @@ and specified with a _tag_.
     $ podman run oci-archive:/tmp/fedora echo hello
 
 ## OPTIONS
-#### **--add-host**=_host_:_ip_
+#### **--add-host**=*host:ip*
 
 Add a custom host-to-IP mapping (host:ip)
 
 Add a line to /etc/hosts. The format is hostname:ip. The **--add-host**
 option can be set multiple times.
 
-#### **--annotation**=_key_=_value_
+#### **--annotation**=*key=value*
 
 Add an annotation to the container.
 This option can be set multiple times.
@@ -98,7 +98,7 @@ This option can be set multiple times.
 #### **--arch**=*ARCH*
 Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
 
-#### **--attach**, **-a**=**stdin**|**stdout**|**stderr**
+#### **--attach**, **-a**=*stdin* | *stdout* | *stderr*
 
 Attach to STDIN, STDOUT or STDERR.
 
@@ -109,7 +109,7 @@ error. It can even pretend to be a TTY (this is what most commandline
 executables expect) and pass along signals. The **-a** option can be set for
 each of **stdin**, **stdout**, and **stderr**.
 
-#### **--authfile**[=*path*]
+#### **--authfile**=*[path]*
 
 Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*.
 
@@ -120,7 +120,7 @@ environment variable.
 
 Block IO relative weight. The _weight_ is a value between **10** and **1000**.
 
-#### **--blkio-weight-device**=*device*:*weight*
+#### **--blkio-weight-device**=*device:weight*
 
 Block IO relative device weight.
 
@@ -151,7 +151,7 @@ Set the cgroup namespace mode for the container.
 
 If the host uses cgroups v1, the default is set to **host**. On cgroups v2, the default is **private**.
 
-#### **--cgroups**=**enabled**|**disabled**|**no-conmon**|**split**
+#### **--cgroups**=*how*
 
 Determines whether the container will create CGroups.
 
@@ -259,7 +259,7 @@ this can result in the following division of CPU shares:
 
 Number of CPUs. The default is *0.0* which means no limit. This is shorthand
 for **--cpu-period** and **--cpu-quota**, so you may only set either
-#### **--cpus** or **--cpu-period** and **--cpu-quota**.
+**--cpus** or **--cpu-period** and **--cpu-quota**.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
@@ -297,7 +297,7 @@ Specify the key sequence for detaching a container. Format is a single character
 
 This option can also be set in **containers.conf**(5) file.
 
-#### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
+#### **--device**=*host-device[:container-device][:permissions]*
 
 Add a host device to the container. Optional *permissions* parameter
 can be used to specify device permissions by combining
@@ -316,23 +316,23 @@ Podman may load kernel modules required for using the specified
 device. The devices that Podman will load modules when necessary are:
 /dev/fuse.
 
-#### **--device-cgroup-rule**=rule
+#### **--device-cgroup-rule**=*rule*
 
 Add a rule to the cgroup allowed devices list
 
-#### **--device-read-bps**=_path_:_rate_
+#### **--device-read-bps**=*path:rate*
 
 Limit read rate (in bytes per second) from a device (e.g. **--device-read-bps=/dev/sda:1mb**).
 
-#### **--device-read-iops**=_path_:_rate_
+#### **--device-read-iops**=*path:rate*
 
 Limit read rate (in IO operations per second) from a device (e.g. **--device-read-iops=/dev/sda:1000**).
 
-#### **--device-write-bps**=_path_:_rate_
+#### **--device-write-bps**=*path:rate*
 
 Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/dev/sda:1mb**).
 
-#### **--device-write-iops**=_path_:_rate_
+#### **--device-write-iops**=*path:rate*
 
 Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**).
 
@@ -402,7 +402,7 @@ Use host environment inside of the container. See **Environment** note below for
 Expose a port, or a range of ports (e.g. **--expose=3300-3310**) to set up port redirection
 on the host system.
 
-#### **--gidmap**=*container_gid*:*host_gid*:*amount*
+#### **--gidmap**=*container_gid:host_gid:amount*
 
 Run the container in a new user namespace using the supplied GID mapping. This
 option conflicts with the **--userns** and **--subgidname** options. This
@@ -411,7 +411,7 @@ __--uidmap__ maps host UIDs to container UIDs. For details see __--uidmap__.
 
 Note: the **--gidmap** flag cannot be called in conjunction with the **--pod** flag as a gidmap cannot be set on the container level when in a pod.
 
-#### **--group-add**=*group|keep-groups*
+#### **--group-add**=*group* | *keep-groups*
 
 Assign additional groups to the primary user running within the container process.
 
@@ -454,7 +454,7 @@ value can be expressed in a time format such as **1m22s**. The default value is
 
 Print usage statement
 
-#### **--hostname**=*name*, **-h**
+#### **--hostname**, **-h**=*name*
 
 Container host name
 
@@ -480,7 +480,7 @@ proxy environment at container build time.) (This option is not available with t
 
 Defaults to **true**.
 
-#### **--image-volume**=**bind**|**tmpfs**|**ignore**
+#### **--image-volume**=**bind** | *tmpfs* | *ignore*
 
 Tells Podman how to handle the builtin image volumes. Default is **bind**.
 
@@ -534,7 +534,7 @@ a private IPC namespace.
 - **private**: private IPC namespace.
 = **shareable**: private IPC namespace with a possibility to share it with  other containers.
 
-#### **--label**, **-l**=*key*=*value*
+#### **--label**, **-l**=*key=value*
 
 Add metadata to a container.
 
@@ -546,9 +546,9 @@ Read in a line-delimited file of labels.
 
 Not implemented.
 
-#### **--log-driver**="*driver*"
+#### **--log-driver**=*driver*
 
-Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none** and **passthrough**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default journald)
+Logging driver for the container. Currently available options are **k8s-file**, **journald**, **none** and **passthrough**, with **json-file** aliased to **k8s-file** for scripting compatibility. (Default **journald**)
 
 The podman info command below will display the default log-driver for the system.
 ```
@@ -560,7 +560,7 @@ container.  It is not allowed with the remote Podman client, including Mac and W
 vulnerable to attacks via TIOCSTI.
 
 
-#### **--log-opt**=*name*=*value*
+#### **--log-opt**=*name=value*
 
 Logging driver specific options.
 
@@ -589,7 +589,7 @@ according to RFC4862.
 
 To specify multiple static MAC addresses per container, set multiple networks using the **--network** option with a static MAC address specified for each using the `mac` mode for that option.
 
-#### **--memory**, **-m**=_number_[_unit_]
+#### **--memory**, **-m**=*number[unit]*
 
 Memory limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes).
 
@@ -599,7 +599,7 @@ RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
 not limited. The actual limit may be rounded up to a multiple of the operating
 system's page size (the value would be very large, that's millions of trillions).
 
-#### **--memory-reservation**=_number_[_unit_]
+#### **--memory-reservation**=*number[unit]*
 
 Memory soft limit. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes).
 
@@ -609,7 +609,7 @@ reservation. So you should always set the value below **--memory**, otherwise th
 hard limit will take precedence. By default, memory reservation will be the same
 as memory limit.
 
-#### **--memory-swap**=_number_[_unit_]
+#### **--memory-swap**=*number[unit]*
 
 A limit value equal to memory plus swap.
 A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes).
@@ -858,11 +858,11 @@ points, Apparmor/SELinux separation, and Seccomp filters are all disabled.
 
 Rootless containers cannot have more privileges than the account that launched them.
 
-#### **--publish**, **-p**=[[_ip_:][_hostPort_]:]_containerPort_[/_protocol_]
+#### **--publish**, **-p**=*[[ip:][hostPort]:]containerPort[/protocol]*
 
 Publish a container's port, or range of ports, to the host.
 
-Both hostPort and containerPort can be specified as a range of ports.
+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.
 
@@ -899,7 +899,7 @@ When using this option, Podman will bind any exposed port to a random port on th
 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 **podman port**.
 
-#### **--pull**=**always**|**missing**|**never**|**newer**
+#### **--pull**=*policy*
 
 Pull image policy. The default is **missing**.
 
@@ -928,7 +928,7 @@ If container is running in **--read-only** mode, then mount a read-write tmpfs o
 
 If another container with the same name already exists, replace and remove it. The default is **false**.
 
-#### **--requires**=**container**
+#### **--requires**=*container*
 
 Specify one or more requirements.
 A requirement is a dependency container that will be started before this container.
@@ -979,7 +979,7 @@ finishes executing, similar to a tmpfs mount point being unmounted.
 Note: On **SELinux** systems, the rootfs needs the correct label, which is by default
 **unconfined_u:object_r:container_file_t**.
 
-#### **--sdnotify**=**container**|**conmon**|**ignore**
+#### **--sdnotify**=**container** | *conmon* | *ignore*
 
 Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify.
 
@@ -996,7 +996,7 @@ Specify the policy to select the seccomp profile. If set to *image*, Podman will
 
 Note that this feature is experimental and may change in the future.
 
-#### **--secret**=*secret*[,opt=opt ...]
+#### **--secret**=*secret[,opt=opt ...]*
 
 Give the container access to a secret. Can be specified multiple times.
 
@@ -1051,7 +1051,7 @@ Note: Labeling can be disabled for all containers by setting label=false in the
 
 Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file.
 
-#### **--shm-size**=_number_[_unit_]
+#### **--shm-size**=*number[unit]*
 
 Size of _/dev/shm_. A _unit_ can be **b** (bytes), **k** (kibibytes), **m** (mebibytes), or **g** (gibibytes).
 If you omit the unit, the system uses bytes. If you omit the size entirely, the default is **64m**.
@@ -1082,7 +1082,7 @@ Run the container in a new user namespace using the map with _name_ in the _/etc
 If calling **podman run** as an unprivileged user, the user needs to have the right to use the mapping. See **subuid**(5).
 This flag conflicts with **--userns** and **--uidmap**.
 
-#### **--sysctl**=_name_=_value_
+#### **--sysctl**=*name=value*
 
 Configure namespaced kernel parameters at runtime.
 
@@ -1106,7 +1106,7 @@ For the network namespace, the following sysctls are allowed:
 
 Note: if you use the **--network=host** option, these sysctls will not be allowed.
 
-#### **--systemd**=**true**|**false**|**always**
+#### **--systemd**=*true* | *false* | *always*
 
 Run container in systemd mode. The default is **true**.
 
@@ -1180,7 +1180,7 @@ echo "asdf" | podman run --rm -i someimage /bin/cat
 Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones.
 Remote connections use local containers.conf for defaults
 
-#### **--uidmap**=*container_uid*:*from_uid*:*amount*
+#### **--uidmap**=*container_uid:from_uid:amount*
 
 Run the container in a new user namespace using the supplied UID mapping. This
 option conflicts with the **--userns** and **--subuidname** options. This
@@ -1275,15 +1275,15 @@ Unset default environment variables for the container. Default environment
 variables include variables provided natively by Podman, environment variables
 configured by the image, and environment variables from containers.conf.
 
-#### **--unsetenv-all**=*true|false*
+#### **--unsetenv-all**
 
 Unset all default environment variables for the container. Default environment
 variables include variables provided natively by Podman, environment variables
 configured by the image, and environment variables from containers.conf.
 
-#### **--user**, **-u**=[_user_ | _user_:_group_ | _uid_ | _uid_:_gid_ | _user_:_gid_ | _uid_:_group_ ]
+#### **--user**, **-u**=*user[:group]*
 
-Sets the username or UID used and optionally the groupname or GID for the specified command.
+Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both *user* and *group* may be symbolic or numeric.
 
 Without this argument, the command will run as the user specified in the container image. Unless overridden by a `USER` command in the Containerfile or by a value passed to this option, this user generally defaults to root.
 
@@ -1345,7 +1345,7 @@ Set the UTS namespace mode for the container. The following values are supported
 #### **--variant**=*VARIANT*
 Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7.
 
-#### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
+#### **--volume**, **-v**=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*
 
 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
@@ -1519,7 +1519,7 @@ Note: if the user only has access rights via a group, accessing the volume
 from inside a rootless container will fail. Use the `--group-add keep-groups`
 flag to pass the user's supplementary group access into the container.
 
-#### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]]
+#### **--volumes-from**=*CONTAINER[:OPTIONS]*
 
 Mount volumes from the specified container(s). Used to share volumes between
 containers. The *options* is a comma-separated list with the following available elements:
diff --git a/docs/source/markdown/podman-stats.1.md b/docs/source/markdown/podman-stats.1.md
index 472cbfbcf..d87da6a60 100644
--- a/docs/source/markdown/podman-stats.1.md
+++ b/docs/source/markdown/podman-stats.1.md
@@ -44,7 +44,7 @@ Valid placeholders for the Go template are listed below:
 
 When using a GO template, you may precede the format with `table` to print headers.
 
-#### **--interval**=*seconds*, **-i**=*seconds*
+#### **--interval**, **-i**=*seconds*
 
 Time in seconds between stats reports, defaults to 5 seconds.
 
diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md
index 76f222f2b..d608ab7a7 100644
--- a/docs/source/markdown/podman-system-connection-add.1.md
+++ b/docs/source/markdown/podman-system-connection-add.1.md
@@ -17,9 +17,9 @@ The user will be prompted for the remote ssh login password or key file pass phr
 
 ## OPTIONS
 
-#### **--default**=*false*, **-d**
+#### **--default**, **-d**
 
-Make the new destination the default for this user.
+Make the new destination the default for this user. The default is **false**.
 
 #### **--identity**=*path*
 
@@ -27,7 +27,7 @@ Path to ssh identity file. If the identity file has been encrypted, Podman promp
 If no identity file is provided and no user is given, Podman defaults to the user running the podman command.
 Podman prompts for the login password on the remote server.
 
-#### **--port**=*port*, **-p**
+#### **--port**, **-p**=*port*
 
 Port for ssh destination. The default value is `22`.
 
diff --git a/docs/source/markdown/podman-system-connection-remove.1.md b/docs/source/markdown/podman-system-connection-remove.1.md
index 4914ac9e9..348b49876 100644
--- a/docs/source/markdown/podman-system-connection-remove.1.md
+++ b/docs/source/markdown/podman-system-connection-remove.1.md
@@ -11,7 +11,7 @@ Delete named ssh destination.
 
 ## OPTIONS
 
-#### **--all**=*false*, **-a**
+#### **--all**, **-a**
 
 Remove all connections.
 
diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md
index f43e647bf..65b788851 100644
--- a/docs/source/markdown/podman-volume-create.1.md
+++ b/docs/source/markdown/podman-volume-create.1.md
@@ -23,11 +23,11 @@ Specify the volume driver name (default **local**). Setting this to a value othe
 
 Print usage statement
 
-#### **--label**=*label*, **-l**
+#### **--label**, **-l**=*label*
 
 Set metadata for a volume (e.g., --label mykey=value).
 
-#### **--opt**=*option*, **-o**
+#### **--opt**, **-o**=*option*
 
 Set driver specific options.
 For the default driver, **local**, this allows a volume to be configured to mount a filesystem on the host.
diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md
index dda83e558..9be0f9c2d 100644
--- a/docs/source/markdown/podman-volume-inspect.1.md
+++ b/docs/source/markdown/podman-volume-inspect.1.md
@@ -20,7 +20,7 @@ Volumes can be queried individually by providing their full name or a unique par
 
 Inspect all volumes.
 
-#### **--format**=*format*, **-f**
+#### **--format**, **-f**=*format*
 
 Format volume output using Go template
 
diff --git a/docs/source/markdown/podman-volume-ls.1.md b/docs/source/markdown/podman-volume-ls.1.md
index 4a3489425..86896b0a2 100644
--- a/docs/source/markdown/podman-volume-ls.1.md
+++ b/docs/source/markdown/podman-volume-ls.1.md
@@ -14,7 +14,7 @@ flag. Use the **--quiet** flag to print only the volume names.
 
 ## OPTIONS
 
-#### **--filter**=*filter*, **-f**
+#### **--filter**, **-f**=*filter*
 
 Volumes can be filtered by the following attributes:
 
diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages
index 7c07a4f01..de9ef8630 100755
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -350,7 +350,7 @@ sub podman_man {
                 # This is a while-loop because there may be multiple long
                 # option names, e.g. --net/--network
                 my $is_first = 1;
-                while ($line =~ s/^\*\*(--[a-z0-9-]+)\*\*(=\*[a-zA-Z0-9-]+\*)?(,\s+)?//g) {
+                while ($line =~ s/^\*\*(--[a-z0-9-]+)\*\*(,\s+)?//g) {
                     my $flag = $1;
                     $man{$flag} = 1;
                     if ($flag lt $previous_flag && $is_first) {
@@ -365,11 +365,50 @@ sub podman_man {
                     $is_first = 0;
                 }
                 # Short form
-                if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*(=\*[a-zA-Z0-9-]+\*)?//g) {
-                    $man{$1} = 1;
+                if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*//) {
+                    my $flag = $1;
+                    $man{$flag} = 1;
 
                     # Keep track of them, in case we see 'Not implemented' below
-                    push @most_recent_flags, $1;
+                    push @most_recent_flags, $flag;
+                }
+
+                # Options with no '=whatever'
+                next if !$line;
+
+                # Anything remaining *must* be of the form '=<possibilities>'
+                if ($line !~ /^=/) {
+                    warn "$ME: $subpath:$.: could not parse '$line' in option description\n";
+                    ++$Errs;
+                }
+
+                # For some years it was traditional, albeit wrong, to write
+                #     **--foo**=*bar*, **-f**
+                # The correct way is to add =*bar* at the end.
+                if ($line =~ s/,\s\*\*(-[a-zA-Z])\*\*//) {
+                    $man{$1} = 1;
+                    warn "$ME: $subpath:$.: please rewrite as ', **$1**$line'\n";
+                    ++$Errs;
+                }
+
+                # List of possibilities ('=*a* | *b*') must be space-separated
+                if ($line =~ /\|/) {
+                    if ($line =~ /[^\s]\|[^\s]/) {
+                        # Sigh, except for this one special case
+                        if ($line !~ /SOURCE-VOLUME.*HOST-DIR.*CONTAINER-DIR/) {
+                            warn "$ME: $subpath:$.: values must be space-separated: '$line'\n";
+                            ++$Errs;
+                        }
+                    }
+                    my $copy = $line;
+                    if ($copy =~ s/\**true\**//) {
+                        if ($copy =~ s/\**false\**//) {
+                            if ($copy !~ /[a-z]/) {
+                                warn "$ME: $subpath:$.: Do not enumerate true/false for boolean-only options\n";
+                                ++$Errs;
+                            }
+                        }
+                    }
                 }
             }
         }