Re: [PATCH] doc: don't require a SYNOPSIS in section 7
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 2, 2026, 17:33 UTC
- Message-ID
- <xmqqv77kvwgr.fsf@gitster.g>
- In-Reply-To
- <pull.2246.git.1790957227881.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 5 quoted lines
> From: Julia Evans <julia@jvns.ca> > > 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.
Show 16 quoted lines
> 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.
Show 12 quoted lines
> 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;