[boost] Asciidoc, an alternative for documentation

Subject: [boost] Asciidoc, an alternative for documentation
From: Peter Dimov (lists_at_[hidden])
Date: 2017-06-06 03:00:17

I've been experimenting with Asciidoc-based documentation, using 
Boost.Assert as my guinea pig. The good thing about Asciidoc is that Github 
shows a preview and you can edit it directly on github.com. This is how the 
source looks there:

https://github.com/boostorg/assert/blob/feature/asciidoc/doc/index.adoc
https://github.com/boostorg/assert/blob/feature/asciidoc/doc/assert.adoc
https://github.com/boostorg/assert/blob/feature/asciidoc/doc/current_function.adoc

This is how the generated HTML documentation looks, using the default 
stylesheet, without any customizations on my part:

https://rawgit.com/boostorg/assert/feature/asciidoc/doc/html/assert.html

And this is how the generated PDF looks:

http://pdimov.com/tmp/assert.pdf

The tool that produces these is Asciidoctor, http://asciidoctor.org/ .