man page crossrefs: add --filter autocompletes

For all commands with a --filter option, cross-reference
against man pages, and vice-versa.

I'm sorry. I know this script has gone off the deep end.

[NO NEW TESTS NEEDED] although actually I would like to test some broken completions

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

1 files changed, 81 insertions, 5 deletions

diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages
index 781e200b3..2ca861f94 100755
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -203,6 +203,13 @@ sub xref_by_help {
 
   OPTION:
     for my $k (sort keys %$help) {
+        if (! ref($man)) {
+            # Super-unlikely but I've seen it
+            warn "$ME: 'podman @subcommand' is not documented in man pages!\n";
+            ++$Errs;
+            next OPTION;
+        }
+
         if (exists $man->{$k}) {
             if (ref $help->{$k}) {
                 # This happens when 'podman foo --format' offers
@@ -233,7 +240,11 @@ sub xref_by_help {
 
             # Nope, it's not that case.
             my $man = $man->{_path} || 'man';
-            warn "$ME: 'podman @subcommand --help' lists '$k', which is not in $man\n";
+            # The usual case is "podman ... --help"...
+            my $what = '--help';
+            # ...but for *options* (e.g. --filter), we're checking command completion
+            $what = '<TAB>' if $subcommand[-1] =~ /^--/;
+            warn "$ME: 'podman @subcommand $what' lists '$k', which is not in $man\n";
             ++$Errs;
         }
     }
@@ -296,7 +307,10 @@ sub xref_by_man {
             # Special case for hidden or external commands
             next if $Skip_Subcommand{$k};
 
-            warn "$ME: 'podman @subcommand': $k in $man, but not --help\n";
+            # It's not always --help, sometimes we check <TAB> completion
+            my $what = '--help';
+            $what = 'command completion' if $subcommand[-1] =~ /^--/;
+            warn "$ME: 'podman @subcommand': '$k' in $man, but not in $what\n";
             ++$Errs;
         }
     }
@@ -420,7 +434,17 @@ sub podman_help {
                         ++$Errs;
                     }
                 }
-           }
+            }
+            # Same thing, for --filter
+            elsif ($opt eq '--filter') {
+                my @completions = _completions(@_, '--filter=');
+                for my $c (@completions) {
+                    if ($c =~ /^(\S+)=/) {
+                        $help{$opt} = {} if ! ref($help{$opt});
+                        $help{$opt}{$1} = 1;
+                    }
+                }
+            }
         }
     }
     close $fh
@@ -447,9 +471,11 @@ sub podman_man {
     my $previous_subcmd = '';
     my $previous_flag = '';
     my $previous_format = '';
+    my $previous_filter = '';
+  LINE:
     while (my $line = <$fh>) {
         chomp $line;
-        next unless $line;		# skip empty lines
+        next LINE unless $line;		# skip empty lines
 
         # First line (page title) must match the command name.
         if ($line =~ /^%\s+/) {
@@ -561,7 +587,7 @@ sub podman_man {
                 }
 
                 # Options with no '=whatever'
-                next if !$line;
+                next LINE if !$line;
 
                 # Anything remaining *must* be of the form '=<possibilities>'
                 if ($line !~ /^=/) {
@@ -639,6 +665,56 @@ sub podman_man {
                     $previous_format = $format;
                 }
             }
+            # Same as above, but with --filter
+            elsif ($previous_flag eq '--filter') {
+                if ($line =~ /^\|\s+(\S+)\s+\|/) {
+                    my $filter = $1;
+
+                    # Special-case transformation: some man pages use
+                    # asterisks, "*foo*", some don't. Ignore asterisks.
+                    $filter =~ tr/\*//d;
+
+                    # (Garbage: these are just table column titles & dividers)
+                    next LINE if $filter eq 'Filter';
+                    next LINE if $filter =~ /---+/;
+
+                    # Another special case: treat slash-separated options
+                    # ("after/since") as identical, and require that each
+                    # be documented.
+                    for my $f (split '/', $filter) {
+                        # Special case for negated options ("label!="): allow,
+                        # but only immediately after the positive case.
+                        if ($f =~ s/!$//) {
+                            if ($f ne $previous_filter) {
+                                warn "$ME: $subpath:$.: filter '$f!' only allowed immediately after its positive\n";
+                                ++$Errs;
+                            }
+                            next LINE;
+                        }
+
+                        if (! ref($man{$previous_flag})) {
+                            $man{$previous_flag} = { _path => $subpath };
+                        }
+                        $man{$previous_flag}{$f} = 1;
+                    }
+
+                    # Sort order check, case-insensitive
+                    # FIXME FIXME! Disabled for now because it would make
+                    # this PR completely impossible to review (as opposed to
+                    # only mostly-impossible)
+                    #if (lc($filter) lt lc($previous_filter)) {
+                    #  warn "$ME: $subpath:$.: filter specifier '$filter' should precede '$previous_filter'\n";
+                    #  ++$Errs;
+                    #}
+
+                    # Dup check. Yes, it happens.
+                    if (lc($filter) eq lc($previous_filter)) {
+                        warn "$ME: $subpath:$.: filter specifier '$filter' is a dup\n";
+                        ++$Errs;
+                    }
+                    $previous_filter = $filter;
+                }
+            }
         }
 
         # It's easy to make mistakes in the SEE ALSO elements.