[Boost-users] [boostbook] Building Boost documentation

From: Edward Diener (eldiener_at_[hidden])
Date: 2007-11-17 06:08:10

Because I wanted to read documentation on some of the new libraries in
the latest Boost SVN repository, which existed only in XML format, it
was time to go through the annual rite of attempting to use Doug
Gregor's excellent documention of "The Boostbook Documentation Format"
in order to setup the documentation system to generate documentation
using bjam. Although Mr. Gregor's documentation is extremely good, I
have never been completely successful in the past, but I had my fingers
crossed in hopeful expectation this time. I am doing this on Windows so
I have to set things up manually.

1) I downloaded xsltproc and doxygen successfully, and "installed" them
into appropriate directories and, to make things easy for myself, put
those directories in my PATH.

2) After making sure I had no .jam file of any kind in my home directory
I went to the \tools\build\v2\user-config,jam in the directory in which
the latest  Boost Subversion resides, and added the line:

using xsltproc ;

3) I downloaded the latest XSL stylesheets and Docbook DTD and put them
in their own separate directies, "E:\Utilities\docbook-xsl-1.73.2" and
"E:\Utilities\docbook-dtd-4.2".

4) I added to my user-config.jam the lines:

#  BoostBook configuration
using boostbook
    : E:/Utilities/docbook-xsl-1.73.2
    : E:/Utilities/docbook-dtd-4.2
    ;

5) Now further following instructions to test out my installation so far
I went to the \libs\function\doc after copying boostbook.css from the
\doc\html directory, and tried the bjam command. My result is:

warning: Graph library does not contain optional GraphML reader.
note: to enable GraphML support, set EXPAT_INCLUDE and EXPAT_LIBPATH to the
note: directories containing the Expat headers and libraries, respectively.
warning: skipping optional Message Passing Interface (MPI) library.
note: to enable MPI support, add "using mpi ;" to user-config.jam.
note: to suppress this message, pass "--without-mpi" to bjam.
note: otherwise, you can safely ignore this message.
Building Boost.Regex with the optional Unicode/ICU support disabled.
Please refer to the Boost.Regex documentation for more information
(don't panic: this is a strictly optional feature).
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/tools\boostbook.jam:300:
   in object(boostbook-generator)@326.run
warning: rulename $(base-target).depends expands to empty string
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:840
: in try-one-generator-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:902
: in try-one-generator
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:111
0: in construct-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:118
6: in generators.construct
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:1398:
in construct
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:1242:
in object(typed-target)@327.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:765: 

i
n generate-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:738: 

i
n object(main-target)@331.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:255: 

i
n object(project-target)@325.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2\build-system.jam:402: 

in
   load
E:\Utilities\BoostLibraries\boost_1_34_0\tools\build\v2/kernel\modules.jam:261:
in import
E:\Utilities\BoostLibraries\boost_1_34_0\tools\build\v2/kernel/bootstrap.jam:132
: in boost-build
E:\Programming\Version Control\Subversion\Boost\boost-build.jam:9: in
module sco
pe
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/tools\boostbook.jam:307:
   in object(boostbook-generator)@326.run
warning: rulename $(target[2]).set-path expands to empty string
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:840
: in try-one-generator-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:902
: in try-one-generator
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:111
0: in construct-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:118
6: in generators.construct
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:1398:
in construct
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:1242:
in object(typed-target)@327.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:765: 

i
n generate-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:738: 

i
n object(main-target)@331.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:255: 

i
n object(project-target)@325.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2\build-system.jam:402: 

in
   load
E:\Utilities\BoostLibraries\boost_1_34_0\tools\build\v2/kernel\modules.jam:261:
in import
E:\Utilities\BoostLibraries\boost_1_34_0\tools\build\v2/kernel/bootstrap.jam:132
: in boost-build
E:\Programming\Version Control\Subversion\Boost\boost-build.jam:9: in
module sco
pe
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/tools\boostbook.jam:308:
   in object(boostbook-generator)@326.run
warning: rulename $(target[2]).depends expands to empty string
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:840
: in try-one-generator-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:902
: in try-one-generator
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:111
0: in construct-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\generators.jam:118
6: in generators.construct
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:1398:
in construct
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:1242:
in object(typed-target)@327.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:765: 

i
n generate-really
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:738: 

i
n object(main-target)@331.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/build\targets.jam:255: 

i
n object(project-target)@325.generate
E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2\build-system.jam:402: 

in
   load
E:\Utilities\BoostLibraries\boost_1_34_0\tools\build\v2/kernel\modules.jam:261:
in import
E:\Utilities\BoostLibraries\boost_1_34_0\tools\build\v2/kernel/bootstrap.jam:132
: in boost-build
E:\Programming\Version Control\Subversion\Boost\boost-build.jam:9: in
module sco
pe
warn: Unable to construct ./function-doc
...found 1 target...

6) I have no doubt done something wrong, but I have no idea what.
Anybody have any clues ?