[asciidoc-wg] Reasons to not use Asciidoc as a foundation for a software

[Jens von Pilgrim <developer@xxxxxxxxx>]

Hi,

I just saw Paul’s mail about the asciidoc-wg, which sounds very interesting. As some of you may know I organized a Birds Of Feather about Asciidoc at EclipseCon 2016 (https://jevopisdeveloperblog.blogspot.com/2016/11/bof-ece2016-eclipse-and-asciidoc.html). So I am interested in Asciidoc in general. However...

After many years using Asciidoc in larger projects I have come to the conclusion that Asciidoc is not a good foundation for writing technical documentation though. Some reasons are:

1. The syntax is not consistent. There are different syntax constructs for different things. E.g., setting parameters for certain elements does not follow a single concept. In some cases a dot is used as prefix, sometimes not, in other cases assignments are used ([.xxx] vs. [xxx] vs. [xxx=yyy]). And the “+” sign at the end of a line is really a pretty bad idea.
2. The syntax is not intuitive nor readable. The Github flavored markdown spec contains a nice comparison of Asciidoc vs markdown (https://github.github.com/gfm/#what-is-markdown-). I think the example is self-explaining.
3. There is no clear definition of blocks and nesting. This makes it really hard for longer texts to write and read. Some things can be nested, others cannot — very confusing.
4. The output cannot be split-up into multiple HTML files. This is a severe issue when it comes to really long documents, which could easily be the case for specifications. You can see the difference here: https://www.eclipse.org/n4js/spec/N4JSSpec.html is the original output of Asciidoctor (with some tweaks, see below), while https://www.eclipse.org/n4js/spec/index.html shows the same specification split up into multiple documents. While the first one needs quite some time to load, the latter loads very fast. I wrote the split-up tool myself, see below as well.
5. PDF output is not acceptable. For example, footnotes are not supported. Overall the PDF quality is very poor. So if you use Asciidoc, you are limited to HTML. As a site note: Also epub is not supported.
6. Important features for technical documents and specifications are missing, such as special numbered blocks, e.g., for requirements, examples etc. As a consequence no list of these special blocks, such as list of requirements, list of examples etc., can be created.
7. Linking is an issue. In particular for documenting software projects, it would be crucial to refer to code (e.g., in the source code repository).

Issues 4 to 7 may be solved with newly written tools — however that would require a lot of effort, basically writing a new Asciidoc processor from scratch. But then there are still the issues 1 to 3, which cannot be solved except for simply not using Asciidoc.

In the Eclipse N4JS project, we have used Asciidoc (and Asciidoctor) for quite some time. The “Specifications” described at https://www.eclipse.org/n4js/userguides/index.html#_specification are all written with Asciidoc (the page includes links to the output and the Asciidoc source code), and also the N4JS user guide is using Asciidoc. We also use these documents in the Eclipse help, unfortunately the nightly build is currently not working (at least not the macos version), and the special enfore version (available at https://download.enfore.com/n4js/, you need a double-click to open a folder) has a bug with the N4JS specification in the Eclipse help (but the N4JS articles and user guide are working in the Eclipse help, and they are written in Asciidoc as well).

In order to understand why I would not use Asciidoc in the future, simply have a look at some of the Asciidoc sources linked above — they are very hard to read, aren’t they? E.g., https://raw.githubusercontent.com/eclipse/n4js/master/docs/org.eclipse.n4js.design/chapters/05_parser/parser.adoc — what do all these things in square brackets mean (sometimes before a construct, sometimes after, sometimes two brackets, etc.). It is very hard to read and very hard to write as well! After having used Asciidoc for several years, I’m still fighting the syntax.

We extended Asciidoctor with some extensions written in Java (using JRuby), we called that Asciispec. It is available at https://github.com/NumberFour/asciispec. These extensions added some features needed for technical and software documentation. However, only after we decided to use JRuby (and having spent too much work there already) we came to the conclusion that the JRuby version is not really usable, as it does not contain the whole Asciidoctor API. In other words: Do not use Java for writing Asciidoctor extensions but Ruby. But I would assume that you would have a “new” tool in mind anyway, don’t you?

For splitting up the document I wrote a small tool which splits the html output. Since I did not want to spend too much time on that tool, it lacks important features such as fulltext search over all documents. Also we spent a lot of time of creating a nice table of contents, which is still not perfect though. Also we wrote a tool for creating the Eclipse Help Toc. See https://github.com/eclipse/n4js/tree/master/releng/org.eclipse.n4js.releng.utils/src/org/eclipse/n4js/doctools for these tools.

Instead of establishing an AsciiDoc Working Group, I would recommend to establish an (Eclipse) Markdown Working Group. Markdown is better readable, and it would be possible (as a working group at Eclipse) to define a defined set of extensions (similar to the Github flavor md), a clear definition of blocks (via indention for example) and other things. I would strongly recommend to not use Asciidoc as a base for a software documentation language due to the problems described above. 

Best regards,

Jens