ci: validate "linkgit:" 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 <gitster@pobox.com>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3e39e2815baca82fe5f1fff8791de37c3c7247ac..f6e288bc634cc9a7b231cac0a237a7770efd098f 100644 (file)
--- 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,7 @@ quick-install-html: require-htmlrepo
 print-man1:
        @for i in $(MAN1_TXT); do echo $$i; done
 
+lint-docs::
+       $(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
+
 .PHONY: FORCE

diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
new file mode 100755 (executable)
index 0000000..476cc30
--- /dev/null
+++ b/Documentation/lint-gitlink.perl
@@ -0,0 +1,71 @@
+#!/usr/bin/perl
+
+use File::Find;
+use Getopt::Long;
+
+my $basedir = ".";
+GetOptions("basedir=s" => \$basedir)
+       or die("Cannot parse command line arguments\n");
+
+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, "<", "$basedir/$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 "$basedir/$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;
+}
+
+sub lint_it {
+       lint($File::Find::name) if -f && /\.txt$/;
+}
+
+if (!@ARGV) {
+       find({ wanted => \&lint_it, no_chdir => 1 }, $basedir);
+} else {
+       for (@ARGV) {
+               lint($_);
+       }
+}
+
+exit $found_errors;

diff --git a/Makefile b/Makefile
index 2742a6977c6ad871897bc758ea2a7d76359b1eee..61bd0abad5e88ceee8e5b6a1814291fa0a0b3ea4 100644 (file)
--- 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 \