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
2) It's easy to represent structure (even if it is in an *ahem* ludicrously
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:
There are three files (besides the .gif):
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.
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).
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?
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk