boost_1_45_0/doc/html/boostbook.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Chapter&#160;30.&#160;The BoostBook Documentation Format</title>
<link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="tools.html" title="Part&#160;II.&#160;Boost Tools">
<link rel="prev" href="tools.html" title="Part&#160;II.&#160;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&#160;30.&#160;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 &#169; 2003-2005 Douglas Gregor</p></div>
<div><div class="legalnotice">
<a name="id3221814"></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>
<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#id3223148">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" 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 &lt;&lt; f(5, 3) &gt;&gt; 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>