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.
Languages
LaTeX
It is an advanced markup language, and it is nice in many aspects, so I
will only list its drawbacks.
Cons:
- Awkward (dated?) 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.
- DVI-, Postscript-, PDF-, paper-oriented: there are quirks
when trying to export relatively complicated LaTeX document
into other markup languages.
- Complicated: though it's easy to learn the basics, its internals are
tricky, making good understanding hard as well.
- Hard to manipulate/process automatically.
- Little focus on semantics, though it doesn't matter much because of
the above.
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.
Pros:
- Semantics can be nicely preserved, and generally it's perhaps the
most 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). Apprently 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.
Data models (DITA, DocBook, perhaps others)
Pros:
- An additional layer makes manipulation more flexible: the
models don't have to be attached to presented pages, and
there's more focus 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 doesn't handle DITA-OT's XSLTs, which rely on
XSLT 2.0, while it only supports 1.0. And there's 10+ KLOC just of
XHTML-specific bits, so rewriting it is non-trivial. Hence 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: though has a lot of features, it's 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 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.
- 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: 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.
- 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's good
for.
CommonMark
A specified Markdown flavor.
Use cases: HTML export is its primary target.
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.
- 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
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.
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.