To use the Boost documentation tools, you will need several tools:
BoostBook provides a nearly-automatic setup script. Once you have downloaded and installed xsltproc, doxygen, and (optionally) java, the setup script can download the required DocBook stylesheets, DocBook DTD, and (when Java is enabled) Apache FOP for PDF output. It will then configure Boost.Build version 2 to build BoostBook documentation. To perform the installation, execute the script tools/boostbook/setup_boostbook.sh from a directory where you would like the resulting XSL, DTD, and Apache FOP installations to occur. This section describes how to manually configure Boost
Boost version 2 (BBv@) for BoostBook. If you can use the
automatic setup script, you should. All configuration will
happen in the BBv2 user configuration file,
To configure xsltproc manually, you
will need to add a directive to
using xsltproc ; If xsltproc is somewhere else, use
this directive, where using xsltproc : XSLTPROC ; This section describes how to configure Boost.Build to use local copies of the DocBook DTD and XSL stylesheets to improve processing time. You will first need to download two packages:
Add the following directive telling BBv2 where to find the DocBook DTD and XSL stylesheets: # BoostBook configuration using boostbook : DOCBOOK_XSL_DIR : DOCBOOK_DTD_DIR ; Whenever you change this directive, you will need to
remove the At this point, you should be able to build HTML
documentation for libraries that do not require Doxygen. To
test this, change into the directory Doxygen is required to build the documentation for
several Boost libraries. You will need a recent version of
Doxygen (most of
the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the
following directive to
using doxygen : DOXYGEN ;
using doxygen ;
In order to generate PDF and PostScript output using
Apache FOP, you will need a Java interpreter and Apache FOP
(version 0.20.5 is best). Unpack Apache FOP to some
directory. The top level directory of the FOP tool should
contain a main script called using fop : FOP_COMMAND : JAVA_HOME ; replacing
Proper generation of images in PDFs depends on the Jimi Image
Library. To get FOP to use Jimi, extract the
To test PDF generation, switch to the directory Once BoostBook has been configured, we can build some
documentation. First, change to the directory
Cannot find function named 'checked_delete' Cannot find function named 'checked_array_delete' Cannot find function named 'next' These warnings are emitted when the Boost documentation
tools cannot find documentation for functions, methods, or classes
that are referenced in the source, and are not harmful in any
way. Once Boost.Jam has completed its execution, HTML
documentation for Boost will be available in
Table?27.1.?BoostBook Output Formats
The Boost documentation tools are still in their early phase of
development, and some things don't work as seamlessly as we would like
them to, yet. In particular, error messages can be somewhat
uninformative at times. If you find yourself in the situation when
you have double checked everything, and yet things still don't work as
expected, consider helping the tools by deleting
|