Documentation


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:

HTML

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

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

  • Generating 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 an 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

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.

QuickBook

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

    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 for your environment:

    The free personal edition is no longer promoted by it's author. The above versions are the last one's available which do not eventually require an upgrade to a paid version. If for some reason the above links no longer function, the following should be equivalent.

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

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

    <XMLMind program directory>
      addon/
        config/
          boostbook
            boostbook.css
            boostbook.dtd
            boostbook.xxe
            boostbookcatalog.xml
            template/
              concept.xml
              function.xml
              library.xml
              metafunction.xml
              section.xml
              type.xml   
  4. 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

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 XSL style sheets

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

These command accomplish the above

xsltproc --nonet --xinclude bb2db.xsl safe_numerics.xml |
xsltproc --nonet 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 like the following

doc/
  html/
    boostbook.css
    index.html
    other html files ....
    images/
        png files ...
  boostbook/
    xml files containing boost book documentation
    makehtml.bat // batch file which creates html from boost bookxml
    makehtml.sh  // batch file which creates html from boost book 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.

m4s0n501
There are 0 comments

Comment on This Page