<!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>Chapter 41. The BoostBook Documentation Format</title>
<link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="tools.html" title="Part II. Boost Tools">
<link rel="prev" href="tools.html" title="Part II. Boost Tools">
<link rel="next" href="boostbook/getting/started.html" title="Getting Started">
</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="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>
</div>
<div class="chapter">
<div class="titlepage"><div>
<div><h2 class="title">
<a name="boostbook"></a>Chapter 41. The BoostBook Documentation Format</h2></div>
<div><div class="author"><h3 class="author">
<span class="firstname">Douglas</span> <span class="surname">Gregor</span>
</h3></div></div>
<div><p class="copyright">Copyright © 2003-2005 Douglas Gregor</p></div>
<div><div class="legalnotice">
<a name="idm45555013180208"></a><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></div>
</div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="section"><a href="boostbook.html#boostbook.introduction">Introduction</a></span></dt>
<dt><span class="section"><a href="boostbook/getting/started.html">Getting Started</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.autounix">Automatic setup for Unix-like systems</a></span></dt>
<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.manual">Manual setup for all systems</a></span></dt>
<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.running">Running BoostBook</a></span></dt>
<dt><span class="section"><a href="boostbook/getting/started.html#boostbook.setup.troubleshooting">Troubleshooting</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="boostbook/documenting.html">Documenting libraries</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="boostbook/documenting.html#boostbook.defining">Defining a BoostBook library</a></span></dt>
<dt><span class="section"><a href="boostbook/documenting.html#idm45555013031568">From HTML to BoostBook</a></span></dt>
<dt><span class="section"><a href="boostbook/documenting.html#boostbook.sectioning">Sectioning in BoostBook</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="boostbook/together.html">Bringing Together a BoostBook Document</a></span></dt>
<dd><dl><dt><span class="section"><a href="boostbook/together.html#boostbook.linking">Linking in BoostBook</a></span></dt></dl></dd>
<dt><span class="section"><a href="reference.html">Reference</a></span></dt>
<dd><dl></dl></dd>
</dl>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boostbook.introduction"></a>Introduction</h2></div></div></div>
<p>The BoostBook documentation format is an extension of <a href="http://www.docbook.org" target="_top">DocBook</a>, an SGML- or
XML-based format for describing documentation. BoostBook augments
DocBook with semantic markup that aids in the documentation of C++
libraries, specifically the <a href="http://www.boost.org" target="_top">Boost C++ libraries</a>, by
providing the ability to express and refer to C++ constructs such
as namespaces, classes, overloaded functions, templates, and
specializations.</p>
<p>
BoostBook offers additional features more specific to its use for
documenting the <a href="http://www.boost.org" target="_top">Boost C++
libraries</a>. These features are intended to eliminate or
reduce the need for duplication of information and to aid in
documenting portions of Boost that might otherwise not be
documented. Examples of Boost-centric features include:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><span class="bold"><strong>Testsuites</strong></span>:
Testsuites in Boost are created by writing an appropriate
Jamfile and including that Jamfile in
<code class="filename">status/Jamfile</code>. If the testsuites are
documented (<a href="http://www.boost.org/libs/multi_array/doc/test_cases.html" target="_top">as
in the MultiArray library</a>), the documentation is
maintained separately from the testcase Jamfile, leading to
duplication of information and the possibility of having the
documentation out of sync with the Jamfile. BoostBook
contains elements that describe a testsuite for both
purposes: the BoostBook stylesheets can generate
documentation for the testcases and also generate an
appropriate Jamfile to integrate the testcases with the
regression testing system.</p></li>
<li class="listitem">
<p><span class="bold"><strong>Example programs</strong></span>:
Example programs in documentation need to be duplicated in
testcases to ensure that the examples compile and execute
correctly. Keeping the two copies in sync is a tedious and
error-prone task. For instance, the following code snippet
persisted for six months:</p>
<pre class="programlisting">
std::cout << f(5, 3) >> std::endl;
</pre>
<p>The BoostBook format allows testcases to be generated
by weaving together program fragments from example programs
in the documentation. This capability is integrated with
testsuite generation so that example programs are normal
tests in BoostBook.</p>
</li>
</ul></div>
<p>
</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"></div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>
