On 1/2/24 16:23, Andrzej Krzemienski wrote:
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 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.
Can I use QuickBook without a BoostBook for the Boost documentation? Is someone doing it already?
My admittedly superfluous understanding is, the pipeline used in the Jamfile is QuickBook -> BoostBook -> DocBook -> HTML. Optionally, the final destination may be PDF instead of HTML, but I don't think we regularly build it these days, so it is of little interest. The xml rule in the Jamfile invokes QuickBook and produces BoostBook on output. The boostbook rule does the rest. For some libraries, you can also see a doxygen rule, which, as you may have guessed, invokes Doxygen and produces BoostBook output, which is then included into QuickBook output via `xinclude` directive and gets into the final output as part of the BoostBook content. Doing so allows to reference Doxygen-generated content from QuickBook content. I haven't seen any library using a direct QuickBook -> HTML pipeline, although the QuickBook executable has the command line switches for it. I haven't looked whether b2 has support for it either.
I tried to have a look at QuickBook docs (https://www.boost.org/doc/libs/1_84_0/doc/html/quickbook.html 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?
It is both the markup format and the tool that converts content in that format to another format. Primarily, BoostBook. BoostBook is a Boost's extension of the standard DocBook format. Both are XML, and therefore are mainly processed with XSL stylesheets. The stylesheets to convert BoostBook to DocBook are in tools/boostbook. Stylesheets and tools for processing DocBook are installed externally (e.g. on Debian-based systems, via the docbook-xml package).
How many tools do I have to learn to write documentation for a Boost Library?
If you mean documentation using QuickBook then at least two: b2 and QuickBook. You need b2 because it is used to build official Boost documentation. And you need QuickBook because, well, you write in it. You don't need to know BoostBook, although for advanced usage it may be useful. For example, you may want to insert BoostBook fragments into QuickBook if you want to use some feature not supported by QuickBook. You may want to look into its stylesheets though, if you want to know what individual xml parameters do in the Jamfile (look for xsl:param tags in tools/boostbook/xsl). Most parameters have a description.
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.
From your output it looks like the problem is during conversion from BoostBook to DocBook. Which means either BoostBook content is broken, or
Boost.Optional docs build successfully for me, albeit with a few warnings. I have created a PR to fox the warnings. I am using up-to-date everything from Boost develop. there is a problem with the BoostBook stylesheets. Check if your tools/boostbook is pristine and up-to-date, and rebuild tools/quickbook from scratch using `b2 release link=static`. Then try building the docs again, from scratch.
But even if this is fixed, I would still want to know why this chain of QuickBook -> BoostBook is needed.
This follows from my description above. BoostBook is a means to integrate Doxygen output into the docs and a way to produce different kinds of output (HTML or PDF). While the latter is of little demand lately, Doxygen integration is a very much needed feature.