1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Documenting libraries</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../boostbook.html" title="Chapter 49. The BoostBook Documentation Format"> 10<link rel="prev" href="getting/started.html" title="Getting Started"> 11<link rel="next" href="together.html" title="Bringing Together a BoostBook Document"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<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> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="boostbook.documenting"></a>Documenting libraries</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="documenting.html#boostbook.defining">Defining a BoostBook library</a></span></dt> 31<dt><span class="section"><a href="documenting.html#id-1.4.3.5.4">From HTML to BoostBook</a></span></dt> 32<dt><span class="section"><a href="documenting.html#boostbook.sectioning">Sectioning in BoostBook</a></span></dt> 33</dl></div> 34<p>BoostBook is an extension to <a href="http://www.docbook.org" target="_top">DocBook</a>, an XML format for 35 representing documentation. BoostBook inherits much of its 36 functionality and many elements from DocBook that are not 37 redocumented here. When writing BoostBook documentation, please 38 refer also to <a href="http://docbook.org/tdg/en/index.html" target="_top">DocBook: The Definitive 39 Guide</a>.</p> 40<div class="section"> 41<div class="titlepage"><div><div><h3 class="title"> 42<a name="boostbook.defining"></a>Defining a BoostBook library</h3></div></div></div> 43<p>BoostBook library documentation is contained entirely within 44 a <library> XML element. To create a skeletal library, we 45 need to create a new XML document (call it <code class="computeroutput">any.xml</code>) 46 that contains basic information about the library. The following 47 <a class="link" href="documenting.html#boostbook.documenting.skeletal" title="Example 49.1. A Skeletal BoostBook Library">BoostBook XML 48 example</a> describes basic information about the <a href="http://www.boost.org/libs/any/index.html" target="_top">Boost.Any</a> 49 library:</p> 50<div class="example"> 51<a name="boostbook.documenting.skeletal"></a><p class="title"><b>Example 49.1. A Skeletal BoostBook Library</b></p> 52<div class="example-contents"><pre class="programlisting"> 53<?xml version="1.0" encoding="utf-8"?> 54<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 55 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 56<library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" 57 id="any" last-revision="$Date$"> 58 <libraryinfo> 59 <author> 60 <firstname>Kevlin</firstname> 61 <surname>Henney</surname> 62 </author> 63 <librarypurpose> 64 Safe, generic container for single values of different value types 65 </librarypurpose> 66 <librarycategory name="category:data-structures"/> 67 </libraryinfo> 68</library> 69</pre></div> 70</div> 71<br class="example-break"><p>The first three lines identify this document as a BoostBook 72 <a href="http://www.w3.org/XML/" target="_top">XML</a> document. The 73 DOCTYPE line states that the document conforms to the BoostBook 74 DTD, and that the top-level element is a BoostBook 75 <library>.</p> 76<p>The <library> element actually describes the aspects 77 of BoostBook library documentation. The attributes for the 78 <library> element are:</p> 79<div class="variablelist"> 80<p class="title"><b>Attributes for the <library> element</b></p> 81<dl class="variablelist"> 82<dt><span class="term"><code class="computeroutput">name</code></span></dt> 83<dd>The full name of the library, e.g., "Any"</dd> 84<dt><span class="term"><code class="computeroutput">dirname</code></span></dt> 85<dd>The name of the directory, relative to 86 <code class="computeroutput">boost/libs</code>, in which the library 87 resides. This name may be a relative path, such as 88 <code class="computeroutput">math/octonion</code>, using "/" for the directory 89 separator.</dd> 90<dt><span class="term"><code class="computeroutput">id</code></span></dt> 91<dd>A short, unique name for the library. For libraries 92 with simple directory names (e.g., ones that do not contain 93 a "/"), this should be the same as the 94 <code class="computeroutput">dirname</code>. This <code class="computeroutput">id</code> will be used to 95 identify libraries and, for HTML output, will be used as the 96 base name for the HTML file in which the library's 97 documentation resides, so it should use only lowercase 98 alphanumeric characters and underscores.</dd> 99<dt><span class="term"><code class="computeroutput">last-revision</code></span></dt> 100<dd>Always set to <code class="computeroutput">$Date$</code>, which is 101 expanded by CVS to include the date and time that the file 102 was last modified.</dd> 103</dl> 104</div> 105<p>Inside the <library> element we have the 106 <libraryinfo> element, which gives information about the 107 library itself. It contains the author's name (there may be more 108 than one <author> element), followed by the purpose of the 109 library and the list of categorizations. The 110 <librarypurpose> element should always contain a very short 111 (single sentence) description of the library's purpose, and should 112 <span class="emphasis"><em>not</em></span> terminate with a period.</p> 113<p>The list of categories is specified by a set of 114 <librarycategory> elements. Each <librarycategory> 115 element has a <code class="computeroutput">name</code> element that identifies one of the 116 categories. The actual list of categories is in the file 117 <code class="filename">doc/src/boost.xml</code>. 118 </p> 119<p>At this point, we can apply the BoostBook XSL stylesheets to 120 <code class="computeroutput">any.xml</code> (to DocBook) followed by a DocBook XSL 121 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> 122</div> 123<div class="section"> 124<div class="titlepage"><div><div><h3 class="title"> 125<a name="id-1.4.3.5.4"></a>From HTML to BoostBook</h3></div></div></div> 126<p>Most library authors are comfortable with writing HTML 127 documentation. Writing <a href="http://www.docbook.org" target="_top">DocBook</a> documentation (and, 128 by extension, BoostBook documentation) is quite similar to writing 129 HTML, except that BoostBook uses different element names from HTML 130 (see <a class="xref" href="documenting.html#html.to.boostbook" title="Table 49.2. Converting HTML elements to BoostBook">Table 49.2, “Converting HTML elements to BoostBook”</a>) and BoostBook XML is a 131 much more rigid format than HTML.</p> 132<p>One of the easiest ways to convert HTML documentation into 133 BoostBook documentation is to use <a href="http://tidy.sourceforge.net/" target="_top">HTML Tidy</a> to transform 134 your HTML into valid XHTML, which will make sure that all elements 135 are properly closed, then apply the transformations in <a class="xref" href="documenting.html#html.to.boostbook" title="Table 49.2. Converting HTML elements to BoostBook">Table 49.2, “Converting HTML elements to BoostBook”</a> to the body of the XHTML 136 document. The following command uses HTML Tidy to transform HTML 137 into valid XHTML:</p> 138<pre class="programlisting"> 139 tidy -asxhtml input.html > output.xhtml</pre> 140<p>When converting documentation from HTML to BoostBook, note 141 that some redundant information that has to be manually maintained 142 in HTML is automatically generated in BoostBook: for instance, the 143 library categorizations, purpose, and author list described in 144 <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 145 documentation for the library and to build alphabetical and 146 categorized lists of known libraries; similarly, tables of 147 contents are built automatically from the titles of sections in 148 the BoostBook document.</p> 149<div class="table"> 150<a name="html.to.boostbook"></a><p class="title"><b>Table 49.2. Converting HTML elements to BoostBook</b></p> 151<div class="table-contents"><table class="table" summary="Converting HTML elements to BoostBook"> 152<colgroup> 153<col> 154<col> 155</colgroup> 156<thead><tr> 157<th align="left">HTML</th> 158<th align="left">BoostBook</th> 159</tr></thead> 160<tbody> 161<tr> 162<td align="left"><p><h1>, <h2>, etc.</p></td> 163<td align="left"> 164<p><section>, <title>; See <a class="xref" href="documenting.html#boostbook.sectioning" title="Sectioning in BoostBook">the section called “Sectioning in BoostBook”</a></p> 165</td> 166</tr> 167<tr> 168<td align="left"><p><i>, <em></p></td> 169<td align="left"><p><emphasis></p></td> 170</tr> 171<tr> 172<td align="left"><p><b></p></td> 173<td align="left"><p><emphasis role="bold"></p></td> 174</tr> 175<tr> 176<td align="left"><p><ol></p></td> 177<td align="left"><p><orderedlist></p></td> 178</tr> 179<tr> 180<td align="left"><p><ul></p></td> 181<td align="left"><p><itemizedlist></p></td> 182</tr> 183<tr> 184<td align="left"><p><li></p></td> 185<td align="left"><p><listitem></p></td> 186</tr> 187<tr> 188<td align="left"><p><pre></p></td> 189<td align="left"><p><programlisting></p></td> 190</tr> 191<tr> 192<td align="left"><p><code></p></td> 193<td align="left"><p><computeroutput>,<code></p></td> 194</tr> 195<tr> 196<td align="left"><p><p></p></td> 197<td align="left"><p><para>, <simpara></p></td> 198</tr> 199<tr> 200<td align="left"><p><a></p></td> 201<td align="left"> 202<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> 203</td> 204</tr> 205<tr> 206<td align="left"><p><table>, <tr>, <th>, <td></p></td> 207<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> 208</tr> 209</tbody> 210</table></div> 211</div> 212<br class="table-break"> 213</div> 214<div class="section"> 215<div class="titlepage"><div><div><h3 class="title"> 216<a name="boostbook.sectioning"></a>Sectioning in BoostBook</h3></div></div></div> 217<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> 218<pre class="programlisting"> 219<section id="any.intro"> 220 <title>Introduction</title> 221 222 <para>Introduction to a library...</para> 223 224 <section> 225 <title>A Subsection</title> 226 <para>Subsection information...</para> 227 </section> 228</section> 229</pre> 230<p>The <section> element contains all information that 231 should logically be grouped within that section. The title of the 232 section is placed within the <title> element, and any 233 paragraphs, programs, lists, tables, or subsections can occur 234 within the section. The <code class="computeroutput">id</code> attribute of the 235 <section> element gives a unique ID to each section, so that 236 it may later be identified for linking. It is suggested that all 237 IDs start with the short name of a library followed by a period, 238 so that IDs do not conflict between libraries.</p> 239</div> 240</div> 241<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 242<td align="left"></td> 243<td align="right"><div class="copyright-footer">Copyright © 2003-2005 Douglas Gregor<p>Distributed under the Boost Software License, Version 1.0. 244 (See accompanying file LICENSE_1_0.txt or copy at 245 <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>). 246 </p> 247</div></td> 248</tr></table> 249<hr> 250<div class="spirit-nav"> 251<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> 252</div> 253</body> 254</html> 255
