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

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 7, 2017, 22:00 UTC
Message-ID: <xmqqfuku3504.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170105164556.b3bzeqqzx4pvni4z@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

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

I've seen "make doc" break for me when it works for other people, and if CI can check the formatting for various combinations of versions of toolchain components, it would have some value. But otherwise, I agree that "make doc" in CI would not give us as much benefit as we spend electricity on it.

If we are to make support for building with AsciiDoctor better, CI that does "make doc" with both AsciiDoc and AsciiDoctor might be of help---a "make it buildable with A" patch may accidentally break B and vice versa.

Show 10 quoted lines

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

I do not mind getting convinced to declare that we will swap the positions of these two documentation toolchains in some future date, and a good first step for it to happen would be an easier out-of-box experience.

Thanks.