opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-10-13 01:06:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

man page checker: enforce stricter options format

Browse Source 
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>
This commit is contained in:
Ed Santiago
2022-07-12 10:55:23 -06:00
parent d4dc067117
commit ad7c54e13a
29 changed files with 182 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
hack/xref-helpmsgs-manpages
View File

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