summaryrefslogtreecommitdiff
path: root/hack/xref-helpmsgs-manpages
diff options
context:
space:
mode:
authorEd Santiago <santiago@redhat.com>2022-03-23 12:29:08 -0600
committerEd Santiago <santiago@redhat.com>2022-03-23 13:49:42 -0600
commit9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541 (patch)
tree37dad6631948e2cfa28165a423c6bf22f9ab4d1e /hack/xref-helpmsgs-manpages
parent73713062806aa4c2db25dc62e2fff47406085dc8 (diff)
downloadpodman-9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541.tar.gz
podman-9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541.tar.bz2
podman-9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541.zip
man pages: sort flags, and keep them that way
Command flags (OPTIONS) in man pages have to date been in haphazard order. Sometimes that order is sensible, e.g., most-important options first, but more often they're just in arbitrary places. This makes life hard for users. Here, I update the man-page-check Makefile script so it checks and enforces alphabetical order in OPTIONS sections. Then -- the hard part -- update all existing man pages to conform to this requirement. Signed-off-by: Ed Santiago <santiago@redhat.com>
Diffstat (limited to 'hack/xref-helpmsgs-manpages')
-rwxr-xr-xhack/xref-helpmsgs-manpages24
1 files changed, 21 insertions, 3 deletions
diff --git a/hack/xref-helpmsgs-manpages b/hack/xref-helpmsgs-manpages
index a447f4da1..33ba43e9b 100755
--- a/hack/xref-helpmsgs-manpages
+++ b/hack/xref-helpmsgs-manpages
@@ -287,6 +287,7 @@ sub podman_man {
my $section = '';
my @most_recent_flags;
my $previous_subcmd = '';
+ my $previous_flag = '';
while (my $line = <$fh>) {
chomp $line;
next unless $line; # skip empty lines
@@ -294,6 +295,12 @@ sub podman_man {
# .md files designate sections with leading double hash
if ($line =~ /^##\s*(GLOBAL\s+)?OPTIONS/) {
$section = 'flags';
+ $previous_flag = '';
+ }
+ elsif ($line =~ /^###\s+\w+\s+OPTIONS/) {
+ # poaman image trust has sections for set & show
+ $section = 'flags';
+ $previous_flag = '';
}
elsif ($line =~ /^\#\#\s+(SUB)?COMMANDS/) {
$section = 'commands';
@@ -320,7 +327,7 @@ sub podman_man {
# $1 will be changed by recursion _*BEFORE*_ left-hand assignment
my $subcmd = $1;
if ($previous_subcmd gt $subcmd) {
- warn "$ME: $subpath: '$previous_subcmd' and '$subcmd' are out of order\n";
+ warn "$ME: $subpath:$.: '$previous_subcmd' and '$subcmd' are out of order\n";
++$Errs;
}
$previous_subcmd = $subcmd;
@@ -342,9 +349,20 @@ sub podman_man {
# If option has long and short form, long must come first.
# 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) {
- $man{$1} = 1;
- push @most_recent_flags, $1;
+ my $flag = $1;
+ $man{$flag} = 1;
+ if ($flag lt $previous_flag && $is_first) {
+ warn "$ME: $subpath:$.: $flag should precede $previous_flag\n";
+ ++$Errs;
+ }
+ $previous_flag = $flag if $is_first;
+ push @most_recent_flags, $flag;
+
+ # Further iterations of /g are allowed to be out of order,
+ # e.g., it's OK for "--namespace, -ns" to precede --nohead
+ $is_first = 0;
}
# Short form
if ($line =~ s/^\*\*(-[a-zA-Z0-9])\*\*(=\*[a-zA-Z0-9-]+\*)?//g) {