1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
<!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 48. The BoostBook Documentation Format</title>
<link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.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 48. 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="idp615571488"></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#idp615720272">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>
|
