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

From: Beman Dawes (bdawes_at_[hidden])
Date: 2008-08-20 11:23:37

Vladimir Prus wrote:
> 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?

IIRC, that additional dependency was introduced to support 
Boost.Accumulators. Perhaps Eric could comment?

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

I got the list from 
http://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted

If that list is wrong, you need to work with Daniel James to correct it.

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

That list also came from 
http://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted

Again, if it is wrong for any platforms, it needs to be corrected.

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

Only when building docs. Better yet, only for the specific docs being built.

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

1) Temporarily rename /usr/share/docbook-xsl and 
/usr/share/xml/docbook/4.2 something else so they won't be found.

2) On a recent trunk checkout, delete bin.v2 and libs/mpi/doc/html if 
they exist.

3) cd boost-root/libs/mpi/doc
    bjam >log

4) Note that while boost-root/libs/mpi/doc/html was created, it doesn't 
contain anything.

5) Note that log doesn't clearly identify the missing component, or even 
clearly say that there was a serious problem.

> For
> example, if I omit "using doxygen" I get hard error immediately. Also,
> commenting out "using boostbook" gives me a hard error as well. 

Hum... I tried that for libs/mpi/doc and got no error, and no 
documentation generated, either.

--Beman