Chapter 14. Getting Started

| Home | Libraries | People | FAQ | More

## Chapter 14. 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 the section called “Configuring local DocBook XSL and DTD distributions”. 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 Table 14.1, “BoostBook Output Formats”. 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 14.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 | 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.

| Copyright © 2003 Douglas Gregor