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

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Jan 7, 2017, 22:08 UTC
Message-ID: <20170107220834.uge5ksdr66asw27q@genre.crustytoothpaste.net>
In-Reply-To: <20170105164556.b3bzeqqzx4pvni4z@sigill.intra.peff.net>

On Thu, Jan 05, 2017 at 11:45:57AM -0500, Jeff King wrote:

Show 16 quoted lines

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

This is indeed the case. Asciidoctor is a bit stricter on some inputs because it provides significant performance improvements, but it also has features that AsciiDoc does not. It also has some bugs that AsciiDoc does not (again, usually due to performance concerns).

For example, Debian's reproducible builds project would probably like it if we had better support for Asciidoctor.

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.

Yes, that would probably be beneficial. I'll see if I can come up with some patches based on Dscho's work.

-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204