Boost logo

Boost :

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:

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.


Boost list run by bdawes at, gregod at, cpdaniel at, john at