Re: [PATCH v4 1/2] Documentation: fix linkgit references

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> I do not think there is any false positive above, so perhaps the
> checker script below can be used as the link checker we discussed?

-- >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.sh.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 ci/lint-gitlink.sh | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100755 ci/lint-gitlink.sh

diff --git a/ci/lint-gitlink.sh b/ci/lint-gitlink.sh
new file mode 100755
index 0000000..2379626
--- /dev/null
+++ b/ci/lint-gitlink.sh
@@ -0,0 +1,47 @@
+#!/bin/sh
+
+git grep -l linkgit: Documentation/ |
+while read path
+do
+	perl -e '
+	sub report {
+		my ($where, $what, $error) = @_;
+		print "$where: $error: $what\n";
+	}
+
+	sub grab_section {
+		my ($page) = @_;
+		open my $fh, "<", "Documentation/$page.txt";
+		my $firstline = <$fh>;
+		chomp $firstline;
+		close $fh;
+		my ($section) = ($firstline =~ /.*\((\d)\)$/);
+		return $section;
+	}
+
+	while (<>) {
+		my $where = "$ARGV:$.";
+		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 "Documentation/$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;
+			}
+		}
+	}
+	' "$path"
+done
-- 
2.8.2-498-g6350fe8