Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

From: Jeff King <peff@peff.net>
Date: Jan 5, 2017, 16:45 UTC
Message-ID: <20170105164556.b3bzeqqzx4pvni4z@sigill.intra.peff.net>
In-Reply-To: <1D7C66EA-E87A-4154-ACAC-8045D28477D2@gmail.com>

On Thu, Jan 05, 2017 at 11:05:29AM +0100, Lars Schneider wrote:

Show 7 quoted lines

> > The git-scm.com site uses asciidoctor, too, and I think I have seen some
> > oddness with the rendering though. So in general I am in favor of making
> > things work under both asciidoc and asciidoctor.
> 
> I am not familiar with both tools but it sounds to me as if "asciidoctor"
> is kind of the "lowest common denominator". Is this true? If yes, would it
> make sense to switch TravisCI [1] to asciidocter if this change gets merged?

I don't think that's quite true.

The two programs produce different output for certain inputs. We tend to see the cases where asciidoc produces the desired output and asciidoctor doesn't, because traditionally the documentation was written _for_ asciidoc. So whenever asciidoctor diverges, it looks like a bug.

If people start developing and checking their work using asciidoctor[1], then we'll see bugs going in the other direction.

As far as CI goes, I am not altogether convinced of the usefulness of building the documentation. It's very expensive, and the failure mode is rarely "whoops, running `make doc` failed". It's almost always that the output looks subtly wrong, but that's very hard to check automatically.

[1] I think we've also traditionally considered asciidoc to be the
    definitive toolchain, and people using asciidoctor are free to
    submit patches to make things work correctly in both places. I'm not
    opposed to changing that attitude, as it seems like asciidoctor is
    faster and more actively maintained these days. But I suspect our
    build chain would need some improvements. Last time I tried building
    with AsciiDoctor it involved a lot manual tweaking of Makefile
    variables. It sounds like Dscho is doing it regularly, though. It
    should probably work out of the box (with something like
    USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it.