Re: [PATCH v4 1/2] Documentation: fix linkgit references
From: Junio C Hamano <hidden>
Date: 2016-06-16 02:19:11
Subsystem:
documentation, kernel build + files below scripts/ (unless maintained elsewhere), the rest · Maintainers:
Jonathan Corbet, Nathan Chancellor, Nicolas Schier, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-16 · Re: [PATCH v4 1/2] Documentation: fix linkgit references · Jeff King <hidden>
- 2016-06-16 · Re: [PATCH v4 1/2] Documentation: fix linkgit references · Junio C Hamano <hidden>
- 2016-06-16 · Re: [PATCH v4 1/2] Documentation: fix linkgit references · Jeff King <hidden>
- 2016-06-16 · Re: [PATCH v4 1/2] Documentation: fix linkgit references · Junio C Hamano <hidden>
- 2016-06-16 · Re: [PATCH v4 1/2] Documentation: fix linkgit references · Jeff King <hidden>
Third time's a charm, perhaps? -- >8 -- Subject: [PATCH] ci: validate "gitlink:" in documentation It is easy to add incorrect "linkgit:<page>[<section>]" references to our documentation suite. Catch these common classes of errors: * Referring to Documentation/<page>.txt that does not exist. * Referring to a <page> outside the Git suite. In general, <page> must begin with "git". * Listing the manual <section> incorrectly. The first line of the Documentation/<page>.txt must end with "(<section>)". with a new script "ci/lint-gitlink", and drive it from "make check-docs". Signed-off-by: Junio C Hamano <redacted> --- Documentation/Makefile | 5 +++++ Makefile | 1 + ci/lint-gitlink | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+) create mode 100755 ci/lint-gitlink
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3e39e28..e9cd43d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile@@ -204,6 +204,7 @@ ifndef V QUIET_DBLATEX = @echo ' ' DBLATEX $@; QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; QUIET_GEN = @echo ' ' GEN $@; + QUIET_LINT = @echo ' ' LINT $@; QUIET_STDERR = 2> /dev/null QUIET_SUBDIR0 = +@subdir= QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \
@@ -427,4 +428,8 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done +lint-docs:: + $(QUIET_LINT)$(foreach txt,$(patsubst %.html,%.txt,$(DOC_HTML)), \ + ../ci/lint-gitlink $(txt)) + .PHONY: FORCE
diff --git a/Makefile b/Makefile
index 2742a69..61bd0ab 100644
--- a/Makefile
+++ b/Makefile@@ -2496,6 +2496,7 @@ ALL_COMMANDS += git-gui git-citool .PHONY: check-docs check-docs:: + $(MAKE) -C Documentation lint-docs @(for v in $(ALL_COMMANDS); \ do \ case "$$v" in \
diff --git a/ci/lint-gitlink b/ci/lint-gitlink
new file mode 100755
index 0000000..6b6bf91
--- /dev/null
+++ b/ci/lint-gitlink@@ -0,0 +1,56 @@ +#!/usr/bin/perl + +my $found_errors = 0; + +sub report { + my ($where, $what, $error) = @_; + print "$where: $error: $what\n"; + $found_errors = 1; +} + +sub grab_section { + my ($page) = @_; + open my $fh, "<", "$page.txt"; + my $firstline = <$fh>; + chomp $firstline; + close $fh; + my ($section) = ($firstline =~ /.*\((\d)\)$/); + return $section; +} + +sub lint { + my ($file) = @_; + open my $fh, "<", $file + or return; + while (<$fh>) { + my $where = "$file:$."; + while (s/linkgit:((.*?)\[(\d)\])//) { + my ($target, $page, $section) = ($1, $2, $3); + + # De-AsciiDoc + $page =~ s/{litdd}/--/g; + + if ($page !~ /^git/) { + report($where, $target, "nongit link"); + next; + } + if (! -f "$page.txt") { + report($where, $target, "no such source"); + next; + } + $real_section = grab_section($page); + if ($real_section != $section) { + report($where, $target, + "wrong section (should be $real_section)"); + next; + } + } + } + close $fh; +} + +for (@ARGV) { + lint($_); +} + +exit $found_errors;
--
2.8.2-498-g6350fe8