1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Getting Started</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../../boostbook.html" title="Chapter 48. The BoostBook Documentation Format">
<link rel="prev" href="../../boostbook.html" title="Chapter 48. The BoostBook Documentation Format">
<link rel="next" href="../documenting.html" title="Documenting libraries">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../boostbook.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../boostbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../documenting.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boostbook.getting.started"></a>Getting Started</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="started.html#boostbook.setup.autounix">Automatic setup for Unix-like systems</a></span></dt>
<dt><span class="section"><a href="started.html#boostbook.setup.manual">Manual setup for all systems</a></span></dt>
<dt><span class="section"><a href="started.html#boostbook.setup.running">Running BoostBook</a></span></dt>
<dt><span class="section"><a href="started.html#boostbook.setup.troubleshooting">Troubleshooting</a></span></dt>
</dl></div>
<p>To use the Boost documentation tools, you will need several tools:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<p class="simpara"><span class="command"><strong>xsltproc</strong></span>:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem">Windows with <a href="http://www.cygwin.com/" target="_top">Cygwin</a>: select the libxml2 and libxslt packages.</li>
<li class="listitem">Windows without Cygwin: Download the <a href="http://www.zlatkovic.com/pub/libxml/" target="_top">binary packages</a>
from Igor Zlatkovic. At the very least, you'll need iconv, zlib, libxml2 and libxslt.</li>
<li class="listitem">Mac OS X with Fink: Get the <code class="computeroutput">libxslt</code> package.</li>
<li class="listitem">Mac OS X without Fink: <a href="http://www.zveno.com/open_source/libxml2xslt.html" target="_top">Download the libxslt binaries</a>
</li>
<li class="listitem">Any platform: <a href="http://xmlsoft.org/XSLT/" target="_top">libxslt source</a>.</li>
</ul></div>
</li>
<li class="listitem">
<p class="simpara"><span class="command"><strong>doxygen</strong></span>:</p> Available from <a href="http://www.doxygen.org" target="_top">http://www.doxygen.org</a>
</li>
</ul></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.setup.autounix"></a>Automatic setup for Unix-like systems</h3></div></div></div>
<p>BoostBook provides a nearly-automatic setup script. Once
you have downloaded and
installed <span class="command"><strong>xsltproc</strong></span>, <span class="command"><strong>doxygen</strong></span>,
and (optionally) <span class="command"><strong>java</strong></span>, the setup script can
download the required DocBook stylesheets, DocBook DTD, and
(when Java is enabled) Apache FOP for PDF output. It will then
configure Boost.Build version 2 to build BoostBook
documentation.</p>
<p>The script requires: <span class="command"><strong>sh</strong></span>,
<span class="command"><strong>curl</strong></span> and <span class="command"><strong>gunzip</strong></span>.
To perform the installation, execute the
script <span class="command"><strong>tools/boostbook/setup_boostbook.sh</strong></span>
from a directory where you would like the resulting XSL, DTD,
and Apache FOP installations to occur. </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.setup.manual"></a>Manual setup for all systems</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="started.html#boostbook.setup.xsltproc">Configuring <span class="command"><strong>xsltproc</strong></span></a></span></dt>
<dt><span class="section"><a href="started.html#boostbook.setup.docbook">Configuring local DocBook XSL and DTD distributions</a></span></dt>
<dt><span class="section"><a href="started.html#boostbook.setup.doxygen">Configuring Doxygen for Documentation Extraction</a></span></dt>
<dt><span class="section"><a href="started.html#boostbook.setup.fop">Configuring Apache FOP</a></span></dt>
</dl></div>
<p>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,
<code class="filename">user-config.jam</code>. If you do not have a copy
of this file in your home directory, you should copy the one
that resides in <code class="computeroutput">tools/build/</code> to your home
directory. Alternatively, you can edit
<code class="filename">tools/build/user-config.jam</code> directly or
a site-wide <code class="filename">site-config.jam</code> file.</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boostbook.setup.xsltproc"></a>Configuring <span class="command"><strong>xsltproc</strong></span>
</h4></div></div></div>
<p>To configure <span class="command"><strong>xsltproc</strong></span> manually, you
will need to add a directive to
<code class="filename">user-config.jam</code> telling it where to find
<span class="command"><strong>xsltproc</strong></span>. If the program is in your path,
just add the following line to
<code class="filename">user-config.jam</code>:</p>
<pre class="programlisting">using xsltproc ;</pre>
<p>If <span class="command"><strong>xsltproc</strong></span> is somewhere else, use
this directive, where <code class="computeroutput">XSLTPROC</code> is the full
pathname to <span class="command"><strong>xsltproc</strong></span> (including
<span class="command"><strong>xsltproc</strong></span>):</p>
<pre class="programlisting">using xsltproc : XSLTPROC ;</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boostbook.setup.docbook"></a>Configuring local DocBook XSL and DTD distributions</h4></div></div></div>
<p>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:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>Norman Walsh's DocBook XSL stylesheets,
available at the <a href="http://docbook.sourceforge.net" target="_top">DocBook sourceforge
site</a>. Extract the DocBook XSL stylesheets to a
directory on your hard disk (which we'll refer to as the
<code class="computeroutput">DOCBOOK_XSL_DIR</code>).</p></li>
<li class="listitem"><p>The DocBook DTD, available as a ZIP archive
at the <a href="http://www.oasis-open.org/docbook/xml/4.2/" target="_top">OASIS
DocBook site</a>. 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
<code class="computeroutput">DOCBOOK_DTD_DIR</code>). You will want to extract this
archive in a subdirectory!</p></li>
</ul></div>
<p>
</p>
<p>Add the following directive telling BBv2 where to find
the DocBook DTD and XSL stylesheets:</p>
<pre class="programlisting"># BoostBook configuration
using boostbook
: DOCBOOK_XSL_DIR
: DOCBOOK_DTD_DIR
;</pre>
<p>Whenever you change this directive, you will need to
remove the <code class="computeroutput">bin.v2</code> directory that BBv2 generates.
This is due to longstanding bug we are trying to fix.</p>
<p>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 <code class="filename">$BOOST_ROOT/libs/function/doc</code> and
run the command <code class="computeroutput">bjam</code>: it should produce HTML
documentation for the Boost.Function library in the
<code class="computeroutput">html</code> subdirectory.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boostbook.setup.doxygen"></a>Configuring Doxygen for Documentation Extraction</h4></div></div></div>
<p>Doxygen is required to build the documentation for
several Boost libraries. You will need a recent version of
<a href="http://www.doxygen.org" target="_top">Doxygen</a> (most of
the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the
following directive to
<code class="filename">user-config.jam</code>:</p>
<pre class="programlisting">using doxygen : DOXYGEN ;</pre>
<p><code class="filename">DOXYGEN</code> should be replaced with the
name of the <span class="command"><strong>doxygen</strong></span> executable (with full
path name). If the right <span class="command"><strong>doxygen</strong></span> executable
can be found via the path, this parameter can be
omitted, e.g.</p>
<pre class="programlisting">using doxygen ;</pre>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>The relative order of declarations in
<code class="filename">user-config.jam</code> /
<code class="filename">site-config.jam</code> files is
significant. In particular, the <code class="literal">using
doxygen</code> line should come
<span class="emphasis"><em>after</em></span> the <code class="literal">using
boostbook</code> declaration.
</p></td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boostbook.setup.fop"></a>Configuring Apache FOP</h4></div></div></div>
<p>In order to generate PDF and PostScript output using
Apache FOP, you will need a <a href="http://java.sun.com" target="_top">Java interpreter</a> and <a href="http://xml.apache.org/fop/download.html" target="_top">Apache FOP</a>
(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 <code class="filename">fop.sh</code> on Unix
and <code class="filename">fop.bat</code> on Windows. You need to specify
the location of that script and Java location to
Boost.Build. Add the following to your
<code class="filename">user-config.jam</code> or
<code class="filename">site-config.jam</code>:
</p>
<pre class="programlisting">
using fop : FOP_COMMAND
: JAVA_HOME
;
</pre>
<p> replacing
<code class="computeroutput">FOP_COMMAND</code> with the full path to the FOP main script, and
replacing <code class="computeroutput">JAVA_HOME</code> with the directory where Java is
installed. If the <code class="envar">JAVA_HOME</code> environment variable is
already set, you don't need to specify it above.
</p>
<p>
Proper generation of images in PDFs depends on the <a href="http://java.sun.com/products/jimi/#" target="_top">Jimi Image
Library</a>. To get FOP to use Jimi, extract the
<code class="filename">JimiProClasses.zip</code> file from the Jimi SDK
and rename it—if on Windows, to
<code class="filename">jimi-1.0.jar</code>, or if on *nix, to
<code class="filename">JimiProClasses.jar</code>—and place it in the
<code class="filename">lib/</code> subdirectory of your FOP
installation.
</p>
<p>To test PDF generation, switch to the directory <code class="filename">$BOOST_ROOT/libs/function/doc</code> and
execute the command <span class="command"><strong>bjam pdf</strong></span>. In the
absence of any errors, Apache FOP will be executed to transform
the XSL:FO output of DocBook into a PDF file.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.setup.running"></a>Running BoostBook</h3></div></div></div>
<p>Once BoostBook has been configured, we can build some
documentation. First, change to the directory
<code class="computeroutput">$BOOST_ROOT/doc</code> and remove (or make writable) the
<code class="computeroutput">.html</code> files in
<code class="computeroutput">$BOOST_ROOT/doc/html</code>. Then, run <code class="computeroutput">bjam</code>
to build HTML documentation. You should see several
warnings like these while DocBook documentation is being built
from BoostBook documentation:</p>
<pre class="programlisting">Cannot find function named 'checked_delete'
Cannot find function named 'checked_array_delete'
Cannot find function named 'next'</pre>
<p>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
<code class="computeroutput">$BOOST_ROOT/doc/html</code>. You can also create HTML
documentation in a single (large!) HTML file with the command line
<code class="computeroutput">bjam onehtml</code>, or Unix man pages with the command
line <code class="computeroutput">bjam man</code>. The complete list of output
formats is listed in <a class="xref" href="started.html#boostbook.output.formats" title="Table 48.1. BoostBook Output Formats">Table 48.1, “BoostBook Output Formats”</a>. Several output formats can
be passed to a single invocation of <code class="computeroutput">bjam</code>, e.g.,
<code class="computeroutput">bjam html man docbook</code> would generate HTML
(multiple files), man pages, and DocBook documentation.</p>
<div class="table">
<a name="boostbook.output.formats"></a><p class="title"><b>Table 48.1. BoostBook Output Formats</b></p>
<div class="table-contents"><table class="table" summary="BoostBook Output Formats">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>Format</th>
<th>Description</th>
</tr></thead>
<tbody>
<tr>
<td>html</td>
<td><p>HTML output (multiple files). This is the default</p></td>
</tr>
<tr>
<td>onehtml</td>
<td><p>HTML output in a single HTML file.</p></td>
</tr>
<tr>
<td>man</td>
<td><p>Unix man pages.</p></td>
</tr>
<tr>
<td>pdf</td>
<td><p>PDF. Requires <a href="http://xml.apache.org/fop/index.html" target="_top">Apache FOP</a>.</p></td>
</tr>
<tr>
<td>ps</td>
<td><p>Postscript. Requires <a href="http://xml.apache.org/fop/index.html" target="_top">Apache FOP</a>.</p></td>
</tr>
<tr>
<td>docbook</td>
<td>
<a href="http://www.docbook.org/" target="_top">DocBook</a>.</td>
</tr>
<tr>
<td>fo</td>
<td><a href="http://www.w3.org/TR/xsl/" target="_top">XSL Formatting Objects</a></td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.setup.troubleshooting"></a>Troubleshooting</h3></div></div></div>
<p>The Boost documentation tools are still in their early phase of
development, and some things don't work as seamlessly as we would like
them to, yet. In particular, error messages can be somewhat
uninformative at times. If you find yourself in the situation when
you have double checked everything, and yet things still don't work as
expected, consider helping the tools by deleting
<code class="literal">bin.v2</code> build directory.
</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2003-2005 Douglas Gregor<p>Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
<a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../boostbook.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../boostbook.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../documenting.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
