On Mon, Oct 30, 2017 at 01:35:19PM +0100, Johannes Schindelin wrote:
> If you want to go into the direction of the web, AsciiDoc is actually the
> wrong choice IMO, and Markdown would be the right choice. Basically
> everybody on the web is either supporting Markdown or being asked by users
> to do so.
> 
> Assuming that *that* is something we want to pursue, I would also suggest
> to move the man pages away from AsciiDoc to Markdown (using e.g.
> [ronn](https://rtomayko.github.io/ronn/ronn.1.html)).

The thing I really like about AsciiDoc is that it works well for a
variety of output formats.  Markdown is designed for HTML, and only
HTML.  It may have converters to other formats, but then you can't use
any extension mechanisms in HTML.  Markdown also lacks features that
AsciiDoc has, like cross-references, named anchors, and the ability to
write the linkgit syntax.

AsciiDoc, via DocBook and the XSLT stylesheets, supports conversion to
PDF, DVI, PS, and ePub, among others.  The things I'm seeing for
Markdown to PDF involve either Pandoc or a browser engine such as
phantomjs.

Also, AsciiDoc has the benefit that it has only two implementations.
Markdown has so many variants that it's hard to write things like tables
in a portable way, so we're going to have at least as many problems
(between the website and the codebase) as we do now.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204