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.
>> 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 (?),
> 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
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,
>> 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
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
3) cd boost-root/libs/mpi/doc
4) Note that while boost-root/libs/mpi/doc/html was created, it doesn't
5) Note that log doesn't clearly identify the missing component, or even
clearly say that there was a serious problem.
> 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.
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk