Markup Languages Compared

There are several popular light weight markup languages for producing printed or displayed typeset output. I use “light weight” to distinguish them from heavy duty markup languages such as TeX, LaTeX, or Troff. One thing they all have in common is that they’re more pleasant to use and generally produce better output than Word and its evil siblings.

I just came across an InfoWorld article from 2019 that compares several markup languages for documentation. The article looks at

1. Markdown
2. reStructuredText
3. AsciiDoc
4. Org-mode

I’m vaguely familiar with Mardown and, of course, intimately familiar with Org-mode but have never used reStructuredText or AsciiDoc. They all have their adherents so a comparison can be useful for those looking for a tool to write their documentation or for other writing projects.

The advantages of Markdown are that it’s everywhere—especially for producing HTML—and is easy to learn. It’s problems are that it’s a bit feature-poor and has several slightly different versions.

reStructuredText, on the other hand, has more features and it has a specification. It began in the Python community so its syntax depends on white space. Other than that, it seems like a good solution. Indeed, Mickey Petersen used it to write Matering Emacs so it can take on large projects as well as simple documentation.

AsciiDoc is another nice solution. My impression is that it’s popular among more technical users.

Finally, there’s Org-mode. Here the article really falls down making the rest of their conclusions suspect in my mind. They say, for instance, that Org-mode is not suited for public documentation despite the fact that books, papers, and the (book length) Org-mode documentation itself is written in it. They seem to believe that its function is mostly restricted to supporting Org Agenda features. It is true, of course, that Org-mode, despite its spinoffs for other editors, is primarily restricted to Emacs but why would the enlightened care?¹

Despite the article’s failure in accurately evaluating Org-mode, you may find its comparison of the other systems helpful. Give it a look if you’re interested.