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 <gits...@pobox.com>
---
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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
