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

Copyright © Sean Elliott Russell

comments powered by Disqus