Chapter 18. Documenting libraries

Table of Contents

Defining a BoostBook library
From HTML to BoostBook
Sectioning in BoostBook

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.

Defining a BoostBook library

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 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

name: The full name of the library, e.g., "Any"
dirname: The name of the directory, relative to boost/libs, in which the library resides. This name may be a relative path, such as math/octonion, using "/" for the directory separator.
id: 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 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: Always set to $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 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 17, Getting Started.