From ad7c54e13a17eed8efb7b1367a17859d6f7e3032 Mon Sep 17 00:00:00 2001
From: Ed Santiago <santiago@redhat.com>
Date: Tue, 12 Jul 2022 10:55:23 -0600
Subject: 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>
---
 hack/xref-helpmsgs-manpages | 47 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 43 insertions(+), 4 deletions(-)

(limited to 'hack/xref-helpmsgs-manpages')

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;
+                            }
+                        }
+                    }
                 }
             }
         }
-- 
cgit v1.2.3-54-g00ecf