Re: [boost] Reference documentation: one approach

From: Douglas Gregor (gregod_at_[hidden])
Date: 2002-10-30 01:51:02

On Tuesday 29 October 2002 06:30 pm, Jeff Garland wrote:
> > I've now finished some more XSLT code to line-wrap function parameters:
> > if the parameter fits on the line, put it on the line; otherwise, indent
> > to the position where the parameters started on the first line and emit
> > the parameter. It's not done for template headers yet, but it will give
> > the same results as in your example (with long parameter names), but it
> > will give the nicer version of swap(). I'm currently working on
> > integrating it to get a full example going.
>
> Nice -- I'm really glad you were the one that had to figure out the weird
> XSL code for that little trick!

It's not too terribly weird, nor is it terribly efficient. Just needed to get 
a better understanding of result tree fragments and everything fell into 
place.

I've updated the XSLT stylesheet (boost-reference.xsl), Function documentation 
(function_ref.xml), and the transformed output (function_ref.html) at the 
usual place:
  http://www.cs.rpi.edu/~gregod/Boost

New features:
  - keyword highlighting in code segments
  - more intelligent layout of function parameters & template header for 
function templates
  - better layout of typedefs in a class
  - doesn't squish HTML markup in requires/effects/etc. clauses :)

So, I think it is doable and perhaps even feasible to use XML & XSLT to 
generate reference documentation, though I don't know if I would recommend 
it. Let's go play with some options and I'll leave the result of this 
experiment available for comparison:

  http://www.cs.rpi.edu/~gregod/Boost/function_ref.html

        Doug