Documentation of software libraries and APIs has a well deserved reputation for being incomplete and hard to use. Personally, I had a lot of difficulty making documentation for the Boost Serialization Library. The following opinions are the result of this and other experience.

Boost Documentation Tools

Libraries on this web site are required to include documentation in the for of HTML pages. This is the common denominator that permits the library documentation to be easily consulted on the web as well as locally. The library directory structure includes a directory labeled HTML for this purpose. The decision as to how to generate these pages is left to the library author. In considering a toolset to perform this function, I've developed my own personal wish list:

  • Wide support from some user/development community.

  • Separation of Content from Presentation. This system should permit same files to be used to generate documentation as web pages, PDF files, and perhaps other formats such as Htmlhelp and ePub.

  • An easy to use WYSISWYG editor which

    • works in all environments.

    • shows the document structure.

    • gives a good idea what the final presentation will look like.

    • guarantees that documents respect structure requirements. For example, it should prohibit the creation of a table row anywhere but inside a table.

    • Includes facilities for specification of document elements such as program listings, tables, etc.

    • Permits the creation of "templates" of pre-made document fragments which can be inserted into the document and then modified. Basically I want to include the "template" for Type and then use it as a form to fill in the specific information for some type.

    • includes a spelling checker

Currently, the most common methods used to generate documentation are:


One can just prepare the HTML pages with a simple text editor. In many cases this is the simplest to do and many libraries have been documented in this manner. The main disadvantage is that PDF (and maybe others) can't be prepared from the HTML pages. Also as the library gets larger, it becomes tedious to keep everything in sync.


BoostBook is an extension of DocBook. The work flow is:

  • Install DocBook

  • Edit documentation files in XML format with a text editor. The XML should follow the rules prescribed for BoostBook

  • Generate of HTML/PDF files from the BoostBook XML depends upon the Boost Build system. This in turn entails (as far as I can tell) updating one's local copy of the $BOOST_ROOT/doc directory and then running Boost bjam.

  • The generated documentation will appear in the $BOOST_ROOT/doc/html directory.

There is lot's to like about BoostBook.

  • The DocBook/BoostBook concept of structuring content and de-coupling it from presentation is sound.

  • The system can produce documentation in HTML and in PDF as well as potentially other formats.

  • Presentation is attractive, consistent and unified across different rendering formats.

  • BootBook defines a large group of XML tags which can be used characterize elements in C++ documentation. These includes things like function name, const, etc.. Potentially these could be used to generate useful things like function cross references, syntax coloring and the like.

  • The documentation for BoostBook is pretty good. It is created as an extension to DocBook. As such, it leverages on the extensive documentation available for that system.

On the other hand, there's a lot to dislike as well:

  • Editing XML is a royal pain. In part its just the ugliness and verbosity. XML documents are edited according to a set of grammar rules specified in a DTD or Schema. As BoostBook is derived from DocBook, it inherits all the rules from DocBook, and adds more of it's own. These rules are enforced by the build system so the author has to get them right. This turns out to be quite an effort since the rules are quite detailed and elaborate.

  • Though BoostBook specifies a large collection of tags to characterize documentation elements, the large majority of these are not used by Boost library documentation It seems that they've been included in the hopes of being available for future use. This would be OK except for the fact that the attaching all these tags to one's documentation would be a huge job - which would yield no benefit with the current document preparation system.

    It's not clear from the BoostBook documentation which tags are used/useful and which should not be bothered with. This leaves one with questions about under what circumstances each tag should be used.

  • Building HTML/PDF files from BoostBook XML files requires threading your library into your local Boost directory hierarchy, learning about how to configure and run BoostBuild, using the HTML/PDF which is left somewhere else in the local Boost directory. That is, conversion of documents in intimately coupled with BoostBuild. I understand the appeal of this for those whose task it to deploy Boost as a monolithic software package. And it may be OK for those whose documentation is done and already checked into the Boost directory, But for the rest of us, its very unwieldy.


DOxygen is a system for generating documentation of class and function types by scanning the program code along with from enhanced comments included by the author.

  • Clearly it's been influenced by Literate Programming concepts.. This looks like a good thing to me.

  • DOxygen works pretty much as advertised.

  • The BoostBook/BoostBuild process can incorporate XML output produced by DOxygen. And a number of boost libraries have successfully incorporated the files it generates in their documentation.

  • Using DOxygen to get a specific kind of output requires setting the right combination of configuration options (There are scores of these) and including special comments in the source code.

  • A lot of the DOxygen generated documentation I've seen seems just to do little more than paraphrase the code. After spending some time experimenting with it, I've come to believe that this is likely in large part due to the manner that DOxygen has been used. One might be able to generate the documentation I want, but it would require a lot of effort in tweaking the configuration and the program comments.


The principle disadvantage of BoostBook is that editing XML in accordance with BoostBook rules is very tedious. To address this issue, QuickBook was created. It has it own, much simpler, set of syntax rules for creating documentation. QuickBook files are created with any text editor. The output from QuickBook is XML which follows the BoostBook rules. This output is processed as would any BoostBook XML would be. QuickBook has been popular. Approximately 1/3 of the boost libraries use it. Of course that's another way of saying that 2/3 of the libraries don't use it. I sill has a few disadvantages:

  • It's not a WYSIWYG editor.

  • It's yet another "little language" to learn.

  • Like many "little languages" it's not that easy to extend if you want to do something that it doesn't already include. Adding a feature means understanding the source, modification and recompiling.

  • I didn't see a way to get what I really want - see below.

Creating BoostBook Documentation with XMLMind

XMLMind includes the following features:

  • An easy to use WYSISWYG editor which

    • works in all environments.

    • shows the document structure.

    • gives a good idea what the final presentation will look like.

    • guarantees that documents respect structure requirements. For example, it should prohibit the creation of a table row anywhere but inside a table.

    • Includes facilities for specification of document elements such as program listings, tables, etc.

    • Permits the creation of "templates" of pre-made document fragments which can be inserted into the document and then modified. Basically I want to include the "template" for Type and then use it as a form to fill in the specific information for some type.

    • includes a spelling checker

    • has a free edition available

    This requirement is fulfilled is - a free XML editor. This beautifully made product permits one to add his own XML syntax checking files (DTD files). I've added files to enforce the extra rules that BoostBook requires. I've also added some "templates" for C++ library documentation elements: library, concept, type, and function. So one can build his documentation from within the editor by adding in the standard templates and "filling in the blanks". This will go a long way to making "C++ library formal documentation" with a minimum of effort. Others agree with this assessment.

  • A system which separates content from presentation so the same files can be used to generate documentation as web pages, PDF files, and perhaps other formats such as Htmlhelp and ePub.

    This requirement is fulfilled by using BoostBook with no changes. A small additional XSLT styling sheet is employed to interface with the rest of the system.

  • I've addressed this by creating some custom XSLT style sheets which extend the standard BoostBook ones. These just remove the requirement that the XML files be part of the standard Boost Source tree. Finally, I've set up a directory containing all the DocBook stuff so that I can create HTML documentation with a three line batch file. This has made my documentation system usable without using BoostBuild and without having to make a source tree which looks like boost. Finally, the generated pages use the same "look and feel" as the BoostBook generated pages.

Figure 1. XML Mind Editor Screen shot
XML Mind Editor Screen shot

Setup one's system to prepare BoostBook documentation with XMLmind.

Setup BoostBook and XSLT.

  1. Make sure the Boost Libraries and Tools are installed.

  2. Install xsltproc as described in Getting Started

  3. Follow the procedure in Configuring xsltproc

  4. Follow the procedure in Configuring local DocBook XSL and DTD distributions

  5. You should now have a designated directory with the DocBook XSL and DTD distributions installed. Set the Shell/Bat variable DOCBOOK to point to the directory.

  6. download catalog.xml to this directory.

  7. Read the comments in catalog.xml and edit the file accordingly. This will result in references to local copies of BoostBook and DocBook tools on your local file system and permit the usage of XML processing tools without dependence on an Internet connection.

  8. Set the Shell/Bat variable XML_CATALOG_FILES to point to the above file:

Setup XMLMind with BoostBook configuration extension

  1. Download and Install the free personal edition of XMLmind/XMLDocbook for your environment:

    • Windows

    • Mac

    • Linux

  2. Invoke XMLMind on your machine and verify that it starts up and seems to work.

  3. Select from the menu XMLmind->Options->Install Add-ons

  4. Download temporary directory. This contains a custom configuration for XMLMind to facilitate the editing of BoostBook documentation.

  5. unzip this file into the XMLMind program directory. This directory should look like:

    <XMLMind program directory>
  6. Verify that XMLMind is properly configured by invoking File->New shows

At this point, one should be able to create BoostBook based documentation with the XMLMind editor.

Using XMLMind to edit BoostBook documentation:

  • Editing with XMLmind takes some getting used to. It does feel quite unwieldy at first.

  • To get the hang of it, practice editing the BoostBook documentation for a library you've already downloaded. Note the safe_numerics demo library documentation has been prepared with this system so it would be a good candidate to practice with.

  • XMLmind is very well documented and explained - including videos! - check though all this information.

  • Ideally one would be totally insulated from details of DocBook/BoostBook. Unfortunately, one still has to know something about these packages. Here is a list of links which contain useful information.

  • Any XML editor is at it's root a system for editing a very elaborate tree of nested XML elements can be very, very tedious. For this reason, it's very helpful to use copy/paste of "branches" which are already complete. This speeds up the process considerably for things like tables, etc.

  • Lookup the "node selection bar" in the XMLMind help. This is key to understanding where you are in the node tree.

  • Edit in WYSIWYG mode. This guarantees that your document follows that BoostBook Document Type Definition and that the BoostBook Tool chain will produce Boost con formant documentation.

  • Make your documentation as a "Modular Document". Use safe_numerics as an example and lookup the XMLMind help that shows how to do this.

  • Using all of the above, the process of making library documentation can be summarized as:

    • File->New and select library to create a new document. This will be a "skeleton" of the documentation for your library.

    • Each time you create a new concept, type, or function, invoke File->New and select the appropriate template. This will create a new document of the selected type and make it ready to edit.

    • Edit the contents of each created template and save it under it's unique file name.

    • Link each newly created document into the library document using the procedure described in the XMLMind help.

    • Delete any unneeded sections and Add any required new ones as appropriate.

Rendering Documentation with xsltproc

Generating HTML Output

Once library documentation has been created in BoostBook/DocBook format we can render it in a variety of formats. This is done with the BoostBook toolset. In the official Boost distribution, this is done with BoostBuild. We use a simpler more transparent method. Creating HTML documentation is a two step process using XSLT.

  1. Translate BoostBook XML to DocBook XML using XSL style sheets

  2. Translate the resulting DocBook XML to HTML using DocBook style sheets.

These commands accomplish the above

xsltproc --nonet --xinclude $BOOST_ROOT/tools/boostbook/xsl/docbook.xsl safe_numerics.xml | \
xsltproc --nonet --xinclude $BOOST_ROOT/tools/boostbook/xsl/html.xsl db2html.xsl -

In addition, we need to copy a few files from the boost installation. The following files should be copied to the HTML directory from the boost root directory.

doc/src/boostbook.css // cascaded style sheet to give boost "look and feel"

doc/html/images // directory of images for arrows, etc.

and finally you should add to the HTML directory a file named pre-boost.jpg. After all this, the HTML documentation director structure should look something like the following

    other html files ....
        png files ...
    xml files containing boost book documentation
    makehtml.bat // batch file which creates html from boostbook xml  // batch file which creates html from boostbook xml

The logo on your documentation can be changed either by replacing the pre-boost.jpg with your own or editing the dbt2html.xsl to point to a different logo.

Customizing HTML Output

The above procedure requires the existence of an xml "style sheet" prepare in the XML style sheet language. This language is which will look something like the following: This specifies various parameters which customize the HTML output according to taste.

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="" version="1.0">

<!-- ************** HTML ************** -->
<xsl:import src="@//"/>

Make library documentation header using some elements from boostbook stylesheets.
Override boost book implemenation of header.navigation with our own
<xsl:template name = "header.navigation">
    <xsl:param name = "prev" select = "/foo"/>
    <xsl:param name = "next" select = "/foo"/>
    <xsl:param name = "nav.context"/>
    <table cellpadding = "2" width = "100%"><tr>
        <td valign = "top">
            <img src="" height="164px" src="" alt="Library Documentation Index" />
        <td><h2>Safe Numerics</h2></td>
    <xsl:call-template name = "navbar.spirit">
       <xsl:with-param name = "prev" select = "$prev"/>
       <xsl:with-param name = "next" select = "$next"/>
       <xsl:with-param name = "nav.context" select = "$nav.context"/>

<!-- remove "Chapter 1" from first page -->
<xsl:param name="chapter.autolabel" select="0"/>
<!-- leave the html files in the directory ../html -->
<xsl:param name="base.dir" select="'../html/'"/>

<!-- ******* Table of Contents ******** -->
<!-- How far down sections get TOC's -->
<xsl:param name = "toc.section.depth" select="2" />

<!-- Max depth in each TOC: -->
<xsl:param name = "toc.max.depth" select="2" />

<!-- How far down we go with TOC's -->
<xsl:param name="generate.section.toc.level" select="1" />

<!-- ************ Chunking ************ -->

BoostBook takes a section node id like safe_numeric.safe_cast
and renders it as safe_numeric/safe_cast. Presumably they do this
so they can make a huge "book" with all the libraries in subdirectories.
But we want something different.  To my mind, this should have been
done using the library "directory" attribute.  But of course that
doesn't matter now.  We'll just re-hack the path to eliminate
the "safe_numeric/" from the above example.

<xsl:template match="*" mode="recursive-chunk-filename">
    <xsl:variable name="their">
        <xsl:apply-imports mode="recursive-chunk-filename" select="."/>
    <xsl:when test="contains($their, '/')">
        <xsl:value-of select="substring-after($their, '/')" />
        <xsl:value-of select="$their"/>

<!-- don't make first sections special - leave TOC in different file -->
<xsl:param name="chunk.first.sections" select="3" />

<!-- How far down we chunk nested sections -->
Note: each chunk have to start with  a section with an id
Otherwise the chunk (i.e. file) will be lost.  There is no 
checking of this
<xsl:param name="chunk.section.depth" select="1" />


The key features which we can specify are

  • HTML Page Header including logo and Title

    We do this overriding the Boost Book default implementation of the "header.navigation" template with our own.

  • "Chunking" - to specifying HTML output is divided into files.

    DocBook includes parameters to specify how the html output is broken into files. In DocBook parlance, this is refered to as "chunking". The DocBook rules for chunking are a little complex, but are well explained in the DocBook documentation. In practice, the defaults mostly work and you won't have to spend too much time. Make sure that you use the "id" element to assign a name to each section which might start an new file. If you don't do this, the file won't be created and you'll be given no error message explaining why!

  • Table of Contents - specifications

    DocBook includes a number of parameters which can be used to "fine tune" the presentation of the table of contents. DocBook documentation includes extensive and complete explanation of how to use specify these parameters to create tables of contents according to taste.


  1. Bob Slayton, DocBook XSL: The Complete Guide

  2. Norman Walsh, DocBook: The Definitive Guide

  3. John W. Shipman, New Mexico Tech Computer Center, Writing documentation with DocBook-XML 4.3

  4. John W. Shipman, New Mexico Tech Computer Center, Customization of the 4.3 DocBook-XSL Stylesheets

There are 0 comments and replies

Comment on This Page