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 15.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: 2004/07/05 16:26:11 $"> <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
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 Chapter 14, Getting Started.
|Copyright © 2003 Douglas Gregor|