Friday, June 17, 2011

Restructuredtext vs Asciidoc

This will be brief: RST beats Asciidoc.  I actually prefer Asciidoc's syntax; it uses markup inherited from the markup people have been using in emails for more than a dozen years, while RST is hacky, obtuse, and contrived.  I never will understand why people ignore defacto, organic standards in favor of inventing new standards which are worse.  In any case, Asciidoc's syntax is better -- but the parse rules are just too involved.  It can be difficult to construct a document from scratch; the parser is extremely picky, and there are too many dependencies on unstable libraries.  This is supposed to be human-composable, human-readable text; the syntax rules should be more relaxed, and the parser more forgiving.  So, for now, I'm sticking with RST, even though it has serious flaws. [1]  It does have unparalleled table syntax, although unfortunately without any support for text alignment in cells.

[1] Such as:

  • No easy syntax for underscore, strike-through, superscript, or subscript
  • Bizarre, unintuitive choices for markup, like *xyz* for italics and **xyz** for bold
  • Unnecessarily verbose syntax for footnotes
  • No mechanism for continuing lines in lists after inline blocks


Tomek said...

I have to say I'm surprise with your comparison of AsciiDoc and RST. I use both - AsciiDoc is my tool of choice at home and we use RST at work, so I have plenty of experience with both.

As for syntax - AsciiDoc is a clear winner (as you say). I really do not understand what you say about "parser being picky" - could you give an example? I also found AsciiDoc mailing list extremely helpful.

BTW. Have you tried Asciidoc + Slidy combo? Really cool. :) See

getreu said...
This comment has been removed by the author.