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

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

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