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
that contains basic information about the library. The following
example describes basic information about the Boost.Any
Example 18.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: 2005/12/04 17:26:48 $"> <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
boost/libs, in which the library resides. This name may be a relative path, such as
math/octonion, using "/" for the directory separator.
idwill 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.
$Date: 2005/12/04 17:26:48 $, 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
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 Chapter 17, Getting Started.
|Copyright © 2003-2005 Douglas Gregor|