Re: [RFC suggestion] Generate manpage directly with Asciidoctor

[Jeff King <peff@peff.net>]

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

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