On Tue, 11 May 2021 at 11:04, Jean-Noël Avila <avila.jn@xxxxxxxxx> wrote: > > 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 We used to be in a situation where Asciidoctor looked worse and the rendered versions were quite different. We've fixed up quite a few discrepancies by making some change that "happens" to be a noop with one engine but an improvement with the other. (That it just "happens" has sometimes been my feeling anyway.) Sometimes, we've been able to improve both by spotting a difference, so that's good. I would also expect that with more eyes on asciidoctor-built docs (because default) and fewer on the other, the non-default will start to degrade. > 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." Thanks for that quote. It's very enlightening. > FWIW, we are already using Asciidoctor for publishing the manpages to > https://git-scm.com Thank you for all your work on that site! Martin
