Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Vinícius dos Santos Oliveira (vini.ipsmaker_at_[hidden])
Date: 2017-06-06 03:34:25

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.

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.

-- 
Vinícius dos Santos Oliveira
https://vinipsmaker.github.io/