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

1 files changed, 11 insertions, 8 deletions

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;
+                }
             }
         }
     }