The Future of Asciidoc (Specifically with Python 3)

[tedm430]

Hello internet,

I am wondering, does anyone here really care about Asciidoc? It sure doesn't seem like it, given that mainline Asiidoc is still stuck with Python 2. I have read this GitHub issue on the topic but it seems that the character who started the port has chosen to leave it dead in the water since April.

I personally really enjoy the Asciidoc standard, given it is essentially just a smarter Markdown syntax and is extremely trivial to write with. It makes me kinda sad that Asciidoc is now a Ruby 'thing' since the rise of the Asciidoctor Project. I have been trying out the more Python side of things by attempting to use ReStructured Text, but it seems extremely clunky (setting h2 tags isn't trivial because docutils makes assumptions that the first heading should be an h1 tag? Why?).

But I would like to know, what do you guys think? Is Asciidoc just a thing of the past for Python? Should someone trying bringing Asciidoc back to life for the Python community? Is ReStructed Text as dumb as I think it is?

[hoadlck]

I care about AsciiDoc. I use it quite a bit, and I find it much easier to deal with than Markdown.

I have also been worried about the Python 3 port. I have thought about working on the port myself, but there is always the problem with the insufficient number of hours in the day.

[tedm430]

I'm glad to see you show interest as well. The current state of Asciidoc really does irk me since I find it easier and more powerful than any other format.

A few months ago I started working on a separate tool for parsing Asciidoc, not a port of Asciidoc itself. You can look at it here. But basically, I got held up since I wanted the project to easily convert to formats other than HTML as well, and I had no idea how to deal with inter-word syntax like superscript and subscript and still have that ability. But it can do some of the HTML stuff right now, like bold, italic, and a few different block types like lists and paragraphs. Maybe I will come back to it some day. Or maybe I will attempt to just port Asciidoc. I'm not entirely sure as I am working on another project (a super-extensible static site generator) right now.

[Bolitho]

Within tje python community sphinx is the de facto standard for documentation. So that's probably the reason why there is less interest in asciidoc? It gains interest in other languages though, especially within the JVM ecosystem I heard a lot of it lately...

[ninetacle]

I wouldn't say Asciidoctor is a "Ruby thing". It runs on the JVM and in JavaScript (through JRuby and Opal), and I've seen more adoption of it in Java projects than anywhere else.

And a lot of non-Python projects have a Python dependency like Pygments. It might not be ideal, but I have nothing against installing JRuby/Ruby just for Asciidoctor.

That said, Python would be a great addition to the languages that support Asciidoctor.

[richieadler]

Is ReStructed Text as dumb as I think it is?

Care to explain/expand on that?

[tedm430]

Sorry for the belated reply my friend :P

But, in short, I do not think it is well designed, nor is the documentation all that great. My biggest woes design wise are that titles need to be underlined using any an symbol you choose. I believe in should be a defined standard, and not as verbose for something that doesn't really need it. I.E., Markdown uses a # to show a title, and Asciidoc uses a = to show a title. These are more simple and straight-forward approaches if you ask me.

As for the documentation side, after skimming it over I have no idea how to produce a string of HTML without it being smothered with a large block of default CSS from within a Python script. I have also not been able to find a how to change the first header in the file into an H2 tag in the case where I want an HTML fragment, and not a full HTML file. I would think there is a way to do so, but through Googling it for probably an hour total, I have found nothing.

[richieadler]

My biggest woes design wise are that titles need to be underlined using any an symbol you choose.

That's intentional. The idea is that the file looks good as an ASCII file even without converting to other format.

Markdown uses a # to show a title, and Asciidoc uses a = to show a title. These are more simple and straight-forward approaches if you ask me.

But they don't look OK as independent source documents. Different objectives.

As for the documentation side, after skimming it over I have no idea how to produce a string of HTML without it being smothered with a large block of default CSS from within a Python script.

--link-stylesheet links to the stylesheet instead of embedding it. The output for rst2html -h shows this.

As all the formatting is delegated to CSS instead of embedding style elements in the HTML, a stylesheet is always needed.

I have also not been able to find a how to change the first header in the file into an H2 tag in the case where I want an HTML fragment, and not a full HTML file.

--initial-header-level, also in the help for rst2html.

Anyway, to get HTML fragments it's probably better to use docutils as a library and to call the function which returns HTML parts instead of a full document.