[PATCH v2 0/7] doc make and lint fixes
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Apr 9, 2021, 15:02 UTC
- Message-ID
- <cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com>
- In-Reply-To
- <cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com>
Lint for and fix the three manual pages that were missing the standard "Part of the linkgit:git[1] suite" end section.
Addresses the feedback on v1, in particular stylistic / variable naming choices. I just went with all the suggestions.
I've added two new patches at the end to detect (and in 7/7 fix) issues with "standard" sections like NAME, SYNOPSIS, OPTIONS etc. that are out of order, e.g. git-mktag was one of two manual pages that OPTIONS before DESCRIPTION. Those and a few other such oddities are now fixed.
I've got a follow-up series to finish the work I started a while ago of including the relevant git config variable descriptions in the respective manual pages, e.g. now we have gc.* variables in git-gc(1), but not in all manual pages. We'll hopefully consistently have that everywhere soon, and this "sections in the right order" lint was very useful to check those patches.
Ævar Arnfjörð Bjarmason (7): Documentation/Makefile: make $(wildcard howto/*.txt) a var Documentation/Makefile: make doc.dep dependencies a variable again doc lint: Perl "strict" and "warnings" in lint-gitlink.perl doc lint: fix bugs in, simplify and improve lint script doc lint: lint and fix missing "GIT" end sections doc lint: lint relative section order docs: fix linting issues due to incorrect relative section order
Documentation/Makefile | 23 ++++- Documentation/git-credential.txt | 4 + Documentation/git-cvsserver.txt | 24 ++--- Documentation/git-grep.txt | 64 ++++++------- Documentation/git-mktag.txt | 16 ++-- Documentation/git-p4.txt | 4 + Documentation/git-rebase.txt | 12 +-- Documentation/git-svn.txt | 38 ++++---- Documentation/gitnamespaces.txt | 4 + Documentation/lint-gitlink.perl | 108 +++++++++++----------- Documentation/lint-man-end-blurb.perl | 24 +++++ Documentation/lint-man-section-order.perl | 105 +++++++++++++++++++++ 12 files changed, 288 insertions(+), 138 deletions(-) create mode 100755 Documentation/lint-man-end-blurb.perl create mode 100755 Documentation/lint-man-section-order.perl
Range-diff against v1:
1: a5ec5fe4bd = 1: 8efebc7a03 Documentation/Makefile: make $(wildcard howto/*.txt) a var
2: fdc55a86cf ! 2: 8046e7941e Documentation/Makefile: make $(wildcard <doc deps>) a var
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- Documentation/Makefile: make $(wildcard <doc deps>) a var
+ Documentation/Makefile: make doc.dep dependencies a variable again
- Refactor the wildcard we'll scan for "include" directives into a
- single INCLUDE_TARGETS_TXT variable for readability, consistency.
+ Re-introduce a variable to declare what *.txt files need to be
+ considered for the purposes of scouring files to generate a dependency
+ graph of includes.
+
+ When doc.dep was introduced in a5ae8e64cf (Fix documentation
+ dependency generation., 2005-11-07) we had such a variable called
+ TEXTFILES, but it was refactored away just a few commits after that in
+ fb612d54c1 (Documentation: fix dependency generation.,
+ 2005-11-07). I'm planning to add more wildcards here, so let's bring
+ it back.
+
+ I'm not calling it TEXTFILES because we e.g. don't consider
+ Documentation/technical/*.txt when generating the graph (they don't
+ use includes). Let's instead call it DOC_DEP_TXT.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/Makefile: MAN1_TXT =
MAN5_TXT =
MAN7_TXT =
HOWTO_TXT =
-+INCLUDE_TARGETS_TXT =
++DOC_DEP_TXT =
TECH_DOCS =
ARTICLES =
SP_ARTICLES =
@@ Documentation/Makefile: MAN7_TXT += gitworkflows.txt
HOWTO_TXT += $(wildcard howto/*.txt)
-+INCLUDE_TARGETS_TXT += $(wildcard *.txt)
-+INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)
++DOC_DEP_TXT += $(wildcard *.txt)
++DOC_DEP_TXT += $(wildcard config/*.txt)
+
ifdef MAN_FILTER
MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
@@ Documentation/Makefile: docdep_prereqs = \
cmd-list.made $(cmds_txt)
-doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl
-+doc.dep : $(docdep_prereqs) $(INCLUDE_TARGETS_TXT) build-docdep.perl
++doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl
$(QUIET_GEN)$(RM) $@+ $@ && \
$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \
mv $@+ $@
3: 12573d9028 = 3: 29545543bd doc lint: Perl "strict" and "warnings" in lint-gitlink.perl
4: 5c8e8f2149 ! 4: 5acb116fea doc lint: fix bugs in, simplify and improve lint script
@@ Commit message
- When the doc-diff script was added in beb188e22a (add a script to
diff rendered documentation, 2018-08-06) we started sometimes having
- a "git worktree" under "documentation". This tree contains a full
- checkout of git.git, as a result the "lint" script would recurse into
- that, and lint any *.txt file found in that entire repository.
+ a "git worktree" under Documentation/.
+
+ This tree contains a full checkout of git.git, as a result the
+ "lint" script would recurse into that, and lint any *.txt file
+ found in that entire repository.
In practice the only in-tree "linkgit" outside of the
Documentation/ tree is contrib/contacts/git-contacts.txt and
contrib/subtree/git-subtree.txt, so this wouldn't emit any errors
- Now we instead simply trust the Makefile to give us *.txt files, and
- since the Makefile also knows what sections each page should be in we
+ Now we instead simply trust the Makefile to give us *.txt files.
+ Since the Makefile also knows what sections each page should be in we
don't have to open the files ourselves and try to parse that out. As a
- bonus this will also catch bugs with the section line in the file
- being incorrect.
+ bonus this will also catch bugs with the section line in the files
+ themselves being incorrect.
The structure of the new script is mostly based on
t/check-non-portable-shell.pl. As an added bonus it will also use
@@ Commit message
We'll now emit:
git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below:
- git-cherry.txt:20: "copied" by means of linkgit:git-cherry-pick[2]' <-- HERE
+ git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2]' <-- HERE
git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below:
- git-cherry.txt:20: "copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE
+ git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE
git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below:
- git-cherry.txt:21: linkgit:git-rebase[4]' <-- HERE
+ git-cherry.txt:21: 'linkgit:git-rebase[4]' <-- HERE
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/Makefile ##
-@@ Documentation/Makefile: MAN5_TXT =
- MAN7_TXT =
- HOWTO_TXT =
- INCLUDE_TARGETS_TXT =
-+ALL_TXT =
- TECH_DOCS =
- ARTICLES =
- SP_ARTICLES =
-@@ Documentation/Makefile: HOWTO_TXT += $(wildcard howto/*.txt)
- INCLUDE_TARGETS_TXT += $(wildcard *.txt)
- INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)
-
-+# For linting
-+ALL_TXT += $(MAN1_TXT)
-+ALL_TXT += $(MAN5_TXT)
-+ALL_TXT += $(MAN7_TXT)
-+ALL_TXT += $(HOWTO_TXT)
-+ALL_TXT += $(INCLUDE_TARGETS_TXT)
-+
- ifdef MAN_FILTER
- MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
- else
@@ Documentation/Makefile: print-man1:
@for i in $(MAN1_TXT); do echo $$i; done
lint-docs::
- $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
+ $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \
++ $(HOWTO_TXT) $(DOC_DEP_TXT) \
+ --section=1 $(MAN1_TXT) \
+ --section=5 $(MAN5_TXT) \
-+ --section=7 $(MAN7_TXT) \
-+ --to-lint $(ALL_TXT)
++ --section=7 $(MAN7_TXT)
ifeq ($(wildcard po/Makefile),po/Makefile)
doc-l10n install-l10n::
@@ Documentation/lint-gitlink.perl
- or die("Cannot parse command line arguments\n");
+# Parse arguments, a simple state machine for input like:
+#
-+# --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
++# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]
+my %TXT;
+my %SECTION;
+my $section;
@@ Documentation/lint-gitlink.perl
+ if (my ($sec) = $arg =~ /^--section=(\d+)$/s) {
+ $section = $sec;
+ next;
-+ } elsif ($arg eq '--to-lint') {
-+ $lint_these = 1;
-+ next;
+ }
-my $found_errors = 0;
+ my ($name) = $arg =~ /^(.*?)\.txt$/s;
-+ if ($lint_these) {
++ unless (defined $section) {
+ $TXT{$name} = $arg;
+ next;
+ }
@@ Documentation/lint-gitlink.perl
+ substr($line, $pos) = "' <-- HERE";
+ $line =~ s/^\s+//;
+ print "$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\n";
-+ print "$ARGV:$.:\t$line\n";
++ print "$ARGV:$.:\t'$line\n";
+ $exit_code = 1;
}
@@ Documentation/lint-gitlink.perl
- while (s/linkgit:((.*?)\[(\d)\])//) {
- my ($target, $page, $section) = ($1, $2, $3);
+@ARGV = sort values %TXT;
++die "BUG: Nothing to process!" unless @ARGV;
+while (<>) {
+ my $line = $_;
+ while ($line =~ m/linkgit:((.*?)\[(\d)\])/g) {
5: d4004b6a7c ! 5: e3af1a9405 doc lint: lint and fix missing "GIT" end sections
@@ Commit message
anything outside those sections), not files to be included,
howto *.txt files etc.
+ We could also add this to the existing (and then renamed)
+ lint-gitlink.perl, but I'm not doing that here.
+
+ Obviously all of that fits in one script, but I think for something
+ like this that's a one-off script with global variables it's much
+ harder to follow when a large part of your script is some if/else or
+ keeping/resetting of state simply to work around the script doing two
+ things instead of one.
+
+ Especially because in this case this script wants to process the file
+ as one big string, but lint-gitlink.perl wants to look at it one line
+ at a time. We could also consolidate this whole thing and
+ t/check-non-portable-shell.pl, but that one likes to join lines as
+ part of its shell parsing.
+
+ So let's just add another script, whole scaffolding is basically:
+
+ use strict;
+ use warnings;
+ sub report { ... }
+ my $code = 0;
+ while (<>) { ... }
+ exit $code;
+
+ We'd spend more lines effort trying to consolidate them than just
+ copying that around.
+
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/Makefile ##
@@ Documentation/Makefile: lint-docs::
+ $(HOWTO_TXT) $(DOC_DEP_TXT) \
+ --section=1 $(MAN1_TXT) \
--section=5 $(MAN5_TXT) \
- --section=7 $(MAN7_TXT) \
- --to-lint $(ALL_TXT)
-+ $(QUIET_LINT)$(PERL_PATH) lint-man-txt.perl \
-+ $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
+- --section=7 $(MAN7_TXT)
++ --section=7 $(MAN7_TXT); \
++ $(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT)
ifeq ($(wildcard po/Makefile),po/Makefile)
doc-l10n install-l10n::
@@ Documentation/gitnamespaces.txt: git clone ext::'git --namespace=foo %s /tmp/pre
+---
+Part of the linkgit:git[1] suite
- ## Documentation/lint-man-txt.perl (new) ##
+ ## Documentation/lint-man-end-blurb.perl (new) ##
@@
+#!/usr/bin/perl
+
-: ---------- > 6: 8c294afe2a doc lint: lint relative section order
-: ---------- > 7: 9cb100826e docs: fix linting issues due to incorrect relative section order-- 2.31.1.622.g1b8cc22e65