Markup languages

There is plenty of markup languages around, and often it is not easy to pick one for a task at hand. I am going to put together a few observations here.

And since I'm interested in exporting documents into HTML and Texinfo, those aspects will be mentioned explicitly. Sometimes will assume that quality of non-native export/conversion is rather low.

1 Languages

1.1 LaTeX

It is the most advanced language of those which I will mention here, and it is great in many aspects, so I will only list its cons.


  • Awkward (outdated?) language and syntax: though I don't have anything better in mind, of which I would be certain that it would be at least as handy, LaTeX still is awkward as a language.
  • PDF/paper-oriented: there is plenty of quirks when trying to export relatively complicated LaTeX document into HTML. Also no native export into Texinfo.
  • Complicated: though it's easy to learn the basics, its internals are a mystery to me. That probably won't stop many programmers, but then they could consider usage being complicated.

Use cases: it's great for complex documents, involving diagrams or mathematical formulæ, or for anything that could use templates, but could be excessive in other cases. "LaTeX is the de facto standard for the communication and publication of scientific documents."

1.2 Org-mode

That's what I'm using at the moment.


  • Easy to use: though has a lot of features, it's easy to learn basics, and then only those features which one would actually use.
  • HTML export and publishing: very handy and nice.


  • There is Texinfo export, but it can't export a whole project, as it does with HTML.
  • Emacs-based: though it is nice when updating documents alone, it's not that nice for shared documents.
  • Awkward syntax for various blocks and properties: while it's nice and handy for basic features, advanced ones do seem awkward to me: long names, which consist of capital letters.

Use cases: all kinds of notes, static websites, probably basic info files.

1.3 Texinfo


  • Export: that's the primary way to create Info files, and GNU uses it for HTML manuals as well. Info, HTML, LaTeX, and a few other export formats are supported natively.
  • A GNU project.


  • Syntax is not great, though better than some others.

Use cases: its primary purpose is to create technical manuals, and it seems to be good at that, so anything manual-alike is what it's good for.

1.4 Markdown

And its derivatives, e.g. "GitHub Flavored Markdown". Actually, there's not much to write here: it's basic and messy (if you throw all the flavours into the same bucket; some may be less messy), which is both good and bad.

Use cases: github, maybe some docstrings and inline code documentation. By itself, it's not much better than textual files, and doesn't even replace those, since it's harder to read as plain text. But HTML export (e.g., using Hakyll/Pandoc) is nice.

1.5 reStructuredText and Sphinx

Probably I shouldn't mix those together, but that's what I'm doing.


  • Export: export into both HTML and Texinfo works fine, and Sphinx also creates handy makefiles.
  • Syntax: it's relatively nice once one gets used to it, and quite readable as plain text.


  • Python, including various Python errors on export.
  • "Fancy" HTML with ugly default theme: though it's nice that it can include MathJax or render formulæ in PNG, highlights code in many languages, and has search that doesn't require any active server-side scripts, it's not that nice for accessibility, is full of JS and depends on it, and basically not minimalistic – probably would look even worse in a few years.

Though the cons don't actually apply to the language itself.

Use cases: manuals, documentation, READMEs (quite comfortable to read as plain text).

1.6 XML

XHTML can be generated out of XML with XSLT (which is pretty neat for templating), there are data models such as DITA, RDFa can be embedded into it, and there's a choice of advanced tools, so it's even tricky to reduce to hard pros and cons. One of the primary issues is that XML is not great for reading or writing by human beings.

1.7 Others

PostScript is a surprisingly readable and somewhat nice for a language that is usually used as a target to compile other languages (perhaps LaTeX most of the time) into.

2 Conclusion

As usual, it's all about preferences, priorities, and tasks. Though it's tempting to pick a single language for everything, it's like with programming languages – there's just no existing solution that would be good for everything (and if one thinks that they've found one, that's probably a "golden hammer").

3 See also