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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<!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>Documenting libraries</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../boostbook.html" title="Chapter 43. The BoostBook Documentation Format">
<link rel="prev" href="getting/started.html" title="Getting Started">
<link rel="next" href="together.html" title="Bringing Together a BoostBook Document">
</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="getting/started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boostbook.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="together.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boostbook.documenting"></a>Documenting libraries</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="documenting.html#boostbook.defining">Defining a BoostBook library</a></span></dt>
<dt><span class="section"><a href="documenting.html#idp513930992">From HTML to BoostBook</a></span></dt>
<dt><span class="section"><a href="documenting.html#boostbook.sectioning">Sectioning in BoostBook</a></span></dt>
</dl></div>
<p>BoostBook is an extension to <a href="http://www.docbook.org" target="_top">DocBook</a>, an XML format for
representing documentation. BoostBook inherits much of its
functionality and many elements from DocBook that are not
redocumented here. When writing BoostBook documentation, please
refer also to <a href="http://docbook.org/tdg/en/index.html" target="_top">DocBook: The Definitive
Guide</a>.</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.defining"></a>Defining a BoostBook library</h3></div></div></div>
<p>BoostBook library documentation is contained entirely within
a <library> XML element. To create a skeletal library, we
need to create a new XML document (call it <code class="computeroutput">any.xml</code>)
that contains basic information about the library. The following
<a class="link" href="documenting.html#boostbook.documenting.skeletal" title="Example 43.1. A Skeletal BoostBook Library">BoostBook XML
example</a> describes basic information about the <a href="http://www.boost.org/libs/any/index.html" target="_top">Boost.Any</a>
library:</p>
<div class="example">
<a name="boostbook.documenting.skeletal"></a><p class="title"><b>Example 43.1. A Skeletal BoostBook Library</b></p>
<div class="example-contents"><pre class="programlisting">
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude"
id="any" last-revision="$Date$">
<libraryinfo>
<author>
<firstname>Kevlin</firstname>
<surname>Henney</surname>
</author>
<librarypurpose>
Safe, generic container for single values of different value types
</librarypurpose>
<librarycategory name="category:data-structures"/>
</libraryinfo>
</library>
</pre></div>
</div>
<br class="example-break"><p>The first three lines identify this document as a BoostBook
<a href="http://www.w3.org/XML/" target="_top">XML</a> document. The
DOCTYPE line states that the document conforms to the BoostBook
DTD, and that the top-level element is a BoostBook
<library>.</p>
<p>The <library> element actually describes the aspects
of BoostBook library documentation. The attributes for the
<library> element are:</p>
<div class="variablelist">
<p class="title"><b>Attributes for the <library> element</b></p>
<dl>
<dt><span class="term"><code class="computeroutput">name</code></span></dt>
<dd>The full name of the library, e.g., "Any"</dd>
<dt><span class="term"><code class="computeroutput">dirname</code></span></dt>
<dd>The name of the directory, relative to
<code class="computeroutput">boost/libs</code>, in which the library
resides. This name may be a relative path, such as
<code class="computeroutput">math/octonion</code>, using "/" for the directory
separator.</dd>
<dt><span class="term"><code class="computeroutput">id</code></span></dt>
<dd>A short, unique name for the library. For libraries
with simple directory names (e.g., ones that do not contain
a "/"), this should be the same as the
<code class="computeroutput">dirname</code>. This <code class="computeroutput">id</code> will be used to
identify libraries and, for HTML output, will be used as the
base name for the HTML file in which the library's
documentation resides, so it should use only lowercase
alphanumeric characters and underscores.</dd>
<dt><span class="term"><code class="computeroutput">last-revision</code></span></dt>
<dd>Always set to <code class="computeroutput">$Date$</code>, which is
expanded by CVS to include the date and time that the file
was last modified.</dd>
</dl>
</div>
<p>Inside the <library> element we have the
<libraryinfo> element, which gives information about the
library itself. It contains the author's name (there may be more
than one <author> element), followed by the purpose of the
library and the list of categorizations. The
<librarypurpose> element should always contain a very short
(single sentence) description of the library's purpose, and should
<span class="emphasis"><em>not</em></span> terminate with a period.</p>
<p>The list of categories is specified by a set of
<librarycategory> elements. Each <librarycategory>
element has a <code class="computeroutput">name</code> element that identifies one of the
categories. The actual list of categories is in the file
<code class="filename">doc/src/boost.xml</code>.
</p>
<p>At this point, we can apply the BoostBook XSL stylesheets to
<code class="computeroutput">any.xml</code> (to DocBook) followed by a DocBook XSL
stylesheet to generate HTML output, as described in <a class="xref" href="getting/started.html" title="Getting Started">the section called “Getting Started”</a>.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="idp513930992"></a>From HTML to BoostBook</h3></div></div></div>
<p>Most library authors are comfortable with writing HTML
documentation. Writing <a href="http://www.docbook.org" target="_top">DocBook</a> documentation (and,
by extension, BoostBook documentation) is quite similar to writing
HTML, except that BoostBook uses different element names from HTML
(see <a class="xref" href="documenting.html#html.to.boostbook" title="Table 43.2. Converting HTML elements to BoostBook">Table 43.2, “Converting HTML elements to BoostBook”</a>) and BoostBook XML is a
much more rigid format than HTML.</p>
<p>One of the easiest ways to convert HTML documentation into
BoostBook documentation is to use <a href="http://tidy.sourceforge.net/" target="_top">HTML Tidy</a> to transform
your HTML into valid XHTML, which will make sure that all elements
are properly closed, then apply the transformations in <a class="xref" href="documenting.html#html.to.boostbook" title="Table 43.2. Converting HTML elements to BoostBook">Table 43.2, “Converting HTML elements to BoostBook”</a> to the body of the XHTML
document. The following command uses HTML Tidy to transform HTML
into valid XHTML:</p>
<pre class="programlisting">
tidy -asxhtml input.html > output.xhtml</pre>
<p>When converting documentation from HTML to BoostBook, note
that some redundant information that has to be manually maintained
in HTML is automatically generated in BoostBook: for instance, the
library categorizations, purpose, and author list described in
<a class="xref" href="documenting.html#boostbook.defining" title="Defining a BoostBook library">the section called “Defining a BoostBook library”</a> are used both in the
documentation for the library and to build alphabetical and
categorized lists of known libraries; similarly, tables of
contents are built automatically from the titles of sections in
the BoostBook document.</p>
<div class="table">
<a name="html.to.boostbook"></a><p class="title"><b>Table 43.2. Converting HTML elements to BoostBook</b></p>
<div class="table-contents"><table class="table" summary="Converting HTML elements to BoostBook">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th align="left">HTML</th>
<th align="left">BoostBook</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><p><h1>, <h2>, etc.</p></td>
<td align="left">
<p><section>, <title>; See <a class="xref" href="documenting.html#boostbook.sectioning" title="Sectioning in BoostBook">the section called “Sectioning in BoostBook”</a></p>
</td>
</tr>
<tr>
<td align="left"><p><i>, <em></p></td>
<td align="left"><p><emphasis></p></td>
</tr>
<tr>
<td align="left"><p><b></p></td>
<td align="left"><p><emphasis role="bold"></p></td>
</tr>
<tr>
<td align="left"><p><ol></p></td>
<td align="left"><p><orderedlist></p></td>
</tr>
<tr>
<td align="left"><p><ul></p></td>
<td align="left"><p><itemizedlist></p></td>
</tr>
<tr>
<td align="left"><p><li></p></td>
<td align="left"><p><listitem></p></td>
</tr>
<tr>
<td align="left"><p><pre></p></td>
<td align="left"><p><programlisting></p></td>
</tr>
<tr>
<td align="left"><p><code></p></td>
<td align="left"><p><computeroutput>,<code></p></td>
</tr>
<tr>
<td align="left"><p><p></p></td>
<td align="left"><p><para>, <simpara></p></td>
</tr>
<tr>
<td align="left"><p><a></p></td>
<td align="left">
<p><xref>, <link>, <ulink>;, See <a class="xref" href="together.html#boostbook.linking" title="Linking in BoostBook">the section called “Linking in BoostBook”</a></p>
</td>
</tr>
<tr>
<td align="left"><p><table>, <tr>, <th>, <td></p></td>
<td align="left"><p><table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good <a href="http://opensource.bureau-cornavin.com/crash-course/en/tables.html" target="_top">tutorial here</a></p></td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.sectioning"></a>Sectioning in BoostBook</h3></div></div></div>
<p>"Sectioning" refers to organization of a document into separate sections, each with a title, some text, and possibly subsections. Each section is described in BoostBook via a <section> element. An introduction section may look like this:</p>
<pre class="programlisting">
<section id="any.intro">
<title>Introduction</title>
<para>Introduction to a library...</para>
<section>
<title>A Subsection</title>
<para>Subsection information...</para>
</section>
</section>
</pre>
<p>The <section> element contains all information that
should logically be grouped within that section. The title of the
section is placed within the <title> element, and any
paragraphs, programs, lists, tables, or subsections can occur
within the section. The <code class="computeroutput">id</code> attribute of the
<section> element gives a unique ID to each section, so that
it may later be identified for linking. It is suggested that all
IDs start with the short name of a library followed by a period,
so that IDs do not conflict between libraries.</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">Copyright © 2003-2005 Douglas Gregor<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></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="getting/started.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boostbook.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="together.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
|
