Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Jean-Noël Avila <avila.jn@gmail.com>
Date: May 11, 2021, 09:04 UTC
Message-ID: <0fd3182c-3805-ee1b-5a35-e0c9a67892ab@gmail.com>
In-Reply-To: <CAN0heSpN_ieGc2HJCvSsmUuEqS-GGPDcZHz=v2Z3hJY=Or_HMw@mail.gmail.com>

On 09/05/2021 at 10:20, Martin Ågren wrote :

Show 9 quoted lines

>
> I tend to think asciidoctor even renders our manpages *better* than
> asciidoc does. Not by a huge margin, but a few things here and there.
> Some time around the Python 2 EOL, I was about to propose flipping the
> default, but then I went to look up the asciidoc EOL schedule, and like
> you, I noticed that it was a lot more alive and kicking than I thought
> it was. So it's not so much "we should flip to avoid a bitrotting
> dependency" as it is "asciidoctor is arguably nicer" or "it's the way
> forward".

If we start to change the documentation format to "the way forward", we may soon end up with a format which is no longer handled by the legacy asciidoc.py

As stated on https://github.com/asciidoc-py/asciidoc-py :

"AsciiDoc.py is a legacy processor for this syntax, handling an older rendition of AsciiDoc. As such, this will not properly handle the current AsciiDoc specification. It is suggested that unless you specifically require the AsciiDoc.py toolchain, you should find a processor that handles the modern AsciiDoc syntax."

So, as soon as the asciidoc format formal specification will gain traction in the public, we can expect asciidoc to be abandoned for new projects and receive minimal maintenance only for compatibility with legacy documentation.

One argument in favor of Asciidoctor is that it's delivered "with batteries", meaning that you can generate manpages, html and even pdf with the same tool, without requiring secondary or even tertiary toolchains, which should ease usage on a broader range of platforms.

FWIW, we are already using Asciidoctor for publishing the manpages to https://git-scm.com

JN