From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-29 08:10:03
Douglas Gregor said:
> 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
> 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*
> 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:
> 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
> 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?
Can you compare and contrast this to DocBook? I expect your XML is a lot
simpler than the DocBook DTD, but since DocBook is an industry standard
for this sort of thing it would be nice to know what we'd be giving up for
-- William E. Kempf
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk