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

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:

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
 }
 

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
 

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

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
 

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

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.
 

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
 

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.
 

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.

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.
 

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.

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.
 
 

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
 

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

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

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.

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
 

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.
 

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.
 

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.

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

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,6 +329,8 @@ sub podman_man {
             }
 
             @most_recent_flags = ();
+            # 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;
@@ -338,6 +340,7 @@ sub podman_man {
                 }
             }
         }
+    }
     close $fh;
 
     # Special case: the 'image trust' man page tries hard to cover both set