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 am interested in exporting documents into HTML, Atom feeds, and info files, possibly printing, and reading as plain text, those aspects will be mentioned explicitly. It is assumed that quality of export/conversion unintended in the design is rather low.

Languages

(La)TeX

It is an advanced markup language, or more of a typesetting system, and it is nice in many aspects, so I will only list its drawbacks.

Cons:

• Awkward as a language (perhaps because it focuses on presentation and imperative control sequences), though so are most of the others.
• DVI-, Postscript-, PDF-, paper-oriented: there are quirks when trying to export relatively complicated LaTeX document into other markup languages. Good for printing though.
• Complex: though it is easy to learn the basics, its internals are tricky, making good understanding, usage, and manipulation (including automated processing) hard as well.
• Focused on presentation (optical markup), rather than semantics (logical markup).
• No freely available specification of TeX in sight.

Use cases: it is useful for complex documents, involving mathematical formulæ (and possibly diagrams), 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."

HTML, other SGML- and XML-based ones

XHTML can be nicely generated out of XML with XSLT (which is handy for templating), as can Atom feeds, though XHTML is retired, as is the XML syntax for HTML LS: it is back to rather vaguely specified and changing markup. Then there is MathML for mathematical formulae, but it is too verbose for manual composition or reading. Use of data models such as DITA and DocBook brings additional pros and cons, so they are summarized separately.

Pros:

• Semantics can be nicely preserved, and generally it is a transformation- and machine-friendly family of languages. RDFa is available.
• Templating/export capabilities in the design, especially handy with other XML-based formats.

Cons:

• XML is not great for reading or writing by human beings.
• The use/evolution/documentation/community are rather chaotic: even now (2018), with more or less consistent browser support of the basics, and with all the W3C specifications, web developers screw it up most of the time, while the learning resources and discussions focus on "whatever is likely to work in an arbitrary HTML-related specification", and the specifications are complex/bloated (for instance, HTML specifications rely on DOM objects, not mere XML objects). Apparently the RDFa XHTML attributes are no longer relevant, and would partially duplicate HTML5 sections and other bits. XHTML in general seems to just add to confusion, while it's superseded by HTML5 with XML syntax (which is supposed to be like XHTML, but not quite). Well, that can go into a separate note.
• The "living standard", which mostly documents the way large and complex browsers handle it, making the specification less stable and less interoperable.

DocBook, DITA, etc

Pros:

• An additional layer makes manipulation more flexible: the models do not have to be attached to presented pages, and they are more focused on semantics.

Cons:

• Mostly "enterprise" software around it, including weird custom scripts for running and installation, violations of common standards, poor integration into systems, sometimes even proprietary.
• libxml2's xsltproc does not handle DITA-OT's XSLTs, which rely on XSLT 2.0, while xsltproc only supports 1.0. And there are 10+ KLOC just of XHTML-specific bits, so rewriting it is non-trivial. So software support is very limited.
• Large multi-page documents, not many primers; not particularly easy to learn in general.

Org-mode

Pros:

• Easy to use: versatile, has a lot of features, but it is easy to learn the basics, and then only those features which one would actually use.
• HTML export and publishing: handy and nice for basic tasks.

Cons:

• There is Texinfo export, but it cannot export a whole project, as it does with HTML.
• Emacs-based: though it is nice when updating documents alone, it is not that nice for shared documents.
• Awkward syntax for various blocks and properties: while it is nice and handy for basic features, advanced ones do seem awkward to me.
• No atom export (apparently that would require writing an export backend).
• RDFa embedding would be tricky and incomplete, probably also requiring a new export backend to set it right.

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

Texinfo

Pros:

• Export: it is 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.
• Export is not flexible, hardly suitable for something other than documentation.

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 is good for.

CommonMark

A specified Markdown flavor.

Use cases: HTML export is its primary target.

reStructuredText and Sphinx

Probably I should not mix those together, but that is what I am doing.

Pros:

• Export: export into both HTML and Texinfo works fine, and Sphinx also creates handy makefiles.
• The syntax is okay.
• Relatively structured and feature-rich.

Cons:

• Python, including various Python errors on export, and the languages itself being geared towards Python.
• "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 generally bloated – probably would look even worse in a few years.

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

Others

roff-based languages (nroff and troff, as implemented in groff) are used for man pages, and are quite usable, though neither handy nor feature-rich. Though as with TeX, no specification (not counting tutorials and user references) in sight.

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. Has a decent freely available specification: PostScript Language Reference Manual.

For lower-level typesetting, one may also be interested in the unofficial DVI specification.

SILE looks like a nice typesetting system, supporting both XML and TeX-style syntaxes, apparently making use of MathML for mathematical formulae (but compiling TeX-style formulae into it), allowing scripting in Lua, relatively well-documented (The SILE Book).

typst is also a typesetting system, but less well-documented, its Rust package seemed broken at the time when I wanted to try it, and it seems to be commercial.

For use of macros with most markup languages, m4 can be handy.

Essentials

Most elements (headings, lists, references, etc) can be handled by plain text, but there are at least a couple of commonly needed things other than regular text that need an explicit support: embedded images (illustrations) and mathematical formulae.

Mathematical formulae are usually delegated to either LaTeX or MathML (possibly embedded as images, but those still have to be created), though groff's (troff's) eqn(1) can produce those as well. There is Content MathML, which focuses on semantics, and which is compared to Lisp (except for MathML being extremely verbose). When writing down notes with formulae and solving textbook problems, I tend to mix plain text with chunks of Emacs Lisp code in order to easily execute them in Emacs at once, but they are relatively legible, compared to MathML or even LaTeX. SymPy formulae and functions are not too bad for legibility, either. Other times I employ Unicode characters for the sake of compactness, though usually programming languages support those (e.g., Agda even uses them extensively). A Lisp language may also provide simplicity and uniformity, at the cost of being a little more verbose than those infix and mixfix operators, with varying precedences.

Apart from formulae and images, URL references are commonly needed and awkward to handle, but they can still be embedded into plain text without harming legibility much. Likewise with tables, though in many cases they can be simply avoided.

Conclusion

As usual, it is about preferences, priorities, and tasks. It may be tempting to pick a single language for everything, but as with programming languages, there is no single tool ("golden hammer") that would be most suitable for all tasks.

See also

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