[CI:DOCS] Restore man page cross-checker

Somewhere in the CIv2 migration we lost the man page vs --help
cross-checker. Add it back, by adding it into the man-page-check
Makefile target; this is part of 'make validate', which is run
in CI even on CI:DOCS PRs.

As happens when CI doesn't run, things broke. Man pages got out
of sync with --help. This PR:

 1) Fixes hack/xref-helpmsgs-manpages to deal with the new
    "Options" (instead of "Flags") form of podman help. #8034
    did part of that, but one of my review comments was
    accidentally left out.

 2) Fixes hack/xref-helpmsgs-manpages to deal with the new
    option syntax in man pages, post- #8292, in which each
    option is preceded by four hashes so as to make them
    HTML <h4> elements with named anchors.

 3) Fixes man pages that #8292 accidentally missed.

 4) Adds man page entries for two flags that got added
    to podman but not documented (pod create --network-alias,
    play kube --log-driver)

Fixes: #8296

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

23 files changed, 55 insertions, 43 deletions

diff --git a/Makefile b/Makefile
index d147987d4..726020cba 100644
--- a/Makefile
+++ b/Makefile
@@ -392,10 +392,6 @@ docdir:
 .PHONY: docs
 docs: $(MANPAGES) ## Generate documentation
 
-.PHONE: xref_helpmsgs_manpages
-xref_helpmsgs_manpages:
-	./hack/xref-helpmsgs-manpages
-
 install-podman-remote-%-docs: podman-remote docs $(MANPAGES)
 	rm -rf docs/build/remote
 	mkdir -p docs/build/remote
@@ -405,6 +401,7 @@ install-podman-remote-%-docs: podman-remote docs $(MANPAGES)
 .PHONY: man-page-check
 man-page-check:
 	hack/man-page-checker
+	hack/xref-helpmsgs-manpages
 
 .PHONY: swagger-check
 swagger-check:
diff --git a/contrib/cirrus/runner.sh b/contrib/cirrus/runner.sh
index b7e7ab852..4107f3b26 100755
--- a/contrib/cirrus/runner.sh
+++ b/contrib/cirrus/runner.sh
@@ -50,6 +50,10 @@ function _run_validate() {
     # Confirm compile via prior task + cache
     bin/podman --version
     bin/podman-remote --version
+
+    # FIXME FIXME FIXME: 2020-11-10: remove once Fedora 33 has FindBin
+    perl -MFindBin -e 0 &>/dev/null || dnf -y install perl-FindBin
+
     make validate  # Some items require a build
 }
 
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md
index e18c623ee..5922e0675 100644
--- a/docs/source/markdown/podman-create.1.md
+++ b/docs/source/markdown/podman-create.1.md
@@ -342,7 +342,7 @@ The initialization time needed for a container to bootstrap. The value can be ex
 The maximum time allowed to complete the healthcheck before an interval is considered failed.  Like start-period, the
 value can be expressed in a time format such as `1m22s`.  The default value is `30s`.
 
-**-h**, **--hostname**=*name*
+#### **-h**, **--hostname**=*name*
 
 Container host name
 
diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md
index 222ecf912..29dfee87e 100644
--- a/docs/source/markdown/podman-image-trust.1.md
+++ b/docs/source/markdown/podman-image-trust.1.md
@@ -37,15 +37,15 @@ Require signature (“signedBy”).
 Trust may be updated using the command **podman image trust set** for an existing trust scope.
 
 ## OPTIONS
-**-h**, **--help**
+#### **-h**, **--help**
   Print usage statement.
 
-**-f**, **--pubkeysfile**=*KEY1*
+#### **-f**, **--pubkeysfile**=*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.
 
-**-t**, **--type**=*value*
+#### **-t**, **--type**=*value*
   The trust type for this policy entry.
   Accepted values:
     **signedBy** (default): Require signatures with corresponding list of
@@ -59,7 +59,7 @@ Trust may be updated using the command **podman image trust set** for an existin
 #### **--raw**
   Output trust policy file as raw JSON
 
-**-j**, **--json**
+#### **-j**, **--json**
   Output trust as JSON for machine parsing
 
 ## EXAMPLES
diff --git a/docs/source/markdown/podman-images.1.md b/docs/source/markdown/podman-images.1.md
index fe5ad6843..531570666 100644
--- a/docs/source/markdown/podman-images.1.md
+++ b/docs/source/markdown/podman-images.1.md
@@ -15,7 +15,7 @@ Displays locally stored images, their names, and their IDs.
 
 ## OPTIONS
 
-**-a**, **--all**
+#### **-a**, **--all**
 
 Show all images (by default filter out the intermediate image layers). The default is false.
 
@@ -23,7 +23,7 @@ Show all images (by default filter out the intermediate image layers). The defau
 
 Show image digests
 
-**-f**, **--filter**=*filter*
+#### **-f**, **--filter**=*filter*
 
 Filter output based on conditions provided
 
diff --git a/docs/source/markdown/podman-import.1.md b/docs/source/markdown/podman-import.1.md
index db0bad241..ba512ca12 100644
--- a/docs/source/markdown/podman-import.1.md
+++ b/docs/source/markdown/podman-import.1.md
@@ -18,7 +18,7 @@ Note: `:` is a restricted character and cannot be part of the file name.
 
 ## OPTIONS
 
-**-c**, **--change**=*instruction*
+#### **-c**, **--change**=*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 19dd61c15..78895fa15 100644
--- a/docs/source/markdown/podman-info.1.md
+++ b/docs/source/markdown/podman-info.1.md
@@ -15,11 +15,11 @@ Displays information pertinent to the host, current storage stats, configured co
 
 ## OPTIONS
 
-**-D**, **--debug**
+#### **-D**, **--debug**
 
 Show additional information
 
-**-f**, **--format**=*format*
+#### **-f**, **--format**=*format*
 
 Change output format to "json" or a Go template.
 
diff --git a/docs/source/markdown/podman-logs.1.md b/docs/source/markdown/podman-logs.1.md
index bd8a01840..c93e4c9d7 100644
--- a/docs/source/markdown/podman-logs.1.md
+++ b/docs/source/markdown/podman-logs.1.md
@@ -30,7 +30,7 @@ to run containers such as CRI-O, the last started container could be from either
 
 The latest option is not supported on the remote client.
 
-**-n**, **--names**
+#### **-n**, **--names**
 
 Output the container name in the log
 
diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md
index 4d52749fa..8b8399c3e 100644
--- a/docs/source/markdown/podman-network-create.1.md
+++ b/docs/source/markdown/podman-network-create.1.md
@@ -22,7 +22,7 @@ Upon completion of creating the network, Podman will display the path to the new
 Disables the DNS plugin for this network which if enabled, can perform container to container name
 resolution.
 
-**-d**, **--driver**
+#### **-d**, **--driver**
 
 Driver to manage the network (default "bridge").  Currently only `bridge` is supported.
 
diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md
index d595afb3e..c8391861d 100644
--- a/docs/source/markdown/podman-play-kube.1.md
+++ b/docs/source/markdown/podman-play-kube.1.md
@@ -42,6 +42,10 @@ 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.
 
+#### **--log-driver**=driver
+
+Set logging driver for all created containers.
+
 #### **--network**=*cni networks*
 
 A comma-separated list of the names of CNI networks the pod should join.
diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md
index 1e1724aeb..6fd42f800 100644
--- a/docs/source/markdown/podman-pod-create.1.md
+++ b/docs/source/markdown/podman-pod-create.1.md
@@ -63,7 +63,7 @@ The image that will be created for the infra container. Default: "k8s.gcr.io/pau
 
 Set a static IP for the pod's shared network.
 
-**-l**, **--label**=*label*
+#### **-l**, **--label**=*label*
 
 Add metadata to a pod (e.g., --label com.example.key=value).
 
@@ -75,7 +75,7 @@ Read in a line delimited file of labels.
 
 Set a static MAC address for the pod's shared network.
 
-**-n**, **--name**=*name*
+#### **-n**, **--name**=*name*
 
 Assign a name to the pod.
 
@@ -96,6 +96,10 @@ Set network mode for the pod. Supported values are
   - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default.
   - **port_handler=slirp4netns**: Use the slirp4netns port forwarding.
 
+#### **--network-alias**=strings
+
+Add a DNS alias for the container. When the container is joined to a CNI network with support for the dnsname plugin, the container will be accessible through this name from other containers in the network.
+
 #### **--no-hosts**=**true**|**false**
 
 Disable creation of /etc/hosts for the pod.
@@ -104,7 +108,7 @@ Disable creation of /etc/hosts for the pod.
 
 Write the pod ID to the file.
 
-**-p**, **--publish**=*port*
+#### **-p**, **--publish**=*port*
 
 Publish a port or range of ports from the pod to the host.
 
diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md
index c35ebee65..ece3ab885 100644
--- a/docs/source/markdown/podman-pod-inspect.1.md
+++ b/docs/source/markdown/podman-pod-inspect.1.md
@@ -18,7 +18,7 @@ to run pods such as CRI-O, the last started pod could be from either of those me
 
 The latest option is not supported on the remote client.
 
-**-f**, **--format**=*format*
+#### **-f**, **--format**=*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-restart.1.md b/docs/source/markdown/podman-restart.1.md
index 5f83bedde..60c90ada1 100644
--- a/docs/source/markdown/podman-restart.1.md
+++ b/docs/source/markdown/podman-restart.1.md
@@ -26,7 +26,7 @@ The latest option is not supported on the remote client.
 #### **--running**
 Restart all containers that are already in the *running* state.
 
-**-t**, **--time**=*time*
+#### **-t**, **--time**=*time*
 Timeout to wait before forcibly stopping the container.
 
 
diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md
index 61789dc8f..f67b7c652 100644
--- a/docs/source/markdown/podman-run.1.md
+++ b/docs/source/markdown/podman-run.1.md
@@ -380,7 +380,7 @@ value can be expressed in a time format such as **1m22s**.  The default value is
 
 Print usage statement
 
-**-h**, **--hostname**=*name*
+#### **-h**, **--hostname**=*name*
 
 Container host name
 
diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md
index f314e8c56..c8c6476bf 100644
--- a/docs/source/markdown/podman-system-connection-add.1.md
+++ b/docs/source/markdown/podman-system-connection-add.1.md
@@ -15,7 +15,7 @@ The user will be prompted for the remote ssh login password or key file pass phr
 
 ## OPTIONS
 
-**-d**, **--default**=*false*
+#### **-d**, **--default**=*false*
 
 Make the new destination the default for this user.
 
@@ -25,7 +25,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.
 
-**-p**, **--port**=*port*
+#### **-p**, **--port**=*port*
 
 Port for ssh destination. The default value is `22`.
 
diff --git a/docs/source/markdown/podman-system-df.1.md b/docs/source/markdown/podman-system-df.1.md
index e0aa2fa47..6c21a20b4 100644
--- a/docs/source/markdown/podman-system-df.1.md
+++ b/docs/source/markdown/podman-system-df.1.md
@@ -14,7 +14,7 @@ Show podman disk usage
 
 Pretty-print images using a Go template
 
-**-v**, **--verbose**[=*true|false*]
+#### **-v**, **--verbose**[=*true|false*]
 Show detailed information on space usage
 
 ## EXAMPLE
diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md
index 9df8e2ec5..4fd911c1f 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).
 
 Print usage statement
 
-**-l**, **--label**=*label*
+#### **-l**, **--label**=*label*
 
 Set metadata for a volume (e.g., --label mykey=value).
 
-**-o**, **--opt**=*option*
+#### **-o**, **--opt**=*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 5652d9faa..e6be69e73 100644
--- a/docs/source/markdown/podman-volume-inspect.1.md
+++ b/docs/source/markdown/podman-volume-inspect.1.md
@@ -16,11 +16,11 @@ Volumes can be queried individually by providing their full name or a unique par
 
 ## OPTIONS
 
-**-a**, **--all**
+#### **-a**, **--all**
 
 Inspect all volumes.
 
-**-f**, **--format**=*format*
+#### **-f**, **--format**=*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 353d37fd7..a3f3ff9ba 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
 
-**-f**, **--filter**=*filter*
+#### **-f**, **--filter**=*filter*
 
 Filter volume output.
 
@@ -26,7 +26,7 @@ Format volume output using Go template.
 
 Print usage statement.
 
-**-q**, **--quiet**
+#### **-q**, **--quiet**
 
 Print volume output in quiet mode. Only print the volume names.
 
diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md
index 753c816b5..097dded86 100644
--- a/docs/source/markdown/podman-volume-prune.1.md
+++ b/docs/source/markdown/podman-volume-prune.1.md
@@ -14,7 +14,7 @@ unused volumes. To bypass the confirmation, use the **--force** flag.
 
 ## OPTIONS
 
-**-f**, **--force**
+#### **-f**, **--force**
 
 Do not prompt for confirmation.
 
diff --git a/docs/source/markdown/podman-volume-rm.1.md b/docs/source/markdown/podman-volume-rm.1.md
index c831ad7b9..5f2137f73 100644
--- a/docs/source/markdown/podman-volume-rm.1.md
+++ b/docs/source/markdown/podman-volume-rm.1.md
@@ -15,11 +15,11 @@ Volumes can be removed individually by providing their full name or a unique par
 
 ## OPTIONS
 
-**-a**, **--all**
+#### **-a**, **--all**
 
 Remove all volumes.
 
-**-f**, **--force**
+#### **-f**, **--force**
 
 Remove a volume by force.
 If it is being used by containers, the containers will be removed first.
diff --git a/hack/podman-commands.sh b/hack/podman-commands.sh
index 587cac782..fd4ff2501 100755
--- a/hack/podman-commands.sh
+++ b/hack/podman-commands.sh
@@ -23,7 +23,7 @@ function die() {
 # the command name but not its description.
 function podman_commands() {
     $PODMAN help "$@" |\
-        awk '/^Available Commands:/{ok=1;next}/^Flags:/{ok=0}ok { print $1 }' |\
+        awk '/^Available Commands:/{ok=1;next}/^Options:/{ok=0}ok { print $1 }' |\
         grep .
 }
 
diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages
index a7063259f..082cc63f2 100755
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -248,7 +248,7 @@ sub podman_help {
                     unless $subcommand eq 'help';       # 'help' not in man
             }
         }
-        elsif ($section eq 'flags') {
+        elsif ($section eq 'options') {
             # Handle '--foo' or '-f, --foo'
             if ($line =~ /^\s{1,10}(--\S+)\s/) {
                 print "> podman @_ $1\n"                        if $debug;
@@ -293,7 +293,7 @@ sub podman_man {
         elsif ($line =~ /^\#\#\s+(SUB)?COMMANDS/) {
             $section = 'commands';
         }
-        elsif ($line =~ /^\#\#/) {
+        elsif ($line =~ /^\#\#[^#]/) {
             $section = '';
         }
 
@@ -329,12 +329,15 @@ sub podman_man {
             }
 
             @most_recent_flags = ();
-            # Handle any variation of '**--foo**, **-f**'
-            while ($line =~ s/^\*\*((--[a-z0-9-]+)|(-.))\*\*(,\s+)?//g) {
-                $man{$1} = 1;
-
-                # Keep track of them, in case we see 'Not implemented' below
-                push @most_recent_flags, $1;
+            # As of PR #8292, all options are <h4> and anchored
+            if ($line =~ s/^\#{4}\s+//) {
+                # Handle any variation of '**--foo**, **-f**'
+                while ($line =~ s/^\*\*((--[a-z0-9-]+)|(-.))\*\*(,\s+)?//g) {
+                    $man{$1} = 1;
+
+                    # Keep track of them, in case we see 'Not implemented' below
+                    push @most_recent_flags, $1;
+                }
             }
         }
     }