Status report: asciidoc & asciidoctor

[Edward K. Ream]

I am now turning my attention to support for asciidoc.  This page shows the relevant issues.

This post discusses recent work, and what remains to be done.

Three tools, one markup language, one Leo command

asciidoc & asciidoc3 are python tools.  Apparently, asciidoc is python 2 only.

asciidoctor is a ruby tool, claiming to be 100 times faster than asciidoc.

The asciidoc markup language is virtually identical, regardless of the tool used.  The asciidoc markup language is very powerful.  Users can specify almost any conceivable option.  For full details, see the users guide.

Leo's new adoc command processes one or more @adoc trees, writing .adoc files that can then be converted to .html files using asciidoctor or asciidoc3. The command's docstring shows an @button script that will generate .html files from the written files. I have been using asciidoctor in my initial tests.  Still to do: verify that asciidoc3 works.

Syntax coloring

Leo now has rudimentary support for syntax coloring when @language asciidoc is in effect.

This page lists support for asciidoc markup in various editors.  My present plan is to regenerate leo/modes/asciidoc.py from asciidoc.xml using the @button jEdit2Py in scripts.leo.

Unlike markdown, it is not possible to embed raw html in asciidoc. This can reasonably be called a good thing. It greatly simplifies syntax coloring.

Asciidoc markup vs markdown and rST

Asciidoc markup is significantly better than markdown, but markdown is a straw man.  The real comparison must be between asciidoc and rST.  Imo, asciidoc is still clearly better than rST.

Furthermore, the asciidoc tool chain is likely more flexible than rST/docutils.  Asciidoc markup contains a lot of options.

adoc command vs rst3 command

The rst3 command is ridiculously complex.   I learned my lesson.  The adoc command is much, much simpler.  Users of the adoc command will use asciidoc (markup) options exclusively.

Like the rst3 command, the adoc command understands the structure of Leo outlines. That is, the adoc command will generate asciidoc markup for sections based on outline level.

Using asciidoc markup without the adoc command

It would be possible to generate .adoc files directly from Leo, but there is a big complication. Asciidoc cross references look like a Leo section references. So if your content contains cross references, you must use @asis files.

#1366 suggests disabling section references within .adoc files, or possibly even when @nosections is in effect.  This is a low priority project, because users can use the adoc command applied to @adoc trees. It probably won't happen.

Live rendering

#333 suggests rending sphinx or asciidoc live in the VR pane.  I'll be investigating this item soon.

For now, you can use Asciidoctor.js.  I use the Live Preview extension for mozilla. 

Summary

Supporting asciidoc markup is the last major project before releasing Leo 6.1 b1. This page summarizes the remaining work.

Leo now contains rudimentary support for @language asciidoc. It will soon be substantially improved.

The new adoc command processes one or more @adoc trees, writing .adoc files. @button nodes can easily convert the

.adoc files to .html files using asciidoctor or asciidoc3.

Live rendering is possible now, using Asciidoctor.js.  It may soon be possible within the VR pane.

Leo 6.1 is a full month ahead of schedule.  I'll take as long as needed to complete all asciidoc projects scheduled for 6.1.

Edward

[Edward K. Ream]

On Friday, October 4, 2019 at 8:26:47 AM UTC-5, Edward K. Ream wrote:

> [Leo's support] for @language asciidoc...will soon be substantially improved.

Done.  #1253 is now complete.

Edward

[Offray Vladimir Luna Cárdenas]

Hi,

On 4/10/19 8:26 a. m., Edward K. Ream wrote:

Asciidoc markup vs markdown and rST

Asciidoc markup is significantly better than markdown, but markdown is a straw man.  The real comparison must be between asciidoc and rST.  Imo, asciidoc is still clearly better than rST.

Totally agree. Almost nobody uses plain Markdown anymore, but some extension in the lines of CommonMark[1]. Pandoc[2] for me is still unbeatable as a light extensible markup language for structured documentation. I really like AsciiDoc, but Pandoc's author makes a really good point about readability of Pandoc's Markdown over AsciiDoc[3]. In my own case, I have enjoyed already the Pandoc's capabilities for academic writing and its extensibility via filters, which enable us to create, at the local hackerspace, customized Markdown for our own workflows, including custom call outs, Font Awesome support and a pretty good printing/PDF output[4].

[1] https://commonmark.org/
[2] https://pandoc.org/
[3] https://news.ycombinator.com/item?id=9206755
[4] https://mutabit.com/repos.fossil/documentaton/uv/es/documentaton-0-2-x-breve.pdf

Cheers,

Offray

[Edward K. Ream]

On Fri, Oct 4, 2019 at 10:18 AM Offray Vladimir Luna Cárdenas <off...@riseup.net> wrote:

>> Asciidoc markup is significantly better than markdown, but markdown is a straw man.  The real comparison must be between asciidoc and rST.  Imo, asciidoc is still clearly better than rST.

> Pandoc[2] for me is still unbeatable as a light extensible markup language for structured documentation. I really like AsciiDoc, but Pandoc's author makes a really good point about readability of Pandoc's Markdown over AsciiDoc[3].

This has just now become timely.  Within Leo, it looks like accessing (using) pandoc (the haskell tool) is no different from accessing asciidoc3 (the python tool) or asciidoctor (the ruby tool).  I'll say more about this in a separate thread.

Edward