From: Julia Evans <julia@jvns.ca>
Date: Fri, 02 Oct 2026 18:10:09 GMT
Subject: Re: [PATCH] doc: don't require a SYNOPSIS in section 7
Message-ID: <bdc1fd67-83dd-4c66-9afe-7f35c572afa3@app.fastmail.com>
In-Reply-To: <xmqq7bk0vv38.fsf@gitster.g>

On Fri, Oct 2, 2026, at 2:03 PM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> diff --git c/Documentation/lint-man-section-order.perl w/Documentation/lint-man-section-order.perl
>> index 02408a0062..ce60c34809 100755
>> --- c/Documentation/lint-man-section-order.perl
>> +++ w/Documentation/lint-man-section-order.perl
>> @@ -55,8 +55,23 @@ sub report {
>>  
>>  my $last_was_section;
>>  my @actual_order;
>> +my $section_tweak_done;
>>  while (my $line = <>) {
>>  	chomp $line;
>> +
>> +	if (!$section_tweak_done) {
>> +		# assume the first line is formatted like 'gitglossary(7)'
>> +		my $firstline = <>;
>
> Ah, this was obviously buggy.  Not <>, but we should use $line here.
>
>> +		$firstline =~ m/\((\d)\)/;
>> +		my $man_section_number = $1;
>> +
>> +		if ($man_section_number == "7") {
>> +			# section 7 usually do not have SYNOPSIS
>> +			$SECTIONS{SYNOPSIS}{required} = 0;
>> +		}
>> +		$section_tweak_done = 1;
>> +	}
>> +
>>  	if ($line =~ $SECTION_RX) {
>>  		push @actual_order => $line;
>>  		$last_was_section = 1;

I'm happy with whichever version of the script you think is easiest to maintain.
I saw that perl also has Tie::File built in which lets you just treat the file as an
array instead of worrying about <>. https://metacpan.org/pod/Tie::File