quickbook/doc/boost-doc-tools/boost-build.qbk

[/
    Copyright 2013-2018 Daniel James

    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
]

[chapter Building documentation using Boost Build
[id boost_doc_tools.boost_build]
[quickbook 1.6]
[source-mode teletype]
]

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.

[section:simple Simple examples]

Starting with the simplest of examples, in
[@boost:/tools/quickbook/examples/simple-boostbook/
 `tools/quickbook/examples/simple-boostbook/`]
you'll find the first example. This consists of a small boostbook file
([@boost:/tools/quickbook/examples/simple-boostbook/simple.xml
 `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
[@boost:/tools/quickbook/examples/simple-boostbook/
 `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.

[endsect] [/simple]

[section:standalone Building documentation outside of the Boost tree]

So far, the documentation has been built inside the boost tree, so it uses
the boost css files and images directly from their original location.
But when building in a separate repository the css and images files need to
be copied into place. You can see an example of this at
[@boost:/tools/quickbook/examples/standalone-quickbook/
 `tools/quickbook/examples/standalone-quickbook/`]. This is in the boost
tree, but it has a `Jamroot.jam` file which makes Boost.Build treat it as
its own build tree. Here the Jamfile is:

    using boostbook ;
    using quickbook ;

    xml simple-boostbook : simple.qbk ;

    boostbook simple : simple-boostbook :
        <dependency>css
        <dependency>images
        ;

    install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
        : <location>html ;
    install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
        : <location>html/images ;
    explicit css ;
    explicit images ;

This time the boostbook build target is a little different:

    boostbook simple : simple-boostbook :
        <dependency>css
        <dependency>images
        ;

There's no reason to specify `boost.root` as the css and image files are
copied into the documentation directory, but it does need to depend on the
`css` and `images` targets which do the copying:

    install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
        : <location>html ;
    install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
        : <location>html/images ;
    explicit css ;
    explicit images ;

The `BOOST_ROOT` variable needs is set in the `Jamroot.jam` file. `css` and
`images` are marked `explicit`, so that they're only copied when required.

[endsect] [/standalone]