UP | HOME

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.

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.

Pros:

  • 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.

Cons:

  • 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

Pros:

  • 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.

Cons:

  • 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 simple, 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.

Pros:

  • 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.

Cons:

  • reStructuredText is not particularly intuitive.
  • Python, including various Python errors on export: at least not PHP or JS, but still.
  • "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.

Use cases: manuals, documentation.

1.6 Others

HTML — when it's used to support semantics and not bloating (i.e., never) — can also be considered a usable markup language.

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