Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Lorenzo Caminiti (lorcaminiti_at_[hidden])
Date: 2017-06-06 15:03:10

On Tue, Jun 6, 2017 at 7:10 AM, Edward Diener via Boost
<boost_at_[hidden]> wrote:
> 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

Looks nice. I am not familiar with asciidoc...

* Does ascii interface with Doxygen? For example, can you embed in the
asciidoc output a reference section generated by Doxygen and have
hyperlinks in between the ascidoc and Doxygen sections? (Similar to
Quickbook [xinclude ...].)

* Does asciidoc allow to show code snips marked in an external source
file? For example, to show example code snips in Quickbook using
[import <file-name>] and then [abc], where //[abc ... //] are used as
markers in file-name.

> 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.

This is my experience as well. For example, if there was a
"pre-compiled" distributable of Quickbook that did not require to
download Boost and did not use BJam (as least not require to the users
to use BJam directly), Quickbook would be easier to use.

--Lorenzo