Re: [boost] Re: Writing Boost Documentation

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-02-04 12:08:02

----- Original Message -----
From: "bill_kempf" <williamkempf_at_[hidden]>

> > ...and now for an experience report: I'm trying to use the
> templates for
> > documenting the next version of Boost.Python. Looking at my index
> page, I
> > can see right away that the format is going to be good for small
> libraries
> > of one or two headers, but that for a project of the scale of
> Boost.Python,
> > a more hierarchical navigation structure will be needed. Here's
> what I see
> > now:
> >
> > Contents
> > Overview
> > Reference
> >     {{header}}
> >         Macros
> >             {{macro name}}
> >         Values
> >             {{value name}}
> >         Types
> >             {{type name}}
> >         Classes
> >             {{class name}}
> >         Functions
> >             {{function name}}
> >         Objects
> >             {{object name}}
> > Configuration Information
> > ...
> >
> > It would be great if we could have someo alternate templates for
> libraries
> > like Boost.Python v2 or MPL which have approximately one component
> per
> > header.
>
> I've got a working example of Boost.Threads using the above style,
> and it is not a "small library of one or two headers".  It works
> nicely there (at least IMO).

The threads docs are great, I agree, but the current CVS state doesn't look
anything like the above. It starts with a "Documentation Map" which has no
mention of headers.

> Yes, that's actually something I changed after posting.  I wanted to
> get the documentation up quickly to get feedback and so rushed things
> a little.  I've actually got a few other modifications locally which
> I can upload later (I'm not at the computer that has the newer files
> and won't be today, but I can try and get it uploaded in the next
> couple of days).

I'd love to get it before I have to go to D.C. this afternoon.

-Dave