Thoughts on Asciidoctor

Asciidoctor is probably the nicest way to write Docbook markup.

It is, basically, just Docbook 4/5 mapped directly to magic sigils. Similar to how Markdown is shorthand for some HTML.

Comes with a means to export single-page HTML. If you want anything else (like paginated HTML) you will need to bring your own processing scripts.

Very nice feature: inclusion via gates. You can include content from another file and tell it "take content from this file, starting at a line which looks like this, ending at another line which looks like this after it." Which means as long as code is properly gated you can clip examples from it in prose. Handy for keeping examples in a compilable file and quoting from the example in a handbook.

Comes in snake code (original asciidoc) and Ruby (asciidoctor.rb)

Most disliked feature: magic sigils are used for everything. If you don't already know what something does expect to search the docs to find the symbols because everything has some special application of punctuation.

Index support exists--which is better than most--but is still weak. Texinfo supports multiple arbitrary indices. Markdown doesn't support any.