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

From: Jeff King <peff@peff.net>
Date: May 4, 2016, 19:25 UTC
Message-ID: <20160504192516.GD21259@sigill.intra.peff.net>
In-Reply-To: <xmqqvb2thczf.fsf@gitster.mtv.corp.google.com>

On Wed, May 04, 2016 at 11:52:52AM -0700, Junio C Hamano wrote:

Show 18 quoted lines

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

It seems like this is something we _should_ be able to do while asciidoc is actually expanding the macro, rather than as a separate step. But:

  1. I don't think stock asciidoc has this much flexibility in its
     macros.

  2. There are some ordering questions (e.g., while building "foo.1",
     "bar.1" may not be built yet, so we still have to massage requests
     for "bar.1" into "bar.txt".

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; it would catch something like using "--" instead of "{litdd}".

Show 6 quoted lines

> +#!/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. :)

Besides being slightly more efficient (reading the files only once rather than filtering once via grep and then re-reading via perl). But more importantly, it avoids a layer of quoting, which makes it less likely to make a mistake by using single-quote in the perl script (I do not see any errors in what you wrote, though).

-Peff