{"thread":{"id":"55390","subject":"[PATCH 0/5] small doc make and lint fixes","startedAt":"2021-03-26T10:37:44Z","lastAt":"2021-04-10T04:14:54Z","messageCount":32,"participants":["Ævar Arnfjörð Bjarmason","Jeff King","Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"420247","messageId":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","threadId":"55390","inReplyTo":null,"subject":"[PATCH 0/5] small doc make and lint fixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T10:36:45Z","receivedAt":"2021-03-26T10:37:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"A small stand-alone series of doc infrastructure fixes. 5/6 fixes an\ninteresting bug that's been missed since doc-diff was introduced.\n\nÆvar Arnfjörð Bjarmason (5):\n Documentation/Makefile: make $(wildcard howto/*.txt) a var\n Documentation/Makefile: make $(wildcard ) a var\n doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl\n doc lint: fix bugs in, simplify and improve lint script\n doc lint: lint and fix missing \"GIT\" end sections\n\n Documentation/Makefile | 31 +++++++--\n Documentation/git-credential.txt | 4 ++\n Documentation/git-p4.txt | 4 ++\n Documentation/gitnamespaces.txt | 4 ++\n Documentation/lint-gitlink.perl | 110 +++++++++++++++----------------\n Documentation/lint-man-txt.perl | 24 +++++++\n 6 files changed, 116 insertions(+), 61 deletions(-)\n create mode 100755 Documentation/lint-man-txt.perl\n\n-- \n2.31.0.419.gfc6e4cae13\n\n"},{"id":"420249","messageId":"patch-1.6-a5ec5fe4bdb-20210326T103454Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"[PATCH 1/5] Documentation/Makefile: make $(wildcard howto/*.txt) a var","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T10:36:46Z","receivedAt":"2021-03-26T10:37:44Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Refactor occurrences of $(wildcard howto/*.txt) into a single\nHOWTO_TXT variable for readability and consistency.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 9 ++++++---\n 1 file changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 81d1bf7a049..0ba7564be93 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -2,6 +2,7 @@\n MAN1_TXT =\n MAN5_TXT =\n MAN7_TXT =\n+HOWTO_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n@@ -42,6 +43,8 @@ MAN7_TXT += gittutorial-2.txt\n MAN7_TXT += gittutorial.txt\n MAN7_TXT += gitworkflows.txt\n \n+HOWTO_TXT += $(wildcard howto/*.txt)\n+\n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n else\n@@ -427,9 +430,9 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n \t$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n \tmv $@+ $@\n \n-howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n+howto-index.txt: howto-index.sh $(HOWTO_TXT)\n \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n-\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n+\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n@@ -438,7 +441,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n-$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS\n+$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \tsed -e '1,/^$$/d' $< | \\\n \t$(TXT_TO_HTML) - >$@+ && \\\n-- \n2.31.0.419.gfc6e4cae13\n\n"},{"id":"420248","messageId":"patch-3.6-12573d90289-20210326T103454Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"[PATCH 3/5] doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T10:36:48Z","receivedAt":"2021-03-26T10:37:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend this script added in ab81411ced (ci: validate \"linkgit:\" in\ndocumentation, 2016-05-04) to pass under \"use strict\", and add a \"use\nwarnings\" for good measure.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/lint-gitlink.perl | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex 476cc30b837..35230875c24 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -1,5 +1,7 @@\n #!/usr/bin/perl\n \n+use strict;\n+use warnings;\n use File::Find;\n use Getopt::Long;\n \n@@ -45,7 +47,7 @@ sub lint {\n \t\t\t\treport($where, $target, \"no such source\");\n \t\t\t\tnext;\n \t\t\t}\n-\t\t\t$real_section = grab_section($page);\n+\t\t\tmy $real_section = grab_section($page);\n \t\t\tif ($real_section != $section) {\n \t\t\t\treport($where, $target,\n \t\t\t\t\t\"wrong section (should be $real_section)\");\n-- \n2.31.0.419.gfc6e4cae13\n\n"},{"id":"420250","messageId":"patch-2.6-fdc55a86cf4-20210326T103454Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"[PATCH 2/5] Documentation/Makefile: make $(wildcard ) a var","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T10:36:47Z","receivedAt":"2021-03-26T10:37:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Refactor the wildcard we'll scan for \"include\" directives into a\nsingle INCLUDE_TARGETS_TXT variable for readability, consistency.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 0ba7564be93..7313956d73f 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -3,6 +3,7 @@ MAN1_TXT =\n MAN5_TXT =\n MAN7_TXT =\n HOWTO_TXT =\n+INCLUDE_TARGETS_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n@@ -45,6 +46,9 @@ MAN7_TXT += gitworkflows.txt\n \n HOWTO_TXT += $(wildcard howto/*.txt)\n \n+INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n+INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n+\n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n else\n@@ -287,7 +291,7 @@ docdep_prereqs = \\\n \tmergetools-list.made $(mergetools_txt) \\\n \tcmd-list.made $(cmds_txt)\n \n-doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl\n+doc.dep : $(docdep_prereqs) $(INCLUDE_TARGETS_TXT) build-docdep.perl\n \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n \t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n \tmv $@+ $@\n-- \n2.31.0.419.gfc6e4cae13\n\n"},{"id":"420251","messageId":"patch-5.6-d4004b6a7cb-20210326T103454Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"[PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T10:36:50Z","receivedAt":"2021-03-26T10:37:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Lint for and fix the three manual pages that were missing the standard\n\"Part of the linkgit:git[1] suite\" end section.\n\nWe only do this for the man[157] section documents (we don't have\nanything outside those sections), not files to be included,\nhowto *.txt files etc.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 2 ++\n Documentation/git-credential.txt | 4 ++++\n Documentation/git-p4.txt | 4 ++++\n Documentation/gitnamespaces.txt | 4 ++++\n Documentation/lint-man-txt.perl | 24 ++++++++++++++++++++++++\n 5 files changed, 38 insertions(+)\n create mode 100755 Documentation/lint-man-txt.perl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 6bfd8c75772..2b6cd0f7be2 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -490,6 +490,8 @@ lint-docs::\n \t\t--section=5 $(MAN5_TXT) \\\n \t\t--section=7 $(MAN7_TXT)\t\\\n \t\t--to-lint $(ALL_TXT)\n+\t$(QUIET_LINT)$(PERL_PATH) lint-man-txt.perl \\\n+\t\t$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 31c81c4c026..206e3c5f407 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -159,3 +159,7 @@ empty string.\n +\n Components which are missing from the URL (e.g., there is no\n username in the example above) will be left unset.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex f89e68b424c..38e5257b2a4 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -762,3 +762,7 @@ IMPLEMENTATION DETAILS\n message indicating the p4 depot location and change number. This\n line is used by later 'git p4 sync' operations to know which p4\n changes are new.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt\nindex b614969ad2c..1c8d2ecc358 100644\n--- a/Documentation/gitnamespaces.txt\n+++ b/Documentation/gitnamespaces.txt\n@@ -62,3 +62,7 @@ git clone ext::'git --namespace=foo %s /tmp/prefixed.git'\n ----------\n \n include::transfer-data-leaks.txt[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-txt.perl b/Documentation/lint-man-txt.perl\nnew file mode 100755\nindex 00000000000..d69312e5db5\n--- /dev/null\n+++ b/Documentation/lint-man-txt.perl\n@@ -0,0 +1,24 @@\n+#!/usr/bin/perl\n+\n+use strict;\n+use warnings;\n+\n+my $exit_code = 0;\n+sub report {\n+\tmy ($target, $msg) = @_;\n+\tprint \"error: $target: $msg\\n\";\n+\t$exit_code = 1;\n+}\n+\n+local $/;\n+while (my $slurp = <>) {\n+\treport($ARGV, \"has no 'Part of the linkgit:git[1] suite' end blurb\")\n+\t\tunless $slurp =~ m[\n+\t\t^GIT\\n\n+\t\t ---\\n\n+\t\t\\QPart of the linkgit:git[1] suite\\E \\n\n+\t\t\\z\n+\t]mx;\n+}\n+\n+exit $exit_code;\n-- \n2.31.0.419.gfc6e4cae13\n\n"},{"id":"420252","messageId":"patch-4.6-5c8e8f21495-20210326T103454Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"[PATCH 4/5] doc lint: fix bugs in, simplify and improve lint script","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T10:36:49Z","receivedAt":"2021-03-26T10:37:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The lint-gitlink.perl script added in ab81411ced (ci: validate\n\"linkgit:\" in documentation, 2016-05-04) was more complex than it\nneeded to be. It:\n\n - Was using File::Find to recursively find *.txt files in\n Documentation/, let's instead use the Makefile as a source of truth\n for *.txt files, and pass it down to the script.\n\n - We now don't lint linkgit:* in RelNotes/* or technical/*, which we\n shouldn't have been doing in the first place anyway.\n\n - When the doc-diff script was added in beb188e22a (add a script to\n diff rendered documentation, 2018-08-06) we started sometimes having\n a \"git worktree\" under \"documentation\". This tree contains a full\n checkout of git.git, as a result the \"lint\" script would recurse into\n that, and lint any *.txt file found in that entire repository.\n\n In practice the only in-tree \"linkgit\" outside of the\n Documentation/ tree is contrib/contacts/git-contacts.txt and\n contrib/subtree/git-subtree.txt, so this wouldn't emit any errors\n\nNow we instead simply trust the Makefile to give us *.txt files, and\nsince the Makefile also knows what sections each page should be in we\ndon't have to open the files ourselves and try to parse that out. As a\nbonus this will also catch bugs with the section line in the file\nbeing incorrect.\n\nThe structure of the new script is mostly based on\nt/check-non-portable-shell.pl. As an added bonus it will also use\npos() to print where the problems it finds are, e.g. given an issue\nlike:\n\n diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt\n [...]\n and line numbers. git-cherry therefore detects when commits have been\n -\"copied\" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or\n -linkgit:git-rebase[1].\n +\"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3] or\n +linkgit:git-rebase[4].\n\nWe'll now emit:\n\n git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below:\n git-cherry.txt:20: \"copied\" by means of linkgit:git-cherry-pick[2]' <-- HERE\n git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below:\n git-cherry.txt:20: \"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE\n git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below:\n git-cherry.txt:21: linkgit:git-rebase[4]' <-- HERE\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 14 ++++-\n Documentation/lint-gitlink.perl | 108 +++++++++++++++-----------------\n 2 files changed, 65 insertions(+), 57 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 7313956d73f..6bfd8c75772 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -4,6 +4,7 @@ MAN5_TXT =\n MAN7_TXT =\n HOWTO_TXT =\n INCLUDE_TARGETS_TXT =\n+ALL_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n@@ -49,6 +50,13 @@ HOWTO_TXT += $(wildcard howto/*.txt)\n INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n \n+# For linting\n+ALL_TXT += $(MAN1_TXT)\n+ALL_TXT += $(MAN5_TXT)\n+ALL_TXT += $(MAN7_TXT)\n+ALL_TXT += $(HOWTO_TXT)\n+ALL_TXT += $(INCLUDE_TARGETS_TXT)\n+\n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n else\n@@ -477,7 +485,11 @@ print-man1:\n \t@for i in $(MAN1_TXT); do echo $$i; done\n \n lint-docs::\n-\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n+\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n+\t\t--section=1 $(MAN1_TXT) \\\n+\t\t--section=5 $(MAN5_TXT) \\\n+\t\t--section=7 $(MAN7_TXT)\t\\\n+\t\t--to-lint $(ALL_TXT)\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex 35230875c24..d42f154e024 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -2,72 +2,68 @@\n \n use strict;\n use warnings;\n-use File::Find;\n-use Getopt::Long;\n \n-my $basedir = \".\";\n-GetOptions(\"basedir=s\" => \\$basedir)\n-\tor die(\"Cannot parse command line arguments\\n\");\n+# Parse arguments, a simple state machine for input like:\n+#\n+# --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]\n+my %TXT;\n+my %SECTION;\n+my $section;\n+my $lint_these = 0;\n+for my $arg (@ARGV) {\n+\tif (my ($sec) = $arg =~ /^--section=(\\d+)$/s) {\n+\t\t$section = $sec;\n+\t\tnext;\n+\t} elsif ($arg eq '--to-lint') {\n+\t\t$lint_these = 1;\n+\t\tnext;\n+\t}\n \n-my $found_errors = 0;\n+\tmy ($name) = $arg =~ /^(.*?)\\.txt$/s;\n+\tif ($lint_these) {\n+\t\t$TXT{$name} = $arg;\n+\t\tnext;\n+\t}\n \n-sub report {\n-\tmy ($where, $what, $error) = @_;\n-\tprint \"$where: $error: $what\\n\";\n-\t$found_errors = 1;\n+\t$SECTION{$name} = $section;\n }\n \n-sub grab_section {\n-\tmy ($page) = @_;\n-\topen my $fh, \"<\", \"$basedir/$page.txt\";\n-\tmy $firstline = <$fh>;\n-\tchomp $firstline;\n-\tclose $fh;\n-\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n-\treturn $section;\n+my $exit_code = 0;\n+sub report {\n+\tmy ($pos, $line, $target, $msg) = @_;\n+\tsubstr($line, $pos) = \"' <-- HERE\";\n+\t$line =~ s/^\\s+//;\n+\tprint \"$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\\n\";\n+\tprint \"$ARGV:$.:\\t$line\\n\";\n+\t$exit_code = 1;\n }\n \n-sub lint {\n-\tmy ($file) = @_;\n-\topen my $fh, \"<\", $file\n-\t\tor return;\n-\twhile (<$fh>) {\n-\t\tmy $where = \"$file:$.\";\n-\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n-\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n+@ARGV = sort values %TXT;\n+while (<>) {\n+\tmy $line = $_;\n+\twhile ($line =~ m/linkgit:((.*?)\\[(\\d)\\])/g) {\n+\t\tmy $pos = pos $line;\n+\t\tmy ($target, $page, $section) = ($1, $2, $3);\n \n-\t\t\t# De-AsciiDoc\n-\t\t\t$page =~ s/{litdd}/--/g;\n+\t\t# De-AsciiDoc\n+\t\t$page =~ s/{litdd}/--/g;\n \n-\t\t\tif ($page !~ /^git/) {\n-\t\t\t\treport($where, $target, \"nongit link\");\n-\t\t\t\tnext;\n-\t\t\t}\n-\t\t\tif (! -f \"$basedir/$page.txt\") {\n-\t\t\t\treport($where, $target, \"no such source\");\n-\t\t\t\tnext;\n-\t\t\t}\n-\t\t\tmy $real_section = grab_section($page);\n-\t\t\tif ($real_section != $section) {\n-\t\t\t\treport($where, $target,\n-\t\t\t\t\t\"wrong section (should be $real_section)\");\n-\t\t\t\tnext;\n-\t\t\t}\n+\t\tif (!exists $TXT{$page}) {\n+\t\t\treport($pos, $line, $target, \"link outside of our own docs\");\n+\t\t\tnext;\n+\t\t}\n+\t\tif (!exists $SECTION{$page}) {\n+\t\t\treport($pos, $line, $target, \"link outside of our sectioned docs\");\n+\t\t\tnext;\n+\t\t}\n+\t\tmy $real_section = $SECTION{$page};\n+\t\tif ($section != $SECTION{$page}) {\n+\t\t\treport($pos, $line, $target, \"wrong section (should be $real_section)\");\n+\t\t\tnext;\n \t\t}\n \t}\n-\tclose $fh;\n-}\n-\n-sub lint_it {\n-\tlint($File::Find::name) if -f && /\\.txt$/;\n-}\n-\n-if (!@ARGV) {\n-\tfind({ wanted => \\&lint_it, no_chdir => 1 }, $basedir);\n-} else {\n-\tfor (@ARGV) {\n-\t\tlint($_);\n-\t}\n+\t# this resets our $. for each file\n+\tclose ARGV if eof;\n }\n \n-exit $found_errors;\n+exit $exit_code;\n-- \n2.31.0.419.gfc6e4cae13\n\n"},{"id":"420254","messageId":"YF2+4I4rH9CQ1A2F@coredump.intra.peff.net","threadId":"55390","inReplyTo":"patch-4.6-5c8e8f21495-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 4/5] doc lint: fix bugs in, simplify and improve lint script","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-03-26T11:00:48Z","receivedAt":"2021-03-26T11:01:37Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 26, 2021 at 11:36:49AM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> lint-docs::\n> -\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n> +\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n> +\t\t--section=1 $(MAN1_TXT) \\\n> +\t\t--section=5 $(MAN5_TXT) \\\n> +\t\t--section=7 $(MAN7_TXT)\t\\\n> +\t\t--to-lint $(ALL_TXT)\n\nThis is probably bikeshedding, but I would have expected the invocation\nto be:\n\n link-gitlink.perl \\\n $(HOWTO_TXT) $(INCLUDE_TARGETS_TXT) \\\n --section=1 $(MAN1_TXT) \\\n --section=5 $(MAN5_TXT) \\\n --section=7 $(MAN7_TXT)\n\nI.e., list each filename only once, with the previous --section giving\nthe expected section (and if before any --section, then expect no\nsection).\n\n-Peff\n"},{"id":"420255","messageId":"YF2/xPMvwhm+OOVz@coredump.intra.peff.net","threadId":"55390","inReplyTo":"patch-5.6-d4004b6a7cb-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-03-26T11:04:36Z","receivedAt":"2021-03-26T11:05:27Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 26, 2021 at 11:36:50AM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> Lint for and fix the three manual pages that were missing the standard\n> \"Part of the linkgit:git[1] suite\" end section.\n\nThis is a definite improvement. Two thoughts come to mind, though:\n\n 1. Do we need a separate script for this? Couldn't the existing linter\n script check this while it is reading all of the files (it knows\n which ones are supposed to be manpages because they are annotated\n with the --section option). That would be more efficient, and\n probably a little less code.\n\n 2. Instead of linting, could we just be automatically sticking this\n boilerplate in as part of the build (either through some asciidoc\n magic, or even just a plain old \"cat\")? Even better than being\n reminded that you forgot something is making it impossible to\n forget it in the first place.\n\n-Peff\n"},{"id":"420256","messageId":"YF3AGsFFX3FQ1/ew@coredump.intra.peff.net","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 0/5] small doc make and lint fixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-03-26T11:06:02Z","receivedAt":"2021-03-26T11:07:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 26, 2021 at 11:36:45AM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> A small stand-alone series of doc infrastructure fixes. 5/6 fixes an\n> interesting bug that's been missed since doc-diff was introduced.\n\nI'm not sure what you mean about doc-diff here. Patch 5 (of 5?) doesn't\nseem related. Patch 4 is related only tangentially, in that you might\nhave more stuff in your Documentation directory.\n\nThat said...\n\n> Documentation/Makefile: make $(wildcard howto/*.txt) a var\n> Documentation/Makefile: make $(wildcard ) a var\n> doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl\n\nThese three look obviously correct.\n\n> doc lint: fix bugs in, simplify and improve lint script\n> doc lint: lint and fix missing \"GIT\" end sections\n\nThese two seem fine, though I left some comments for possible\nimprovements.\n\n-Peff\n"},{"id":"420260","messageId":"a7e1bbc1-eb3e-72d0-ef65-24cc38346a04@iee.email","threadId":"55390","inReplyTo":"patch-4.6-5c8e8f21495-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 4/5] doc lint: fix bugs in, simplify and improve lint script","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-03-26T12:48:45Z","receivedAt":"2021-03-26T12:49:44Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Ævar,\n minor naming comment.\n\nOn 26/03/2021 10:36, Ævar Arnfjörð Bjarmason wrote:\n> The lint-gitlink.perl script added in ab81411ced (ci: validate\n> \"linkgit:\" in documentation, 2016-05-04) was more complex than it\n> needed to be. It:\n>\n> - Was using File::Find to recursively find *.txt files in\n> Documentation/, let's instead use the Makefile as a source of truth\n> for *.txt files, and pass it down to the script.\n>\n> - We now don't lint linkgit:* in RelNotes/* or technical/*, which we\n> shouldn't have been doing in the first place anyway.\n>\n> - When the doc-diff script was added in beb188e22a (add a script to\n> diff rendered documentation, 2018-08-06) we started sometimes having\n> a \"git worktree\" under \"documentation\". This tree contains a full\n> checkout of git.git, as a result the \"lint\" script would recurse into\n> that, and lint any *.txt file found in that entire repository.\n>\n> In practice the only in-tree \"linkgit\" outside of the\n> Documentation/ tree is contrib/contacts/git-contacts.txt and\n> contrib/subtree/git-subtree.txt, so this wouldn't emit any errors\n>\n> Now we instead simply trust the Makefile to give us *.txt files, and\n> since the Makefile also knows what sections each page should be in we\n> don't have to open the files ourselves and try to parse that out. As a\n> bonus this will also catch bugs with the section line in the file\n> being incorrect.\n>\n> The structure of the new script is mostly based on\n> t/check-non-portable-shell.pl. As an added bonus it will also use\n> pos() to print where the problems it finds are, e.g. given an issue\n> like:\n>\n> diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt\n> [...]\n> and line numbers. git-cherry therefore detects when commits have been\n> -\"copied\" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or\n> -linkgit:git-rebase[1].\n> +\"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3] or\n> +linkgit:git-rebase[4].\n>\n> We'll now emit:\n>\n> git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below:\n> git-cherry.txt:20: \"copied\" by means of linkgit:git-cherry-pick[2]' <-- HERE\n> git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below:\n> git-cherry.txt:20: \"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE\n> git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below:\n> git-cherry.txt:21: linkgit:git-rebase[4]' <-- HERE\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 14 ++++-\n> Documentation/lint-gitlink.perl | 108 +++++++++++++++-----------------\n> 2 files changed, 65 insertions(+), 57 deletions(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 7313956d73f..6bfd8c75772 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -4,6 +4,7 @@ MAN5_TXT =\n> MAN7_TXT =\n> HOWTO_TXT =\n> INCLUDE_TARGETS_TXT =\n> +ALL_TXT =\n\nMaybe LINT_TXT would better clarify its use, rather than squatting on\nthe generic \"ALL\"?\n-- \nPhilip\n> TECH_DOCS =\n> ARTICLES =\n> SP_ARTICLES =\n> @@ -49,6 +50,13 @@ HOWTO_TXT += $(wildcard howto/*.txt)\n> INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n> INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n> \n> +# For linting\n> +ALL_TXT += $(MAN1_TXT)\n> +ALL_TXT += $(MAN5_TXT)\n> +ALL_TXT += $(MAN7_TXT)\n> +ALL_TXT += $(HOWTO_TXT)\n> +ALL_TXT += $(INCLUDE_TARGETS_TXT)\n> +\n> ifdef MAN_FILTER\n> MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n> else\n> @@ -477,7 +485,11 @@ print-man1:\n> \t@for i in $(MAN1_TXT); do echo $$i; done\n> \n> lint-docs::\n> -\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n> +\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n> +\t\t--section=1 $(MAN1_TXT) \\\n> +\t\t--section=5 $(MAN5_TXT) \\\n> +\t\t--section=7 $(MAN7_TXT)\t\\\n> +\t\t--to-lint $(ALL_TXT)\n> \n> ifeq ($(wildcard po/Makefile),po/Makefile)\n> doc-l10n install-l10n::\n> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\n> index 35230875c24..d42f154e024 100755\n> --- a/Documentation/lint-gitlink.perl\n> +++ b/Documentation/lint-gitlink.perl\n> @@ -2,72 +2,68 @@\n> \n> use strict;\n> use warnings;\n> -use File::Find;\n> -use Getopt::Long;\n> \n> -my $basedir = \".\";\n> -GetOptions(\"basedir=s\" => \\$basedir)\n> -\tor die(\"Cannot parse command line arguments\\n\");\n> +# Parse arguments, a simple state machine for input like:\n> +#\n> +# --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]\n> +my %TXT;\n> +my %SECTION;\n> +my $section;\n> +my $lint_these = 0;\n> +for my $arg (@ARGV) {\n> +\tif (my ($sec) = $arg =~ /^--section=(\\d+)$/s) {\n> +\t\t$section = $sec;\n> +\t\tnext;\n> +\t} elsif ($arg eq '--to-lint') {\n> +\t\t$lint_these = 1;\n> +\t\tnext;\n> +\t}\n> \n> -my $found_errors = 0;\n> +\tmy ($name) = $arg =~ /^(.*?)\\.txt$/s;\n> +\tif ($lint_these) {\n> +\t\t$TXT{$name} = $arg;\n> +\t\tnext;\n> +\t}\n> \n> -sub report {\n> -\tmy ($where, $what, $error) = @_;\n> -\tprint \"$where: $error: $what\\n\";\n> -\t$found_errors = 1;\n> +\t$SECTION{$name} = $section;\n> }\n> \n> -sub grab_section {\n> -\tmy ($page) = @_;\n> -\topen my $fh, \"<\", \"$basedir/$page.txt\";\n> -\tmy $firstline = <$fh>;\n> -\tchomp $firstline;\n> -\tclose $fh;\n> -\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n> -\treturn $section;\n> +my $exit_code = 0;\n> +sub report {\n> +\tmy ($pos, $line, $target, $msg) = @_;\n> +\tsubstr($line, $pos) = \"' <-- HERE\";\n> +\t$line =~ s/^\\s+//;\n> +\tprint \"$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\\n\";\n> +\tprint \"$ARGV:$.:\\t$line\\n\";\n> +\t$exit_code = 1;\n> }\n> \n> -sub lint {\n> -\tmy ($file) = @_;\n> -\topen my $fh, \"<\", $file\n> -\t\tor return;\n> -\twhile (<$fh>) {\n> -\t\tmy $where = \"$file:$.\";\n> -\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n> -\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n> +@ARGV = sort values %TXT;\n> +while (<>) {\n> +\tmy $line = $_;\n> +\twhile ($line =~ m/linkgit:((.*?)\\[(\\d)\\])/g) {\n> +\t\tmy $pos = pos $line;\n> +\t\tmy ($target, $page, $section) = ($1, $2, $3);\n> \n> -\t\t\t# De-AsciiDoc\n> -\t\t\t$page =~ s/{litdd}/--/g;\n> +\t\t# De-AsciiDoc\n> +\t\t$page =~ s/{litdd}/--/g;\n> \n> -\t\t\tif ($page !~ /^git/) {\n> -\t\t\t\treport($where, $target, \"nongit link\");\n> -\t\t\t\tnext;\n> -\t\t\t}\n> -\t\t\tif (! -f \"$basedir/$page.txt\") {\n> -\t\t\t\treport($where, $target, \"no such source\");\n> -\t\t\t\tnext;\n> -\t\t\t}\n> -\t\t\tmy $real_section = grab_section($page);\n> -\t\t\tif ($real_section != $section) {\n> -\t\t\t\treport($where, $target,\n> -\t\t\t\t\t\"wrong section (should be $real_section)\");\n> -\t\t\t\tnext;\n> -\t\t\t}\n> +\t\tif (!exists $TXT{$page}) {\n> +\t\t\treport($pos, $line, $target, \"link outside of our own docs\");\n> +\t\t\tnext;\n> +\t\t}\n> +\t\tif (!exists $SECTION{$page}) {\n> +\t\t\treport($pos, $line, $target, \"link outside of our sectioned docs\");\n> +\t\t\tnext;\n> +\t\t}\n> +\t\tmy $real_section = $SECTION{$page};\n> +\t\tif ($section != $SECTION{$page}) {\n> +\t\t\treport($pos, $line, $target, \"wrong section (should be $real_section)\");\n> +\t\t\tnext;\n> \t\t}\n> \t}\n> -\tclose $fh;\n> -}\n> -\n> -sub lint_it {\n> -\tlint($File::Find::name) if -f && /\\.txt$/;\n> -}\n> -\n> -if (!@ARGV) {\n> -\tfind({ wanted => \\&lint_it, no_chdir => 1 }, $basedir);\n> -} else {\n> -\tfor (@ARGV) {\n> -\t\tlint($_);\n> -\t}\n> +\t# this resets our $. for each file\n> +\tclose ARGV if eof;\n> }\n> \n> -exit $found_errors;\n> +exit $exit_code;\n\n"},{"id":"420264","messageId":"87sg4indt1.fsf@evledraar.gmail.com","threadId":"55390","inReplyTo":"YF3AGsFFX3FQ1/ew@coredump.intra.peff.net","subject":"Re: [PATCH 0/5] small doc make and lint fixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T15:18:50Z","receivedAt":"2021-03-26T15:19:28Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Mar 26 2021, Jeff King wrote:\n\n> On Fri, Mar 26, 2021 at 11:36:45AM +0100, Ævar Arnfjörð Bjarmason wrote:\n>\n>> A small stand-alone series of doc infrastructure fixes. 5/6 fixes an\n>> interesting bug that's been missed since doc-diff was introduced.\n>\n> I'm not sure what you mean about doc-diff here. Patch 5 (of 5?) doesn't\n> seem related. Patch 4 is related only tangentially, in that you might\n> have more stuff in your Documentation directory.\n\nThat's how it's related, the lint script recursively looks for all *.txt\nunder Documentation/, before doc-diff we could safely assume this was\n*.txt at that version of the repository, after doc-diff our recursively\nsearch leads us to a different checkout at a different revision.\n\nI don't think it had any practical effect, just say'n.\n\n> That said...\n>\n>> Documentation/Makefile: make $(wildcard howto/*.txt) a var\n>> Documentation/Makefile: make $(wildcard ) a var\n>> doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl\n>\n> These three look obviously correct.\n>\n>> doc lint: fix bugs in, simplify and improve lint script\n>> doc lint: lint and fix missing \"GIT\" end sections\n>\n> These two seem fine, though I left some comments for possible\n> improvements.\n>\n> -Peff\n\n"},{"id":"420265","messageId":"87pmzmnd5h.fsf@evledraar.gmail.com","threadId":"55390","inReplyTo":"YF2/xPMvwhm+OOVz@coredump.intra.peff.net","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-03-26T15:32:58Z","receivedAt":"2021-03-26T15:33:43Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Mar 26 2021, Jeff King wrote:\n\n> On Fri, Mar 26, 2021 at 11:36:50AM +0100, Ævar Arnfjörð Bjarmason wrote:\n>\n>> Lint for and fix the three manual pages that were missing the standard\n>> \"Part of the linkgit:git[1] suite\" end section.\n>\n> This is a definite improvement. Two thoughts come to mind, though:\n>\n> 1. Do we need a separate script for this? Couldn't the existing linter\n> script check this while it is reading all of the files (it knows\n> which ones are supposed to be manpages because they are annotated\n> with the --section option).\n\nIt's not needed, but I think it's better, one is iterating a\nline-at-time, one slurps all lines, they have different sorts of error\nreporting (one quotes the whole line).\n\nSo I thought about joining them into one, and also make them and\ncheck-non-portable-shell.pl some general lint-line-ish checker.\n\nObviously all of that fits in one script, but I think for something like\nthis that's a one-off script with global variables it's much harder to\nfollow when a large part of your script is some if/else or\nkeeping/resetting of state simply to work around the script doing two\nthings instead of one.\n\nI mean, the whole scaffolding is basically:\n\n use strict;\n use warnings;\n sub report { ... }\n my $code = 0;\n while (<>) {\n ...\n }\n exit $code;\n\nWe'd spend more lines effort trying to consolidate them than just\ncopying that around.\n\n> That would be more efficient, and probably a little less code.\n\nThis thing takes ~5ms to run on my (and most) boxes, by comparison the\nwhole asciidoc dance takes some eons...\n\n> 2. Instead of linting, could we just be automatically sticking this\n> boilerplate in as part of the build (either through some asciidoc\n> magic, or even just a plain old \"cat\")? Even better than being\n> reminded that you forgot something is making it impossible to\n> forget it in the first place.\n\nWhenever I take an aborted effort at the docs I end up with some aborted\neffort to migrte them to texinfo, so I'm sympathetic to the automatic\ngeneration part of this.\n\nBut for something trivial like this I think there's more value in having\na 1=1 match between WYS and WYG, not adding magic blurbs by the build\nsystem for something so trivial.\n\nThat being said I wouldn't mind it much, just seemed like an obvious\nthing to add a lint for as it stands now...\n\n"},{"id":"420299","messageId":"YF7/VJmb+B1eH6Ro@coredump.intra.peff.net","threadId":"55390","inReplyTo":"87sg4indt1.fsf@evledraar.gmail.com","subject":"Re: [PATCH 0/5] small doc make and lint fixes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-03-27T09:48:04Z","receivedAt":"2021-03-27T09:49:14Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 26, 2021 at 04:18:50PM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> >> A small stand-alone series of doc infrastructure fixes. 5/6 fixes an\n> >> interesting bug that's been missed since doc-diff was introduced.\n> >\n> > I'm not sure what you mean about doc-diff here. Patch 5 (of 5?) doesn't\n> > seem related. Patch 4 is related only tangentially, in that you might\n> > have more stuff in your Documentation directory.\n> \n> That's how it's related, the lint script recursively looks for all *.txt\n> under Documentation/, before doc-diff we could safely assume this was\n> *.txt at that version of the repository, after doc-diff our recursively\n> search leads us to a different checkout at a different revision.\n> \n> I don't think it had any practical effect, just say'n.\n\nOK, thanks. I just wanted to make sure I wasn't missing something.\n\n-Peff\n"},{"id":"420300","messageId":"YF7/3GN4H/agNaxH@coredump.intra.peff.net","threadId":"55390","inReplyTo":"87pmzmnd5h.fsf@evledraar.gmail.com","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-03-27T09:50:20Z","receivedAt":"2021-03-27T09:51:26Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Mar 26, 2021 at 04:32:58PM +0100, Ævar Arnfjörð Bjarmason wrote:\n\n> > This is a definite improvement. Two thoughts come to mind, though:\n> >\n> > 1. Do we need a separate script for this? Couldn't the existing linter\n> > script check this while it is reading all of the files (it knows\n> > which ones are supposed to be manpages because they are annotated\n> > with the --section option).\n> \n> It's not needed, but I think it's better, one is iterating a\n> line-at-time, one slurps all lines, they have different sorts of error\n> reporting (one quotes the whole line).\n> [...]\n\nOK. As the person who looked at all of it much more closely, I'll trust\nyour judgement there.\n\n> > 2. Instead of linting, could we just be automatically sticking this\n> > boilerplate in as part of the build (either through some asciidoc\n> > magic, or even just a plain old \"cat\")? Even better than being\n> > reminded that you forgot something is making it impossible to\n> > forget it in the first place.\n> \n> Whenever I take an aborted effort at the docs I end up with some aborted\n> effort to migrte them to texinfo, so I'm sympathetic to the automatic\n> generation part of this.\n> \n> But for something trivial like this I think there's more value in having\n> a 1=1 match between WYS and WYG, not adding magic blurbs by the build\n> system for something so trivial.\n> \n> That being said I wouldn't mind it much, just seemed like an obvious\n> thing to add a lint for as it stands now...\n\nYeah, I agree that complicating the build may create its own problems.\nIf we were already munging the *.txt files it may not be a big deal to\nadd further munging, but it would be a jump from the current state of\n\"we feed it directly to asciidoc\".\n\nI'm OK to forget about it for now and see if other useful applications\nof such munging come up.\n\n-Peff\n"},{"id":"420326","messageId":"xmqqo8f4oych.fsf@gitster.g","threadId":"55390","inReplyTo":"a7e1bbc1-eb3e-72d0-ef65-24cc38346a04@iee.email","subject":"Re: [PATCH 4/5] doc lint: fix bugs in, simplify and improve lint script","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T01:34:22Z","receivedAt":"2021-03-28T01:35:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n>> diff --git a/Documentation/Makefile b/Documentation/Makefile\n>> index 7313956d73f..6bfd8c75772 100644\n>> --- a/Documentation/Makefile\n>> +++ b/Documentation/Makefile\n>> @@ -4,6 +4,7 @@ MAN5_TXT =\n>> MAN7_TXT =\n>> HOWTO_TXT =\n>> INCLUDE_TARGETS_TXT =\n>> +ALL_TXT =\n>\n> Maybe LINT_TXT would better clarify its use, rather than squatting on\n> the generic \"ALL\"?\n\nAs long as it is truly \"all the .txt files\" and will stay that way,\nand the set of files we lint happens to be \"everything under the sun\",\nI am OK to have this as ALL_TXT. We may in the future want to do\nsomething other than running lint-foo scripts to all the .txt files.\n"},{"id":"420328","messageId":"xmqqk0psoya2.fsf@gitster.g","threadId":"55390","inReplyTo":"YF2+4I4rH9CQ1A2F@coredump.intra.peff.net","subject":"Re: [PATCH 4/5] doc lint: fix bugs in, simplify and improve lint script","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T01:35:49Z","receivedAt":"2021-03-28T01:36:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Fri, Mar 26, 2021 at 11:36:49AM +0100, Ævar Arnfjörð Bjarmason wrote:\n>\n>> lint-docs::\n>> -\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n>> +\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n>> +\t\t--section=1 $(MAN1_TXT) \\\n>> +\t\t--section=5 $(MAN5_TXT) \\\n>> +\t\t--section=7 $(MAN7_TXT)\t\\\n>> +\t\t--to-lint $(ALL_TXT)\n>\n> This is probably bikeshedding, but I would have expected the invocation\n> to be:\n>\n> link-gitlink.perl \\\n> $(HOWTO_TXT) $(INCLUDE_TARGETS_TXT) \\\n> --section=1 $(MAN1_TXT) \\\n> --section=5 $(MAN5_TXT) \\\n> --section=7 $(MAN7_TXT)\n>\n> I.e., list each filename only once, with the previous --section giving\n> the expected section (and if before any --section, then expect no\n> section).\n\nMakes more sense than the presented patch. Optionally \"--section=\"\ncould be used to cancel the section that was previously given.\n"},{"id":"420360","messageId":"xmqqczvjolee.fsf@gitster.g","threadId":"55390","inReplyTo":"patch-1.6-a5ec5fe4bdb-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 1/5] Documentation/Makefile: make $(wildcard howto/*.txt) a var","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T06:14:01Z","receivedAt":"2021-03-28T06:17:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Refactor occurrences of $(wildcard howto/*.txt) into a single\n> HOWTO_TXT variable for readability and consistency.\n\nOK.\n"},{"id":"420363","messageId":"xmqq35wfokqe.fsf@gitster.g","threadId":"55390","inReplyTo":"patch-3.6-12573d90289-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 3/5] doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T06:28:25Z","receivedAt":"2021-03-28T06:29:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Amend this script added in ab81411ced (ci: validate \"linkgit:\" in\n> documentation, 2016-05-04) to pass under \"use strict\", and add a \"use\n> warnings\" for good measure.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/lint-gitlink.perl | 4 +++-\n> 1 file changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\n> index 476cc30b837..35230875c24 100755\n> --- a/Documentation/lint-gitlink.perl\n> +++ b/Documentation/lint-gitlink.perl\n> @@ -1,5 +1,7 @@\n> #!/usr/bin/perl\n> \n> +use strict;\n> +use warnings;\n\nYes! Thanks.\n\n> use File::Find;\n> use Getopt::Long;\n> \n> @@ -45,7 +47,7 @@ sub lint {\n> \t\t\t\treport($where, $target, \"no such source\");\n> \t\t\t\tnext;\n> \t\t\t}\n> -\t\t\t$real_section = grab_section($page);\n> +\t\t\tmy $real_section = grab_section($page);\n> \t\t\tif ($real_section != $section) {\n> \t\t\t\treport($where, $target,\n> \t\t\t\t\t\"wrong section (should be $real_section)\");\n"},{"id":"420364","messageId":"xmqq7dlrokqx.fsf@gitster.g","threadId":"55390","inReplyTo":"patch-2.6-fdc55a86cf4-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 2/5] Documentation/Makefile: make $(wildcard ) a var","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T06:28:06Z","receivedAt":"2021-03-28T06:29:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Refactor the wildcard we'll scan for \"include\" directives into a\n> single INCLUDE_TARGETS_TXT variable for readability, consistency.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 6 +++++-\n> 1 file changed, 5 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 0ba7564be93..7313956d73f 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -3,6 +3,7 @@ MAN1_TXT =\n> MAN5_TXT =\n> MAN7_TXT =\n> HOWTO_TXT =\n> +INCLUDE_TARGETS_TXT =\n> TECH_DOCS =\n> ARTICLES =\n> SP_ARTICLES =\n> @@ -45,6 +46,9 @@ MAN7_TXT += gitworkflows.txt\n> \n> HOWTO_TXT += $(wildcard howto/*.txt)\n> \n> +INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n> +INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n> +\n> ifdef MAN_FILTER\n> MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n> else\n> @@ -287,7 +291,7 @@ docdep_prereqs = \\\n> \tmergetools-list.made $(mergetools_txt) \\\n> \tcmd-list.made $(cmds_txt)\n> \n> -doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl\n> +doc.dep : $(docdep_prereqs) $(INCLUDE_TARGETS_TXT) build-docdep.perl\n> \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n> \t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n> \tmv $@+ $@\n\nWhile this may not break anything per-se, I find the name of the new\nmacro not quite intuitive.\n\nThe build-docdep script opens $(wildcard *.txt) itself (without\ngetting them fed from Makefile) to find what other files are used\nvia \"include::\", and then it recursively scans more files that are\nused via \"include::\" to build dependencies. Makefile assumes the\n\"include::\" chain would pull in $(wildcard config/*.txt) files, but\nthis assumption may not prevent other *.txt files from getting\npulled in (not a new problem introduced by this patch).\n\nI am not sure what these *.txt files involved in the process should\nbe called, but \"include targets\" sounds something else. Naïvely, I\nwould say \"we rebuild documentation dependency any time any source\ntext file changes\", so if this were called \"ALL_TXT\" or something\nlike that, I wouldn't have such a reaction.\n\nThanks.\n\n"},{"id":"420366","messageId":"xmqqv99bn5ov.fsf@gitster.g","threadId":"55390","inReplyTo":"patch-4.6-5c8e8f21495-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 4/5] doc lint: fix bugs in, simplify and improve lint script","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T06:38:40Z","receivedAt":"2021-03-28T06:39:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> - Was using File::Find to recursively find *.txt files in\n> Documentation/, let's instead use the Makefile as a source of truth\n> for *.txt files, and pass it down to the script.\n\nOK.\n\n> - We now don't lint linkgit:* in RelNotes/* or technical/*, which we\n> shouldn't have been doing in the first place anyway.\n\nI understand RelNotes (which I consider is plain text file), but are\ntechnical/* documentation forbidden from referring to our manual\npages for the commands they talk about?\n\n> - When the doc-diff script was added in beb188e22a (add a script to\n> diff rendered documentation, 2018-08-06) we started sometimes having\n> a \"git worktree\" under \"documentation\". This tree contains a full\n> checkout of git.git, as a result the \"lint\" script would recurse into\n> that, and lint any *.txt file found in that entire repository.\n\nOuch.\n\n> In practice the only in-tree \"linkgit\" outside of the\n> Documentation/ tree is contrib/contacts/git-contacts.txt and\n> contrib/subtree/git-subtree.txt, so this wouldn't emit any errors\n\nHmm, the nested copy of git has Documentation/ subdirectory of its\nown, and we do not want to scan it, I think.\n\nThat is a problem worth fixing. Thanks for noticing it.\n\n> Now we instead simply trust the Makefile to give us *.txt files, and\n> since the Makefile also knows what sections each page should be in we\n> don't have to open the files ourselves and try to parse that out. As a\n> bonus this will also catch bugs with the section line in the file\n> being incorrect.\n\nOK.\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 7313956d73f..6bfd8c75772 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -4,6 +4,7 @@ MAN5_TXT =\n> MAN7_TXT =\n> HOWTO_TXT =\n> INCLUDE_TARGETS_TXT =\n> +ALL_TXT =\n> TECH_DOCS =\n> ARTICLES =\n> SP_ARTICLES =\n> @@ -49,6 +50,13 @@ HOWTO_TXT += $(wildcard howto/*.txt)\n> INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n> INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n> \n> +# For linting\n> +ALL_TXT += $(MAN1_TXT)\n> +ALL_TXT += $(MAN5_TXT)\n> +ALL_TXT += $(MAN7_TXT)\n> +ALL_TXT += $(HOWTO_TXT)\n> +ALL_TXT += $(INCLUDE_TARGETS_TXT)\n\nThe \"INCLUDE_TARGETS_TXT\" looks more and more like \"all txt\nsources\", which is a superset of MAN1_TXT and its friends.\n\nListing all of them in ALL_TXT duplicated feels somewhat iffy.\n\n> ifdef MAN_FILTER\n> MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n> else\n> @@ -477,7 +485,11 @@ print-man1:\n> \t@for i in $(MAN1_TXT); do echo $$i; done\n> \n> lint-docs::\n> -\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n> +\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n> +\t\t--section=1 $(MAN1_TXT) \\\n> +\t\t--section=5 $(MAN5_TXT) \\\n> +\t\t--section=7 $(MAN7_TXT)\t\\\n> +\t\t--to-lint $(ALL_TXT)\n"},{"id":"420367","messageId":"xmqqr1jzn5j5.fsf@gitster.g","threadId":"55390","inReplyTo":"patch-5.6-d4004b6a7cb-20210326T103454Z-avarab@gmail.com","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T06:42:06Z","receivedAt":"2021-03-28T06:42:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Lint for and fix the three manual pages that were missing the standard\n> \"Part of the linkgit:git[1] suite\" end section.\n>\n> We only do this for the man[157] section documents (we don't have\n> anything outside those sections), not files to be included,\n> howto *.txt files etc.\n\nOK. Alternatively we could drop the footer from all pages. IIRC,\nwe used to have another footer section to credit primary authors,\nwhich we dropped years ago. I doubt \"git-foo is part of git suite\"\nis something worth repeating over and over.\n\nThanks.\n\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/Makefile | 2 ++\n> Documentation/git-credential.txt | 4 ++++\n> Documentation/git-p4.txt | 4 ++++\n> Documentation/gitnamespaces.txt | 4 ++++\n> Documentation/lint-man-txt.perl | 24 ++++++++++++++++++++++++\n> 5 files changed, 38 insertions(+)\n> create mode 100755 Documentation/lint-man-txt.perl\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 6bfd8c75772..2b6cd0f7be2 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -490,6 +490,8 @@ lint-docs::\n> \t\t--section=5 $(MAN5_TXT) \\\n> \t\t--section=7 $(MAN7_TXT)\t\\\n> \t\t--to-lint $(ALL_TXT)\n> +\t$(QUIET_LINT)$(PERL_PATH) lint-man-txt.perl \\\n> +\t\t$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n> \n> ifeq ($(wildcard po/Makefile),po/Makefile)\n> doc-l10n install-l10n::\n> diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\n> index 31c81c4c026..206e3c5f407 100644\n> --- a/Documentation/git-credential.txt\n> +++ b/Documentation/git-credential.txt\n> @@ -159,3 +159,7 @@ empty string.\n> +\n> Components which are missing from the URL (e.g., there is no\n> username in the example above) will be left unset.\n> +\n> +GIT\n> +---\n> +Part of the linkgit:git[1] suite\n> diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\n> index f89e68b424c..38e5257b2a4 100644\n> --- a/Documentation/git-p4.txt\n> +++ b/Documentation/git-p4.txt\n> @@ -762,3 +762,7 @@ IMPLEMENTATION DETAILS\n> message indicating the p4 depot location and change number. This\n> line is used by later 'git p4 sync' operations to know which p4\n> changes are new.\n> +\n> +GIT\n> +---\n> +Part of the linkgit:git[1] suite\n> diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt\n> index b614969ad2c..1c8d2ecc358 100644\n> --- a/Documentation/gitnamespaces.txt\n> +++ b/Documentation/gitnamespaces.txt\n> @@ -62,3 +62,7 @@ git clone ext::'git --namespace=foo %s /tmp/prefixed.git'\n> ----------\n> \n> include::transfer-data-leaks.txt[]\n> +\n> +GIT\n> +---\n> +Part of the linkgit:git[1] suite\n> diff --git a/Documentation/lint-man-txt.perl b/Documentation/lint-man-txt.perl\n> new file mode 100755\n> index 00000000000..d69312e5db5\n> --- /dev/null\n> +++ b/Documentation/lint-man-txt.perl\n> @@ -0,0 +1,24 @@\n> +#!/usr/bin/perl\n> +\n> +use strict;\n> +use warnings;\n> +\n> +my $exit_code = 0;\n> +sub report {\n> +\tmy ($target, $msg) = @_;\n> +\tprint \"error: $target: $msg\\n\";\n> +\t$exit_code = 1;\n> +}\n> +\n> +local $/;\n> +while (my $slurp = <>) {\n> +\treport($ARGV, \"has no 'Part of the linkgit:git[1] suite' end blurb\")\n> +\t\tunless $slurp =~ m[\n> +\t\t^GIT\\n\n> +\t\t ---\\n\n> +\t\t\\QPart of the linkgit:git[1] suite\\E \\n\n> +\t\t\\z\n> +\t]mx;\n> +}\n> +\n> +exit $exit_code;\n"},{"id":"420416","messageId":"xmqqk0prmafq.fsf@gitster.g","threadId":"55390","inReplyTo":"xmqqr1jzn5j5.fsf@gitster.g","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-03-28T17:53:45Z","receivedAt":"2021-03-28T17:54:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Ævar Arnfjörð Bjarmason writes:\n>\n>> Lint for and fix the three manual pages that were missing the standard\n>> \"Part of the linkgit:git[1] suite\" end section.\n>>\n>> We only do this for the man[157] section documents (we don't have\n>> anything outside those sections), not files to be included,\n>> howto *.txt files etc.\n>\n> OK. Alternatively we could drop the footer from all pages. IIRC,\n> we used to have another footer section to credit primary authors,\n> which we dropped years ago. I doubt \"git-foo is part of git suite\"\n> is something worth repeating over and over.\n>\n> Thanks.\n\nHaving said that, making sure all pages consistently have them is\nfine, too. It is just the repetition, even though my eyes have\nlearned to take it as perfectly normal state of affairs, did not\nseem to be adding that much value.\n\n"},{"id":"421385","messageId":"87lf9rhe4y.fsf@evledraar.gmail.com","threadId":"55390","inReplyTo":"xmqqk0prmafq.fsf@gitster.g","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T11:49:01Z","receivedAt":"2021-04-09T11:49:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sun, Mar 28 2021, Junio C Hamano wrote:\n\n> Junio C Hamano writes:\n>\n>> Ævar Arnfjörð Bjarmason writes:\n>>\n>>> Lint for and fix the three manual pages that were missing the standard\n>>> \"Part of the linkgit:git[1] suite\" end section.\n>>>\n>>> We only do this for the man[157] section documents (we don't have\n>>> anything outside those sections), not files to be included,\n>>> howto *.txt files etc.\n>>\n>> OK. Alternatively we could drop the footer from all pages. IIRC,\n>> we used to have another footer section to credit primary authors,\n>> which we dropped years ago. I doubt \"git-foo is part of git suite\"\n>> is something worth repeating over and over.\n>>\n>> Thanks.\n>\n> Having said that, making sure all pages consistently have them is\n> fine, too. It is just the repetition, even though my eyes have\n> learned to take it as perfectly normal state of affairs, did not\n> seem to be adding that much value.\n\nIt adds the value of:\n\n * If you're looking at e.g. git-subtree's manpage it doesn't have it,\n so we're clearly marking things that are part of git itself, also if\n you're doing e.g. \"man git-annex\" (or other non-git.git tool)\n somewhere.\n\n * Once you're at the bottom of a manpage in e.g. a web view it's a\n handy link back to the start, see\n e.g. https://git-scm.com/docs/git-add#_git\n"},{"id":"421399","messageId":"patch-1.7-8efebc7a03-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 1/7] Documentation/Makefile: make $(wildcard howto/*.txt) a var","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:44Z","receivedAt":"2021-04-09T15:03:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Refactor occurrences of $(wildcard howto/*.txt) into a single\nHOWTO_TXT variable for readability and consistency.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 9 ++++++---\n 1 file changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 874a01d7a8..f0597777b9 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -2,6 +2,7 @@\n MAN1_TXT =\n MAN5_TXT =\n MAN7_TXT =\n+HOWTO_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n@@ -42,6 +43,8 @@ MAN7_TXT += gittutorial-2.txt\n MAN7_TXT += gittutorial.txt\n MAN7_TXT += gitworkflows.txt\n \n+HOWTO_TXT += $(wildcard howto/*.txt)\n+\n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n else\n@@ -428,9 +431,9 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml\n \t$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \\\n \tmv $@+ $@\n \n-howto-index.txt: howto-index.sh $(wildcard howto/*.txt)\n+howto-index.txt: howto-index.sh $(HOWTO_TXT)\n \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n-\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \\\n+\t'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@+ && \\\n \tmv $@+ $@\n \n $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n@@ -439,7 +442,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n WEBDOC_DEST = /pub/software/scm/git/docs\n \n howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n-$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt GIT-ASCIIDOCFLAGS\n+$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \tsed -e '1,/^$$/d' $< | \\\n \t$(TXT_TO_HTML) - >$@+ && \\\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421400","messageId":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.6-00000000000-20210326T103454Z-avarab@gmail.com","subject":"[PATCH v2 0/7] doc make and lint fixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:43Z","receivedAt":"2021-04-09T15:03:04Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Lint for and fix the three manual pages that were missing the standard\n\"Part of the linkgit:git[1] suite\" end section.\n\nAddresses the feedback on v1, in particular stylistic / variable\nnaming choices. I just went with all the suggestions.\n\nI've added two new patches at the end to detect (and in 7/7 fix)\nissues with \"standard\" sections like NAME, SYNOPSIS, OPTIONS etc. that\nare out of order, e.g. git-mktag was one of two manual pages that\nOPTIONS before DESCRIPTION. Those and a few other such oddities are\nnow fixed.\n\nI've got a follow-up series to finish the work I started a while ago\nof including the relevant git config variable descriptions in the\nrespective manual pages, e.g. now we have gc.* variables in git-gc(1),\nbut not in all manual pages. We'll hopefully consistently have that\neverywhere soon, and this \"sections in the right order\" lint was very\nuseful to check those patches.\n\nÆvar Arnfjörð Bjarmason (7):\n Documentation/Makefile: make $(wildcard howto/*.txt) a var\n Documentation/Makefile: make doc.dep dependencies a variable again\n doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl\n doc lint: fix bugs in, simplify and improve lint script\n doc lint: lint and fix missing \"GIT\" end sections\n doc lint: lint relative section order\n docs: fix linting issues due to incorrect relative section order\n\n Documentation/Makefile | 23 ++++-\n Documentation/git-credential.txt | 4 +\n Documentation/git-cvsserver.txt | 24 ++---\n Documentation/git-grep.txt | 64 ++++++-------\n Documentation/git-mktag.txt | 16 ++--\n Documentation/git-p4.txt | 4 +\n Documentation/git-rebase.txt | 12 +--\n Documentation/git-svn.txt | 38 ++++----\n Documentation/gitnamespaces.txt | 4 +\n Documentation/lint-gitlink.perl | 108 +++++++++++-----------\n Documentation/lint-man-end-blurb.perl | 24 +++++\n Documentation/lint-man-section-order.perl | 105 +++++++++++++++++++++\n 12 files changed, 288 insertions(+), 138 deletions(-)\n create mode 100755 Documentation/lint-man-end-blurb.perl\n create mode 100755 Documentation/lint-man-section-order.perl\n\nRange-diff against v1:\n1: a5ec5fe4bd = 1: 8efebc7a03 Documentation/Makefile: make $(wildcard howto/*.txt) a var\n2: fdc55a86cf ! 2: 8046e7941e Documentation/Makefile: make $(wildcard ) a var\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - Documentation/Makefile: make $(wildcard ) a var\n + Documentation/Makefile: make doc.dep dependencies a variable again\n \n - Refactor the wildcard we'll scan for \"include\" directives into a\n - single INCLUDE_TARGETS_TXT variable for readability, consistency.\n + Re-introduce a variable to declare what *.txt files need to be\n + considered for the purposes of scouring files to generate a dependency\n + graph of includes.\n +\n + When doc.dep was introduced in a5ae8e64cf (Fix documentation\n + dependency generation., 2005-11-07) we had such a variable called\n + TEXTFILES, but it was refactored away just a few commits after that in\n + fb612d54c1 (Documentation: fix dependency generation.,\n + 2005-11-07). I'm planning to add more wildcards here, so let's bring\n + it back.\n +\n + I'm not calling it TEXTFILES because we e.g. don't consider\n + Documentation/technical/*.txt when generating the graph (they don't\n + use includes). Let's instead call it DOC_DEP_TXT.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n @@ Documentation/Makefile: MAN1_TXT =\n MAN5_TXT =\n MAN7_TXT =\n HOWTO_TXT =\n -+INCLUDE_TARGETS_TXT =\n ++DOC_DEP_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n @@ Documentation/Makefile: MAN7_TXT += gitworkflows.txt\n \n HOWTO_TXT += $(wildcard howto/*.txt)\n \n -+INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n -+INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n ++DOC_DEP_TXT += $(wildcard *.txt)\n ++DOC_DEP_TXT += $(wildcard config/*.txt)\n +\n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n @@ Documentation/Makefile: docdep_prereqs = \\\n \tcmd-list.made $(cmds_txt)\n \n -doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl\n -+doc.dep : $(docdep_prereqs) $(INCLUDE_TARGETS_TXT) build-docdep.perl\n ++doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl\n \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n \t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n \tmv $@+ $@\n3: 12573d9028 = 3: 29545543bd doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl\n4: 5c8e8f2149 ! 4: 5acb116fea doc lint: fix bugs in, simplify and improve lint script\n @@ Commit message\n \n - When the doc-diff script was added in beb188e22a (add a script to\n diff rendered documentation, 2018-08-06) we started sometimes having\n - a \"git worktree\" under \"documentation\". This tree contains a full\n - checkout of git.git, as a result the \"lint\" script would recurse into\n - that, and lint any *.txt file found in that entire repository.\n + a \"git worktree\" under Documentation/.\n +\n + This tree contains a full checkout of git.git, as a result the\n + \"lint\" script would recurse into that, and lint any *.txt file\n + found in that entire repository.\n \n In practice the only in-tree \"linkgit\" outside of the\n Documentation/ tree is contrib/contacts/git-contacts.txt and\n contrib/subtree/git-subtree.txt, so this wouldn't emit any errors\n \n - Now we instead simply trust the Makefile to give us *.txt files, and\n - since the Makefile also knows what sections each page should be in we\n + Now we instead simply trust the Makefile to give us *.txt files.\n + Since the Makefile also knows what sections each page should be in we\n don't have to open the files ourselves and try to parse that out. As a\n - bonus this will also catch bugs with the section line in the file\n - being incorrect.\n + bonus this will also catch bugs with the section line in the files\n + themselves being incorrect.\n \n The structure of the new script is mostly based on\n t/check-non-portable-shell.pl. As an added bonus it will also use\n @@ Commit message\n We'll now emit:\n \n git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below:\n - git-cherry.txt:20: \"copied\" by means of linkgit:git-cherry-pick[2]' <-- HERE\n + git-cherry.txt:20: '\"copied\" by means of linkgit:git-cherry-pick[2]' <-- HERE\n git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below:\n - git-cherry.txt:20: \"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE\n + git-cherry.txt:20: '\"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE\n git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below:\n - git-cherry.txt:21: linkgit:git-rebase[4]' <-- HERE\n + git-cherry.txt:21: 'linkgit:git-rebase[4]' <-- HERE\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n -@@ Documentation/Makefile: MAN5_TXT =\n - MAN7_TXT =\n - HOWTO_TXT =\n - INCLUDE_TARGETS_TXT =\n -+ALL_TXT =\n - TECH_DOCS =\n - ARTICLES =\n - SP_ARTICLES =\n -@@ Documentation/Makefile: HOWTO_TXT += $(wildcard howto/*.txt)\n - INCLUDE_TARGETS_TXT += $(wildcard *.txt)\n - INCLUDE_TARGETS_TXT += $(wildcard config/*.txt)\n - \n -+# For linting\n -+ALL_TXT += $(MAN1_TXT)\n -+ALL_TXT += $(MAN5_TXT)\n -+ALL_TXT += $(MAN7_TXT)\n -+ALL_TXT += $(HOWTO_TXT)\n -+ALL_TXT += $(INCLUDE_TARGETS_TXT)\n -+\n - ifdef MAN_FILTER\n - MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n - else\n @@ Documentation/Makefile: print-man1:\n \t@for i in $(MAN1_TXT); do echo $$i; done\n \n lint-docs::\n -\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n +\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n ++\t\t$(HOWTO_TXT) $(DOC_DEP_TXT) \\\n +\t\t--section=1 $(MAN1_TXT) \\\n +\t\t--section=5 $(MAN5_TXT) \\\n -+\t\t--section=7 $(MAN7_TXT)\t\\\n -+\t\t--to-lint $(ALL_TXT)\n ++\t\t--section=7 $(MAN7_TXT)\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\n @@ Documentation/lint-gitlink.perl\n -\tor die(\"Cannot parse command line arguments\\n\");\n +# Parse arguments, a simple state machine for input like:\n +#\n -+# --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]\n ++# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]\n +my %TXT;\n +my %SECTION;\n +my $section;\n @@ Documentation/lint-gitlink.perl\n +\tif (my ($sec) = $arg =~ /^--section=(\\d+)$/s) {\n +\t\t$section = $sec;\n +\t\tnext;\n -+\t} elsif ($arg eq '--to-lint') {\n -+\t\t$lint_these = 1;\n -+\t\tnext;\n +\t}\n \n -my $found_errors = 0;\n +\tmy ($name) = $arg =~ /^(.*?)\\.txt$/s;\n -+\tif ($lint_these) {\n ++\tunless (defined $section) {\n +\t\t$TXT{$name} = $arg;\n +\t\tnext;\n +\t}\n @@ Documentation/lint-gitlink.perl\n +\tsubstr($line, $pos) = \"' <-- HERE\";\n +\t$line =~ s/^\\s+//;\n +\tprint \"$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\\n\";\n -+\tprint \"$ARGV:$.:\\t$line\\n\";\n ++\tprint \"$ARGV:$.:\\t'$line\\n\";\n +\t$exit_code = 1;\n }\n \n @@ Documentation/lint-gitlink.perl\n -\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n -\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n +@ARGV = sort values %TXT;\n ++die \"BUG: Nothing to process!\" unless @ARGV;\n +while (<>) {\n +\tmy $line = $_;\n +\twhile ($line =~ m/linkgit:((.*?)\\[(\\d)\\])/g) {\n5: d4004b6a7c ! 5: e3af1a9405 doc lint: lint and fix missing \"GIT\" end sections\n @@ Commit message\n anything outside those sections), not files to be included,\n howto *.txt files etc.\n \n + We could also add this to the existing (and then renamed)\n + lint-gitlink.perl, but I'm not doing that here.\n +\n + Obviously all of that fits in one script, but I think for something\n + like this that's a one-off script with global variables it's much\n + harder to follow when a large part of your script is some if/else or\n + keeping/resetting of state simply to work around the script doing two\n + things instead of one.\n +\n + Especially because in this case this script wants to process the file\n + as one big string, but lint-gitlink.perl wants to look at it one line\n + at a time. We could also consolidate this whole thing and\n + t/check-non-portable-shell.pl, but that one likes to join lines as\n + part of its shell parsing.\n +\n + So let's just add another script, whole scaffolding is basically:\n +\n + use strict;\n + use warnings;\n + sub report { ... }\n + my $code = 0;\n + while (<>) { ... }\n + exit $code;\n +\n + We'd spend more lines effort trying to consolidate them than just\n + copying that around.\n +\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/Makefile ##\n @@ Documentation/Makefile: lint-docs::\n + \t\t$(HOWTO_TXT) $(DOC_DEP_TXT) \\\n + \t\t--section=1 $(MAN1_TXT) \\\n \t\t--section=5 $(MAN5_TXT) \\\n - \t\t--section=7 $(MAN7_TXT)\t\\\n - \t\t--to-lint $(ALL_TXT)\n -+\t$(QUIET_LINT)$(PERL_PATH) lint-man-txt.perl \\\n -+\t\t$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)\n +-\t\t--section=7 $(MAN7_TXT)\n ++\t\t--section=7 $(MAN7_TXT); \\\n ++\t$(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT)\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\n @@ Documentation/gitnamespaces.txt: git clone ext::'git --namespace=foo %s /tmp/pre\n +---\n +Part of the linkgit:git[1] suite\n \n - ## Documentation/lint-man-txt.perl (new) ##\n + ## Documentation/lint-man-end-blurb.perl (new) ##\n @@\n +#!/usr/bin/perl\n +\n-: ---------- > 6: 8c294afe2a doc lint: lint relative section order\n-: ---------- > 7: 9cb100826e docs: fix linting issues due to incorrect relative section order\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421401","messageId":"patch-3.7-29545543bd-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 3/7] doc lint: Perl \"strict\" and \"warnings\" in lint-gitlink.perl","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:46Z","receivedAt":"2021-04-09T15:03:10Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Amend this script added in ab81411ced (ci: validate \"linkgit:\" in\ndocumentation, 2016-05-04) to pass under \"use strict\", and add a \"use\nwarnings\" for good measure.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/lint-gitlink.perl | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex 476cc30b83..35230875c2 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -1,5 +1,7 @@\n #!/usr/bin/perl\n \n+use strict;\n+use warnings;\n use File::Find;\n use Getopt::Long;\n \n@@ -45,7 +47,7 @@ sub lint {\n \t\t\t\treport($where, $target, \"no such source\");\n \t\t\t\tnext;\n \t\t\t}\n-\t\t\t$real_section = grab_section($page);\n+\t\t\tmy $real_section = grab_section($page);\n \t\t\tif ($real_section != $section) {\n \t\t\t\treport($where, $target,\n \t\t\t\t\t\"wrong section (should be $real_section)\");\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421402","messageId":"patch-2.7-8046e7941e-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 2/7] Documentation/Makefile: make doc.dep dependencies a variable again","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:45Z","receivedAt":"2021-04-09T15:03:13Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Re-introduce a variable to declare what *.txt files need to be\nconsidered for the purposes of scouring files to generate a dependency\ngraph of includes.\n\nWhen doc.dep was introduced in a5ae8e64cf (Fix documentation\ndependency generation., 2005-11-07) we had such a variable called\nTEXTFILES, but it was refactored away just a few commits after that in\nfb612d54c1 (Documentation: fix dependency generation.,\n2005-11-07). I'm planning to add more wildcards here, so let's bring\nit back.\n\nI'm not calling it TEXTFILES because we e.g. don't consider\nDocumentation/technical/*.txt when generating the graph (they don't\nuse includes). Let's instead call it DOC_DEP_TXT.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 6 +++++-\n 1 file changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f0597777b9..164d5ff2f9 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -3,6 +3,7 @@ MAN1_TXT =\n MAN5_TXT =\n MAN7_TXT =\n HOWTO_TXT =\n+DOC_DEP_TXT =\n TECH_DOCS =\n ARTICLES =\n SP_ARTICLES =\n@@ -45,6 +46,9 @@ MAN7_TXT += gitworkflows.txt\n \n HOWTO_TXT += $(wildcard howto/*.txt)\n \n+DOC_DEP_TXT += $(wildcard *.txt)\n+DOC_DEP_TXT += $(wildcard config/*.txt)\n+\n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\n else\n@@ -288,7 +292,7 @@ docdep_prereqs = \\\n \tmergetools-list.made $(mergetools_txt) \\\n \tcmd-list.made $(cmds_txt)\n \n-doc.dep : $(docdep_prereqs) $(wildcard *.txt) $(wildcard config/*.txt) build-docdep.perl\n+doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl\n \t$(QUIET_GEN)$(RM) $@+ $@ && \\\n \t$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \\\n \tmv $@+ $@\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421403","messageId":"patch-4.7-5acb116fea-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 4/7] doc lint: fix bugs in, simplify and improve lint script","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:47Z","receivedAt":"2021-04-09T15:03:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The lint-gitlink.perl script added in ab81411ced (ci: validate\n\"linkgit:\" in documentation, 2016-05-04) was more complex than it\nneeded to be. It:\n\n - Was using File::Find to recursively find *.txt files in\n Documentation/, let's instead use the Makefile as a source of truth\n for *.txt files, and pass it down to the script.\n\n - We now don't lint linkgit:* in RelNotes/* or technical/*, which we\n shouldn't have been doing in the first place anyway.\n\n - When the doc-diff script was added in beb188e22a (add a script to\n diff rendered documentation, 2018-08-06) we started sometimes having\n a \"git worktree\" under Documentation/.\n\n This tree contains a full checkout of git.git, as a result the\n \"lint\" script would recurse into that, and lint any *.txt file\n found in that entire repository.\n\n In practice the only in-tree \"linkgit\" outside of the\n Documentation/ tree is contrib/contacts/git-contacts.txt and\n contrib/subtree/git-subtree.txt, so this wouldn't emit any errors\n\nNow we instead simply trust the Makefile to give us *.txt files.\nSince the Makefile also knows what sections each page should be in we\ndon't have to open the files ourselves and try to parse that out. As a\nbonus this will also catch bugs with the section line in the files\nthemselves being incorrect.\n\nThe structure of the new script is mostly based on\nt/check-non-portable-shell.pl. As an added bonus it will also use\npos() to print where the problems it finds are, e.g. given an issue\nlike:\n\n diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt\n [...]\n and line numbers. git-cherry therefore detects when commits have been\n -\"copied\" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or\n -linkgit:git-rebase[1].\n +\"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3] or\n +linkgit:git-rebase[4].\n\nWe'll now emit:\n\n git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below:\n git-cherry.txt:20: '\"copied\" by means of linkgit:git-cherry-pick[2]' <-- HERE\n git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below:\n git-cherry.txt:20: '\"copied\" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE\n git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below:\n git-cherry.txt:21: 'linkgit:git-rebase[4]' <-- HERE\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 6 +-\n Documentation/lint-gitlink.perl | 106 +++++++++++++++-----------------\n 2 files changed, 55 insertions(+), 57 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 164d5ff2f9..de55c4ecf5 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -478,7 +478,11 @@ print-man1:\n \t@for i in $(MAN1_TXT); do echo $$i; done\n \n lint-docs::\n-\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl\n+\t$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl \\\n+\t\t$(HOWTO_TXT) $(DOC_DEP_TXT) \\\n+\t\t--section=1 $(MAN1_TXT) \\\n+\t\t--section=5 $(MAN5_TXT) \\\n+\t\t--section=7 $(MAN7_TXT)\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex 35230875c2..b22a367844 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -2,72 +2,66 @@\n \n use strict;\n use warnings;\n-use File::Find;\n-use Getopt::Long;\n \n-my $basedir = \".\";\n-GetOptions(\"basedir=s\" => \\$basedir)\n-\tor die(\"Cannot parse command line arguments\\n\");\n+# Parse arguments, a simple state machine for input like:\n+#\n+# howto/*.txt config/*.txt --section=1 git.txt git-add.txt [...] --to-lint git-add.txt a-file.txt [...]\n+my %TXT;\n+my %SECTION;\n+my $section;\n+my $lint_these = 0;\n+for my $arg (@ARGV) {\n+\tif (my ($sec) = $arg =~ /^--section=(\\d+)$/s) {\n+\t\t$section = $sec;\n+\t\tnext;\n+\t}\n \n-my $found_errors = 0;\n+\tmy ($name) = $arg =~ /^(.*?)\\.txt$/s;\n+\tunless (defined $section) {\n+\t\t$TXT{$name} = $arg;\n+\t\tnext;\n+\t}\n \n-sub report {\n-\tmy ($where, $what, $error) = @_;\n-\tprint \"$where: $error: $what\\n\";\n-\t$found_errors = 1;\n+\t$SECTION{$name} = $section;\n }\n \n-sub grab_section {\n-\tmy ($page) = @_;\n-\topen my $fh, \"<\", \"$basedir/$page.txt\";\n-\tmy $firstline = <$fh>;\n-\tchomp $firstline;\n-\tclose $fh;\n-\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n-\treturn $section;\n+my $exit_code = 0;\n+sub report {\n+\tmy ($pos, $line, $target, $msg) = @_;\n+\tsubstr($line, $pos) = \"' <-- HERE\";\n+\t$line =~ s/^\\s+//;\n+\tprint \"$ARGV:$.: error: $target: $msg, shown with 'HERE' below:\\n\";\n+\tprint \"$ARGV:$.:\\t'$line\\n\";\n+\t$exit_code = 1;\n }\n \n-sub lint {\n-\tmy ($file) = @_;\n-\topen my $fh, \"<\", $file\n-\t\tor return;\n-\twhile (<$fh>) {\n-\t\tmy $where = \"$file:$.\";\n-\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n-\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n+@ARGV = sort values %TXT;\n+die \"BUG: Nothing to process!\" unless @ARGV;\n+while (<>) {\n+\tmy $line = $_;\n+\twhile ($line =~ m/linkgit:((.*?)\\[(\\d)\\])/g) {\n+\t\tmy $pos = pos $line;\n+\t\tmy ($target, $page, $section) = ($1, $2, $3);\n \n-\t\t\t# De-AsciiDoc\n-\t\t\t$page =~ s/{litdd}/--/g;\n+\t\t# De-AsciiDoc\n+\t\t$page =~ s/{litdd}/--/g;\n \n-\t\t\tif ($page !~ /^git/) {\n-\t\t\t\treport($where, $target, \"nongit link\");\n-\t\t\t\tnext;\n-\t\t\t}\n-\t\t\tif (! -f \"$basedir/$page.txt\") {\n-\t\t\t\treport($where, $target, \"no such source\");\n-\t\t\t\tnext;\n-\t\t\t}\n-\t\t\tmy $real_section = grab_section($page);\n-\t\t\tif ($real_section != $section) {\n-\t\t\t\treport($where, $target,\n-\t\t\t\t\t\"wrong section (should be $real_section)\");\n-\t\t\t\tnext;\n-\t\t\t}\n+\t\tif (!exists $TXT{$page}) {\n+\t\t\treport($pos, $line, $target, \"link outside of our own docs\");\n+\t\t\tnext;\n+\t\t}\n+\t\tif (!exists $SECTION{$page}) {\n+\t\t\treport($pos, $line, $target, \"link outside of our sectioned docs\");\n+\t\t\tnext;\n+\t\t}\n+\t\tmy $real_section = $SECTION{$page};\n+\t\tif ($section != $SECTION{$page}) {\n+\t\t\treport($pos, $line, $target, \"wrong section (should be $real_section)\");\n+\t\t\tnext;\n \t\t}\n \t}\n-\tclose $fh;\n-}\n-\n-sub lint_it {\n-\tlint($File::Find::name) if -f && /\\.txt$/;\n-}\n-\n-if (!@ARGV) {\n-\tfind({ wanted => \\&lint_it, no_chdir => 1 }, $basedir);\n-} else {\n-\tfor (@ARGV) {\n-\t\tlint($_);\n-\t}\n+\t# this resets our $. for each file\n+\tclose ARGV if eof;\n }\n \n-exit $found_errors;\n+exit $exit_code;\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421404","messageId":"patch-6.7-8c294afe2a-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 6/7] doc lint: lint relative section order","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:49Z","receivedAt":"2021-04-09T15:03:17Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a linting script to check the relative order of the sections in\nthe documentation. We should have NAME, then SYNOPSIS, DESCRIPTION,\nOPTIONS etc. in that order.\n\nThat holds true throughout our documentation, except for a few\nexceptions which are hardcoded in the linting script.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 +-\n Documentation/lint-man-section-order.perl | 125 ++++++++++++++++++++++\n 2 files changed, 127 insertions(+), 1 deletion(-)\n create mode 100755 Documentation/lint-man-section-order.perl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 34b4f5716a..5e0828869b 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -483,7 +483,8 @@ lint-docs::\n \t\t--section=1 $(MAN1_TXT) \\\n \t\t--section=5 $(MAN5_TXT) \\\n \t\t--section=7 $(MAN7_TXT); \\\n-\t$(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT)\n+\t$(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT); \\\n+\t$(PERL_PATH) lint-man-section-order.perl $(MAN_TXT);\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nnew file mode 100755\nindex 0000000000..5767e7e456\n--- /dev/null\n+++ b/Documentation/lint-man-section-order.perl\n@@ -0,0 +1,125 @@\n+#!/usr/bin/perl\n+\n+use strict;\n+use warnings;\n+\n+my %SECTIONS;\n+{\n+\tmy $order = 0;\n+\t%SECTIONS = (\n+\t\t'NAME' => {\n+\t\t\trequired => 1,\n+\t\t\torder => $order++,\n+\t\t},\n+\t\t'SYNOPSIS' => {\n+\t\t\trequired => 1,\n+\t\t\torder => $order++,\n+\t\t},\n+\t\t'DESCRIPTION' => {\n+\t\t\trequired => 1,\n+\t\t\torder => $order++,\n+\t\t\tbad => {\n+\t\t\t\t'git-mktag.txt' => 'OPTIONS',\n+\t\t\t\t'git-cvsserver.txt' => 'OPTIONS',\n+\t\t\t},\n+\t\t},\n+\t\t'OPTIONS' => {\n+\t\t\torder => $order++,\n+\t\t\trequired => 0,\n+\t\t\tbad => {\n+\t\t\t\t'git-grep.txt' => 'CONFIGURATION',\n+\t\t\t\t'git-rebase.txt' => 'CONFIGURATION',\n+\t\t\t},\n+\t\t},\n+\t\t'CONFIGURATION' => {\n+\t\t\torder => $order++,\n+\t\t\tbad => {\n+\t\t\t\t'git-svn.txt' => 'BUGS',\n+\t\t\t},\n+\t\t},\n+\t\t'BUGS' => {\n+\t\t\torder => $order++,\n+\t\t},\n+\t\t'SEE ALSO' => {\n+\t\t\torder => $order++,\n+\t\t},\n+\t\t'GIT' => {\n+\t\t\trequired => 1,\n+\t\t\torder => $order++,\n+\t\t},\n+\t);\n+}\n+my $SECTION_RX = do {\n+\tmy ($names) = join \"|\", keys %SECTIONS;\n+\tqr/^($names)$/s;\n+};\n+\n+my $exit_code = 0;\n+sub report {\n+\tmy ($msg) = @_;\n+\tprint \"$ARGV:$.: $msg\\n\";\n+\t$exit_code = 1;\n+}\n+\n+my $last_was_section;\n+my @actual_order;\n+while (my $line = <>) {\n+\tchomp $line;\n+\tif ($line =~ $SECTION_RX) {\n+\t\tpush @actual_order => $line;\n+\t\t$last_was_section = 1;\n+\t\t# Have no \"last\" section yet, processing NAME\n+\t\tnext if @actual_order == 1;\n+\n+\t\tmy @expected_order = sort {\n+\t\t\t$SECTIONS{$a}->{order} <=> $SECTIONS{$b}->{order}\n+\t\t} @actual_order;\n+\n+\t\tmy $expected_last = $expected_order[-2];\n+\t\tmy $actual_last = $actual_order[-2];\n+\t\tmy $except_last = $SECTIONS{$line}->{bad}->{$ARGV} || '';\n+\t\tif (($SECTIONS{$line}->{bad}->{$ARGV} || '') eq $actual_last) {\n+\t\t\t# Either we're whitelisted, or ...\n+\t\t\tnext\n+\t\t} elsif (exists $SECTIONS{$actual_last}->{bad}->{$ARGV}) {\n+\t\t\t# ... we're complaing about the next section\n+\t\t\t# which is out of order because this one is,\n+\t\t\t# don't complain about that one.\n+\t\t\tnext;\n+\t\t} elsif ($actual_last ne $expected_last) {\n+\t\t\treport(\"section '$line' incorrectly ordered, comes after '$actual_last'\");\n+\t\t}\n+\t\tnext;\n+\t}\n+\tif ($last_was_section) {\n+\t\tmy $last_section = $actual_order[-1];\n+\t\tif (length $last_section ne length $line) {\n+\t\t\treport(\"dashes under '$last_section' should match its length!\");\n+\t\t}\n+\t\tif ($line !~ /^-+$/) {\n+\t\t\treport(\"dashes under '$last_section' should be '-' dashes!\");\n+\t\t}\n+\t\t$last_was_section = 0;\n+\t}\n+\n+\tif (eof) {\n+\t\t# We have both a hash and an array to consider, for\n+\t\t# convenience\n+\t\tmy %actual_sections;\n+\t\t@actual_sections{@actual_order} = ();\n+\n+\t\tfor my $section (sort keys %SECTIONS) {\n+\t\t\tnext if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};\n+\t\t\treport(\"has no required '$section' section!\");\n+\t\t}\n+\n+\t\t# Reset per-file state\n+\t\t{\n+\t\t\t@actual_order = ();\n+\t\t\t# this resets our $. for each file\n+\t\t\tclose ARGV;\n+\t\t}\n+\t}\n+}\n+\n+exit $exit_code;\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421405","messageId":"patch-5.7-e3af1a9405-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 5/7] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:48Z","receivedAt":"2021-04-09T15:03:24Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Lint for and fix the three manual pages that were missing the standard\n\"Part of the linkgit:git[1] suite\" end section.\n\nWe only do this for the man[157] section documents (we don't have\nanything outside those sections), not files to be included,\nhowto *.txt files etc.\n\nWe could also add this to the existing (and then renamed)\nlint-gitlink.perl, but I'm not doing that here.\n\nObviously all of that fits in one script, but I think for something\nlike this that's a one-off script with global variables it's much\nharder to follow when a large part of your script is some if/else or\nkeeping/resetting of state simply to work around the script doing two\nthings instead of one.\n\nEspecially because in this case this script wants to process the file\nas one big string, but lint-gitlink.perl wants to look at it one line\nat a time. We could also consolidate this whole thing and\nt/check-non-portable-shell.pl, but that one likes to join lines as\npart of its shell parsing.\n\nSo let's just add another script, whole scaffolding is basically:\n\n use strict;\n use warnings;\n sub report { ... }\n my $code = 0;\n while (<>) { ... }\n exit $code;\n\nWe'd spend more lines effort trying to consolidate them than just\ncopying that around.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 3 ++-\n Documentation/git-credential.txt | 4 ++++\n Documentation/git-p4.txt | 4 ++++\n Documentation/gitnamespaces.txt | 4 ++++\n Documentation/lint-man-end-blurb.perl | 24 ++++++++++++++++++++++++\n 5 files changed, 38 insertions(+), 1 deletion(-)\n create mode 100755 Documentation/lint-man-end-blurb.perl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex de55c4ecf5..34b4f5716a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -482,7 +482,8 @@ lint-docs::\n \t\t$(HOWTO_TXT) $(DOC_DEP_TXT) \\\n \t\t--section=1 $(MAN1_TXT) \\\n \t\t--section=5 $(MAN5_TXT) \\\n-\t\t--section=7 $(MAN7_TXT)\n+\t\t--section=7 $(MAN7_TXT); \\\n+\t$(PERL_PATH) lint-man-end-blurb.perl $(MAN_TXT)\n \n ifeq ($(wildcard po/Makefile),po/Makefile)\n doc-l10n install-l10n::\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 31c81c4c02..206e3c5f40 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -159,3 +159,7 @@ empty string.\n +\n Components which are missing from the URL (e.g., there is no\n username in the example above) will be left unset.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt\nindex f89e68b424..38e5257b2a 100644\n--- a/Documentation/git-p4.txt\n+++ b/Documentation/git-p4.txt\n@@ -762,3 +762,7 @@ IMPLEMENTATION DETAILS\n message indicating the p4 depot location and change number. This\n line is used by later 'git p4 sync' operations to know which p4\n changes are new.\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt\nindex b614969ad2..1c8d2ecc35 100644\n--- a/Documentation/gitnamespaces.txt\n+++ b/Documentation/gitnamespaces.txt\n@@ -62,3 +62,7 @@ git clone ext::'git --namespace=foo %s /tmp/prefixed.git'\n ----------\n \n include::transfer-data-leaks.txt[]\n+\n+GIT\n+---\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/lint-man-end-blurb.perl b/Documentation/lint-man-end-blurb.perl\nnew file mode 100755\nindex 0000000000..d69312e5db\n--- /dev/null\n+++ b/Documentation/lint-man-end-blurb.perl\n@@ -0,0 +1,24 @@\n+#!/usr/bin/perl\n+\n+use strict;\n+use warnings;\n+\n+my $exit_code = 0;\n+sub report {\n+\tmy ($target, $msg) = @_;\n+\tprint \"error: $target: $msg\\n\";\n+\t$exit_code = 1;\n+}\n+\n+local $/;\n+while (my $slurp = <>) {\n+\treport($ARGV, \"has no 'Part of the linkgit:git[1] suite' end blurb\")\n+\t\tunless $slurp =~ m[\n+\t\t^GIT\\n\n+\t\t ---\\n\n+\t\t\\QPart of the linkgit:git[1] suite\\E \\n\n+\t\t\\z\n+\t]mx;\n+}\n+\n+exit $exit_code;\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421406","messageId":"patch-7.7-9cb100826e-20210409T145728Z-avarab@gmail.com","threadId":"55390","inReplyTo":"cover-0.7-0000000000-20210409T145728Z-avarab@gmail.com","subject":"[PATCH v2 7/7] docs: fix linting issues due to incorrect relative section order","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-04-09T15:02:50Z","receivedAt":"2021-04-09T15:03:25Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Re-order the sections of a few manual pages to be consistent with the\nentirety of the rest of our documentation. This allows us to remove\nthe just-added whitelist of \"bad\" order from\nlint-man-section-order.perl.\n\nI'm doing that this way around so that code will be easy to dig up if\nwe'll need it in the future. I've intentionally not added some other\nsections such as EXAMPLES to the list of known sections.\n\nIf we were to add that we'd find some out of order. Perhaps we'll want\nto order those consistently as well in the future, at which point\nwhitelisting some of them might become handy again.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-cvsserver.txt | 24 ++++-----\n Documentation/git-grep.txt | 64 +++++++++++------------\n Documentation/git-mktag.txt | 16 +++---\n Documentation/git-rebase.txt | 12 ++---\n Documentation/git-svn.txt | 38 +++++++-------\n Documentation/lint-man-section-order.perl | 22 +-------\n 6 files changed, 78 insertions(+), 98 deletions(-)\n\ndiff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt\nindex 1b1c71ad9d..f2e4a47ebe 100644\n--- a/Documentation/git-cvsserver.txt\n+++ b/Documentation/git-cvsserver.txt\n@@ -24,6 +24,18 @@ Usage:\n [verse]\n 'git-cvsserver' [] [pserver|server] [ ...]\n \n+DESCRIPTION\n+-----------\n+\n+This application is a CVS emulation layer for Git.\n+\n+It is highly functional. However, not all methods are implemented,\n+and for those methods that are implemented,\n+not all switches are implemented.\n+\n+Testing has been done using both the CLI CVS client, and the Eclipse CVS\n+plugin. Most functionality works fine with both of these clients.\n+\n OPTIONS\n -------\n \n@@ -57,18 +69,6 @@ access still needs to be enabled by the `gitcvs.enabled` config option\n unless `--export-all` was given, too.\n \n \n-DESCRIPTION\n------------\n-\n-This application is a CVS emulation layer for Git.\n-\n-It is highly functional. However, not all methods are implemented,\n-and for those methods that are implemented,\n-not all switches are implemented.\n-\n-Testing has been done using both the CLI CVS client, and the Eclipse CVS\n-plugin. Most functionality works fine with both of these clients.\n-\n LIMITATIONS\n -----------\n \ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 4e0ba8234a..3d393fbac1 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -38,38 +38,6 @@ are lists of one or more search expressions separated by newline\n characters. An empty string as search expression matches all lines.\n \n \n-CONFIGURATION\n--------------\n-\n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n-\n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n-\n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n-\t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will return to the default matching behavior.\n-\n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n-\toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n-\n-grep.threads::\n-\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n-\tuse as many threads as the number of logical cores available.\n-\n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n-\n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to git grep --no-index if git grep\n-\tis executed outside of a git repository. Defaults to false.\n-\n-\n OPTIONS\n -------\n --cached::\n@@ -363,6 +331,38 @@ with multiple threads might perform slower than single threaded if `--textconv`\n is given and there're too many text conversions. So if you experience low\n performance in this case, it might be desirable to use `--threads=1`.\n \n+CONFIGURATION\n+-------------\n+\n+grep.lineNumber::\n+\tIf set to true, enable `-n` option by default.\n+\n+grep.column::\n+\tIf set to true, enable the `--column` option by default.\n+\n+grep.patternType::\n+\tSet the default matching behavior. Using a value of 'basic', 'extended',\n+\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n+\t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n+\tvalue 'default' will return to the default matching behavior.\n+\n+grep.extendedRegexp::\n+\tIf set to true, enable `--extended-regexp` option by default. This\n+\toption is ignored when the `grep.patternType` option is set to a value\n+\tother than 'default'.\n+\n+grep.threads::\n+\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n+\tuse as many threads as the number of logical cores available.\n+\n+grep.fullName::\n+\tIf set to true, enable `--full-name` option by default.\n+\n+grep.fallbackToNoIndex::\n+\tIf set to true, fall back to git grep --no-index if git grep\n+\tis executed outside of a git repository. Defaults to false.\n+\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt\nindex 17a2603a60..466a697519 100644\n--- a/Documentation/git-mktag.txt\n+++ b/Documentation/git-mktag.txt\n@@ -11,14 +11,6 @@ SYNOPSIS\n [verse]\n 'git mktag'\n \n-OPTIONS\n--------\n-\n---strict::\n-\tBy default mktag turns on the equivalent of\n-\tlinkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to\n-\tdisable it.\n-\n DESCRIPTION\n -----------\n \n@@ -45,6 +37,14 @@ the appropriate `fsck.` varible:\n \n git -c fsck.extraHeaderEntry=ignore mktag ::\n@@ -1266,6 +1260,12 @@ merge tlsv1.3\n merge cmake\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::config/rebase.txt[]\n+include::config/sequencer.txt[]\n+\n BUGS\n ----\n The todo list presented by the deprecated `--preserve-merges --interactive`\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 67b143cc81..d5776ffcfd 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -1061,25 +1061,6 @@ with different name spaces. For example:\n \tbranches = stable/*:refs/remotes/svn/stable/*\n \tbranches = debug/*:refs/remotes/svn/debug/*\n \n-BUGS\n-----\n-\n-We ignore all SVN properties except svn:executable. Any unhandled\n-properties are logged to $GIT_DIR/svn//unhandled.log\n-\n-Renamed and copied directories are not detected by Git and hence not\n-tracked when committing to SVN. I do not plan on adding support for\n-this as it's quite difficult and time-consuming to get working for all\n-the possible corner cases (Git doesn't do it, either). Committing\n-renamed and copied files is fully supported if they're similar enough\n-for Git to detect them.\n-\n-In SVN, it is possible (though discouraged) to commit changes to a tag\n-(because a tag is just a directory copy, thus technically the same as a\n-branch). When cloning an SVN repository, 'git svn' cannot know if such a\n-commit to a tag will happen in the future. Thus it acts conservatively\n-and imports all SVN tags as branches, prefixing the tag name with 'tags/'.\n-\n CONFIGURATION\n -------------\n \n@@ -1166,6 +1147,25 @@ $GIT_DIR/svn/\\**/.rev_map.*::\n if it is missing or not up to date. 'git svn reset' automatically\n rewinds it.\n \n+BUGS\n+----\n+\n+We ignore all SVN properties except svn:executable. Any unhandled\n+properties are logged to $GIT_DIR/svn//unhandled.log\n+\n+Renamed and copied directories are not detected by Git and hence not\n+tracked when committing to SVN. I do not plan on adding support for\n+this as it's quite difficult and time-consuming to get working for all\n+the possible corner cases (Git doesn't do it, either). Committing\n+renamed and copied files is fully supported if they're similar enough\n+for Git to detect them.\n+\n+In SVN, it is possible (though discouraged) to commit changes to a tag\n+(because a tag is just a directory copy, thus technically the same as a\n+branch). When cloning an SVN repository, 'git svn' cannot know if such a\n+commit to a tag will happen in the future. Thus it acts conservatively\n+and imports all SVN tags as branches, prefixing the tag name with 'tags/'.\n+\n SEE ALSO\n --------\n linkgit:git-rebase[1]\ndiff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl\nindex 5767e7e456..b05f9156dd 100755\n--- a/Documentation/lint-man-section-order.perl\n+++ b/Documentation/lint-man-section-order.perl\n@@ -18,24 +18,13 @@\n \t\t'DESCRIPTION' => {\n \t\t\trequired => 1,\n \t\t\torder => $order++,\n-\t\t\tbad => {\n-\t\t\t\t'git-mktag.txt' => 'OPTIONS',\n-\t\t\t\t'git-cvsserver.txt' => 'OPTIONS',\n-\t\t\t},\n \t\t},\n \t\t'OPTIONS' => {\n \t\t\torder => $order++,\n \t\t\trequired => 0,\n-\t\t\tbad => {\n-\t\t\t\t'git-grep.txt' => 'CONFIGURATION',\n-\t\t\t\t'git-rebase.txt' => 'CONFIGURATION',\n-\t\t\t},\n \t\t},\n \t\t'CONFIGURATION' => {\n \t\t\torder => $order++,\n-\t\t\tbad => {\n-\t\t\t\t'git-svn.txt' => 'BUGS',\n-\t\t\t},\n \t\t},\n \t\t'BUGS' => {\n \t\t\torder => $order++,\n@@ -77,16 +66,7 @@ sub report {\n \n \t\tmy $expected_last = $expected_order[-2];\n \t\tmy $actual_last = $actual_order[-2];\n-\t\tmy $except_last = $SECTIONS{$line}->{bad}->{$ARGV} || '';\n-\t\tif (($SECTIONS{$line}->{bad}->{$ARGV} || '') eq $actual_last) {\n-\t\t\t# Either we're whitelisted, or ...\n-\t\t\tnext\n-\t\t} elsif (exists $SECTIONS{$actual_last}->{bad}->{$ARGV}) {\n-\t\t\t# ... we're complaing about the next section\n-\t\t\t# which is out of order because this one is,\n-\t\t\t# don't complain about that one.\n-\t\t\tnext;\n-\t\t} elsif ($actual_last ne $expected_last) {\n+\t\tif ($actual_last ne $expected_last) {\n \t\t\treport(\"section '$line' incorrectly ordered, comes after '$actual_last'\");\n \t\t}\n \t\tnext;\n-- \n2.31.1.622.g1b8cc22e65\n\n"},{"id":"421516","messageId":"xmqq4kgelqrt.fsf@gitster.g","threadId":"55390","inReplyTo":"87lf9rhe4y.fsf@evledraar.gmail.com","subject":"Re: [PATCH 5/5] doc lint: lint and fix missing \"GIT\" end sections","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-04-10T04:14:46Z","receivedAt":"2021-04-10T04:14:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> It adds the value of:\n>\n> * If you're looking at e.g. git-subtree's manpage it doesn't have it,\n> so we're clearly marking things that are part of git itself, also if\n> you're doing e.g. \"man git-annex\" (or other non-git.git tool)\n> somewhere.\n>\n> * Once you're at the bottom of a manpage in e.g. a web view it's a\n> handy link back to the start, see\n> e.g. https://git-scm.com/docs/git-add#_git\n\nOK, that's fair enough.\n\nThanks for a clarification.\n\n"}]}