...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
BoostBook is an extension to DocBook, 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 DocBook: The Definitive Guide.
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 any.xml
)
that contains basic information about the library. The following
BoostBook XML
example describes basic information about the Boost.Any
library:
Example 40.1. A Skeletal BoostBook Library
<?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 20:30:45 +0100 (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>
The first three lines identify this document as a BoostBook XML document. The DOCTYPE line states that the document conforms to the BoostBook DTD, and that the top-level element is a BoostBook <library>.
The <library> element actually describes the aspects of BoostBook library documentation. The attributes for the <library> element are:
Attributes for the <library> element
name
dirname
boost/libs
, in which the library
resides. This name may be a relative path, such as
math/octonion
, using "/" for the directory
separator.id
dirname
. This id
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.last-revision
$Date: 2008-07-12 20:30:45 +0100 (Sat, 12 Jul 2008) $
, which is
expanded by CVS to include the date and time that the file
was last modified.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 not terminate with a period.
The list of categories is specified by a set of
<librarycategory> elements. Each <librarycategory>
element has a name
element that identifies one of the
categories. The actual list of categories is in the file
doc/src/boost.xml
.
At this point, we can apply the BoostBook XSL stylesheets to
any.xml
(to DocBook) followed by a DocBook XSL
stylesheet to generate HTML output, as described in the section called “Getting Started”.
Most library authors are comfortable with writing HTML documentation. Writing DocBook documentation (and, by extension, BoostBook documentation) is quite similar to writing HTML, except that BoostBook uses different element names from HTML (see Table 40.2, “Converting HTML elements to BoostBook”) and BoostBook XML is a much more rigid format than HTML.
One of the easiest ways to convert HTML documentation into BoostBook documentation is to use HTML Tidy to transform your HTML into valid XHTML, which will make sure that all elements are properly closed, then apply the transformations in Table 40.2, “Converting HTML elements to BoostBook” to the body of the XHTML document. The following command uses HTML Tidy to transform HTML into valid XHTML:
tidy -asxhtml input.html > output.xhtml
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 the section called “Defining a BoostBook library” 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.
Table 40.2. Converting HTML elements to BoostBook
HTML | BoostBook |
---|---|
<h1>, <h2>, etc. |
<section>, <title>; See the section called “Sectioning in BoostBook” |
<i>, <em> |
<emphasis> |
<b> |
<emphasis role="bold"> |
<ol> |
<orderedlist> |
<ul> |
<itemizedlist> |
<li> |
<listitem> |
<pre> |
<programlisting> |
<code> |
<computeroutput>,<code> |
<p> |
<para>, <simpara> |
<a> |
<xref>, <link>, <ulink>;, See the section called “Linking in BoostBook” |
<table>, <tr>, <th>, <td> |
<table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good tutorial here |
"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:
<section id="any.intro"> <title>Introduction</title> <para>Introduction to a library...</para> <section> <title>A Subsection</title> <para>Subsection information...</para> </section> </section>
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 id
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.