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

[Jeff King <peff@peff.net>]

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

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

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