| Home | Libraries | People | FAQ | More

## Manual setup for all systems

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, `user-config.jam`. If you do not have a copy of this file in your home directory, you should copy the one that resides in `tools/build/v2` to your home directory. Alternatively, you can edit `tools/build/v2/user-config.jam` directly or a site-wide `site-config.jam` file.

### Configuring xsltproc

To configure xsltproc manually, you will need to add a directive to `user-config.jam` telling it where to find xsltproc. If the program is in your path, just add the following line to `user-config.jam`:

    using xsltproc ;

If xsltproc is somewhere else, use this directive, where `XSLTPROC` is the full pathname to xsltproc (including xsltproc):

    using xsltproc : XSLTPROC ;

### Configuring local DocBook XSL and DTD distributions

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:

- 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`). You will want to extract this archive in a subdirectory!

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 `bin.v2` directory that BBv2 generates. This is due to longstanding bug we are trying to fix.

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 `$BOOST_ROOT/libs/function/doc` and run the command `bjam --v2`: it should produce HTML documentation for the Boost.Function library in the `html` subdirectory.

### Configuring Doxygen for Documentation Extraction

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 `user-config.jam`:

    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, e.g.

    using doxygen ;

### Important

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

### Configuring Apache FOP

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 `fop.sh` on Unix and `fop.bat` on Windows. You need to specify the location of that script and Java location to Boost.Build. Add the following to your `user-config.jam` or `site-config.jam`:

    using fop : FOP_COMMAND
              : JAVA_HOME
              ;

replacing `FOP_COMMAND` with the full path to the FOP main script, and replacing `JAVA_HOME` with the directory where Java is installed. If the `JAVA_HOME` environment variable is already set, you don't need to specify it above.

To test PDF generation, switch to the directory `$BOOST_ROOT/libs/function/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.

| Copyright © 2003-2005 Douglas Gregor