From: Julia Evans <julia@jvns.ca>
Date: Sat, 03 Oct 2026 11:37:00 GMT
Subject: Re: [PATCH] doc: don't require a SYNOPSIS in section 7
Message-ID: <79451beb-15c4-42f3-92fe-1b7fd284b21c@app.fastmail.com>
In-Reply-To: <20261003073303.G-Gck%taahol@utu.fi>

> Something slightly more declarative I managed to hack up:
>
> 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 @@
>  		},
>  		'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) {
> +		# assume the first line is formatted like 'gitglossary(7)'
> +		$line =~ m/\((\d)\)/;
> +		$man_section_number = $1;
> +	}
> +
>  	if ($line =~ $SECTION_RX) {
>  		push @actual_order => $line;
>  		$last_was_section = 1;
> @@ -92,7 +103,9 @@ sub report {
>  		@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
> +				exists $actual_sections{$section};
>  			report("has no required '$section' section!");
>  		}

This looks great! Will use for v2 and mark you as a coauthor, thank you :D
(let me know if there's a better way to do that also, still learning the process)

I wasn't sure what `$.` was before but this makes it clear that it's the current
line number (and https://perldoc.perl.org/perlvar agrees). Apparently
`$ARGV` is the name of the current file. (different from @ARGV)