From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 04 Oct 2026 13:17:27 GMT
Subject: Re: [PATCH v2] doc: don't require a SYNOPSIS in section 7
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.

> 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, ...

>  	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.