[PATCH v3] doc: don't require a SYNOPSIS in section 7
flat view
WARM3d
From: Julia Evans via GitGitGadget <hidden>
Date: 2026-10-06 16:54:33
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
From: Julia Evans <redacted>
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 [off-list ref]
Signed-off-by: Tuomas Ahola <redacted>
Signed-off-by: Julia Evans <redacted>
---
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