Markup languages

There are plenty of markup languages around, and sometimes it is tricky 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, Atom feeds, and info files, those aspects will be mentioned explicitly. It is assumed that quality of export/conversion unintended in the design is rather low.



It is an advanced markup language, and it is nice in many aspects, so I will only list its drawbacks.


Use cases: it is useful 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."

SGML- and XML-based ones

XHTML can be nicely generated out of XML with XSLT (which is handy for templating), as well as atom feeds. Use of data models such as DITA and DocBook brings additional pros and cons, so they are summarized separately.



Data models (DITA, DocBook, perhaps others)






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




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.


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. Probably mostly bad.

Use cases: 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, especially since one of markdown flavours is what Pandoc aims for in its internal representation.

reStructuredText and Sphinx

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



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

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


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.


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").

See also

Wikipedia: Comparison of document markup languages, List of document markup languages.