Re: Writing Boost Documentation

From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-02-04 12:16:14

--- In boost_at_y..., "David Abrahams" <david.abrahams_at_r...> wrote:
> 
> ----- Original Message -----
> From: "bill_kempf" <williamkempf_at_h...>
> 
> > > ...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.

I meant a local working copy.  The CVS docs for Boost.Threads don't 
really use the structure/style presented in these documents.

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

I can try, but I'm in "training" all day so it may not be possible.  
Sorry :(.

Bill Kempf