git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Julia Evans <julia@jvns.ca>
Date
Oct 2, 2026, 18:10 UTC
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:
Show 33 quoted lines
> 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

Previous: Junio C HamanoNext: Julia Evans
Message 4 of 15 in “doc: don't require a SYNOPSIS in section 7”
  1. doc: don't require a SYNOPSIS in section 7Julia Evans via GitGitGadget, Oct 2, 2026
  2. Junio C HamanoOct 2, 2026
  3. Junio C HamanoOct 2, 2026
  4. Julia EvansOct 2, 2026
  5. Julia EvansOct 2, 2026
  6. Junio C HamanoOct 2, 2026
  7. Tuomas AholaOct 3, 2026
  8. Julia EvansOct 3, 2026
  9. Tuomas AholaOct 3, 2026
  10. doc: don't require a SYNOPSIS in section 7Julia Evans via GitGitGadget, Oct 3, 2026
  11. Junio C HamanoOct 4, 2026
  12. Julia EvansOct 6, 2026
  13. Junio C HamanoOct 6, 2026
  14. doc: don't require a SYNOPSIS in section 7Julia Evans via GitGitGadget, Oct 6, 2026
  15. Junio C HamanoOct 6, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.