AsciiDoc is a light-weight markup language for structured text.
I have previously been using Emacs org-mode for writing up specifications and such. Org-mode is great, however a major drawback is that it is not a specified standard and there is only a single implementation. I think AsciiDoc, as a specified format, is a better format for writing up specifications and design documents.
AsciiDoctor is the reference implementation for transforming AsciiDoc documents to HTML/PDF/ePub.
There is also a tool called Metanorma for translating AsciiDoc to RFC documents or other standardization body document formats.This is also how I found AsciiDoc, after researching the tool @how mentioned in the Kick-off meeting for translating Markdown to RFC documents.
I use org-mode most of the time as well, and indeed it can be troublesome for collaboration with non-emacs users. Although a simple subset of it is well supported, there’s a vim plugin and a ruby module that brings it to github and other web platforms.
After a brief look, asciidoc seems interesting, and it appears to have been designed specifically for publishing, which org-mode is also trying to do, but it has a proper specification.
How well is it supported across various editors and web platforms (emacs, vim, github/gitlab/etc)?
I have used pandoc before for publishing org & markdown to web (e.g. on p2pcollab.net), however, it only has support for asciidoc writing, not reading. Asciidoc has its own tool for this that offers similar functionality with templates.
This is super unfortunate that pandoc does not have a AsciiDoc reader. There is an issue to add AsciiDoc reading functionality: https://github.com/jgm/pandoc/issues/1456
What would also work is: AsciiDoc → DocBook → Pandoc
AsciiDoc is syntactically equivalent to DocBook (which is in XML) so I think nothing would be lost with the first transformation.
Yup. They work neatly and templates can be customized.
For now I’ve been using the standard template. It has two major issues:
Uses webfonts from Google (can be disabled with attribute webfonts!).
Uses MathJax from CDN (better to use a local copy, as you do with P2PCollab @tg-x)
Eventually we might have our own DREAM template, solving this and looking nice.
I plan on updating the ERIS specification this week as well and will do so in AsciiDoc. Also might play around with Metanorma to see how export to IETF RFC format works.
I looked into this some more, and found out the following.
Implementations
seems that AsciiDoc is the legacy Python implementation,
while AsciiDoctor is in Ruby with more features.
Syntax
many things I like about the syntax but found some issues that could’ve been avoided:
no parentheses around links & footnotes: footnote:[text] & http://url[text], which means
footnotes are awkward to write without a space before, would have to use text{blank}footnote:[text] which is too verbose or textfootnote:[text] which is messy
only common URI schemes are supported by default, e.g. http, for others one would have to use an additional link: prefix, e.g. link:xmpp:foo@bar
extra syntax for curved quotes due to legacy reasons
Editor support
not so great in Emacs, much easier to write/edit Org-mode documents with keyboard shortcuts for many common editing/inserting tasks
HTML export
there’s no proper semantic HTML with <article><section> etc tags, there’s a html5s export backend that tries to do some of this, but not really properly and all the way. pandoc’s html5 export is much better, I started to fix up the html5s template a bit to become closer to pandoc’s output so that I could use the same stylesheets
also, it’s been quite difficult to get it working with the html5s backend, which is not packaged for Nix, and I had to make some dirty hacks with hand-editing Nix outputs to be able to try it out (I dont know how to package ruby things properly and i dont want to learn it now just to try…)
Conclusion
while I like some of the ideas behind it and that it’s designed for book publishing in mind, I find it harder to use in my setup than org-mode with pandoc. It seems to me that using a subset of org-mode that pandoc supports might work better, and this way there’s no dependency on Emacs and custom configurations to compile the document, and there’s also a possibility to also use Markdown syntax for some documents with the same workflow, if some people prefer that. I’m going to explore this option further.
Note that the ProGit Book is made with AsciiDoc. I think it’s a good starting point to create DREAM documentation since it will enable producing online documentation, an epub version, a PDF version, and something we can print. (I reserved some ISBN numbers we can use for docs.)
Note that the ProGit Book was made with Pandoc & Markdown before.
Some reasons why they moved they mention in this issue. The ToC is not an issue with org-mode & pandoc, the rest I was able to do with org-mode & emacs but not sure about pandoc & org-mode, have to check how much that is usable.
Also just noticed that this emacs instance I used to edit a couple of asciidoc files ended up using 2.5G RAM before I had to kill it. Have to investigate this further, but sounds worrying if it was caused by adoc-mode…
Agree that syntax is not as nice as org-mode and Emacs editor support is pretty shitty…
Nevertheless I think it is good for documents that might outlive this project and be maintained by people we do not even know about now. Having a specified standard is nice and not assuming that those people like Emacs also.
I don’t think we need or should use it for internal notes and websites…for that markdown or org-mode is sufficient and better suited.
Being able to use Pandoc is nice.
Have you tried: AsciiDoc --- (using AsciiDoctor) ---> DocBook --- (using Pandoc) ---> HTML
DocBook is semantically equivalent to AsciiDoc and DocBook can be read by Pandoc. Maybe this is a way of unifying style of documents written in md, org, asciidoc.
I’ve just published the Makefile & CSS files I’m using to generate HTML via Pandoc from org/md/adoc, it uses tufte-css for styling. For asciidoc it uses the docbook route you suggested.