From: Junio C Hamano Date: Fri, 02 Oct 2026 17:33:24 GMT Subject: Re: [PATCH] doc: don't require a SYNOPSIS in section 7 Message-ID: In-Reply-To: "Julia Evans via GitGitGadget" writes: > From: Julia Evans > > Remove the SYNOPSIS section from the section 7 man pages where > appropriate, to avoid having a section that contains no information. > It's not the norm in section 7 to always require a SYNOPSIS. Very true. > diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc > index 6815d6bfb7..9c4598e29c 100644 > --- a/Documentation/gitcli.adoc > +++ b/Documentation/gitcli.adoc > @@ -5,11 +5,6 @@ NAME > ---- > gitcli - Git command-line interface and conventions > > -SYNOPSIS > --------- > -gitcli > - > - > DESCRIPTION > ----------- > Yup. Thanks for starting this move. These "we add meaningless filler only because we need to" were always eyesore. > diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl > index 02408a0062..e032f6ae53 100755 > --- a/Documentation/lint-man-section-order.perl > +++ b/Documentation/lint-man-section-order.perl > @@ -53,6 +53,11 @@ sub report { > $exit_code = 1; > } > > +# assume the first line is formatted like 'gitglossary(7)' > +my $firstline = <>; > +$firstline =~ m/\((\d)\)/; > +my $man_section_number = $1; This means that the main loop that has already read all the lines of the file no longer sees the first line. I do not think it would immediately break anything (in other words, the current implementation of the loop only checks the section header and nothing else), but it may be an unhealthy thing to assume that this will not change. It would be very simple to move it inside the loop. Would it work better to do it this way, I wonder? The idea is to notice what manual sections we are in, and tweak the %SECTIONS contents there, to allow us customize behaviour for other sections later, and keep such customizations out of the actual code. Documentation/lint-man-section-order.perl | 15 +++++++++++++++ 1 file changed, 15 insertions(+) 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 = <>; + $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;