Re: Recommendations for documentation authors

From: John Maddock (jz.maddock_at_[hidden])
Date: 2024-01-04 09:30:20

On 03/01/2024 19:55, Robert Ramey via Boost wrote:
> On 1/3/24 8:37 AM, Andrzej Krzemienski via Boost wrote:
>
>> For now, I have upgraded my Fedora, redownloaded the Boost repo, and 
>> lo, my
>> documentation builds!
>> I guess I will never know what that was.
>>
>> Regards,
>> &rzej;
>>
>
> FWIW - here is the shell script I use to build the HTML documentation 
> for the safe numerics library.
>
> https://github.com/boostorg/safe_numerics/blob/develop/doc/boostbook/makehtml.sh 
>
>
> There is a similar one to build PDF documentation.
>
> Basically, it transforms the DocBook XML into the specified targets.  
> I don't use quickbook so I didn't need to include this is the script.  
> I'm sure it could easily be added though.
>
> I did require download a couple of tools: xstltproc, ?.dtd, etc. But 
> once that was done, things run pretty smoothly with not opaque magic.
>
> Keep it simple stupid - that's my motto.

Good shout: Boost.Math has a Makefile which does he same and includes 
the quickbook step, plus optional PDF output: 
https://github.com/boostorg/math/blob/develop/doc/win32_nmake.mak

Note that quickbook itself outputs Docbook directly, the 
BoostBook->Docbook step that Boost.Build puts in there is actually 
redundant (though mostly harmless).

John.