From: Junio C Hamano <gitster@pobox.com>
To: Jeff King <peff@peff.net>
Cc: Lars Schneider <larsxschneider@gmail.com>,
Ramsay Jones <ramsay@ramsayjones.plus.com>,
git@vger.kernel.org, Matthieu.Moy@grenoble-inp.fr,
sbeller@google.com
Subject: Re: [PATCH v4 1/2] Documentation: fix linkgit references
Date: Wed, 04 May 2016 12:57:31 -0700 [thread overview]
Message-ID: <xmqq7ff9h9zo.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <20160504192516.GD21259@sigill.intra.peff.net> (Jeff King's message of "Wed, 4 May 2016 15:25:16 -0400")
Jeff King <peff@peff.net> writes:
> Likewise, I think we could build the whole HTML source and then actually
> just look for broken links in it. But that script would probably end up
> looking similar to this one, with s/linkgit/href/. But it does more
> directly measure what we want, which is that the rendered doc is usable;
I debated about this myself, but chose to inspect the source
material, as that approach is easier to give actionable lint output
to the user that points out the file:lineno to be corrected.
> it would catch something like using "--" instead of "{litdd}".
That is true indeed. With the "source" approach, that would indeed
be harder.
>> +#!/bin/sh
>> +
>> +git grep -l linkgit: Documentation/ |
>> +while read path
>> +do
>> + perl -e '
>
> Is it worth just making this a perl script, rather than a shell script
> with a giant inline perl script? Perl is actually really good at doing
> that "grep" as it reads the file. :)
OK.
-- >8 --
From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 4 May 2016 11:48:06 -0700
Subject: [PATCH v2] 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".
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
ci/lint-gitlink | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 60 insertions(+)
create mode 100755 ci/lint-gitlink
diff --git a/ci/lint-gitlink b/ci/lint-gitlink
new file mode 100755
index 0000000..bb73e89
--- /dev/null
+++ b/ci/lint-gitlink
@@ -0,0 +1,60 @@
+#!/usr/bin/perl
+
+use File::Find;
+
+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, "<", "Documentation/$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 "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;
+ }
+ }
+ }
+ close $fh;
+}
+
+sub lint_it {
+ lint($File::Find::name) if -f;
+}
+
+find({ wanted => \&lint_it, no_chdir => 1 }, "Documentation");
+
+exit $found_errors;
--
2.8.2-498-g6350fe8
next prev parent reply other threads:[~2016-05-04 19:57 UTC|newest]
Thread overview: 53+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-04-29 9:35 [PATCH v2] travis-ci: build documentation larsxschneider
2016-04-29 12:14 ` Jeff King
2016-04-29 12:21 ` Matthieu Moy
2016-04-29 14:22 ` Lars Schneider
2016-04-29 14:32 ` Jeff King
2016-04-29 17:27 ` Stefan Beller
2016-04-29 17:53 ` Matthieu Moy
2016-04-29 20:44 ` Lars Schneider
2016-04-29 21:05 ` Junio C Hamano
2016-05-02 20:20 ` [PATCH v3 0/2] " larsxschneider
2016-05-02 20:20 ` [PATCH v3 1/2] Documentation: fix linkgit references larsxschneider
2016-05-02 20:34 ` Jeff King
2016-05-03 8:30 ` Lars Schneider
2016-05-03 15:41 ` Junio C Hamano
2016-05-03 17:59 ` Jeff King
2016-05-03 17:58 ` Jeff King
2016-05-04 8:38 ` [PATCH v4 0/2] travis-ci: build documentation larsxschneider
2016-05-04 8:38 ` [PATCH v4 1/2] Documentation: fix linkgit references larsxschneider
2016-05-04 8:43 ` Lars Schneider
2016-05-04 8:57 ` Jeff King
2016-05-04 11:38 ` Ramsay Jones
2016-05-04 17:28 ` Junio C Hamano
2016-05-04 17:36 ` Junio C Hamano
2016-05-04 18:52 ` Junio C Hamano
2016-05-04 19:25 ` Jeff King
2016-05-04 19:57 ` Junio C Hamano [this message]
2016-05-04 20:06 ` Jeff King
2016-05-04 21:15 ` Junio C Hamano
2016-05-04 21:31 ` Jeff King
2016-05-04 21:34 ` Junio C Hamano
2016-05-04 21:44 ` Jeff King
2016-05-04 21:52 ` Junio C Hamano
2016-05-04 22:09 ` Jeff King
2016-05-04 22:17 ` Junio C Hamano
2016-05-04 22:27 ` Junio C Hamano
2016-05-04 23:28 ` Junio C Hamano
2016-05-04 23:41 ` Jeff King
2016-05-04 23:53 ` Jeff King
2016-05-04 21:54 ` Ævar Arnfjörð Bjarmason
2016-05-04 22:11 ` Jeff King
2016-05-04 8:38 ` [PATCH v4 2/2] travis-ci: build documentation larsxschneider
2016-05-10 17:12 ` Junio C Hamano
2016-05-13 6:26 ` Lars Schneider
2016-05-02 20:20 ` [PATCH v3 " larsxschneider
2016-05-02 20:45 ` Junio C Hamano
2016-05-03 8:12 ` Lars Schneider
2016-05-03 15:43 ` Junio C Hamano
2016-05-04 8:04 ` Lars Schneider
2016-05-04 8:18 ` Eric Wong
2016-05-04 8:19 ` Junio C Hamano
2016-05-04 9:11 ` Christian Couder
2016-05-04 11:27 ` Matthieu Moy
2016-04-29 14:40 ` [PATCH v2] " Matthieu Moy
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq7ff9h9zo.fsf@gitster.mtv.corp.google.com \
--to=gitster@pobox.com \
--cc=Matthieu.Moy@grenoble-inp.fr \
--cc=git@vger.kernel.org \
--cc=larsxschneider@gmail.com \
--cc=peff@peff.net \
--cc=ramsay@ramsayjones.plus.com \
--cc=sbeller@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).