Volume XXII, number 279Tuesday, October 6, 2026Latest message 22 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patchdoc: don't require a SYNOPSIS in section 7

11 messages between Oct 2, 2026 and Oct 4, 2026, from Julia Evans via GitGitGadget, Junio C Hamano, Julia Evans, Tuomas Ahola.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Julia Evans via GitGitGadgetOct 2, 2026, 16:07 UTC on lore
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(-)
Show changes to 12 files +7 −40

Documentation/gitcli.adoc, Documentation/gitcore-tutorial.adoc, Documentation/gitdatamodel.adoc, Documentation/giteveryday.adoc, Documentation/gitfaq.adoc, Documentation/gitglossary.adoc, Documentation/gitpacking.adoc, Documentation/gitrevisions.adoc, Documentation/gittutorial-2.adoc, Documentation/gittutorial.adoc, Documentation/gitworkflows.adoc, Documentation/lint-man-section-order.perl

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
Junio C HamanoOct 2, 2026, 17:33 UTC in reply to Julia Evans via GitGitGadget on lore

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

"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(+)
Show changes to diff +15 −0
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;
Junio C HamanoOct 2, 2026, 18:03 UTC in reply to Junio C Hamano on lore

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

Junio C Hamano <gitster@pobox.com> writes:
Show 15 quoted lines
> 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.
Show 13 quoted lines
> +		$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;
Julia EvansOct 2, 2026, 18:10 UTC in reply to Junio C Hamano on lore

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

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

Julia EvansOct 2, 2026, 18:20 UTC in reply to Julia Evans via GitGitGadget on lore

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

Show 17 quoted lines
> +# 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 :/

Junio C HamanoOct 2, 2026, 21:34 UTC in reply to Julia Evans on lore

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

"Julia Evans" <julia@jvns.ca> writes:
Show 21 quoted lines
>> +# 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).

Tuomas AholaOct 3, 2026, 07:33 UTC in reply to Junio C Hamano on lore

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

Junio C Hamano <gitster@pobox.com> wrote:
Show 33 quoted lines
> "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:
Show changes to Documentation/lint-man-section-order.perl +14 −1
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!");
 		}
Julia EvansOct 3, 2026, 11:37 UTC in reply to Tuomas Ahola on lore

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

Show 48 quoted lines
> 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)

Tuomas AholaOct 3, 2026, 12:55 UTC in reply to Julia Evans on lore

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

"Julia Evans" <julia@jvns.ca> wrote:
Show 6 quoted lines
> > 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/
Julia Evans via GitGitGadgetOct 3, 2026, 13:10 UTC in reply to Julia Evans via GitGitGadget on lore

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

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(-)
Show changes to 12 files +14 −41

Documentation/gitcli.adoc, Documentation/gitcore-tutorial.adoc, Documentation/gitdatamodel.adoc, Documentation/giteveryday.adoc, Documentation/gitfaq.adoc, Documentation/gitglossary.adoc, Documentation/gitpacking.adoc, Documentation/gitrevisions.adoc, Documentation/gittutorial-2.adoc, Documentation/gittutorial.adoc, Documentation/gitworkflows.adoc, Documentation/lint-man-section-order.perl

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
Junio C HamanoOct 4, 2026, 13:17 UTC in reply to Julia Evans via GitGitGadget on lore

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

"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.
Show 25 quoted lines
> 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, ...
Show 10 quoted lines
>  	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.

Back to recent threads