Re: [boost] Reference documentation: one approach

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
> 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?

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
the simplicity.

-- 
William E. Kempf