1<?xml version="1.0" encoding="utf-8"?> 2<!-- 3 Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> 4 5 Distributed under the Boost Software License, Version 1.0. 6 (See accompanying file LICENSE_1_0.txt or copy at 7 http://www.boost.org/LICENSE_1_0.txt) 8 --> 9<!DOCTYPE part PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 10 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 11<part xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook" 12 last-revision="$Date$"> 13 <partinfo> 14 <author> 15 <firstname>Douglas</firstname> 16 <surname>Gregor</surname> 17 </author> 18 19 <copyright> 20 <year>2003</year> 21 <year>2004</year> 22 <year>2005</year> 23 <holder>Douglas Gregor</holder> 24 </copyright> 25 26 <legalnotice> 27 <para>Distributed under the Boost Software License, Version 1.0. 28 (See accompanying file LICENSE_1_0.txt or copy at 29 <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>). 30 </para> 31 </legalnotice> 32 </partinfo> 33 34 <title>The BoostBook Documentation Format</title> 35 36 <chapter id="boostbook.introduction"> 37 <title>Introduction</title> 38 39 <para>The BoostBook documentation format is an extension of <ulink 40 url="http://www.docbook.org">DocBook</ulink>, an SGML- or 41 XML-based format for describing documentation. BoostBook augments 42 DocBook with semantic markup that aids in the documentation of C++ 43 libraries, specifically the <ulink 44 url="http://www.boost.org">Boost C++ libraries</ulink>, by 45 providing the ability to express and refer to C++ constructs such 46 as namespaces, classes, overloaded functions, templates, and 47 specializations.</para> 48 49 <para> 50 BoostBook offers additional features more specific to its use for 51 documenting the <ulink url="http://www.boost.org">Boost C++ 52 libraries</ulink>. These features are intended to eliminate or 53 reduce the need for duplication of information and to aid in 54 documenting portions of Boost that might otherwise not be 55 documented. Examples of Boost-centric features include: 56 <itemizedlist> 57 <listitem> 58 <para><emphasis role="bold">Testsuites</emphasis>: 59 Testsuites in Boost are created by writing an appropriate 60 Jamfile and including that Jamfile in 61 <filename>status/Jamfile</filename>. If the testsuites are 62 documented (<ulink 63 url="http://www.boost.org/libs/multi_array/doc/test_cases.html">as 64 in the MultiArray library</ulink>), the documentation is 65 maintained separately from the testcase Jamfile, leading to 66 duplication of information and the possibility of having the 67 documentation out of sync with the Jamfile. BoostBook 68 contains elements that describe a testsuite for both 69 purposes: the BoostBook stylesheets can generate 70 documentation for the testcases and also generate an 71 appropriate Jamfile to integrate the testcases with the 72 regression testing system.</para> 73 </listitem> 74 <listitem> 75 <para><emphasis role="bold">Example programs</emphasis>: 76 Example programs in documentation need to be duplicated in 77 testcases to ensure that the examples compile and execute 78 correctly. Keeping the two copies in sync is a tedious and 79 error-prone task. For instance, the following code snippet 80 persisted for six months:</para> 81<programlisting> 82std::cout << f(5, 3) >> std::endl; 83</programlisting> 84 <para>The BoostBook format allows testcases to be generated 85 by weaving together program fragments from example programs 86 in the documentation. This capability is integrated with 87 testsuite generation so that example programs are normal 88 tests in BoostBook.</para> 89 </listitem> 90 </itemizedlist> 91 </para> 92 </chapter> 93 94 <chapter id="boostbook.getting.started"> 95 <title>Getting Started</title> 96 97 <para>To use the Boost documentation tools, you will need several tools:</para> 98 <itemizedlist> 99 <listitem><simpara><command>xsltproc</command>:</simpara> 100 <itemizedlist> 101 <listitem>Windows with <ulink 102 url="http://www.cygwin.com/">Cygwin</ulink>: select the libxml2 and libxslt packages.</listitem> 103 <listitem>Windows without Cygwin: Download the <ulink url="http://www.zlatkovic.com/pub/libxml/">binary packages</ulink> 104 from Igor Zlatkovic. At the very least, you'll need iconv, zlib, libxml2 and libxslt.</listitem> 105 <listitem>Mac OS X with Fink: Get the <code>libxslt</code> package.</listitem> 106 <listitem>Mac OS X without Fink: <ulink url="http://www.zveno.com/open_source/libxml2xslt.html">Download the libxslt binaries</ulink></listitem> 107 <listitem>Any platform: <ulink 108 url="http://xmlsoft.org/XSLT/">libxslt source</ulink>.</listitem> 109 </itemizedlist> 110 </listitem> 111 <listitem><simpara><command>doxygen</command>:</simpara> Available from <ulink url="http://www.doxygen.org">http://www.doxygen.org</ulink></listitem> 112 </itemizedlist> 113 114 <section id="boostbook.setup.autounix"> 115 <title>Automatic setup for Unix-like systems</title> 116 117 <para>BoostBook provides a nearly-automatic setup script. Once 118 you have downloaded and 119 installed <command>xsltproc</command>, <command>doxygen</command>, 120 and (optionally) <command>java</command>, the setup script can 121 download the required DocBook stylesheets, DocBook DTD, and 122 (when Java is enabled) Apache FOP for PDF output. It will then 123 configure Boost.Build version 2 to build BoostBook 124 documentation.</para> 125 126 <para>The script requires: <command>sh</command>, 127 <command>curl</command> and <command>gunzip</command>. 128 To perform the installation, execute the 129 script <command>tools/boostbook/setup_boostbook.sh</command> 130 from a directory where you would like the resulting XSL, DTD, 131 and Apache FOP installations to occur. </para> 132 </section> 133 134 <section id="boostbook.setup.manual"> 135 <title>Manual setup for all systems</title> 136 137 <para>This section describes how to manually configure Boost 138 Boost version 2 (BBv@) for BoostBook. If you can use the 139 automatic setup script, you should. All configuration will 140 happen in the BBv2 user configuration file, 141 <filename>user-config.jam</filename>. If you do not have a copy 142 of this file in your home directory, you should copy the one 143 that resides in <code>tools/build/</code> to your home 144 directory. Alternatively, you can edit 145 <filename>tools/build/user-config.jam</filename> directly or 146 a site-wide <filename>site-config.jam</filename> file.</para> 147 148 <section id="boostbook.setup.xsltproc"> 149 <title>Configuring <command>xsltproc</command></title> 150 151 <para>To configure <command>xsltproc</command> manually, you 152 will need to add a directive to 153 <filename>user-config.jam</filename> telling it where to find 154 <command>xsltproc</command>. If the program is in your path, 155 just add the following line to 156 <filename>user-config.jam</filename>:</para> 157 158<programlisting>using xsltproc ;</programlisting> 159 160 <para>If <command>xsltproc</command> is somewhere else, use 161 this directive, where <code>XSLTPROC</code> is the full 162 pathname to <command>xsltproc</command> (including 163 <command>xsltproc</command>):</para> 164 165<programlisting>using xsltproc : XSLTPROC ;</programlisting> 166 </section> 167 168 <section id="boostbook.setup.docbook"> 169 <title>Configuring local DocBook XSL and DTD distributions</title> 170 171 <para>This section describes how to configure Boost.Build to 172 use local copies of the DocBook DTD and XSL stylesheets to 173 improve processing time. You will first need to download two 174 packages: 175 176 <itemizedlist> 177 <listitem><para>Norman Walsh's DocBook XSL stylesheets, 178 available at the <ulink 179 url="http://docbook.sourceforge.net">DocBook sourceforge 180 site</ulink>. Extract the DocBook XSL stylesheets to a 181 directory on your hard disk (which we'll refer to as the 182 <code>DOCBOOK_XSL_DIR</code>).</para> 183 </listitem> 184 185 <listitem><para>The DocBook DTD, available as a ZIP archive 186 at the <ulink 187 url="http://www.oasis-open.org/docbook/xml/4.2/">OASIS 188 DocBook site</ulink>. The package is called "DocBook XML 189 4.2". Extract the DocBook DTD to a directory on your hard 190 disk (which we'll refer to as the 191 <code>DOCBOOK_DTD_DIR</code>). You will want to extract this 192 archive in a subdirectory!</para></listitem> 193 </itemizedlist> 194 </para> 195 196 <para>Add the following directive telling BBv2 where to find 197 the DocBook DTD and XSL stylesheets:</para> 198 199 <programlisting># BoostBook configuration 200using boostbook 201 : DOCBOOK_XSL_DIR 202 : DOCBOOK_DTD_DIR 203 ;</programlisting> 204 205 <para>Whenever you change this directive, you will need to 206 remove the <code>bin.v2</code> directory that BBv2 generates. 207 This is due to longstanding bug we are trying to fix.</para> 208 209 <para>At this point, you should be able to build HTML 210 documentation for libraries that do not require Doxygen. To 211 test this, change into the directory <filename 212 class="directory">$BOOST_ROOT/libs/function/doc</filename> and 213 run the command <code>bjam</code>: it should produce HTML 214 documentation for the Boost.Function library in the 215 <code>html</code> subdirectory.</para> 216 </section> 217 218 <section id="boostbook.setup.doxygen"> 219 <title>Configuring Doxygen for Documentation Extraction</title> 220 221 <para>Doxygen is required to build the documentation for 222 several Boost libraries. You will need a recent version of 223 <ulink url="http://www.doxygen.org">Doxygen</ulink> (most of 224 the 1.3.x and 1.4.x versions will suffice). BBv2 by adding the 225 following directive to 226 <filename>user-config.jam</filename>:</para> 227 228 <programlisting>using doxygen : DOXYGEN ;</programlisting> 229 230 <para><filename>DOXYGEN</filename> should be replaced with the 231 name of the <command>doxygen</command> executable (with full 232 path name). If the right <command>doxygen</command> executable 233 can be found via the path, this parameter can be 234 omitted, e.g.</para> 235 236 <programlisting>using doxygen ;</programlisting> 237 238 <important> 239 <para>The relative order of declarations in 240 <filename>user-config.jam</filename> / 241 <filename>site-config.jam</filename> files is 242 significant. In particular, the <literal>using 243 doxygen</literal> line should come 244 <emphasis>after</emphasis> the <literal>using 245 boostbook</literal> declaration. 246 </para> 247 </important> 248 </section> 249 250 <section id="boostbook.setup.fop"> 251 <title>Configuring Apache FOP</title> 252 253 <para>In order to generate PDF and PostScript output using 254 Apache FOP, you will need a <ulink 255 url="http://java.sun.com">Java interpreter</ulink> and <ulink 256 url="http://xml.apache.org/fop/download.html">Apache FOP</ulink> 257 (version 0.20.5 is best). Unpack Apache FOP to some 258 directory. The top level directory of the FOP tool should 259 contain a main script called <filename>fop.sh</filename> on Unix 260 and <filename>fop.bat</filename> on Windows. You need to specify 261 the location of that script and Java location to 262 Boost.Build. Add the following to your 263 <filename>user-config.jam</filename> or 264 <filename>site-config.jam</filename>: 265<programlisting> 266using fop : FOP_COMMAND 267 : JAVA_HOME 268 ; 269</programlisting> replacing 270 <code>FOP_COMMAND</code> with the full path to the FOP main script, and 271 replacing <code>JAVA_HOME</code> with the directory where Java is 272 installed. If the <envar>JAVA_HOME</envar> environment variable is 273 already set, you don't need to specify it above. 274 </para> 275 276 <para> 277 Proper generation of images in PDFs depends on the <ulink 278 url="http://java.sun.com/products/jimi/#">Jimi Image 279 Library</ulink>. To get FOP to use Jimi, extract the 280 <filename>JimiProClasses.zip</filename> file from the Jimi SDK 281 and rename it—if on Windows, to 282 <filename>jimi-1.0.jar</filename>, or if on *nix, to 283 <filename>JimiProClasses.jar</filename>—and place it in the 284 <filename>lib/</filename> subdirectory of your FOP 285 installation. 286 </para> 287 288 <para>To test PDF generation, switch to the directory <filename 289 class="directory">$BOOST_ROOT/libs/function/doc</filename> and 290 execute the command <command>bjam pdf</command>. In the 291 absence of any errors, Apache FOP will be executed to transform 292 the XSL:FO output of DocBook into a PDF file.</para> 293 </section> 294 </section> 295 296 <section id="boostbook.setup.running"> 297 <title>Running BoostBook</title> 298 299 <para>Once BoostBook has been configured, we can build some 300 documentation. First, change to the directory 301 <code>$BOOST_ROOT/doc</code> and remove (or make writable) the 302 <code>.html</code> files in 303 <code>$BOOST_ROOT/doc/html</code>. Then, run <code>bjam</code> 304 to build HTML documentation. You should see several 305 warnings like these while DocBook documentation is being built 306 from BoostBook documentation:</para> 307 308 <programlisting>Cannot find function named 'checked_delete' 309Cannot find function named 'checked_array_delete' 310Cannot find function named 'next'</programlisting> 311 312 <para>These warnings are emitted when the Boost documentation 313 tools cannot find documentation for functions, methods, or classes 314 that are referenced in the source, and are not harmful in any 315 way. Once Boost.Jam has completed its execution, HTML 316 documentation for Boost will be available in 317 <code>$BOOST_ROOT/doc/html</code>. You can also create HTML 318 documentation in a single (large!) HTML file with the command line 319 <code>bjam onehtml</code>, or Unix man pages with the command 320 line <code>bjam man</code>. The complete list of output 321 formats is listed in <xref 322 linkend="boostbook.output.formats"/>. Several output formats can 323 be passed to a single invocation of <code>bjam</code>, e.g., 324 <code>bjam html man docbook</code> would generate HTML 325 (multiple files), man pages, and DocBook documentation.</para> 326 327 <table id="boostbook.output.formats"> 328 <title>BoostBook Output Formats</title> 329 <tgroup cols="2"> 330 <thead> 331 <row><entry>Format</entry><entry>Description</entry></row> 332 </thead> 333 <tbody> 334 <row> 335 <entry>html</entry> 336 <entry><simpara>HTML output (multiple files). This is the default</simpara></entry> 337 </row> 338 <row> 339 <entry>onehtml</entry> 340 <entry><simpara>HTML output in a single HTML file.</simpara></entry> 341 </row> 342 <row> 343 <entry>man</entry> 344 <entry><simpara>Unix man pages.</simpara></entry> 345 </row> 346 <row> 347 <entry>pdf</entry> 348 <entry><simpara>PDF. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry> 349 </row> 350 <row> 351 <entry>ps</entry> 352 <entry><simpara>Postscript. Requires <ulink url="http://xml.apache.org/fop/index.html">Apache FOP</ulink>.</simpara></entry> 353 </row> 354 <row> 355 <entry>docbook</entry> 356 <entry><ulink url="http://www.docbook.org/">DocBook</ulink>.</entry> 357 </row> 358 <row> 359 <entry>fo</entry> 360 <entry><ulink url="http://www.w3.org/TR/xsl/">XSL Formatting Objects</ulink></entry> 361 </row> 362 </tbody> 363 </tgroup> 364 </table> 365 </section> 366 367 <section id="boostbook.setup.troubleshooting"> 368 <title>Troubleshooting</title> 369 370 <para>The Boost documentation tools are still in their early phase of 371 development, and some things don't work as seamlessly as we would like 372 them to, yet. In particular, error messages can be somewhat 373 uninformative at times. If you find yourself in the situation when 374 you have double checked everything, and yet things still don't work as 375 expected, consider helping the tools by deleting 376 <literal>bin.v2</literal> build directory. 377 </para> 378 379 </section> 380 </chapter> 381 382 <xi:include href="documenting.xml"/> 383 <xi:include href="together.xml"/> 384 <xi:include href="reference.xml"/> 385</part> 386