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>Chapter 49. The BoostBook Documentation Format</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="tools.html" title="Part II. Boost Tools"> 10<link rel="prev" href="tools.html" title="Part II. Boost Tools"> 11<link rel="next" href="boostbook/getting/started.html" title="Getting Started"> 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="tools.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tools.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="boostbook/getting/started.html"><img src="../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="chapter"> 27<div class="titlepage"><div> 28<div><h2 class="title"> 29<a name="boostbook"></a>Chapter 49. The BoostBook Documentation Format</h2></div> 30<div><div class="author"><h3 class="author"> 31<span class="firstname">Douglas</span> <span class="surname">Gregor</span> 32</h3></div></div> 33<div><p class="copyright">Copyright © 2003-2005 Douglas Gregor</p></div> 34<div><div class="legalnotice"> 35<a name="id-1.4.3.1.3"></a><p>Distributed under the Boost Software License, Version 1.0. 36 (See accompanying file LICENSE_1_0.txt or copy at 37 <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>). 38 </p> 39</div></div> 40</div></div> 41<div class="toc"> 42<p><b>Table of Contents</b></p> 43<dl class="toc"> 44<dt><span class="section"><a href="boostbook.html#boostbook.introduction">Introduction</a></span></dt> 45<dt><span class="section"><a href="boostbook/getting/started.html">Getting Started</a></span></dt> 46<dd><dl> 47<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.autounix">Automatic setup for Unix-like systems</a></span></dt> 48<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.manual">Manual setup for all systems</a></span></dt> 49<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.running">Running BoostBook</a></span></dt> 50<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.troubleshooting">Troubleshooting</a></span></dt> 51</dl></dd> 52<dt><span class="section"><a href="boostbook/documenting.html">Documenting libraries</a></span></dt> 53<dd><dl> 54<dt><span class="section"><a href="boostbook/documenting.html#boostbook.defining">Defining a BoostBook library</a></span></dt> 55<dt><span class="section"><a href="boostbook/documenting.html#id-1.4.3.5.4">From HTML to BoostBook</a></span></dt> 56<dt><span class="section"><a href="boostbook/documenting.html#boostbook.sectioning">Sectioning in BoostBook</a></span></dt> 57</dl></dd> 58<dt><span class="section"><a href="boostbook/together.html">Bringing Together a BoostBook Document</a></span></dt> 59<dd><dl><dt><span class="section"><a href="boostbook/together.html#boostbook.linking">Linking in BoostBook</a></span></dt></dl></dd> 60<dt><span class="section"><a href="reference.html">Reference</a></span></dt> 61<dd><dl></dl></dd> 62</dl> 63</div> 64<div class="section"> 65<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 66<a name="boostbook.introduction"></a>Introduction</h2></div></div></div> 67<p>The BoostBook documentation format is an extension of <a href="http://www.docbook.org" target="_top">DocBook</a>, an SGML- or 68 XML-based format for describing documentation. BoostBook augments 69 DocBook with semantic markup that aids in the documentation of C++ 70 libraries, specifically the <a href="http://www.boost.org" target="_top">Boost C++ libraries</a>, by 71 providing the ability to express and refer to C++ constructs such 72 as namespaces, classes, overloaded functions, templates, and 73 specializations.</p> 74<p> 75 BoostBook offers additional features more specific to its use for 76 documenting the <a href="http://www.boost.org" target="_top">Boost C++ 77 libraries</a>. These features are intended to eliminate or 78 reduce the need for duplication of information and to aid in 79 documenting portions of Boost that might otherwise not be 80 documented. Examples of Boost-centric features include: 81 </p> 82<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 83<li class="listitem"><p><span class="bold"><strong>Testsuites</strong></span>: 84 Testsuites in Boost are created by writing an appropriate 85 Jamfile and including that Jamfile in 86 <code class="filename">status/Jamfile</code>. If the testsuites are 87 documented (<a href="http://www.boost.org/libs/multi_array/doc/test_cases.html" target="_top">as 88 in the MultiArray library</a>), the documentation is 89 maintained separately from the testcase Jamfile, leading to 90 duplication of information and the possibility of having the 91 documentation out of sync with the Jamfile. BoostBook 92 contains elements that describe a testsuite for both 93 purposes: the BoostBook stylesheets can generate 94 documentation for the testcases and also generate an 95 appropriate Jamfile to integrate the testcases with the 96 regression testing system.</p></li> 97<li class="listitem"> 98<p><span class="bold"><strong>Example programs</strong></span>: 99 Example programs in documentation need to be duplicated in 100 testcases to ensure that the examples compile and execute 101 correctly. Keeping the two copies in sync is a tedious and 102 error-prone task. For instance, the following code snippet 103 persisted for six months:</p> 104<pre class="programlisting"> 105std::cout << f(5, 3) >> std::endl; 106</pre> 107<p>The BoostBook format allows testcases to be generated 108 by weaving together program fragments from example programs 109 in the documentation. This capability is integrated with 110 testsuite generation so that example programs are normal 111 tests in BoostBook.</p> 112</li> 113</ul></div> 114<p> 115 </p> 116</div> 117</div> 118<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 119<td align="left"></td> 120<td align="right"><div class="copyright-footer"></div></td> 121</tr></table> 122<hr> 123<div class="spirit-nav"> 124<a accesskey="p" href="tools.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tools.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="boostbook/getting/started.html"><img src="../../doc/src/images/next.png" alt="Next"></a> 125</div> 126</body> 127</html> 128
