From 9b0c8d23bddd0fccd6a1faa3fa7f5b7e0373f541 Mon Sep 17 00:00:00 2001
From: Ed Santiago <santiago@redhat.com>
Date: Wed, 23 Mar 2022 12:29:08 -0600
Subject: 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>
---
hack/xref-helpmsgs-manpages | 24 +++++++++++++++++++++---
1 file changed, 21 insertions(+), 3 deletions(-)
(limited to 'hack')
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) {
--
cgit v1.2.3-54-g00ecf