Re: need help with building QuickBook docs

From: pbristow_at_[hidden]
Date: 2022-05-22 11:52:54

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Andrzej Krzemienski via Boost
> Sent: 22 May 2022 00:00
> To: Boost mailing list <boost_at_[hidden]>
> Cc: Andrzej Krzemienski <akrzemi1_at_[hidden]>
> Subject: [boost] need help with building QuickBook docs
> 
> Hi Everyone,
> This is to ask for help with building QuickBook documentation, but also to spill my frustration.
> I would like to offer some feedback in connection with the recent "the future of Boost" threads: about
> the entry barrier for someone who wants to contribute to Boost.

You are right that Quickbook is nice to write documents and produces very nice documentation, especially for complex libraries.  I have yet to see any other documentation system that can produce results that are as good.

But setup is tricky and when it goes wrong it is even more difficult to figure what to do.

I'd put part of the blame on B2 whose error messages are generally no help because that fail to tell you what to do to put things right.  (OK that's *much* trickier than automatically telling what went wrong).

 > I maintain Boost.Optional. Getting my environment to the point where I was actually able to apply
> modifications to the official repo took some time, but it has been working fine since. Modifying the
> source files, so that they compile on multiple compilers, platforms and versions, including C++03 is the
> easiest part. Testing is a bit harder, but basically works also: I go to folder `test`, run the `b2` command,
> and it is done. But updating the documentation is the most difficult task for me. Not the content -- this is
> easy -- but the process/pipeline/framework. I inherited the documentation in QuickBook format, which
> as I understand was the recommended way for providing documentation for Boost libraries. Maybe it
> still is? (but I see more and more docs being rewritten to AsciDocs.) I understand that library authors
> have the freedom to choose their own format of docs for their libraries, but does boost recommend (as
> opposed to enforcing) one format?
> 
> Anyway, in order to test if my QuickBook dos are correct, I need to build HTML version from the sources.
> Sometimes it "just works" with `b2` command, but when something goes wrong, this becomes a pain.
> I cannot just call `b2` for my library, because apparently my Fedora comes with preinstalled version of b2
> (4.4) which appears to be incompatible with something in Boost libraries sources, as I get error:
> 
> error: mismatched versions of B2 engine and core
> > error: B2 engine (b2) is 4.4.1
> > error: B2 core (at /home/andrzej/Repos/boost/tools/build/src) is
> > 4.9-git

I think the error message should say "re-build B2"  and tell you *in detail* how to do that.

I suspect all your further difficulties result from not rebuilding B2 (and making sure that it is visible everywhere).

I share your frustration with B2, but it does things painlessly something that no other build system does - build lots of variants of operating systems and compilers and options.  Its key feature is handling portability.  Cmake, for example, is easy to use - but only for one single users build system.

As regards your small project, you can use any documentation system - but Quickbook will have the best look and feel.
(And if you have to struggle with building the Boost.Optional docs, it will work painlessly for your project.

Good luck - and ask for help early and often.  On Boost-build <boost-build_at_[hidden]> for B2 and boost-docs_at_[hidden] for Quickbook etc.

Paul

Paul A. Bristow
Prizet Farmhouse
Kendal, Cumbria 
LA8 8AB           UK