Re: [boost] Asciidoc, an alternative for documentation

On 6/5/2017 11:34 PM, Vinícius dos Santos Oliveira via Boost wrote:

2017-06-06 0:00 GMT-03:00 Peter Dimov via Boost :

...

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

I've converted all of Boost.Http documentation to asciidoc. I don't intend to use QuickBook/BoostBook again. Too much NIH syndrome and too much inconvenient.

Using quickbook has always appeared easy to me. Generating html and pdf doc from quickbook source involves a number of steps that need to be correctly setup via a jamfile, and I think this is what always appears hard to others. I am certainly not against other methods of writing Boost documentation and will look at asciidoc. But I did want to point out that I do not think the issue with quickbook is really the quickbook syntax itself. Others of course may well disagree with this assessment.

I use the following options to generate the HTML:

asciidoctor -a toc=left -a toclevels=3 -a sectnums -a sectnumlevels=4 http.adoc

And the following to generate the ePUB:

asciidoctor -b docbook5 http.adoc pandoc -f docbook http.xml -o http.epub

I was considering paying someone to design a Boost-like theme and the opened the Boost.Asio documentation. I changed my mind. There is no reason somebody would like to mirror this theme.

It's infinitely easier to write documentation using asciidoc, and this is a plus also to receive contributions. Nobody outside Boost know how to get boostbook up and ready to generate HTML, PDF and ePUB.

Also, asciidoc was designed to make syntactic elements directly mirror docbook semantics. So you have great Docbook output with a syntax that is as pleasant to use as MarkDown.

Also, I've found many different ways to generate PDF using asciidoc. All of them are pretty different when you compare the output of each process. Just noting in case you didn't like this one generated PDF.

Have fun playing with asciidoc.