Boost
C++ Libraries
...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Boost
C++ Libraries
...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
 | Home | Libraries | People | FAQ | More |
To use the Boost documentation tools, you will need an XSLT processor. There are many XSLT processors available, but for now we suggest that you use xsltproc, part of libxslt. There are several ways to get libxslt, depending on your platform:
On Unix: Build and install libxml2 and then libxslt. Both libraries are part of the GNOME project.
On Windows:
With Cygwin, select the libxml2 and libxslt packages
Without Cygwin, you can at download the libxml2, libxslt, and iconv binaries. Or, use my minimal repackaged version.
You will also need a recent checkout of Boost from CVS. If you would like to limit your network bandwidth or limit delays in building documentation, now might be a good time to download the DocBook DTD and XSL stylesheets as described in the section called “Configuring local DocBook XSL and DTD distributions”.
Now we can build some documentation. Change to the directory $BOOST_ROOT/doc and run bjam --v2 to build HTML documentation. You should see several warnings like these while DocBook documentation is being built from BoostBook documentation:
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 $BOOST_ROOT/doc/html. You can also create HTML documentation in a single (large!) HTML file with the command line bjam --v2 onehtml, or Unix man pages with the command line bjam --v2 man. The complete list of output formats is listed in Table 1. Several output formats can be passed to a single invocation of bjam, e.g., bjam --v2 html man docbook would generate HTML (multiple files), man pages, and DocBook documentation.
Table 1. BoostBook Output Formats
| Format | Description |
|---|---|
| html | HTML output (multiple files). This is the default |
| onehtml | HTML output in a single HTML file. |
| man | Unix man pages. |
PDF. Requires Apache FOP. | |
| ps | Postscript. Requires Apache FOP. |
| docbook | DocBook. |
| fo | XSL Formatting Objects |
By default, the DocBook DTD and XSL stylesheets are accessed over a network automatically by the XSLT processor. However, these documents tend to be large and introduce a noticeable delay in the XSLT transformation step. This section describes how to configure Boost.Build to use local copies of the DocBook DTD and XSL stylesheets to improve processing time. There are a few requirements:
Norman Walsh's DocBook XSL stylesheets, available at the DocBook sourceforge site. Extract the DocBook XSL stylesheets to a directory on your hard disk (which we'll refer to as the DOCBOOK_XSL_DIR).
The DocBook DTD, available as a ZIP archive at the OASIS DocBook site. The package is called "DocBook XML 4.2". Extract the DocBook DTD to a directory on your hard disk (which we'll refer to as the DOCBOOK_DTD_DIR).
In the directory tools/build/new is a file named user-config.jam. Copy it to your home directory (or edit it in-place), and add a directive telling Boost.Build where to find the DocBook DTD and XSL stylesheets, replacing DOCBOOK_XSL_DIR and DOCBOOK_DTD_DIR with the paths of the DocBook XSL stylsheets and DTD, respectively:
# BoostBook configuration
using boostbook : DOCBOOK_XSL_DIR
: DOCBOOK_DTD_DIR
;Future invocations of bjam will use the specified local copies of the DTD and XSL stylesheets in lieu of downloading the same sources over the network.
This section describes the steps required to configure Apache FOP to generate PostScript and PDF output for BoostBook documents. To begin, you will need two pieces of software:
Once Java is installed (we'll call Java's directory JAVA_HOME) and Apache FOP has been extracted into a directory (we'll call FOP's directory FOP_DIR), we need to configure Boost.Build to use FOP. Edit your user-config.jam or site-config.jam and add the following, replacing FOP_DIR with the directory where Apache FOP is installed, and replace JAVA_HOME with the directory where Java is installed:
using fop : FOP_DIR
: JAVA_HOME
;In some cases, JAVA_HOME is optional, but it often helps to specify it.
To test PDF generation, switch to the directory $BOOST_ROOT/doc and execute the command bjam --v2 pdf. In the absence of any errors, Apache FOP will be executed to transform the XSL:FO output of DocBook into a PDF file.
This section details the steps necessary to use Doxygen to extract documentation and comments from source code to build a BoostBook document (and transform it into end-user documentation). You will need a somewhat recent version of Doxygen; 1.2.18 or newer should suffice.
Boost.Build can be configured for Doxygen support by editing user-config.jam or site-config.jam to add:
using doxygen : DOXYGEN ;
DOXYGEN should be replaced with the name of the doxygen executable (with full path name). If the right doxygen executable can be found via the path, this parameter can be omitted.
Generating of documentation from source files using Doxygen requires two steps. The first step involves identifying the source files so that Doxygen can process them. The second step is to specify that the output of this process, a file in the Doxygen XML format, is input for a BoostBook document. The following Jamfile.v2 illustrates a simple case of generating reference documentation for the Any library:
project boost/any/doc ; import boostbook : boostbook ; import doxygen : doxygen ; doxygen any.doxygen : ../../../boost/any.hpp ; boostbook any : any.doxygen ;
In this example, we generate the Doxygen XML representation in the file any.doxygen from the source file ../../../boost/any.hpp by invocing Doxygen. We then use any.doxygen as a source for the BoostBook target any, which will generate documentation in any format the user requests. The actual sequence of events in this transformation is:
| Last revised: , at GMT | Copyright © 2003 Douglas Gregor |
 |  |  |
| The BoostBook Documentation Format |  | Documenting libraries |