Re: Recommendations for documentation authors

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2024-01-02 16:22:25

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.

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.

>From your output it looks like the problem is during conversion from
BoostBook to DocBook. Which means either BoostBook content is broken, or
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.