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 17:31:40

Beman Dawes wrote:

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

As I've already mentioned, it seems wrong to me to silently add more and
more dependencies.

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

Oh, this list is for that thing called Cygwin. I've no idea why they call
packages this way, and why one has to explicitly install dependency libraries,
so I'm gonna check for xsltproc *binary*, everywhere.

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

What do you mean? Detecting which tools specific docs want? I don't think
we can do that in case of latex/dvips/gs, because we don't know if doxygen
needs those.

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

Well, I've changed paths in 'using boostbook' to something wrong, as
I don't have system-wide docbook.

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

I get this:

xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/lib/lib.xsl

    XML_CATALOG_FILES=../../../bin.v2/boostbook_catalog.xml
export XML_CATALOG_FILES
 "xsltproc" --stringparam
manifest "standalone_HTML.manifest" --xinclude -o "html/" "/home/ghost/Work/Boost/boost-svn/tools/boostbook/xs..failed
xslt-xsltproc-dir html/standalone_HTML.manifest...
...failed updating 1 target...

which seems like a serious problem report to me. Do you get different output? If yes, what system
are you doing this on and do you have a log handy?

Of course, producing an error right away, and in a clear wording is better, so I'll look at #2232,
but we also need to figure what's different between our setups and causes silent error for you.

- Volodya