Re: [Boost-build] building documentation with boostbook

Subject: Re: [Boost-build] building documentation with boostbook
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2015-07-17 12:51:25

On 17/07/15 12:39 PM, John Maddock wrote:
>
> There is no boostbook tool as such, just the docbook stylesheets. Have
> you looked at
> https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted ?

Not yet.

(I'm fairly familiar with XML, and DocBook in particular, having even
GSOC-mentored a student once to integrate BoostBook into DocBook 5, in
the hopes to simplify this entire process. Sadly, that never got
completed...)

But I'm also saddened to see that, again, things are so fragile that one
needs to become an expert in yet another tangential area just to be able
to build boost. (I really want to work on Boost.Python, not hack the
Boost build system !!)

>
> Note that:
>
> * System installed stylesheets are probably not what you need anyway
> since we're tied to a specific docbook DTD version - using any other
> DTD version will almost certainly cause you grief.  The XSL
> stylesheets and system supplied xsltproc you can of course use.

Yeah, I noticed. Perhaps one day I'll get enough motivated to finish the
BoostBook DocBook 5 integration, so Boost doesn't have to continue
maintaining this process.

>
> * I'd also generally advise against FOP for anything but
> casual/lightweight use as it tends not be very reliable sadly :(

So far fop has been serving me well. I know of (some of) its
limitations, but can live with that, in particular for lack of viable /
Free alternatives. (Note that the BoostBook setup script is still using
fop 0.94, which is *extremely* old. We are now at FOP 2.0, which works
fairly well. Perhaps it's time for Boost to update its documentation
build logic, and in doing that, make it possible / easier for upstream
package maintainers to provide boost packages containing those tools and
required infrastructure ?

Thanks,
        Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...