Re: "docs: stop using asciidoc no-inline-literal" breaks asciidoc 8.2.5

[Jeff King <peff@peff.net>]

On Wed, May 30, 2012 at 12:42:32AM +0200, Ævar Arnfjörð Bjarmason wrote:

> Anyway, I've tested dropping asciidoc.py from the source distribution
> into compat/asciidoc.py and doing "make doc
> ASCIIDOC=../compat/asciidoc.py", it seems to work.
> 
> I wonder if the easiest solution is to change the default asciidoc
> invocation from "asciidoc" to a small Documentation/asciidoc.sh script
> that we supply, it would check if there's an asciidoc present on the
> system, whether it's sufficiently new, and if not fall back on a copy
> we have in compat/.

That makes me somewhat nervous. The asciidoc package on my system
contains 311 files. It seems probable that at least one of those files
beyond asciidoc.py is necessary for the system to work, and that it may
even depend on matching versions.

If we are going to go the route of providing an asciidoc for people
whose asciidoc is buggy, we might as well go all out and provide a
complete standalone asciidoc (or at least some subset) for those who
don't have it at all. Part of me finds that utterly gross, but part of
me likes the fact that we would be able to move our documentation and
our asciidoc interpreter in lockstep, which avoids some other bugs we
have seen in the past.  Of course, that doesn't help the rest of the
documentation toolchain (differing docbook versions have created
problems in the past, too).

I suppose the grossness would depend on how small a minimal asciidoc
distribution could be made (of those 311 files, many are documentation
and examples).

-Peff