Re: [PATCH] doc: don't require a SYNOPSIS in section 7

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 2, 2026, 21:34 UTC
Message-ID: <xmqqo6dbvlaf.fsf@gitster.g>
In-Reply-To: <01891b4b-ce04-41aa-8065-d7b88e466dbc@app.fastmail.com>

"Julia Evans" <julia@jvns.ca> writes:

Show 21 quoted lines

>> +# assume the first line is formatted like 'gitglossary(7)'
>> +my $firstline = <>;
>> +$firstline =~ m/\((\d)\)/;
>> +my $man_section_number = $1;
>> +
>>  my $last_was_section;
>>  my @actual_order;
>>  while (my $line = <>) {
>> @@ -93,6 +98,8 @@ while (my $line = <>) {
>> 
>>  		for my $section (sort keys %SECTIONS) {
>>  			next if !$SECTIONS{$section}->{required} or exists 
>> $actual_sections{$section};
>> +			# Synopsis is not required in section 7
>> +			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
>>  			report("has no required '$section' section!");
>>  		}
>
>
> I just realized that this script is actually supposed to be able to process multiple
> files as command line arguments, and that this patch won't work for that.

Yeah, your version would then notice only the first line of the first file, and my update would also do the same.

You can work from what I gave you and inside the "eof" part of the loop reset the %SECTIONS back to the original (which means you'd need to keep a separate copy of the original) and also reset the "did I tweak the %SECTIONS thing already? have I handled the first line of the current file?" variable.

> I don't understand how Perl's `<>`  works when you pass multiple files as
> command line arguments and that might be too much of a can of worms for me to
> figure right now :/

"man perlfunc" section on "eof" has an example to show what to detect and reset when you reached the end of each file within a "while (<>)" loop.

               # reset line numbering on each input file
               while (<>) {
                   next if /^\s*#/;  # skip comments
                   print "$.\t$_";
               } continue {
                   close ARGV if eof;  # Not eof()!
               }

The explicit "close ARGV if eof;" is how the example resets the $. counter (which by default counts all the lines coming from <> across multiple files).