I must add Asciidoctor. Which is mostly compatible with Asciidoc, but even more powerful.
I have spent a lot of time trying to make Asciidoc create beautiful PDFs for technical documentation, but Asciidoctor makes it all a lot easier to customize its own stylesheets.
The only negative thing about it is that it is hard to install since it typically isn't found in your distros package repo by default.
Thanks to your comment I just tried out Asciidoctor and 'it's absolutely beautiful. It's insanely easy to install on OSX/Linux systems. I can see myself using on some of my pet projects.
I agree. For me, Asciidoc hits the sweet spot as it seems to have much of the simplicity of Markdown, and with the AsciiDoctor/DocBook toolchain it has the publishing power of RestructuredText.
But its tables beat both hands down. You can include a csv file with some headers or micromanage merged cells, alignment and such.
I was in attendance for a conference presentation a few years back that O'Rielly was moving to writing books in an asciidoc editor which would be converted to (x)html5 for easy conversion to PDF and ePUB.
I wonder if that thing ever took off. Previously, it was said, that they were working in docbook (XML)
AFAIK (I have a few friends who have written for O'reilly) this is their canonical mode of publishing. It uses Git and Asciidoctor (not asciidoc) with a few additional plugins
I would also add that Asciidoctor has the best extension experience out there. It has named blocks and inline sequences that can be handled correctly by a plugin, which is amazing if you ever tried to add syntax into Markdown. Just compare how bug-free and simple is embedding Mathjax into Asciidoctor compared to Markdown: last time I've checked you had to manually process Markdown to extract all Mathjax stuff, apply Markdown and then inject Mathjax back. With Asciidoctor it's a no-brainer.
I looked into these recently and found AsciiDoc the most promising for lightweight technical documentation, but I'm still having a very hard time getting myself to use it instead of Markdown.
AsciiDoc has some very newbie-hostile quirks, at least as of now it more or less requires asciidoctor, and even then its output HTML is terrible. Terrible as in Wrong, as in...
<div class="paragraph"><p>Oh no...</p></div>
In fact, since I have not yet found an asciidoc converter that produces decent HTML, and I don't have time to write one, I may yet fall back into the "everything sorta supports Markdown" trap.
Markdown is one of those "worse is better" computer pop culture things that raise to the top, despite the existence of better tools.
I dare anyone to write a scientific paper or book using Markdown. In Asciidoc it's doable. And before you say that a markup language is the wrong tool for the job, let me remind you that nowadays authors might want to produce different formats (HTML, ePub, text-only) from the same source file which is difficult with LaTeX.
If you consider Markdown on its own, I agree that it's rather difficult, but you should really try Pandoc, any output is possible, including scientific papers (pandoc-citeproc is fantastic) and books. Without Pandoc, Markdown would be very limited for my use cases.
I had forgotten about PanDoc! That's true, for some time I was pondering going Asciidoc vs Markdown+Pandoc. I liked the "purity" of Asciidoc (most things you will ever want to do are built-in), and Pandoc felt like it was a non-portable collection of hacks to get Markdown to do useful things.
I wish I had time to evaluate them in more detail, but so far I've stayed with LaTeX, which I feel is not the right tool for the job for material that's not going to be printed on paper.
I think it's more the case that there is no good general-purpose solution yet, and a bunch of people use Markdown because it's easy within a very limited scope, so now you have to deal with Markdown's near-ubiquity if you suggest something else.
I would never try to write a book in Markdown, no matter how extended; but considering the HTML produced by asciidoc|tor, you might also say "don't use AsciiDoc for simple Web publishing."
What I find much more fascinating is the question why there is no good general-purpose format that works equally well for blogging and for scientific papers and for books?
Indeed. We recently started a large rewrite of our product's Developer's Guide which was previously written in DocBook. All the writers are quite happy about Asciidoc and it took us only a few days of work to recreate custom additions we added to DocBook.
That being said, while the user documentation is (mostly) excellent, the developer documentation is abysmal to non-existent. On the positive side, though, the developers are quite active and responsive on Github. But if you're only writing documents instead of extending the language with new macros, you won't notice anything of that.
Asciidoc is really underrated. It feels more "natural" than RST and scales up to large documents.
I wish people spent more time looking at alternatives instead of jumping on bandwagons.
http://asciidoc.org