I don't have a particularly strong opinion about most markup, but I know for sure I'll never use something that uses xmlto/xsltproc as part of the toolchain (su

I don't have a particularly strong opinion about most markup, but I know for sure I'll never use something that uses xmlto/xsltproc as part of the toolchain (such as Docbook). As a maintainer of several packages for a Linux distribution, I've gotten far too many headaches dealing with packages that rely on Docbook for generating their manpages or other documentation. The user's xsltproc setup has to be just right for the packages to build. Anything off in the XML catalog will break the whole build. Supporting it has been the opposite of fun. For manpages, I write mdoc directly. It's not hard. There are several great mdoc resources on http://bsd.lv http://bsd.lv For reference material, I stick with either Pandoc or I use LaTeX (along with tex2page for generating HTML). Anything fairly small tends to get the Markdown treatment. If it's something I foresee will need to be split into multiple documents, I reach for LaTeX. Scribble is pretty nice, too, if you're dealing with Racket or Scheme.