Re: [Boost-build] Fixing the building of documentation on Linux

Subject: Re: [Boost-build] Fixing the building of documentation on Linux
From: Daniel James (dnljms_at_[hidden])
Date: 2010-04-14 12:00:34

On 14 April 2010 15:04, Philipp Thomas <pth_at_[hidden]> wrote:
>
> while trying to also build the documentation when creating boost rpms I
> noticed that tools/build/v2/tools/boostbook.jam hasn't been adapted to
> linux because in Linux the xml stuff has standardized directories so there
> is no need for explicit paths to xml sylesheets and DTDs. I fixed that with
> the attached patch but I'd need help in making the fixes OS dependent so
> that the non-Linux case is unchanged.

There's no guarantee that the system catalog files will be setup
correctly (e.g. the user might not have root access or might be using
a distribution that doesn't set them up) so that's only appropriate if
there's some sort of configuration check first, which we generally
don't do. We'd probably also want to check if xsltproc is compiled to
use different defaults and if the appropriate environment variables
are set. Which is a lot of work for very little gain.

> BTW, I dumped the doc generation idea after I noticed that a) it needed
> hours and b) needs a java lib from SUN which has a license that is
> unacceptable to a Linux distributor.

Isn't the supplied documentation acceptable? If you want development
documentation I also upload occasional snapshots to
http://boost.cowic.de/rc/ (boost-docs.7z and boost-trunk-docs.7z, they
contain the 'doc/html' directory so you have to be careful to unzip
them in the right place).

FWIW you don't need Java for generating html, only for generating pdf.
At the moment, I don't think there are any decent open source
alternatives, the best I've managed is to generate a single html file
and print it with some appropriate css but that's not a great
solution. PhD (http://doc.php.net/phd/docs/) looks promising, but it
currently doesn't support some of the tags we use.

Daniel