So, let me give you my story, and maybe you -- or anyone else in this list -- can give me some advice. As probably most of us, I have only limited time to devote to Boost maintenance. I have one library in charge that I inherited from Fernando: Boost.Optional. I inherited a working toolchain for producing documentation and I try not to touch it: only modify the content. There is a Jamfile that to the initiated probably tells everything: https://github.com/boostorg/optional/blob/develop/doc/Jamfile.v2 I do not know what it does exactly. I know it uses BoostBook and QuickBook. It uses xsltproc indirectly, I guess. Correct, think of quickbook as an "easy" way to write Docbook XML, everything else is just a means of converting the XML to a human readable output.
Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already? No idea. I tried to have a look at QuickBook docs ( https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html) and I cannot figure out if it is a format or a tool that transforms one format into another. I guess it is the latter, but what does it output? Docbook XML.
How many tools do I have to learn to write documentation for a Boost Library?
Only quickbook. I agree that the long toolchain required to transform the XML into something useful is painful to set up. Ironically it was chosen precisely because it was externally maintained.
Of course, I could learn all of it. If I had unlimited time. But I only have like a couple of hours in a week or sometimes month. I barely have time to do the maintenance of the source code and the tests.
This is my experience, but I suppose something similar is faced by anyone who considers proposing their libraries into Boost.
I enclose the output from my running the `b2` command in folder doc. I would greatly appreciate it if anyone can help me fix this.
I suspect the information we need isn't showing up in there, and this all works for me locally, I'm using: xsltproc: libxml 20708, libxslt 10126 and libexslt 815 Docbook DTD 4.2 Docbook XSL stylesheets 1.79.1 My hunch is that you "upgraded" the docbook DTD to something other than 4.2 - and that's wrong, it's not something that can ever be upgraded, it's a language specification, and we're fixed in stone at version 4.2. Very occasionally, newer versions of the stylesheets can cause issues, but these are rare, and the stylesheets are well maintained IMO.
But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed.
The idea was to transform to a common language (Docbook) that multiple external tools could parse and handle the actual formatting in a range of outputs (html, pdf, man, html-help etc). John.