[Boost-users] [units] Problem building HTML documentation from QuickBook sources

From: Torsten Mähne (Torsten.Maehne_at_[hidden])
Date: 2007-12-06 13:32:03

Hello,

I'm very interested in the Boost.Units library. I've been therefore
trying to use the version, which is available from the Boost Sandbox SVN
repository (Revision 41778):

svn co http://svn.boost.org/svn/boost/sandbox/units boost_units

I've no problems using the header-only Boost.Units library in my own
small test programs, but I'm struggling to build the reference
documentation located in libs/units/doc/. Therefore, I'm currently
forced to use the outdated HTML documentation from the
mcs_units_v0.7.2.zip archive available from the Boost file vault or read
directly the units.qbk source.

I'm using Boost.Units together with boost-1.34.1, which is unpacked in a
parallel directory:

$ ls
boost-1.34.1
boost_units

on my laptop running Debian Etch:

$ uname -a
Linux babylon5 2.6.18-5-686 #1 SMP Wed Oct 3 00:12:50 UTC 2007 i686
GNU/Linux
$ g++ --version
g++ (GCC) 4.1.2 20061115 (prerelease) (Debian 4.1.1-21)

After defining the environment variable:

BOOST_BUILD_PATH=<absolute_path_to_boost-1.34.1>/tools/build/v2

and creating the following user-config.jam in $BOOST_BUILD_PATH, I was
able to build the boost libraries itself, and the HTML and PDF
documentation from their Boost.Book and Quickbook sources:

#### Begin user-config.jam ####
using gcc : 4.1 : g++-4.1 ;

using xsltproc : "/usr/bin/xsltproc" ;

using boostbook
         : "/usr/share/xml/docbook/stylesheet/nwalsh/"
         : "/usr/share/xml/docbook/schema/dtd/4.2"
         ;

using doxygen : "/usr/bin/doxygen" ;

using fop : "/usr/bin/fop"
          : "/usr/lib/jvm/java-6-sun-1.6.0.00"
          ;
##### End user-config.jam #####

I have to admit that I don't fully understand yet the boost.build
system, but I achieved to create the necessary Jamroot file in
boost_units/ (my working copy of the units library). It contains only

#### Begin of Jamroot ####
use-project boost
  : ../boost-1.34.1 ;
##### End of Jamroot #####

Then I was able to build the tests in libs/units/test and
libs/units/test_headers. All tests in tests in libs/units/test and only
the test for non_si_units.hpp fails in libs/units/test_headers. Judging
from the #define error in this header, it seems to be expected. But
running bjam in the libs/units/doc directory fails after outputting
several times:

runtime error: file
/home/maehne/build/boost-1.34.1/tools/boostbook/xsl/docbook.xsl line 338
element element
xsl:element: The QName 'xi:include' has no namespace binding in scope in
the stylesheet; this is an error, since the namespace was not s
pecified by the instruction itself.

There are also a lot of warnings like:

warning: cannot find header `boost/units/operators.hpp'
warning: cannot find header `boost/units/systems/trig.hpp'
Cannot find class named 'boost::units::unit'
Cannot find class named 'boost::units::quantity'

I've seen on the Boost developers mailing list, that there were
previously problems with Boost.Book discussed as in the thread from
"[units] Boost.Book problems" from August 2007
<http://lists.boost.org/Archives/boost/2007/08/126004.php>.

I also tried to use boost-trunk from the SVN repository (revision
41797). But then I seem to run into the same error, which was posted by
John Maddock <http://lists.boost.org/Archives/boost/2007/08/126031.php>
in the above mentioned thread:

Generate XML output for dir /home/torsten/build/boost-units/boost/
Generate XML output for dir
/home/torsten/build/boost-units/boost/units/systems/physical_dimensions/
Generate XML output for dir
/home/torsten/build/boost-units/boost/units/systems/
Generate XML output for dir /home/torsten/build/boost-units/boost/units/
[1]+  Done                    rm -f
"bin/gcc-4.2.2/debug/dimensions_reference-xml/*.xml"
xslt-xsltproc bin/gcc-4.2.2/debug/dimensions_reference-xml.doxygen
xslt-xsltproc bin/gcc-4.2.2/debug/dimensions_reference-xml.boostbook
warning: failed to load external entity "Reference"
cannot parse Reference

  XML_CATALOG_FILES=../../../../boost-trunk/bin.v2/boostbook_catalog.xml
export XML_CATALOG_FILES
 "/usr/bin/xsltproc" --stringparam boost.doxygen.reftitle ""Dimensions
Reference"" --xinclude -o
"bin/gcc-4.2.2/debug/dimensions_reference-xml.boostbook"
"/home/torsten/build/boost-trunk/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl"
"bin/gcc-4.2.2/debug/dimensions_reference-xml.doxygen"

...failed xslt-xsltproc
bin/gcc-4.2.2/debug/dimensions_reference-xml.boostbook...
...skipped <p.>dimensions_reference.xml for lack of
<pbin/gcc-4.2.2/debug>dimensions_reference-xml.boostbook...
...skipped <pbin/gcc-4.2.2/debug>units.docbook for lack of
<p.>trig_reference.xml...
...skipped <phtml>standalone_HTML.manifest for lack of
<pbin/gcc-4.2.2/debug>units.docbook...
...failed updating 7 targets...
...skipped 10 targets...
...updated 64 targets...
Exit 1

Am I doing something wrong or am I facing a bug in the Boost.Units,
Boost.Book or QuickBook? Could maybe someone, who succeeded to build the
Boost.Units documentation, send it to me in HTML or PDF format?

Best regards,

Torsten Mähne