[boost] boost-cmake and quickbook

Subject: [boost] boost-cmake and quickbook
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2018-10-23 19:53:04

On 23.10.18 21:29, Edward Diener via Boost wrote:
> On 10/23/2018 2:36 PM, Robert Ramey via Boost wrote:
>> On 10/23/18 11:17 AM, Peter Dimov via Boost wrote:
>>> Robert Ramey wrote:
>>>
>>>> And I place the html and pdf versions into the repo so users don't 
>>>> have to build it.
>>>
>>> Placing the .html/pdf files into the repo is one - unquestionably 
>>> modular - way to do it, but it does have its downsides.
>>
>> Both true.
>>
>> downside
>> - "wastes" a lot of space
>> - redundant - docs could get out sync with the code.
>>
>>
>> upside
>>
>> - current documentation is always available to the user.  In the two 
>> libraries of mine - documentation is an important part and I don't 
>> think the either would be usable without them.
>> - only needs to be built on one machine no hassle for users
>> - document build doesn't have to be "portable"
>> - potential users can easily browse the documentation before they 
>> clone/download the package.  This works well with github.  I think 
>> this is very valuable - especialy for safe_numerics which most people 
>> don't actually see the need for.  Call it a sales tool.
> 
> I am sure you know that github already has support for viewing the 
> documentation via the github io mechanism, so your last '-' item is not 
> really applicable to your argument.
> 
> My argument is simply that lots and lots of libraries use Boost Build to 
> generate the docs, very often through the quickbook -> docbook -> 
> pdf/html mechanism and unless we are going to continue to do it that way 
> when Boost uses CMake we will eventually need a way to duplicate the 
> Boost Build mechanism for creating the docs in CMake.
> 
> Nonetheless I continue to believe that the move to CMake by Boost should 
> be achieved in small steps, so that we can assure success in one step 
> for all libraries before we even think about attempting the next. I 
> still have the same fear that trying to accomplish everything at one 
> time will mean that nothing really will ever get done. I only added item 
> 5) to Peter's list because that is something we will eventually have to 
> decide about.

Talking about small steps, feel free to copy paste this wherever you 
need it:

https://github.com/raffienficiaud/boost-cmake/blob/master/boost-cmake/quickbook.cmake

I compiled Boost.Test documentation with this, this is fully cmake and 
it does the catalog generation on the fly.

This is a small step, usually this is where collaboration starts, since 
I do not have all the knowledge of quickbook/docbook nor the bandwidth ATM.

*But* if somebody is kind enough to assist me on this, in particular 
explaining me if we would want

    --stringparam chunk.first.sections "1"
    --stringparam chunk.section.depth "4"
    --stringparam generate.section.toc.level "3"
    --stringparam html.stylesheet "boostbook.css"
    --stringparam toc.max.depth "3"
    --stringparam toc.section.depth "10"

to be exposed when compiling a documentation, or how to run the doxygen 
part, then porting things to cmake will be definitely faster.

Raffi