Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Jeff King <peff@peff.net>
Date: May 7, 2021, 22:19 UTC
Message-ID: <YJW81zNr5bgW+yVs@coredump.intra.peff.net>
In-Reply-To: <YJWiQH2nf0B14Zy7@camp.crustytoothpaste.net>

On Fri, May 07, 2021 at 08:25:36PM +0000, brian m. carlson wrote:

Show 9 quoted lines

> > So completely migrating to Asciidoctor can eliminate xmlto requirement
> > for generating manpage.
> > 
> > What do you think about above?
> 
> I didn't do this because it makes things very complicated in the
> Makefile and my goal was to minimize the needed changes and divergence.
> I'm not opposed to someone else doing it, but I expect it will be a
> bunch of work.

Yeah. In the period where we support both asciidoc and asciidoctor, using the same flow for both (even if it's suboptimal for asciidoctor) kept the complexity down.

I _thought_ the original asciidoc was marked as deprecated / unmaintained at some point. But it does seem to have gotten a few releases in the last year (it looks like maybe the python 2 version was EOL, but somebody decided to make the effort to port it to python 3?).

But I wouldn't be at all sad to just standardize on asciidoctor. I think we're at parity in terms of the output (thanks to lots of work from you and Martin over the past couple of years), and I've generally found it nicer to work with.

The only downside is that it may be available in fewer places (though I'd think that python vs ruby is not so different). IMHO it's OK to be aggressive about the doc toolchain requirements, because the fallback is always grabbing the preformatted roff or HTML pages that were generated on a different system.

-Peff