doc/html/boostbook/documenting.html

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