Boost C++ Libraries

PrevUpHomeNext

Chapter 3. Building documentation using Boost Build

Table of Contents

Simple examples
Building documentation outside of the Boost tree

This chapter is an introduction to building boostbook and quickbook documentation using Boost.Build. It assumes you're already a little familiar with using it.

Starting with the simplest of examples, in tools/quickbook/examples/simple-boostbook/ you'll find the first example. This consists of a small boostbook file (tools/quickbook/examples/simple-boostbook/simple.xml and a Jamfile to build it, which looks like this:

using boostbook ;

boostbook simple : simple.xml :
    <xsl:param>boost.root=../../../../..
    ;

The first line just tells Boost.Build that we'll be using the boostbook toolset:

using boostbook ;

This isn't needed if you already have a using boostbook line in your user-config.jam file, but it's useful for other people who don't.

Next we specify the build target:

boostbook simple : simple.xml :

This says that we are creating a document called simple from the source file simple.xml. simple is just an identifier for Boost.Build, html documentation is built in a sub-directory called html.

After that we write the build parameters:

<xsl:param>boost.root=../../../../..

This is the bare minimum, it just tells boost build where the root of the boost tree is, so that it can link to things like css and image files which the documentation uses. Getting the value right is a bit tricky - it's relative to the build target, which is the html subdirectory. The full path from root will be: tools/quickbook/examples/simple-boostbook/html, which has five parts, so the root is five directories up.

And finally there's a ; to end the build target.

To build this example, go to the directory in the command line, and run b2:

cd $BOOST_ROOT
cd tools/quickbook/examples/simple-boostbook
b2

You do have to be in the correct directory, as Boost.Build always builds the documentation in a subdirectory of the current directory. Having done this the documentation should be at tools/quickbook/examples/simple-boostbook/html/index.html.

Building quickbook is very similar, there's a corresponding example at tools/quickbook/examples/simple-boostbook/. For that case, the Jamfile is:

using boostbook ;
using quickbook ;

xml simple-boostbook : simple.qbk ;

boostbook simple : simple-boostbook :
    <xsl:param>boost.root=../../../../..
    ;

This time it specifies that it's using both boostbook and quickbook. Then there's a target to build the boostbook representation from quickbook:

xml simple-boostbook : simple.qbk ;

And finally, the target to build the documentation is almost exactly the same, but instead of having a source file, the source is the boostbook xml generated from the quickbook file.


PrevUpHomeNext