Re: [Boost-build] Ticket #2232: Documentation build needs to detect missing prerequisites

From: Stefan Seefeld (seefeld_at_[hidden])
Date: 2008-08-20 08:52:11

Beman Dawes wrote:
> I've just created ticket #2232. See below.
>
> This is a very high priority issue; it has already cost Daniel and me 
> a great deal of trouble. I suspect it may be the cause of several 
> trouble reports from other Boost developers where one developer gets 
> different results from another developer.
>
> Who is willing to work on it? Neither Daniel or I know enough about 
> jam files to tackle it.
>
> --Beman
>
> ---------------
>
> Building documentation requires a lengthy tool chain to work correctly.
>
> The following tools have to be installed:
>
>    libxml2, libxslt, doxygen, docbook-xml42, docbook-xsl, tetex (?),
>    ghostscript
You are missing python-docutils, which is required for rst 
(ReStructuredText) processing. (This one has a separate issue, as it 
currently is misconfigured and results in a quite misleading error.)

In any case, I fully agree that the current state is a pita. Having this 
long a prerequisite list is bad.

>
> user-config.jam needs to supply usings for:
>
>    xsltproc, boostbook with docbook-xsl and docbook/4.2, doxygen,
>    quickbook

...and docutils.

> Experience has shown that (1) even very experienced Boost developers 
> can have missing tool chain items, and (2) missing tool chain items 
> are very difficult to diagnose and repair because the current bjam 
> setup does not issue meaningful error messages, produces partial 
> documentation, and gives the appearance of working.
>
> The requested fix is twofold:
>
> * Specific error messages should be issued if the tool chain is not 
> complete. The messages should distinguish between tools not being 
> installed and user-config.jam not having all the required entires. The 
> error messages should name the specific missing tool or missing 
> user-config.jam entry.
At what point should this validation be done ? Given how heterogenous 
the projects are in terms of doc generation, I would hope that these 
checks are target-dependent, i.e. that I don't need to set up tetex if 
the project I'm working on doesn't require it.

> * If one of the above errors is detected, the process should stop at 
> that point. Currently partial documentation is built, and that can be 
> very misleading and time-consuming. If the tool chain is wrong, 
> nothing at all should be built.
>

I would suggest that there is a build target that generates some form of 
source tarball, which includes some preprocessed stuff, such as built 
documentation. These source packages then only have a limited set of 
prerequisites, and would be used for testing.
Only those who run the 'generate-source-tarball' target would need the 
doc 'toolchains' (but not the compilers, for example).
Isn't that a useful division of concern & labour ?

Regards,
       Stefan

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