Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`

From: Jeff King <peff@peff.net>
Date: Mar 19, 2019, 02:59 UTC
Message-ID: <20190319025945.GB6173@sigill.intra.peff.net>
In-Reply-To: <20190319024645.GA6173@sigill.intra.peff.net>

On Mon, Mar 18, 2019 at 10:46:46PM -0400, Jeff King wrote:

Show 11 quoted lines

> > Let's instead try to stay as close as possible to what asciidoc.conf
> > does. We'll make it fairly obvious that we aim to inject the exact same
> > three lines of `<refmiscinfo/>` that asciidoc.conf provides. The only
> > somewhat tricky part is that we inject them *post*-processing so we need
> > to do the variable expansion ourselves.
> 
> One thing that asciidoctor buys us that asciidoc does not is that we
> might eventually move to directly generating the manpages, without the
> XML / Docbook step in between. And if we do, then all of this XML
> hackery is going to have to get replaced with something else. I guess we
> can cross that bridge when we come to it.

I see there was some discussion of that in the side-thread, too. Just to give my two cents: I think that's where we want to go eventually, but I also think that while we are maintaining a dual asciidoc/asciidoctor tool chain, it's probably crazy not to go through docbook, just because it keeps so much of the pipeline the same for both tools.

So in my mind, the endgame is that we eventually drop asciidoc in favor of asciidoctor. The repo at:

  https://github.com/asciidoc/asciidoc

says:

  NOTE: This implementation is written in Python 2, which EOLs in Jan
  2020. AsciiDoc development is being continued under @asciidoctor.

I'm not sure when is the right time to switch. If we can get the output at parity, I don't think asciidoctor is too onerous to install (and we don't have to worry about ancient platforms, as they can use pre-formatted manpages).

-Peff