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