Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-15 02:47:10

On 8/14/2017 9:13 PM, Soul Studios via Boost wrote:
>> The only thing you have to learn is Quickbook and doxygen. I see 
>> nothing "ridiculous" in that. You can ignore boostbook/docbook 
>> completely.
> 
>  From what I recall there were about 12 different dependencies you had 
> to set up in order to render anything from quickbook, with unclear 
> guidelines, and no standard path for authoring quickbook. At any rate, I 
> just thought I'd offer my impression as someone new to boosts doc 
> process. I'm not interested in an argument.

There is full documentation for quickbook. It is a Boost tool that comes 
with its own documentation, or you can regenerate the doc yourself.

I agree that the bjam setup needed to go from qbk files to html and/or 
pdf output is not documented, as I think it should be in the Boost Build 
docs.

You can take a look at the doc jamfile in numerous Boost libraries that 
use quickbook to see how to set things up, including my own tti or vmd. 
The main dependency for quickbook is boostbook/docbook, with alternate 
dependencies on auto_index and doxygen. That is 3, not 12.

> 
> 
>>> If there had been an insistence on a particular look-and-feel with a 
>>> supplied .css, I would've been fine with that. Instead I gave up.
>>
>> No one forces you to use Quickbook or doxygen. But your emotional 
>> response to both is very surprising.
> 
> I don't agree with that.

I understand the frustration in the almost total lack of formal docs for 
going from quickbook to html/pdf. But quickbook itself is a piece of 
cake, is very well documented, and blissfully easy to specify most 
everything you need to do in creating library documentation.