Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Jeff King <peff@peff.net>
Date: May 11, 2021, 19:07 UTC
Message-ID: <YJrV52HOv0mlbJB1@coredump.intra.peff.net>
In-Reply-To: <CAN0heSp6uw7yqNZLD5w13xJUgnUtgHM0OYw9KQ6Z-FKk+x4OPA@mail.gmail.com>

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

Show 12 quoted lines

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