doc: don't require a SYNOPSIS in section 7
PATCH 1/1 doc: don't require a SYNOPSIS in section 7
From: Julia Evans <[email protected]>
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
---
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(-)
Documentation/gitcli.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gitcli - Git command-line interface and conventions -SYNOPSIS --------- -gitcli - - DESCRIPTION -----------
Documentation/gitcore-tutorial.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitcore-tutorial - A Git core tutorial for developers -SYNOPSIS --------- -git * - DESCRIPTION -----------
Documentation/gitdatamodel.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitdatamodel - Git's core data model -SYNOPSIS --------- -gitdatamodel - DESCRIPTION -----------
Documentation/giteveryday.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- giteveryday - A useful minimum set of commands for Everyday Git -SYNOPSIS --------- - -Everyday Git With 20 Commands Or So - DESCRIPTION -----------
Documentation/gitfaq.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitfaq - Frequently asked questions about using Git -SYNOPSIS --------- -gitfaq - DESCRIPTION -----------
Documentation/gitglossary.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitglossary - A Git Glossary -SYNOPSIS --------- -* - DESCRIPTION -----------
Documentation/gitpacking.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitpacking - Advanced concepts related to packing in Git -SYNOPSIS --------- -gitpacking - DESCRIPTION -----------
Documentation/gitrevisions.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gitrevisions - Specifying revisions and ranges for Git -SYNOPSIS --------- -gitrevisions - - DESCRIPTION -----------
Documentation/gittutorial-2.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gittutorial-2 - A tutorial introduction to Git: part two -SYNOPSIS --------- -[verse] -git * - DESCRIPTION -----------
Documentation/gittutorial.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gittutorial - A tutorial introduction to Git -SYNOPSIS --------- -[verse] -git * - DESCRIPTION -----------
Documentation/gitworkflows.adoc +0 -6
@@ -5,12 +5,6 @@ NAME ---- gitworkflows - An overview of recommended workflows with Git -SYNOPSIS --------- -[verse] -git * - - DESCRIPTION -----------
Documentation/lint-man-section-order.perl +7 -0
@@ -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
Signature · 1 line
gitgitgadget
Quoted 5 lines · Julia Evans via GitGitGadget
From: Julia Evans <[email protected]>
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.
Quoted 6 lines
Documentation/gitcli.adoc +0
-0@@ -5,11 +5,6 @@ NAME ----
Documentation/gitcli.adoc NAME · line 10
Quoted 10 lines
Documentation/gitcli.adoc +0
-5gitcli - 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.
Documentation/lint-man-section-order.perl sub report { · line 59
Quoted 12 lines
Documentation/lint-man-section-order.perl +4
-0@@ -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(+)
Documentation/lint-man-section-order.perl +15 -0
@@ -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;
Quoted 5 lines · Junio C Hamano
Documentation/lint-man-section-order.perl +0
-0
Documentation/lint-man-section-order.perl sub report { · line 64
Quoted 10 lines
Documentation/lint-man-section-order.perl +5
-0@@ -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.
Quoted 13 lines
Documentation/lint-man-section-order.perl +10
-0+ $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;
Quoted 20 lines · Junio C Hamano
Quoted 5 lines · Junio C Hamano
Documentation/lint-man-section-order.perl +0
-0Documentation/lint-man-section-order.perl sub report { · line 64
Quoted 10 lines
Documentation/lint-man-section-order.perl +5
-0@@ -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.
Quoted 13 lines
Documentation/lint-man-section-order.perl sub report { · line 77
Quoted 13 lines
Documentation/lint-man-section-order.perl +10
-0+ $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
Quoted 9 lines
Documentation/lint-man-section-order.perl +5
-0+# 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 = <>) {
Documentation/lint-man-section-order.perl while (my $line = <>) { · line 105
Quoted 8 lines
Documentation/lint-man-section-order.perl +2
-0@@ -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 :/
Quoted 10 lines · Julia Evans
Quoted 10 lines
Documentation/lint-man-section-order.perl +5
-0+# 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 = <>) {
Quoted 11 lines
Documentation/lint-man-section-order.perl while (my $line = <>) { · line 104
Quoted 7 lines
Documentation/lint-man-section-order.perl +2
-0for 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.
Quoted 3 lines
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).
Quoted 24 lines · Junio C Hamano
Quoted 10 lines · Julia Evans
Quoted 10 lines
(quoted diff) +5
-0+# 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 = <>) {Quoted 11 lines
Review while (my $line = <>) { · line 105
Quoted 7 lines
(quoted diff) +2
-0for 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.
Quoted 9 lines
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:
Documentation/lint-man-section-order.perl +14 -1
@@ -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!"); }
Quoted 45 lines
Something slightly more declarative I managed to hack up:
Documentation/lint-man-section-order.perl +13
-1@@ -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
Documentation/lint-man-section-order.perl sub report { · line 110
Quoted 3 lines
Documentation/lint-man-section-order.perl +1
-0+ 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)
Quoted 6 lines · Julia Evans
Quoted 2 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:
That seems to be the usual formula for marking coauthors (cf. [1] for a random example).
Quoted 3 lines
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$ARGVis the name of the current file. (different from @ARGV)
Yes, the Perl syntax is... interesting.
PATCH v2 1/1 doc: don't require a SYNOPSIS in section 7
In reply to Julia Evans via GitGitGadgetFrom: Julia Evans <[email protected]>
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
---
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 <[email protected]>
+ Signed-off-by: Tuomas Ahola <[email protected]>
Signed-off-by: Julia Evans <[email protected]>
## 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(-)
Documentation/gitcli.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gitcli - Git command-line interface and conventions -SYNOPSIS --------- -gitcli - - DESCRIPTION -----------
Documentation/gitcore-tutorial.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitcore-tutorial - A Git core tutorial for developers -SYNOPSIS --------- -git * - DESCRIPTION -----------
Documentation/gitdatamodel.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitdatamodel - Git's core data model -SYNOPSIS --------- -gitdatamodel - DESCRIPTION -----------
Documentation/giteveryday.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- giteveryday - A useful minimum set of commands for Everyday Git -SYNOPSIS --------- - -Everyday Git With 20 Commands Or So - DESCRIPTION -----------
Documentation/gitfaq.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitfaq - Frequently asked questions about using Git -SYNOPSIS --------- -gitfaq - DESCRIPTION -----------
Documentation/gitglossary.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitglossary - A Git Glossary -SYNOPSIS --------- -* - DESCRIPTION -----------
Documentation/gitpacking.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitpacking - Advanced concepts related to packing in Git -SYNOPSIS --------- -gitpacking - DESCRIPTION -----------
Documentation/gitrevisions.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gitrevisions - Specifying revisions and ranges for Git -SYNOPSIS --------- -gitrevisions - - DESCRIPTION -----------
Documentation/gittutorial-2.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gittutorial-2 - A tutorial introduction to Git: part two -SYNOPSIS --------- -[verse] -git * - DESCRIPTION -----------
Documentation/gittutorial.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gittutorial - A tutorial introduction to Git -SYNOPSIS --------- -[verse] -git * - DESCRIPTION -----------
Documentation/gitworkflows.adoc +0 -6
@@ -5,12 +5,6 @@ NAME ---- gitworkflows - An overview of recommended workflows with Git -SYNOPSIS --------- -[verse] -git * - - DESCRIPTION -----------
Documentation/lint-man-section-order.perl +14 -1
@@ -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
Signature · 1 line
gitgitgadget
Quoted 19 lines · Julia Evans via GitGitGadget
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.
Documentation/lint-man-section-order.perl +3
-0@@ -13,6 +13,9 @@ my %SECTIONS; }, 'SYNOPSIS' => { required => 1, + optional_in_man_sections => { + '7' => 1, + }, order => $order++, }, 'DESCRIPTION' => {
Documentation/lint-man-section-order.perl sub report { · line 65
Quoted 10 lines
Documentation/lint-man-section-order.perl +3
-0@@ -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 ...
Documentation/lint-man-section-order.perl sub report { · line 68
Quoted 3 lines
Documentation/lint-man-section-order.perl +3
-0+ # 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, ...
Documentation/lint-man-section-order.perl while (my $line = <>) { · line 107
Quoted 10 lines
Documentation/lint-man-section-order.perl +2
-1if ($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.
Quoted 43 lines · Junio C Hamano
Quoted 19 lines · Julia Evans via GitGitGadget
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.
Documentation/lint-man-section-order.perl +3
-0@@ -13,6 +13,9 @@ my %SECTIONS; }, 'SYNOPSIS' => { required => 1, + optional_in_man_sections => { + '7' => 1, + }, order => $order++, }, 'DESCRIPTION' => {Documentation/lint-man-section-order.perl sub report { · line 65
Quoted 10 lines
Documentation/lint-man-section-order.perl +3
-0@@ -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 ...
Quoted 7 lines
Documentation/lint-man-section-order.perl sub report { · line 68
Quoted 3 lines
Documentation/lint-man-section-order.perl +3
-0+ # 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
Quoted 5 lines · Julia Evans
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 1/1 doc: don't require a SYNOPSIS in section 7
In reply to Julia Evans via GitGitGadgetFrom: Julia Evans <[email protected]>
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
---
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(-)
Documentation/gitcli.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gitcli - Git command-line interface and conventions -SYNOPSIS --------- -gitcli - - DESCRIPTION -----------
Documentation/gitcore-tutorial.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitcore-tutorial - A Git core tutorial for developers -SYNOPSIS --------- -git * - DESCRIPTION -----------
Documentation/gitdatamodel.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitdatamodel - Git's core data model -SYNOPSIS --------- -gitdatamodel - DESCRIPTION -----------
Documentation/giteveryday.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- giteveryday - A useful minimum set of commands for Everyday Git -SYNOPSIS --------- - -Everyday Git With 20 Commands Or So - DESCRIPTION -----------
Documentation/gitfaq.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitfaq - Frequently asked questions about using Git -SYNOPSIS --------- -gitfaq - DESCRIPTION -----------
Documentation/gitglossary.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitglossary - A Git Glossary -SYNOPSIS --------- -* - DESCRIPTION -----------
Documentation/gitpacking.adoc +0 -4
@@ -5,10 +5,6 @@ NAME ---- gitpacking - Advanced concepts related to packing in Git -SYNOPSIS --------- -gitpacking - DESCRIPTION -----------
Documentation/gitrevisions.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gitrevisions - Specifying revisions and ranges for Git -SYNOPSIS --------- -gitrevisions - - DESCRIPTION -----------
Documentation/gittutorial-2.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gittutorial-2 - A tutorial introduction to Git: part two -SYNOPSIS --------- -[verse] -git * - DESCRIPTION -----------
Documentation/gittutorial.adoc +0 -5
@@ -5,11 +5,6 @@ NAME ---- gittutorial - A tutorial introduction to Git -SYNOPSIS --------- -[verse] -git * - DESCRIPTION -----------
Documentation/gitworkflows.adoc +0 -6
@@ -5,12 +5,6 @@ NAME ---- gitworkflows - An overview of recommended workflows with Git -SYNOPSIS --------- -[verse] -git * - - DESCRIPTION -----------
Documentation/lint-man-section-order.perl +18 -1
@@ -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
Signature · 1 line
gitgitgadget
Quoted 21 lines · Julia Evans via GitGitGadget
From: Julia Evans <[email protected]>
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)
endCo-authored-by Tuomas Ahola <[email protected]>Signed-off-by Tuomas Ahola <[email protected]>Signed-off-by Julia Evans <[email protected]>---
doc: don't require a SYNOPSIS in section 7
Quoted 7 lines
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.