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

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

[Julia Evans via GitGitGadget]

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

Signed-off-by: Julia Evans <julia@jvns.ca>
---
    doc: don't require a SYNOPSIS in section 7
    
    Seemed like a nice quick improvement, though happy to drop this if it
    turns into a can of worms
    
    I haven't written Perl since probably 2007 so might have made a mistake
    there but the code does seem to run :). Even managed to write it with no
    LLMs and just some good ol perlrequick.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2246%2Fjvns%2Fno-synopsis-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2246/jvns/no-synopsis-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2246

 Documentation/gitcli.adoc                 | 5 -----
 Documentation/gitcore-tutorial.adoc       | 4 ----
 Documentation/gitdatamodel.adoc           | 4 ----
 Documentation/giteveryday.adoc            | 5 -----
 Documentation/gitfaq.adoc                 | 4 ----
 Documentation/gitglossary.adoc            | 4 ----
 Documentation/gitpacking.adoc             | 4 ----
 Documentation/gitrevisions.adoc           | 5 -----
 Documentation/gittutorial-2.adoc          | 5 -----
 Documentation/gittutorial.adoc            | 5 -----
 Documentation/gitworkflows.adoc           | 6 ------
 Documentation/lint-man-section-order.perl | 7 +++++++
 12 files changed, 7 insertions(+), 51 deletions(-)

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
 -----------
 
diff --git a/Documentation/gitcore-tutorial.adoc b/Documentation/gitcore-tutorial.adoc
index 2122aeb976..71fda63a1c 100644
--- a/Documentation/gitcore-tutorial.adoc
+++ b/Documentation/gitcore-tutorial.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitcore-tutorial - A Git core tutorial for developers
 
-SYNOPSIS
---------
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index 56b7635c19..8d9be02036 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitdatamodel - Git's core data model
 
-SYNOPSIS
---------
-gitdatamodel
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/giteveryday.adoc b/Documentation/giteveryday.adoc
index 6cfdd0e07b..0c9db2f150 100644
--- a/Documentation/giteveryday.adoc
+++ b/Documentation/giteveryday.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 giteveryday - A useful minimum set of commands for Everyday Git
 
-SYNOPSIS
---------
-
-Everyday Git With 20 Commands Or So
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitfaq.adoc b/Documentation/gitfaq.adoc
index f6c9b9d9f7..b26e4e3a09 100644
--- a/Documentation/gitfaq.adoc
+++ b/Documentation/gitfaq.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitfaq - Frequently asked questions about using Git
 
-SYNOPSIS
---------
-gitfaq
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitglossary.adoc b/Documentation/gitglossary.adoc
index b046d9cb29..eb1e60832e 100644
--- a/Documentation/gitglossary.adoc
+++ b/Documentation/gitglossary.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitglossary - A Git Glossary
 
-SYNOPSIS
---------
-*
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitpacking.adoc b/Documentation/gitpacking.adoc
index e6de6ec824..b0d952c797 100644
--- a/Documentation/gitpacking.adoc
+++ b/Documentation/gitpacking.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitpacking - Advanced concepts related to packing in Git
 
-SYNOPSIS
---------
-gitpacking
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitrevisions.adoc b/Documentation/gitrevisions.adoc
index 7146117de5..4412f84d83 100644
--- a/Documentation/gitrevisions.adoc
+++ b/Documentation/gitrevisions.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gitrevisions - Specifying revisions and ranges for Git
 
-SYNOPSIS
---------
-gitrevisions
-
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gittutorial-2.adoc b/Documentation/gittutorial-2.adoc
index 8bdb7d0bd3..6a4d482ed6 100644
--- a/Documentation/gittutorial-2.adoc
+++ b/Documentation/gittutorial-2.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gittutorial-2 - A tutorial introduction to Git: part two
 
-SYNOPSIS
---------
-[verse]
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gittutorial.adoc b/Documentation/gittutorial.adoc
index 519b8d8be2..03120ba191 100644
--- a/Documentation/gittutorial.adoc
+++ b/Documentation/gittutorial.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gittutorial - A tutorial introduction to Git
 
-SYNOPSIS
---------
-[verse]
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc
index 59305265c5..ad02828bff 100644
--- a/Documentation/gitworkflows.adoc
+++ b/Documentation/gitworkflows.adoc
@@ -5,12 +5,6 @@ NAME
 ----
 gitworkflows - An overview of recommended workflows with Git
 
-SYNOPSIS
---------
-[verse]
-git *
-
-
 DESCRIPTION
 -----------
 
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;
+
 my $last_was_section;
 my @actual_order;
 while (my $line = <>) {
@@ -93,6 +98,8 @@ while (my $line = <>) {
 
 		for my $section (sort keys %SECTIONS) {
 			next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
+			# Synopsis is not required in section 7
+			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
 			report("has no required '$section' section!");
 		}
 

base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
-- 
gitgitgadget

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

[Junio C Hamano]

"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.

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;

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

[Junio C Hamano]

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;

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

[Julia Evans]

On Fri, Oct 2, 2026, at 2:03 PM, Junio C Hamano wrote:
> 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

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

[Julia Evans]

> +# assume the first line is formatted like 'gitglossary(7)'
> +my $firstline = <>;
> +$firstline =~ m/\((\d)\)/;
> +my $man_section_number = $1;
> +
>  my $last_was_section;
>  my @actual_order;
>  while (my $line = <>) {
> @@ -93,6 +98,8 @@ while (my $line = <>) {
> 
>  		for my $section (sort keys %SECTIONS) {
>  			next if !$SECTIONS{$section}->{required} or exists 
> $actual_sections{$section};
> +			# Synopsis is not required in section 7
> +			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
>  			report("has no required '$section' section!");
>  		}


I just realized that this script is actually supposed to be able to process multiple
files as command line arguments, and that this patch won't work for that.

I don't understand how Perl's `<>`  works when you pass multiple files as
command line arguments and that might be too much of a can of worms for me to
figure right now :/

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

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

>> +# assume the first line is formatted like 'gitglossary(7)'
>> +my $firstline = <>;
>> +$firstline =~ m/\((\d)\)/;
>> +my $man_section_number = $1;
>> +
>>  my $last_was_section;
>>  my @actual_order;
>>  while (my $line = <>) {
>> @@ -93,6 +98,8 @@ while (my $line = <>) {
>> 
>>  		for my $section (sort keys %SECTIONS) {
>>  			next if !$SECTIONS{$section}->{required} or exists 
>> $actual_sections{$section};
>> +			# Synopsis is not required in section 7
>> +			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
>>  			report("has no required '$section' section!");
>>  		}
>
>
> I just realized that this script is actually supposed to be able to process multiple
> files as command line arguments, and that this patch won't work for that.

Yeah, your version would then notice only the first line of the
first file, and my update would also do the same.

You can work from what I gave you and inside the "eof" part of the
loop reset the %SECTIONS back to the original (which means you'd
need to keep a separate copy of the original) and also reset the
"did I tweak the %SECTIONS thing already?  have I handled the first
line of the current file?" variable.

> I don't understand how Perl's `<>`  works when you pass multiple files as
> command line arguments and that might be too much of a can of worms for me to
> figure right now :/

"man perlfunc" section on "eof" has an example to show what to
detect and reset when you reached the end of each file within a
"while (<>)" loop.

               # reset line numbering on each input file
               while (<>) {
                   next if /^\s*#/;  # skip comments
                   print "$.\t$_";
               } continue {
                   close ARGV if eof;  # Not eof()!
               }

The explicit "close ARGV if eof;" is how the example resets the
$. counter (which by default counts all the lines coming from <>
across multiple files).

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

[Tuomas Ahola]

Junio C Hamano <gitster@pobox.com> wrote:

> "Julia Evans" <julia@jvns.ca> writes:
> 
> >> +# assume the first line is formatted like 'gitglossary(7)'
> >> +my $firstline = <>;
> >> +$firstline =~ m/\((\d)\)/;
> >> +my $man_section_number = $1;
> >> +
> >>  my $last_was_section;
> >>  my @actual_order;
> >>  while (my $line = <>) {
> >> @@ -93,6 +98,8 @@ while (my $line = <>) {
> >> 
> >>  		for my $section (sort keys %SECTIONS) {
> >>  			next if !$SECTIONS{$section}->{required} or exists 
> >> $actual_sections{$section};
> >> +			# Synopsis is not required in section 7
> >> +			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
> >>  			report("has no required '$section' section!");
> >>  		}
> >
> >
> > I just realized that this script is actually supposed to be able to process multiple
> > files as command line arguments, and that this patch won't work for that.
> 
> Yeah, your version would then notice only the first line of the
> first file, and my update would also do the same.
> 
> You can work from what I gave you and inside the "eof" part of the
> loop reset the %SECTIONS back to the original (which means you'd
> need to keep a separate copy of the original) and also reset the
> "did I tweak the %SECTIONS thing already?  have I handled the first
> line of the current file?" variable.
> 

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!");
 		}
 

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

[Julia Evans]

> 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)

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

[Tuomas Ahola]

"Julia Evans" <julia@jvns.ca> wrote:

> > Something slightly more declarative I managed to hack up:
> >
> 
> 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)
> 

Cool!  You can add these before your S-o-b line:

	Co-authored-by: Tuomas Ahola <taahol@utu.fi>
	Signed-off-by: Tuomas Ahola <taahol@utu.fi>

That seems to be the usual formula for marking coauthors (cf. [1] for a random
example).

> 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)

Yes, the Perl syntax is... interesting.

Links:
  1. https://lore.kernel.org/git/20260711160447.99708-3-marcelomlage@usp.br/

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

[Julia Evans via GitGitGadget]

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 v2: Tuomas rewrote the Perl script changes to be both more
    declarative and and more correct. Previously it didn't work if there
    were multiple files passed on the command line.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2246%2Fjvns%2Fno-synopsis-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2246/jvns/no-synopsis-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2246

Range-diff vs v1:

 1:  b6f8878a1f ! 1:  d6004e0c6b doc: don't require a SYNOPSIS in section 7
     @@ Commit message
             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>
      
       ## Documentation/gitcli.adoc ##
     @@ Documentation/gitworkflows.adoc: NAME
       
      
       ## Documentation/lint-man-section-order.perl ##
     +@@ Documentation/lint-man-section-order.perl: my %SECTIONS;
     + 		},
     + 		'SYNOPSIS' => {
     + 			required => 1,
     ++			optional_in_man_sections => {
     ++				'7' => 1,
     ++			},
     + 			order => $order++,
     + 		},
     + 		'DESCRIPTION' => {
      @@ Documentation/lint-man-section-order.perl: sub report {
       	$exit_code = 1;
       }
       
     -+# assume the first line is formatted like 'gitglossary(7)'
     -+my $firstline = <>;
     -+$firstline =~ m/\((\d)\)/;
     -+my $man_section_number = $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;
      @@ Documentation/lint-man-section-order.perl: while (my $line = <>) {
     + 		@actual_sections{@actual_order} = ();
       
       		for my $section (sort keys %SECTIONS) {
     - 			next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
     -+			# Synopsis is not required in section 7
     -+			next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
     +-			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!");
       		}
       


 Documentation/gitcli.adoc                 |  5 -----
 Documentation/gitcore-tutorial.adoc       |  4 ----
 Documentation/gitdatamodel.adoc           |  4 ----
 Documentation/giteveryday.adoc            |  5 -----
 Documentation/gitfaq.adoc                 |  4 ----
 Documentation/gitglossary.adoc            |  4 ----
 Documentation/gitpacking.adoc             |  4 ----
 Documentation/gitrevisions.adoc           |  5 -----
 Documentation/gittutorial-2.adoc          |  5 -----
 Documentation/gittutorial.adoc            |  5 -----
 Documentation/gitworkflows.adoc           |  6 ------
 Documentation/lint-man-section-order.perl | 15 ++++++++++++++-
 12 files changed, 14 insertions(+), 52 deletions(-)

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
 -----------
 
diff --git a/Documentation/gitcore-tutorial.adoc b/Documentation/gitcore-tutorial.adoc
index 2122aeb976..71fda63a1c 100644
--- a/Documentation/gitcore-tutorial.adoc
+++ b/Documentation/gitcore-tutorial.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitcore-tutorial - A Git core tutorial for developers
 
-SYNOPSIS
---------
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index 56b7635c19..8d9be02036 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitdatamodel - Git's core data model
 
-SYNOPSIS
---------
-gitdatamodel
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/giteveryday.adoc b/Documentation/giteveryday.adoc
index 6cfdd0e07b..0c9db2f150 100644
--- a/Documentation/giteveryday.adoc
+++ b/Documentation/giteveryday.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 giteveryday - A useful minimum set of commands for Everyday Git
 
-SYNOPSIS
---------
-
-Everyday Git With 20 Commands Or So
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitfaq.adoc b/Documentation/gitfaq.adoc
index f6c9b9d9f7..b26e4e3a09 100644
--- a/Documentation/gitfaq.adoc
+++ b/Documentation/gitfaq.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitfaq - Frequently asked questions about using Git
 
-SYNOPSIS
---------
-gitfaq
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitglossary.adoc b/Documentation/gitglossary.adoc
index b046d9cb29..eb1e60832e 100644
--- a/Documentation/gitglossary.adoc
+++ b/Documentation/gitglossary.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitglossary - A Git Glossary
 
-SYNOPSIS
---------
-*
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitpacking.adoc b/Documentation/gitpacking.adoc
index e6de6ec824..b0d952c797 100644
--- a/Documentation/gitpacking.adoc
+++ b/Documentation/gitpacking.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitpacking - Advanced concepts related to packing in Git
 
-SYNOPSIS
---------
-gitpacking
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitrevisions.adoc b/Documentation/gitrevisions.adoc
index 7146117de5..4412f84d83 100644
--- a/Documentation/gitrevisions.adoc
+++ b/Documentation/gitrevisions.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gitrevisions - Specifying revisions and ranges for Git
 
-SYNOPSIS
---------
-gitrevisions
-
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gittutorial-2.adoc b/Documentation/gittutorial-2.adoc
index 8bdb7d0bd3..6a4d482ed6 100644
--- a/Documentation/gittutorial-2.adoc
+++ b/Documentation/gittutorial-2.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gittutorial-2 - A tutorial introduction to Git: part two
 
-SYNOPSIS
---------
-[verse]
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gittutorial.adoc b/Documentation/gittutorial.adoc
index 519b8d8be2..03120ba191 100644
--- a/Documentation/gittutorial.adoc
+++ b/Documentation/gittutorial.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gittutorial - A tutorial introduction to Git
 
-SYNOPSIS
---------
-[verse]
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc
index 59305265c5..ad02828bff 100644
--- a/Documentation/gitworkflows.adoc
+++ b/Documentation/gitworkflows.adoc
@@ -5,12 +5,6 @@ NAME
 ----
 gitworkflows - An overview of recommended workflows with Git
 
-SYNOPSIS
---------
-[verse]
-git *
-
-
 DESCRIPTION
 -----------
 
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 @@ my %SECTIONS;
 		},
 		'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 @@ while (my $line = <>) {
 		@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!");
 		}
 

base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
-- 
gitgitgadget

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

[Junio C Hamano]

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

>     Changes in v2: Tuomas rewrote the Perl script changes to be both more
>     declarative and and more correct. Previously it didn't work if there
>     were multiple files passed on the command line.

> 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 @@ my %SECTIONS;
>  		},
>  		'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) {

OK, this, together with the explicit "close ARGV" later in
postcontext upon seeing eof, lets us do a "special" thing on the
first line.


I think for the purpose of "doc lint", this implementation is good
enough, especially with documented "assumption".

If we wanted to shoot for a bit more robustness, on the other hand,
we would want to handle when $1 is left undef ...

> +		# assume the first line is formatted like 'gitglossary(7)'
> +		$line =~ m/\((\d)\)/;
> +		$man_section_number = $1;

... here.  Perhaps like

	$man_section_number = ($line =~ /\((\d)\)/) ? $1 : "0";

If we left $man_section_number undef, ...

>  	if ($line =~ $SECTION_RX) {
>  		push @actual_order => $line;
>  		$last_was_section = 1;
> @@ -92,7 +103,9 @@ while (my $line = <>) {
>  		@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

... this will access

	$SECTIONS{$section}->{optional_in_man_sections}->{undef}

and may trigger a warning on use of uninitialized value.  

Also, this would autovivify $SECTIONS{*}{optional_in_man_sections}
for sections that don't have optional_in_man_sections hash (like
NAME and DESCRIPTION), which may be harmless but needless.

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

[Julia Evans]

On Sun, Oct 4, 2026, at 9:17 AM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>>     Changes in v2: Tuomas rewrote the Perl script changes to be both more
>>     declarative and and more correct. Previously it didn't work if there
>>     were multiple files passed on the command line.
>
>> 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 @@ my %SECTIONS;
>>  		},
>>  		'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) {
>
> OK, this, together with the explicit "close ARGV" later in
> postcontext upon seeing eof, lets us do a "special" thing on the
> first line.
>
>
> I think for the purpose of "doc lint", this implementation is good
> enough, especially with documented "assumption".
>
> If we wanted to shoot for a bit more robustness, on the other hand,
> we would want to handle when $1 is left undef ...
>
>> +		# assume the first line is formatted like 'gitglossary(7)'
>> +		$line =~ m/\((\d)\)/;
>> +		$man_section_number = $1;
>
> ... here.  Perhaps like
>
> 	$man_section_number = ($line =~ /\((\d)\)/) ? $1 : "0";

Or maybe like

   `$line =~ m/\((\d)\)/ or report("first line should look like `somename(1)`");`

or some similar error message

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

[Junio C Hamano]

"Julia Evans" <julia@jvns.ca> writes:

> Or maybe like
>
>    `$line =~ m/\((\d)\)/ or report("first line should look like `somename(1)`");`
>
> or some similar error message

Sure, not being totally silent is better but we also need to make
sure that we do not end up using undef when we issue such a warning.

Thanks.

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

[Julia Evans via GitGitGadget]

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)'

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2246%2Fjvns%2Fno-synopsis-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2246/jvns/no-synopsis-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/2246

Range-diff vs v2:

 1:  d6004e0c6b ! 1:  6359681fa1 doc: don't require a SYNOPSIS in section 7
     @@ Documentation/lint-man-section-order.perl: sub report {
       	chomp $line;
      +
      +	if ($. == 1) {
     -+		# assume the first line is formatted like 'gitglossary(7)'
      +		$line =~ m/\((\d)\)/;
      +		$man_section_number = $1;
     ++		if (!$man_section_number) {
     ++			report("first line must be formatted like 'gitfaq(7)'");
     ++			# exit to avoid dealing with $man_section_number being undefined later
     ++			last;
     ++		}
      +	}
      +
       	if ($line =~ $SECTION_RX) {


 Documentation/gitcli.adoc                 |  5 -----
 Documentation/gitcore-tutorial.adoc       |  4 ----
 Documentation/gitdatamodel.adoc           |  4 ----
 Documentation/giteveryday.adoc            |  5 -----
 Documentation/gitfaq.adoc                 |  4 ----
 Documentation/gitglossary.adoc            |  4 ----
 Documentation/gitpacking.adoc             |  4 ----
 Documentation/gitrevisions.adoc           |  5 -----
 Documentation/gittutorial-2.adoc          |  5 -----
 Documentation/gittutorial.adoc            |  5 -----
 Documentation/gitworkflows.adoc           |  6 ------
 Documentation/lint-man-section-order.perl | 19 ++++++++++++++++++-
 12 files changed, 18 insertions(+), 52 deletions(-)

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
 -----------
 
diff --git a/Documentation/gitcore-tutorial.adoc b/Documentation/gitcore-tutorial.adoc
index 2122aeb976..71fda63a1c 100644
--- a/Documentation/gitcore-tutorial.adoc
+++ b/Documentation/gitcore-tutorial.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitcore-tutorial - A Git core tutorial for developers
 
-SYNOPSIS
---------
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index 56b7635c19..8d9be02036 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitdatamodel - Git's core data model
 
-SYNOPSIS
---------
-gitdatamodel
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/giteveryday.adoc b/Documentation/giteveryday.adoc
index 6cfdd0e07b..0c9db2f150 100644
--- a/Documentation/giteveryday.adoc
+++ b/Documentation/giteveryday.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 giteveryday - A useful minimum set of commands for Everyday Git
 
-SYNOPSIS
---------
-
-Everyday Git With 20 Commands Or So
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitfaq.adoc b/Documentation/gitfaq.adoc
index f6c9b9d9f7..b26e4e3a09 100644
--- a/Documentation/gitfaq.adoc
+++ b/Documentation/gitfaq.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitfaq - Frequently asked questions about using Git
 
-SYNOPSIS
---------
-gitfaq
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitglossary.adoc b/Documentation/gitglossary.adoc
index b046d9cb29..eb1e60832e 100644
--- a/Documentation/gitglossary.adoc
+++ b/Documentation/gitglossary.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitglossary - A Git Glossary
 
-SYNOPSIS
---------
-*
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitpacking.adoc b/Documentation/gitpacking.adoc
index e6de6ec824..b0d952c797 100644
--- a/Documentation/gitpacking.adoc
+++ b/Documentation/gitpacking.adoc
@@ -5,10 +5,6 @@ NAME
 ----
 gitpacking - Advanced concepts related to packing in Git
 
-SYNOPSIS
---------
-gitpacking
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitrevisions.adoc b/Documentation/gitrevisions.adoc
index 7146117de5..4412f84d83 100644
--- a/Documentation/gitrevisions.adoc
+++ b/Documentation/gitrevisions.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gitrevisions - Specifying revisions and ranges for Git
 
-SYNOPSIS
---------
-gitrevisions
-
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gittutorial-2.adoc b/Documentation/gittutorial-2.adoc
index 8bdb7d0bd3..6a4d482ed6 100644
--- a/Documentation/gittutorial-2.adoc
+++ b/Documentation/gittutorial-2.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gittutorial-2 - A tutorial introduction to Git: part two
 
-SYNOPSIS
---------
-[verse]
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gittutorial.adoc b/Documentation/gittutorial.adoc
index 519b8d8be2..03120ba191 100644
--- a/Documentation/gittutorial.adoc
+++ b/Documentation/gittutorial.adoc
@@ -5,11 +5,6 @@ NAME
 ----
 gittutorial - A tutorial introduction to Git
 
-SYNOPSIS
---------
-[verse]
-git *
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc
index 59305265c5..ad02828bff 100644
--- a/Documentation/gitworkflows.adoc
+++ b/Documentation/gitworkflows.adoc
@@ -5,12 +5,6 @@ NAME
 ----
 gitworkflows - An overview of recommended workflows with Git
 
-SYNOPSIS
---------
-[verse]
-git *
-
-
 DESCRIPTION
 -----------
 
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 02408a0062..35af3b8f67 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -13,6 +13,9 @@ my %SECTIONS;
 		},
 		'SYNOPSIS' => {
 			required => 1,
+			optional_in_man_sections => {
+				'7' => 1,
+			},
 			order => $order++,
 		},
 		'DESCRIPTION' => {
@@ -53,10 +56,22 @@ sub report {
 	$exit_code = 1;
 }
 
+my $man_section_number;
 my $last_was_section;
 my @actual_order;
 while (my $line = <>) {
 	chomp $line;
+
+	if ($. == 1) {
+		$line =~ m/\((\d)\)/;
+		$man_section_number = $1;
+		if (!$man_section_number) {
+			report("first line must be formatted like 'gitfaq(7)'");
+			# exit to avoid dealing with $man_section_number being undefined later
+			last;
+		}
+	}
+
 	if ($line =~ $SECTION_RX) {
 		push @actual_order => $line;
 		$last_was_section = 1;
@@ -92,7 +107,9 @@ while (my $line = <>) {
 		@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!");
 		}
 

base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
-- 
gitgitgadget

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

[Junio C Hamano]

"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.