need help with building QuickBook docs

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2022-05-21 22:59:50

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.

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
>

Ok, I learned to live with it and to launch b2 from tools/build. It used to
work for a while, but yesterday when I did a `git pull --rebase` on Boost
repo, it no longer works. I get an error:

Jamfile.v2:45: Unescaped special character in argument
> <format>pdf:<xsl:param>boost.url.prefix=
> http://www.boost.org/doc/libs/release/libs/optional/doc/html
> Performing configuration checks
>
>     - default address-model    : 64-bit (cached) [1]
> error: at /home/andrzej/Repos/boost/tools/build/src/kernel/modules.jam:106
> error: Unable to find file or target named
> error:     '/boost/architecture//mips'
> error: referred to from project at
> error:     '.'
>

Ok, I can remove line `: /boost/architecture//mips` from file
`boostcpp.jam`. (Am I supposed to do it before using `b2`?). But then, when
trying to build the docs, I get a lot of errors, saying:

runtime error: file
> /home/andrzej/Repos/boost/tools/boostbook/xsl/annotation.xsl line 432
> element element
> xsl:element: The effective name '' is not a valid QName.
>

(Full error message is enclosed.) I have no clue which element in the
pipeline is causing or reporting this. QuickBook, BoostBook, DocBook,
xsltproc? The process involves many components, at least according to this
diagram:
https://svn.boost.org/trac10/wiki/BoostDocs/GettingStarted

Is this something obvious that I am missing?
Is this a good idea, or a recommended practice to use QuickBook nowadays
for Boost docs?

I feel comfortable fixing or writing C++ code, and I am willing to devote
some of my limited time to do this. But fighting with QuickBook
documentation is something I would not rather do.

I have a small library that I considered submitting to Boost:
https://github.com/akrzemi1/markable
But as long as it is on my GitHub page, it is simple to maintain, test and
document. If I imagine how many nights I will have to spend making the
documentation compatible with Boost, or getting all the b2-related stuff to
work, I feel discouraged. Maybe I am being unfair to `b2` now. But it is
certainly my personal emotional impression.

I do not mind the current Boost website format or the underlying technology.
I do not mind the mailing list format.
My primary obstacle is this perceived or real difficulty to get a boost
library into a shape where it just builds, including its documentation. My
ideal as a Boost library maintainer, is that I just provide the source for
the library and the documentation, and anything else "just works". Maybe
this is not achievable, but the closer to this ideal, the more encouraged I
would be to consider authoring or maintaining a library.

Any help in fixing my build problem is most welcome.

Regards,
&rzej;