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