Re: [RFC suggestion] Generate manpage directly with Asciidoctor

[Jeff King <peff@peff.net>]

On Tue, May 11, 2021 at 08:45:10PM +0200, Martin Ågren wrote:

> > That does make things a little less convenient; Debian stable, for
> > instance, still has 1.5.8. It's not too hard to install an updated gem,
> > but not quite as nice as using the system package (it also makes things
> > weird for building the stable Debian package itself, which would want to
> > rely only on other packages; but of course any proposed change to the
> > doc toolchain would be for new versions, and would not get backported
> > there anyway).
> 
> Right. And 1.5.8 is perfectly fine for ascidoctor *with* xmlto, i.e., as
> long as we're discussing moving away from asciidoc, not moving away from
> xmlto entirely. And soon enough, Debian stable should be at 2.12. ;-)
> (I realize Debian stable was just an example.)

Debian stable is just an example, but I also consider it a bit of a
benchmark for "reasonable". Surely there are people running RHEL6
somewhere in this world, but it's hard to care too much about them.

I think the transition you're proposing would probably take a while to
do, too. If we don't drop the python asciidoc support until close to the
end, then that buys a bit more time. Likewise, this isn't a hard limit
for OS support for users. The worst case is just making things slightly
more inconvenient for Git developers on older systems, because because
they might have to install an updated gem rather than using the system
package (you sometimes can end up in dependency hell for a gem upgrade
with versions of ruby, system libraries, etc, but I haven't found
asciidoctor particularly needy in that respect).

So I dunno. I certainly don't have a big complaint about _starting_ the
transition. If we can hold on to python asciidoc support (or even
old-asciidoctor + xmlto) for a while as a fallback, even if we know it's
slowly bitrotting, then it's possible nobody would even complain.

-Peff