| <?xml version="1.0" encoding="utf-8"?> |
| <!-- |
| Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> |
| |
| Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt) |
| --> |
| <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| <chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.documenting" |
| last-revision="$Date: 2008-07-12 15:30:45 -0400 (Sat, 12 Jul 2008) $"> |
| <title>Documenting libraries</title> |
| |
| <para>BoostBook is an extension to <ulink |
| url="http://www.docbook.org">DocBook</ulink>, an XML format for |
| representing documentation. BoostBook inherits much of its |
| functionality and many elements from DocBook that are not |
| redocumented here. When writing BoostBook documentation, please |
| refer also to <ulink |
| url="http://docbook.org/tdg/en/index.html">DocBook: The Definitive |
| Guide</ulink>.</para> |
| |
| <section id="boostbook.defining"> |
| <title>Defining a BoostBook library</title> |
| |
| <para>BoostBook library documentation is contained entirely within |
| a <library> XML element. To create a skeletal library, we |
| need to create a new XML document (call it <code>any.xml</code>) |
| that contains basic information about the library. The following |
| <link linkend="boostbook.documenting.skeletal">BoostBook XML |
| example</link> describes basic information about the <ulink |
| url="http://www.boost.org/libs/any/index.html">Boost.Any</ulink> |
| library:</para> |
| |
| <example id="boostbook.documenting.skeletal"> |
| <title>A Skeletal BoostBook Library</title> |
| <programlisting> |
| <?xml version="1.0" encoding="utf-8"?> |
| <!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| <library name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude" |
| id="any" last-revision="$Date: 2008-07-12 15:30:45 -0400 (Sat, 12 Jul 2008) $"> |
| <libraryinfo> |
| <author> |
| <firstname>Kevlin</firstname> |
| <surname>Henney</surname> |
| </author> |
| <librarypurpose> |
| Safe, generic container for single values of different value types |
| </librarypurpose> |
| <librarycategory name="category:data-structures"/> |
| </libraryinfo> |
| </library> |
| </programlisting> |
| </example> |
| |
| <para>The first three lines identify this document as a BoostBook |
| <ulink url="http://www.w3.org/XML/">XML</ulink> document. The |
| DOCTYPE line states that the document conforms to the BoostBook |
| DTD, and that the top-level element is a BoostBook |
| <library>.</para> |
| |
| <para>The <library> element actually describes the aspects |
| of BoostBook library documentation. The attributes for the |
| <library> element are:</para> |
| |
| <variablelist> |
| <title>Attributes for the <library> element</title> |
| <varlistentry> |
| <term><code>name</code></term> |
| <listitem> |
| <simpara>The full name of the library, e.g., "Any"</simpara> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><code>dirname</code></term> |
| <listitem> |
| <simpara>The name of the directory, relative to |
| <code>boost/libs</code>, in which the library |
| resides. This name may be a relative path, such as |
| <code>math/octonion</code>, using "/" for the directory |
| separator.</simpara> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><code>id</code></term> |
| <listitem> |
| <simpara>A short, unique name for the library. For libraries |
| with simple directory names (e.g., ones that do not contain |
| a "/"), this should be the same as the |
| <code>dirname</code>. This <code>id</code> will be used to |
| identify libraries and, for HTML output, will be used as the |
| base name for the HTML file in which the library's |
| documentation resides, so it should use only lowercase |
| alphanumeric characters and underscores.</simpara> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><code>last-revision</code></term> |
| <listitem> |
| <simpara>Always set to <code>$Date: 2008-07-12 15:30:45 -0400 (Sat, 12 Jul 2008) $</code>, which is |
| expanded by CVS to include the date and time that the file |
| was last modified.</simpara> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>Inside the <library> element we have the |
| <libraryinfo> element, which gives information about the |
| library itself. It contains the author's name (there may be more |
| than one <author> element), followed by the purpose of the |
| library and the list of categorizations. The |
| <librarypurpose> element should always contain a very short |
| (single sentence) description of the library's purpose, and should |
| <emphasis>not</emphasis> terminate with a period.</para> |
| |
| <para>The list of categories is specified by a set of |
| <librarycategory> elements. Each <librarycategory> |
| element has a <code>name</code> element that identifies one of the |
| categories. The actual list of categories is in the file |
| <filename>doc/src/boost.xml</filename>. |
| </para> |
| |
| <para>At this point, we can apply the BoostBook XSL stylesheets to |
| <code>any.xml</code> (to DocBook) followed by a DocBook XSL |
| stylesheet to generate HTML output, as described in <xref |
| linkend="boostbook.getting.started"/>.</para> |
| </section> |
| |
| <section> |
| <title>From HTML to BoostBook</title> |
| |
| <para>Most library authors are comfortable with writing HTML |
| documentation. Writing <ulink |
| url="http://www.docbook.org">DocBook</ulink> documentation (and, |
| by extension, BoostBook documentation) is quite similar to writing |
| HTML, except that BoostBook uses different element names from HTML |
| (see <xref linkend="html.to.boostbook"/>) and BoostBook XML is a |
| much more rigid format than HTML.</para> |
| |
| <para>One of the easiest ways to convert HTML documentation into |
| BoostBook documentation is to use <ulink |
| url="http://tidy.sourceforge.net/">HTML Tidy</ulink> to transform |
| your HTML into valid XHTML, which will make sure that all elements |
| are properly closed, then apply the transformations in <xref |
| linkend="html.to.boostbook"/> to the body of the XHTML |
| document. The following command uses HTML Tidy to transform HTML |
| into valid XHTML:</para> |
| |
| <programlisting> |
| tidy -asxhtml input.html > output.xhtml</programlisting> |
| |
| <para>When converting documentation from HTML to BoostBook, note |
| that some redundant information that has to be manually maintained |
| in HTML is automatically generated in BoostBook: for instance, the |
| library categorizations, purpose, and author list described in |
| <xref linkend="boostbook.defining"/> are used both in the |
| documentation for the library and to build alphabetical and |
| categorized lists of known libraries; similarly, tables of |
| contents are built automatically from the titles of sections in |
| the BoostBook document.</para> |
| |
| <table id="html.to.boostbook"> |
| <title>Converting HTML elements to BoostBook</title> |
| <tgroup cols="2" align="left"> |
| <thead> |
| <row> |
| <entry>HTML</entry> |
| <entry>BoostBook</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><simpara><h1>, <h2>, etc.</simpara></entry> |
| <entry> |
| <simpara><section>, <title>; See <xref |
| linkend="boostbook.sectioning"/></simpara> |
| </entry> |
| </row> |
| <row> |
| <entry><simpara><i>, <em></simpara></entry> |
| <entry><simpara><emphasis></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><b></simpara></entry> |
| <entry><simpara><emphasis role="bold"></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><ol></simpara></entry> |
| <entry><simpara><orderedlist></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><ul></simpara></entry> |
| <entry><simpara><itemizedlist></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><li></simpara></entry> |
| <entry><simpara><listitem></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><pre></simpara></entry> |
| <entry><simpara><programlisting></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><code></simpara></entry> |
| <entry><simpara><computeroutput>,<code></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><p></simpara></entry> |
| <entry><simpara><para>, <simpara></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><a></simpara></entry> |
| <entry> |
| <simpara><xref>, <link>, <ulink>;, See <xref |
| linkend="boostbook.linking"/></simpara></entry> |
| </row> |
| <row> |
| <entry><simpara><table>, <tr>, <th>, <td></simpara></entry> |
| <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> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </section> |
| |
| <section id="boostbook.sectioning"> |
| <title>Sectioning in BoostBook</title> |
| <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> |
| <programlisting> |
| <section id="any.intro"> |
| <title>Introduction</title> |
| |
| <para>Introduction to a library...</para> |
| |
| <section> |
| <title>A Subsection</title> |
| <para>Subsection information...</para> |
| </section> |
| </section> |
| </programlisting> |
| <para>The <section> element contains all information that |
| should logically be grouped within that section. The title of the |
| section is placed within the <title> element, and any |
| paragraphs, programs, lists, tables, or subsections can occur |
| within the section. The <code>id</code> attribute of the |
| <section> element gives a unique ID to each section, so that |
| it may later be identified for linking. It is suggested that all |
| IDs start with the short name of a library followed by a period, |
| so that IDs do not conflict between libraries.</para> |
| </section> |
| </chapter> |
| |
