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