Re: [PATCH v2] doc: don't require a SYNOPSIS in section 7
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 4, 2026, 13:17 UTC
- Message-ID
- <xmqqece5vc48.fsf@gitster.g>
- In-Reply-To
- <pull.2246.v2.git.1791033057232.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Changes in v2: Tuomas rewrote the Perl script changes to be both more > declarative and and more correct. Previously it didn't work if there > were multiple files passed on the command line.
Show 25 quoted lines
> diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
> index 02408a0062..160c65e1be 100755
> --- a/Documentation/lint-man-section-order.perl
> +++ b/Documentation/lint-man-section-order.perl
> @@ -13,6 +13,9 @@ my %SECTIONS;
> },
> 'SYNOPSIS' => {
> required => 1,
> + optional_in_man_sections => {
> + '7' => 1,
> + },
> order => $order++,
> },
> 'DESCRIPTION' => {
> @@ -53,10 +56,18 @@ sub report {
> $exit_code = 1;
> }
>
> +my $man_section_number;
> my $last_was_section;
> my @actual_order;
> while (my $line = <>) {
> chomp $line;
> +
> + if ($. == 1) {OK, this, together with the explicit "close ARGV" later in postcontext upon seeing eof, lets us do a "special" thing on the first line.
I think for the purpose of "doc lint", this implementation is good enough, especially with documented "assumption".
If we wanted to shoot for a bit more robustness, on the other hand, we would want to handle when $1 is left undef ...
> + # assume the first line is formatted like 'gitglossary(7)' > + $line =~ m/\((\d)\)/; > + $man_section_number = $1;
... here. Perhaps like
$man_section_number = ($line =~ /\((\d)\)/) ? $1 : "0";
If we left $man_section_number undef, ...
Show 10 quoted lines
> if ($line =~ $SECTION_RX) {
> push @actual_order => $line;
> $last_was_section = 1;
> @@ -92,7 +103,9 @@ while (my $line = <>) {
> @actual_sections{@actual_order} = ();
>
> for my $section (sort keys %SECTIONS) {
> - next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
> + next if !$SECTIONS{$section}->{required} or
> + $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or... this will access
$SECTIONS{$section}->{optional_in_man_sections}->{undef}and may trigger a warning on use of uninitialized value.
Also, this would autovivify $SECTIONS{*}{optional_in_man_sections} for sections that don't have optional_in_man_sections hash (like NAME and DESCRIPTION), which may be harmless but needless.