| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Chapter 30. 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 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 30. 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="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 << 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> |