ceph/src/boost/tools/boostbook/doc/documenting.xml

   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 &lt;library&gt; 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 &lt;?xml version="1.0" encoding="utf-8"?&gt;
  40 &lt;!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  41   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"&gt;
  42 &lt;library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude"
  43   id="any" last-revision="$Date$"&gt;
  44   &lt;libraryinfo&gt;
  45     &lt;author&gt;
  46       &lt;firstname&gt;Kevlin&lt;/firstname&gt;
  47       &lt;surname&gt;Henney&lt;/surname&gt;
  48     &lt;/author&gt;
  49     &lt;librarypurpose&gt;
  50       Safe, generic container for single values of different value types
  51     &lt;/librarypurpose&gt;
  52     &lt;librarycategory name="category:data-structures"/&gt;
  53   &lt;/libraryinfo&gt;
  54 &lt;/library&gt;
  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     &lt;library&gt;.</para>
  63
  64     <para>The &lt;library&gt; element actually describes the aspects
  65     of BoostBook library documentation. The attributes for the
  66     &lt;library&gt; element are:</para>
  67
  68     <variablelist>
  69       <title>Attributes for the &lt;library&gt; 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 &lt;library&gt; element we have the
 110     &lt;libraryinfo&gt; element, which gives information about the
 111     library itself. It contains the author's name (there may be more
 112     than one &lt;author&gt; element), followed by the purpose of the
 113     library and the list of categorizations. The
 114     &lt;librarypurpose&gt; 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     &lt;librarycategory&gt; elements. Each &lt;librarycategory&gt;
 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 &gt; 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>&lt;h1&gt;, &lt;h2&gt;, etc.</simpara></entry>
 176             <entry>
 177 <simpara>&lt;section&gt;, &lt;title&gt;; See <xref
 178 linkend="boostbook.sectioning"/></simpara>
 179 </entry>
 180           </row>
 181           <row>
 182             <entry><simpara>&lt;i&gt;, &lt;em&gt;</simpara></entry>
 183             <entry><simpara>&lt;emphasis&gt;</simpara></entry>
 184           </row>
 185           <row>
 186             <entry><simpara>&lt;b&gt;</simpara></entry>
 187             <entry><simpara>&lt;emphasis role="bold"&gt;</simpara></entry>
 188           </row>
 189           <row>
 190             <entry><simpara>&lt;ol&gt;</simpara></entry>
 191             <entry><simpara>&lt;orderedlist&gt;</simpara></entry>
 192           </row>
 193           <row>
 194             <entry><simpara>&lt;ul&gt;</simpara></entry>
 195             <entry><simpara>&lt;itemizedlist&gt;</simpara></entry>
 196           </row>
 197           <row>
 198             <entry><simpara>&lt;li&gt;</simpara></entry>
 199             <entry><simpara>&lt;listitem&gt;</simpara></entry>
 200           </row>
 201           <row>
 202             <entry><simpara>&lt;pre&gt;</simpara></entry>
 203             <entry><simpara>&lt;programlisting&gt;</simpara></entry>
 204           </row>
 205           <row>
 206             <entry><simpara>&lt;code&gt;</simpara></entry>
 207             <entry><simpara>&lt;computeroutput&gt;,&lt;code&gt;</simpara></entry>
 208           </row>
 209           <row>
 210             <entry><simpara>&lt;p&gt;</simpara></entry>
 211             <entry><simpara>&lt;para&gt;, &lt;simpara&gt;</simpara></entry>
 212           </row>
 213           <row>
 214             <entry><simpara>&lt;a&gt;</simpara></entry>
 215             <entry>
 216 <simpara>&lt;xref&gt;, &lt;link&gt;, &lt;ulink&gt;;, See <xref
 217 linkend="boostbook.linking"/></simpara></entry>
 218           </row>
 219           <row>
 220             <entry><simpara>&lt;table&gt;, &lt;tr&gt;, &lt;th&gt;, &lt;td&gt;</simpara></entry>
 221             <entry><simpara>&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 <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 &lt;section&gt; element. An introduction section may look like this:</para>
 231     <programlisting>
 232 &lt;section id="any.intro"&gt;
 233   &lt;title&gt;Introduction&lt;/title&gt;
 234
 235   &lt;para&gt;Introduction to a library...&lt;/para&gt;
 236
 237   &lt;section&gt;
 238     &lt;title&gt;A Subsection&lt;/title&gt;
 239     &lt;para&gt;Subsection information...&lt;/para&gt;
 240   &lt;/section&gt;
 241 &lt;/section&gt;
 242 </programlisting>
 243     <para>The &lt;section&gt; element contains all information that
 244     should logically be grouped within that section. The title of the
 245     section is placed within the &lt;title&gt; element, and any
 246     paragraphs, programs, lists, tables, or subsections can occur
 247     within the section. The <code>id</code> attribute of the
 248     &lt;section&gt; 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