From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 06 Oct 2026 20:40:34 GMT
Subject: Re: [PATCH v3] doc: don't require a SYNOPSIS in section 7
Message-ID: <xmqqfqyid0l9.fsf@gitster.g>
In-Reply-To: <pull.2246.v3.git.1791305670386.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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.
>
> Update the perl script with a special case for section 7.
>
> Tested by running `make lint-docs`, and looked at the renaming synopses
> with this fish script snippet:
>
> for i in *.7
>    echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
> end
>
> Co-authored-by: Tuomas Ahola <taahol@utu.fi>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>     doc: don't require a SYNOPSIS in section 7
>     
>     Changes in v3: Make sure that $man_section_number doesn't become
>     undefined if the first line doesn't match the regex
>     
>     Tested on a file with a first line that isn't well-formatted to make
>     sure it works and got this output:
>     
>     gitdatamodel.adoc:1: first line must be formatted like 'gitfaq(7)'

And it aborts the whole thing?  That does count as a lint.  We are
promoting the "assume the first line is ..." to require the format,
which is probably a good thing to do.

Will replace.  Thanks.