[boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-28 23:06:23

Boost library documentation is scattered amongst many HTML files in many 
different directories. Several users and developers have expressed an 
interest in unified reference documentation for all of the Boost libraries. 

There are roughly a gazillion ways to implement something like this, and 
almost all of them are painful. If we're going to do something painful, we 
should be careful not to require having to do it again.

I chose to try out an XML format for the documentation, using XSLT to 
transform the XML into a suitable HTML document. I tried this because:
  1) XML and its tools are omnipresent, and they aren't going to disappear on 
us 
  2) It's easy to represent structure (even if it is in an *ahem* ludicrously 
verbose way)
  3) Later on, we could easily validate that structure with a DTD
  4) We can transform the XML into whatever sort of medium we want. I've 
written a partial transformation to HTML already, and there's no reason we 
couldn't write transformations to other formatting languages (e.g., one 
suitable for print).

Anyway, the current example is available at:
  http://www.cs.rpi.edu/~gregod/Boost/

There are three files (besides the .gif):

http://www.cs.rpi.edu/~gregod/Boost/boost-reference.xsl
  This file is the XSLT transformation from XML to HTML. It handles a 
reasonable chunk of documentation reasonably well. I opted to try to mimic 
the C++ standard's method of specification closely because I think that is a 
reasonable way to go.
    
http://www.cs.rpi.edu/~gregod/Boost/function_ref.xml
  This is the XML description of part of the Boost.Function reference 
documentation. It covers the part of Boost.Function that was proposed for the 
TR. If you store the XSLT file (above) locally and load this into a modern 
browser, it should do the transformation on the fly, but whitespace is a 
problem (IE6 and Mozilla 1.0 both got the whitespace wrong).

http://www.cs.rpi.edu/~gregod/Boost/function_ref.html
  This is the HTML file generated by xsltproc from the XSLT and XML files. At 
least xsltproc handles whitespace correctly, so if you look at only one file, 
look at this one.

Comments? Questions? Boos from the crowd?

        Doug