Re: [RFC suggestion] Generate manpage directly with Asciidoctor

["Jean-Noël Avila" <avila.jn@gmail.com>]

On 09/05/2021 at 10:20, Martin Ågren wrote :
>
> 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