Douglas
Gregor
2003
Douglas Gregor

Permission to copy, use, sell and distribute this software is granted provided this copyright notice appears in all copies. Permission to modify the code and to distribute modified code is granted provided this copyright notice appears in all copies, and a notice that the code was modified is included with the copyright notice.

This software is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

# The BoostBook Documentation Format

## Introduction

The BoostBook documentation format is an extension of DocBook, an SGML- or XML-based format for describing documentation. BoostBook augments DocBook with semantic markup that aids in the documentation of C++ libraries, specifically the Boost C++ libraries, by providing the ability to express and refer to C++ constructs such as namespaces, classes, overloaded functions, templates, and specializations.

BoostBook offers additional features more specific to its use for documenting the Boost C++ libraries. These features are intended to eliminate or reduce the need for duplication of information and to aid in documenting portions of Boost that might otherwise not be documented. Examples of Boost-centric features include:

- Testsuites: Testsuites in Boost are created by writing an appropriate Jamfile and including that Jamfile in `status/Jamfile`. If the testsuites are documented (as in the MultiArray library), the documentation is maintained separately from the testcase Jamfile, leading to duplication of information and the possibility of having the documentation out of sync with the Jamfile. BoostBook contains elements that describe a testsuite for both purposes: the BoostBook stylesheets can generate documentation for the testcases and also generate an appropriate Jamfile to integrate the testcases with the regression testing system.

- Example programs: Example programs in documentation need to be duplicated in testcases to ensure that the examples compile and execute correctly. Keeping the two copies in sync is a tedious and error-prone task. For instance, the following code snippet persisted for six months:

      std::cout << f(5, 3) >> std::endl;

  The BoostBook format allows testcases to be generated by weaving together program fragments from example programs in the documentation. This capability is integrated with testsuite generation so that example programs are normal tests in BoostBook.

- Library categorization: BoostBook contains primitives for placing libraries into categories and generating categorized and alphabetized lists of libraries.

## Getting Started

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 need a patched version of the tools available from here.

- On MacOS X:

  - If you have Fink, just get the `libxslt` and `doxygen` packages.

    Without Fink, you can download the libxslt binaries.

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 . You should delete or make writable the `.html` files in `$BOOST_ROOT/doc/html` before continuing.

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

### 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 | PDF. Requires Apache FOP.
ps | Postscript. Requires Apache FOP.
docbook | DocBook.
fo | XSL Formatting Objects

### Configuring local DocBook XSL and DTD distributions

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/v2` 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.

### Configuring Apache FOP for PostScript/PDF Output

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:

- A Java interpreter, available at .

- Apache FOP, available at . Version 0.20.4 seems to be most stable.

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.

### Configuring Doxygen for Documentation Extraction

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.

The relative order of declarations in `user-config.jam` / `site-config.jam` files is significant. In particular, `using doxygen` line should come after the `using boostbook` declaration.

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:

1. Doxygen parses the header file `../../../boost/any.hpp` and outputs a single XML file `any.doxygen`.

2. The XSLT processor applies the stylesheet `doxygen2boostbook.xsl` to transform `any.doxygen` into the BoostBook file `any.xml`.

3. The XSLT processor applies the stylesheet `docbook.xsl` to transform `any.xml` into the DocBook XML document `any.docbook`.

4. Further transformations may generate HTML, FO, PDF, etc. from `any.docbook`.

### Troubleshooting

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 `bin.v2` build directory.