Re: Recommendations for documentation authors

From: John Maddock (jz.maddock_at_[hidden])
Date: 2024-01-03 09:42:38

> 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.