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

Subject: [Boost-docs] Ticket #2232: Documentation build needs to detect missing prerequisites
From: Beman Dawes (bdawes_at_[hidden])
Date: 2008-08-20 11:20:07

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

user-config.jam needs to supply usings for:

    xsltproc, boostbook with docbook-xsl and docbook/4.2, doxygen,
    quickbook

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.

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