git/Documentation/lint-man-section-order.perl
Ævar Arnfjörð Bjarmason 414abf159f docs: fix linting issues due to incorrect relative section order
Re-order the sections of a few manual pages to be consistent with the
entirety of the rest of our documentation. This allows us to remove
the just-added whitelist of "bad" order from
lint-man-section-order.perl.

I'm doing that this way around so that code will be easy to dig up if
we'll need it in the future. I've intentionally not added some other
sections such as EXAMPLES to the list of known sections.

If we were to add that we'd find some out of order. Perhaps we'll want
to order those consistently as well in the future, at which point
whitelisting some of them might become handy again.

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-10 23:36:34 -07:00

105 lines
2 KiB
Perl
Executable file

#!/usr/bin/perl
use strict;
use warnings;
my %SECTIONS;
{
my $order = 0;
%SECTIONS = (
'NAME' => {
required => 1,
order => $order++,
},
'SYNOPSIS' => {
required => 1,
order => $order++,
},
'DESCRIPTION' => {
required => 1,
order => $order++,
},
'OPTIONS' => {
order => $order++,
required => 0,
},
'CONFIGURATION' => {
order => $order++,
},
'BUGS' => {
order => $order++,
},
'SEE ALSO' => {
order => $order++,
},
'GIT' => {
required => 1,
order => $order++,
},
);
}
my $SECTION_RX = do {
my ($names) = join "|", keys %SECTIONS;
qr/^($names)$/s;
};
my $exit_code = 0;
sub report {
my ($msg) = @_;
print "$ARGV:$.: $msg\n";
$exit_code = 1;
}
my $last_was_section;
my @actual_order;
while (my $line = <>) {
chomp $line;
if ($line =~ $SECTION_RX) {
push @actual_order => $line;
$last_was_section = 1;
# Have no "last" section yet, processing NAME
next if @actual_order == 1;
my @expected_order = sort {
$SECTIONS{$a}->{order} <=> $SECTIONS{$b}->{order}
} @actual_order;
my $expected_last = $expected_order[-2];
my $actual_last = $actual_order[-2];
if ($actual_last ne $expected_last) {
report("section '$line' incorrectly ordered, comes after '$actual_last'");
}
next;
}
if ($last_was_section) {
my $last_section = $actual_order[-1];
if (length $last_section ne length $line) {
report("dashes under '$last_section' should match its length!");
}
if ($line !~ /^-+$/) {
report("dashes under '$last_section' should be '-' dashes!");
}
$last_was_section = 0;
}
if (eof) {
# We have both a hash and an array to consider, for
# convenience
my %actual_sections;
@actual_sections{@actual_order} = ();
for my $section (sort keys %SECTIONS) {
next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
report("has no required '$section' section!");
}
# Reset per-file state
{
@actual_order = ();
# this resets our $. for each file
close ARGV;
}
}
}
exit $exit_code;