| 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
|---|
| 4 | <title>Chapter 18. Documenting libraries</title> |
|---|
| 5 | <link rel="stylesheet" href="../boostbook.css" type="text/css"> |
|---|
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.69.1"> |
|---|
| 7 | <link rel="start" href="../index.html" title="The Boost C++ Libraries"> |
|---|
| 8 | <link rel="up" href="../boostbook.html" title="Part II. The BoostBook Documentation Format"> |
|---|
| 9 | <link rel="prev" href="setup/troubleshooting.html" title="Troubleshooting"> |
|---|
| 10 | <link rel="next" href="documenting/s02.html" title="From HTML to BoostBook"> |
|---|
| 11 | </head> |
|---|
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
|---|
| 13 | <table cellpadding="2" width="100%"> |
|---|
| 14 | <td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../../boost.png"></td> |
|---|
| 15 | <td align="center"><a href="../../../index.htm">Home</a></td> |
|---|
| 16 | <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
|---|
| 17 | <td align="center"><a href="../../../people/people.htm">People</a></td> |
|---|
| 18 | <td align="center"><a href="../../../more/faq.htm">FAQ</a></td> |
|---|
| 19 | <td align="center"><a href="../../../more/index.htm">More</a></td> |
|---|
| 20 | </table> |
|---|
| 21 | <hr> |
|---|
| 22 | <div class="spirit-nav"> |
|---|
| 23 | <a accesskey="p" href="setup/troubleshooting.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../boostbook.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="documenting/s02.html"><img src="../images/next.png" alt="Next"></a> |
|---|
| 24 | </div> |
|---|
| 25 | <div class="chapter" lang="en"> |
|---|
| 26 | <div class="titlepage"><div><div><h2 class="title"> |
|---|
| 27 | <a name="boostbook.documenting"></a>Chapter 18. Documenting libraries</h2></div></div></div> |
|---|
| 28 | <div class="toc"> |
|---|
| 29 | <p><b>Table of Contents</b></p> |
|---|
| 30 | <dl> |
|---|
| 31 | <dt><span class="section"><a href="documenting.html#boostbook.defining">Defining a BoostBook library</a></span></dt> |
|---|
| 32 | <dt><span class="section"><a href="documenting/s02.html">From HTML to BoostBook</a></span></dt> |
|---|
| 33 | <dt><span class="section"><a href="sectioning.html">Sectioning in BoostBook</a></span></dt> |
|---|
| 34 | </dl> |
|---|
| 35 | </div> |
|---|
| 36 | <p>BoostBook is an extension to <a href="http://www.docbook.org" target="_top">DocBook</a>, an XML format for |
|---|
| 37 | representing documentation. BoostBook inherits much of its |
|---|
| 38 | functionality and many elements from DocBook that are not |
|---|
| 39 | redocumented here. When writing BoostBook documentation, please |
|---|
| 40 | refer also to <a href="http://docbook.org/tdg/en/index.html" target="_top">DocBook: The Definitive |
|---|
| 41 | Guide</a>.</p> |
|---|
| 42 | <div class="section" lang="en"> |
|---|
| 43 | <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
|---|
| 44 | <a name="boostbook.defining"></a>Defining a BoostBook library</h2></div></div></div> |
|---|
| 45 | <p>BoostBook library documentation is contained entirely within |
|---|
| 46 | a <library> XML element. To create a skeletal library, we |
|---|
| 47 | need to create a new XML document (call it <code class="computeroutput">any.xml</code>) |
|---|
| 48 | that contains basic information about the library. The following |
|---|
| 49 | <a href="documenting.html#boostbook.documenting.skeletal" title="Example 18.1. A Skeletal BoostBook Library">BoostBook XML |
|---|
| 50 | example</a> describes basic information about the <a href="http://www.boost.org/libs/any/index.html" target="_top">Boost.Any</a> |
|---|
| 51 | library:</p> |
|---|
| 52 | <div class="example"> |
|---|
| 53 | <a name="boostbook.documenting.skeletal"></a><p class="title"><b>Example 18.1. A Skeletal BoostBook Library</b></p> |
|---|
| 54 | <pre class="programlisting"> |
|---|
| 55 | <?xml version="1.0" encoding="utf-8"?> |
|---|
| 56 | <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
|---|
| 57 | "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
|---|
| 58 | <library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" |
|---|
| 59 | id="any" last-revision="$Date: 2005/12/04 17:26:48 $"> |
|---|
| 60 | <libraryinfo> |
|---|
| 61 | <author> |
|---|
| 62 | <firstname>Kevlin</firstname> |
|---|
| 63 | <surname>Henney</surname> |
|---|
| 64 | </author> |
|---|
| 65 | <librarypurpose> |
|---|
| 66 | Safe, generic container for single values of different value types |
|---|
| 67 | </librarypurpose> |
|---|
| 68 | <librarycategory name="category:data-structures"/> |
|---|
| 69 | </libraryinfo> |
|---|
| 70 | </library> |
|---|
| 71 | </pre> |
|---|
| 72 | </div> |
|---|
| 73 | <p>The first three lines identify this document as a BoostBook |
|---|
| 74 | <a href="http://www.w3.org/XML/" target="_top">XML</a> document. The |
|---|
| 75 | DOCTYPE line states that the document conforms to the BoostBook |
|---|
| 76 | DTD, and that the top-level element is a BoostBook |
|---|
| 77 | <library>.</p> |
|---|
| 78 | <p>The <library> element actually describes the aspects |
|---|
| 79 | of BoostBook library documentation. The attributes for the |
|---|
| 80 | <library> element are:</p> |
|---|
| 81 | <div class="variablelist"> |
|---|
| 82 | <p class="title"><b>Attributes for the <library> element</b></p> |
|---|
| 83 | <dl> |
|---|
| 84 | <dt><span class="term"><code class="computeroutput">name</code></span></dt> |
|---|
| 85 | <dd>The full name of the library, e.g., "Any"</dd> |
|---|
| 86 | <dt><span class="term"><code class="computeroutput">dirname</code></span></dt> |
|---|
| 87 | <dd>The name of the directory, relative to |
|---|
| 88 | <code class="computeroutput">boost/libs</code>, in which the library |
|---|
| 89 | resides. This name may be a relative path, such as |
|---|
| 90 | <code class="computeroutput">math/octonion</code>, using "/" for the directory |
|---|
| 91 | separator.</dd> |
|---|
| 92 | <dt><span class="term"><code class="computeroutput">id</code></span></dt> |
|---|
| 93 | <dd>A short, unique name for the library. For libraries |
|---|
| 94 | with simple directory names (e.g., ones that do not contain |
|---|
| 95 | a "/"), this should be the same as the |
|---|
| 96 | <code class="computeroutput">dirname</code>. This <code class="computeroutput">id</code> will be used to |
|---|
| 97 | identify libraries and, for HTML output, will be used as the |
|---|
| 98 | base name for the HTML file in which the library's |
|---|
| 99 | documentation resides, so it should use only lowercase |
|---|
| 100 | alphanumeric characters and underscores.</dd> |
|---|
| 101 | <dt><span class="term"><code class="computeroutput">last-revision</code></span></dt> |
|---|
| 102 | <dd>Always set to <code class="computeroutput">$Date: 2005/12/04 17:26:48 $</code>, which is |
|---|
| 103 | expanded by CVS to include the date and time that the file |
|---|
| 104 | was last modified.</dd> |
|---|
| 105 | </dl> |
|---|
| 106 | </div> |
|---|
| 107 | <p>Inside the <library> element we have the |
|---|
| 108 | <libraryinfo> element, which gives information about the |
|---|
| 109 | library itself. It contains the author's name (there may be more |
|---|
| 110 | than one <author> element), followed by the purpose of the |
|---|
| 111 | library and the list of categorizations. The |
|---|
| 112 | <librarypurpose> element should always contain a very short |
|---|
| 113 | (single sentence) description of the library's purpose, and should |
|---|
| 114 | <span class="emphasis"><em>not</em></span> terminate with a period.</p> |
|---|
| 115 | <p>The list of categories is specified by a set of |
|---|
| 116 | <librarycategory> elements. Each <librarycategory> |
|---|
| 117 | element has a <code class="computeroutput">name</code> element that identifies one of the |
|---|
| 118 | categories. The actual list of categories is in the file |
|---|
| 119 | <code class="filename">doc/src/boost.xml</code>. |
|---|
| 120 | </p> |
|---|
| 121 | <p>At this point, we can apply the BoostBook XSL stylesheets to |
|---|
| 122 | <code class="computeroutput">any.xml</code> (to DocBook) followed by a DocBook XSL |
|---|
| 123 | stylesheet to generate HTML output, as described in <a href="getting/started.html" title="Chapter 17. Getting Started">Chapter 17, <i>Getting Started</i></a>.</p> |
|---|
| 124 | </div> |
|---|
| 125 | </div> |
|---|
| 126 | <table width="100%"><tr> |
|---|
| 127 | <td align="left"></td> |
|---|
| 128 | <td align="right"><small>Copyright © 2003-2005 Douglas Gregor</small></td> |
|---|
| 129 | </tr></table> |
|---|
| 130 | <hr> |
|---|
| 131 | <div class="spirit-nav"> |
|---|
| 132 | <a accesskey="p" href="setup/troubleshooting.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../boostbook.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="documenting/s02.html"><img src="../images/next.png" alt="Next"></a> |
|---|
| 133 | </div> |
|---|
| 134 | </body> |
|---|
| 135 | </html> |
|---|
