[migration] asciidoc_reader

[trammell]

If someone creates https://github.com/pelican-plugins/asciidoc-reader I can take a stab at migrating
code over from https://github.com/getpelican/pelican-plugins/tree/master/asciidoc_reader.

OK weird I see the asciidoc3 site refers to an asciidoc3_reader, but I don't see any source code for that.

OK I see this PR, looks like we need to consolidate some things.

Rough code at https://github.com/trammell/asciidoc-reader

[justinmayer]

Hey John. Many thanks for offering to help with consolidating the Asciidoc-related efforts into a new repository under the new Pelican Plugins organization. According to the asciidoc-py repo README, that project is a legacy implementation that doesn't handle the current Asciidoc specification. I don't know whether that is also true for Asciidoc3, which was last updated in 2021. Perhaps there isn't any Python-based tool that handles the current Asciidoc specification?

[trammell]

Yes, there are a number of asciidoc implementations, and it's not clear to me how complete any of them are, or which one would be best for integrating with Pelican, or indeed if any of them are adequate. What do you think?

(Dumping browser tab URLs here for future reference and/or lamentation)

• https://asciidoc.org/
• https://github.com/asciidoctor/asciidoc-grammar-prototype
• https://groups.google.com/g/asciidoc/
• https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang
• https://projects.eclipse.org/projects/asciidoc
• https://asciidoc3.org/
• https://github.com/asciidoc-py/asciidoc-py
• https://asciidoctor.org/

[justinmayer]

I have never used Asciidoc and am thus unfortunately ill-equipped to determine which parser/renderer would be best to use as the basis for a Pelican plugin.

Moreover, while there seem to be tools written in Ruby, Java, and JavaScript that support the current Asciidoc specification, I get the impression that none of the Python implementations support the current Asciidoc specification (as I mentioned above).

That being the case, I suppose the question is where would you like to start, and how far would you like to go? Do you have an interest in adding support for the latest Asciidoc specification to one of the existing Python implementations? Or is the goal to only support the older AsciiDoc.py syntax?

[wessven]

I use Asciidoc and can comment on a few things. Currently I use Asciidoctor with Pelican, but I would be happy if I could use a native Python solution and didn't need Ruby as a dependency (as required by Asciidoctor).

AsciiDoc

The first thing to say is that AsciiDoc, while open source, is now a registered trademark owned by the Eclipse Foundation. One of the appeals of AsciiDoc is that it doesn't suffer from the fragmentation of markdown languages, with different flavours and specifications. Unfortunately that began to happen: for various reasons Asciidoctor (which, at the time, was the only real actively maintained Asciidoc implementation) began to deviate from the original project (which had been abandoned).

To prevent further fragmentation, the people from Asciidoctor approached the Eclipse Foundation to create the AsciiDoc language specification.

Unless the specific project states otherwise, each of the options mentioned above which include "Asciidoctor" or "Eclipse" can be grouped, as they all ought to point to the official specification as owned by Eclipse.

It is my opinion that, if an effort is going to be made to integrate Asciidoc with any project, it needs to be a "flavour" which conforms to the official specification.

asciidoc-py

This is the old and original asciidoc-py implementation. It is being maintained, but does not seem to be actively developed. Indeed the website itself states that

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.

Therefore this should not be a serious contender for inclusion in a new project or development.

AsciiDoc3

This is probably the best and most actively maintained pure Python implementation of "AsciiDoc". It got a new release last month, and a new release is planned for over the next couple of months. The project acknowledges that the official AsciiDoc specification, and they have "signed up for it", but as far as I am aware it still mostly uses the old syntax. I could (and I hope that I am) wrong. I'll check out the new version (which they promise to be a significant update) when it gets released.

AsciiDoc3 has joined the [Eclipse Foundation Specification Process] but it is too early to rate this process. We’ll see in the next months what happens and shall report from time to time.

---

So I would say that the decision comes down to AsciiDoc3, which is available and being actively maintained, but not conformant to the official specification, and the official AsciiDoc, which (as far as I am aware) currently doesn't have a pure native Python implementation (I am only aware of the Asciidoctor implementation).

[justinmayer]

Thanks for the detailed comment, @wessven. My inclination is to use the Python-based AsciiDoc3 implementation for now, with the hope that someday in the future there will be a Python-powered option that supports the specification now managed by Eclipse.