• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2    Copyright 2013-2018 Daniel James
3
4    Distributed under the Boost Software License, Version 1.0.
5    (See accompanying file LICENSE_1_0.txt or copy at
6    http://www.boost.org/LICENSE_1_0.txt)
7]
8
9[chapter Building documentation using Boost Build
10[id boost_doc_tools.boost_build]
11[quickbook 1.6]
12[source-mode teletype]
13]
14
15This chapter is an introduction to building boostbook and quickbook
16documentation using Boost.Build. It assumes you're already a little
17familiar with using it.
18
19[section:simple Simple examples]
20
21Starting with the simplest of examples, in
22[@boost:/tools/quickbook/examples/simple-boostbook/
23 `tools/quickbook/examples/simple-boostbook/`]
24you'll find the first example. This consists of a small boostbook file
25([@boost:/tools/quickbook/examples/simple-boostbook/simple.xml
26 `tools/quickbook/examples/simple-boostbook/simple.xml`] and a Jamfile
27to build it, which looks like this:
28
29    using boostbook ;
30
31    boostbook simple : simple.xml :
32        <xsl:param>boost.root=../../../../..
33        ;
34
35The first line just tells Boost.Build that we'll be using the boostbook
36toolset:
37
38    using boostbook ;
39
40This isn't needed if you already have a `using boostbook` line in your
41`user-config.jam` file, but it's useful for other people who don't.
42
43Next we specify the build target:
44
45    boostbook simple : simple.xml :
46
47This says that we are creating a document called `simple` from the source
48file `simple.xml`. `simple` is just an identifier for Boost.Build, html
49documentation is built in a sub-directory called `html`.
50
51After that we write the build parameters:
52
53        <xsl:param>boost.root=../../../../..
54
55This is the bare minimum, it just tells boost build where the root of the
56boost tree is, so that it can link to things like css and image files which
57the documentation uses. Getting the value right is a bit tricky - it's
58relative to the build target, which is the `html` subdirectory. The full
59path from root will be: `tools/quickbook/examples/simple-boostbook/html`,
60which has five parts, so the root is five directories up.
61
62And finally there's a `;` to end the build target.
63
64To build this example, go to the directory in the command line, and run `b2`:
65
66    cd $BOOST_ROOT
67    cd tools/quickbook/examples/simple-boostbook
68    b2
69
70You do have to be in the correct directory, as Boost.Build always
71builds the documentation in a subdirectory of the current directory.
72Having done this the documentation should be at
73`tools/quickbook/examples/simple-boostbook/html/index.html`.
74
75Building quickbook is very similar, there's a corresponding example at
76[@boost:/tools/quickbook/examples/simple-boostbook/
77 `tools/quickbook/examples/simple-boostbook/`].
78For that case, the Jamfile is:
79
80    using boostbook ;
81    using quickbook ;
82
83    xml simple-boostbook : simple.qbk ;
84
85    boostbook simple : simple-boostbook :
86        <xsl:param>boost.root=../../../../..
87        ;
88
89This time it specifies that it's using both `boostbook` and `quickbook`.
90Then there's a target to build the boostbook representation from quickbook:
91
92    xml simple-boostbook : simple.qbk ;
93
94And finally, the target to build the documentation is almost exactly the
95same, but instead of having a source file, the source is the boostbook
96xml generated from the quickbook file.
97
98[endsect] [/simple]
99
100[section:standalone Building documentation outside of the Boost tree]
101
102So far, the documentation has been built inside the boost tree, so it uses
103the boost css files and images directly from their original location.
104But when building in a separate repository the css and images files need to
105be copied into place. You can see an example of this at
106[@boost:/tools/quickbook/examples/standalone-quickbook/
107 `tools/quickbook/examples/standalone-quickbook/`]. This is in the boost
108tree, but it has a `Jamroot.jam` file which makes Boost.Build treat it as
109its own build tree. Here the Jamfile is:
110
111    using boostbook ;
112    using quickbook ;
113
114    xml simple-boostbook : simple.qbk ;
115
116    boostbook simple : simple-boostbook :
117        <dependency>css
118        <dependency>images
119        ;
120
121    install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
122        : <location>html ;
123    install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
124        : <location>html/images ;
125    explicit css ;
126    explicit images ;
127
128This time the boostbook build target is a little different:
129
130    boostbook simple : simple-boostbook :
131        <dependency>css
132        <dependency>images
133        ;
134
135There's no reason to specify `boost.root` as the css and image files are
136copied into the documentation directory, but it does need to depend on the
137`css` and `images` targets which do the copying:
138
139    install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
140        : <location>html ;
141    install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
142        : <location>html/images ;
143    explicit css ;
144    explicit images ;
145
146The `BOOST_ROOT` variable needs is set in the `Jamroot.jam` file. `css` and
147`images` are marked `explicit`, so that they're only copied when required.
148
149[endsect] [/standalone]
150