On Thu, Jan 05, 2017 at 11:05:29AM +0100, Lars Schneider wrote:
> > 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.