Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-06-06 14:10:57

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 <boost_at_[hidden]>:
> 
>> 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.
>