From: Julia Evans <julia@jvns.ca>
Date: Tue, 06 Oct 2026 11:17:36 GMT
Subject: Re: [PATCH v2] doc: don't require a SYNOPSIS in section 7
Message-ID: <afb72458-bc22-4a7a-87ec-83c77e83aeaf@app.fastmail.com>
In-Reply-To: <xmqqece5vc48.fsf@gitster.g>



On Sun, Oct 4, 2026, at 9:17 AM, Junio C Hamano wrote:
> "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.
>
>> 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";

Or maybe like

   `$line =~ m/\((\d)\)/ or report("first line should look like `somename(1)`");`

or some similar error message