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

Subject: Re: [Boost-docs] Ticket #2232: Documentation build needs to detect missing prerequisites
From: Vladimir Prus (vladimir_at_[hidden])
Date: 2008-08-20 13:30:31

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

This list seems fairly strange to me:

- How comes we depend on tetex? And ghostscript? Is this always necessary 
for building docs, or just for maintaining some files that are subsequently
included into final docs? If the latter, then it's not our problem. If the
former, then how comes?

- libxml2 and libxslt are libraries, whereas we only need a binary called
xstlproc. How that binary works is an implementation detail of that library.

> 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, 

Note that quickbook needs no specific configuration; it's built from source
if necessary. Which leaves xstlproc, boostbook/docbook and doxygen as things
that must be configured.

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

Do you want those checks to be done even when not building docs?

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

Can you explain how exactly can I get "partial documentation" built? For
example, if I omit "using doxygen" I get hard error immediately. Also,
commenting out "using boostbook" gives me a hard error as well. 

- Volodya