Re: [boost] Re: Writing Boost Documentation

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-02-04 15:23:00

----- Original Message -----
From: "bill_kempf" <williamkempf_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Monday, February 04, 2002 12:16 PM
Subject: [boost] Re: Writing Boost Documentation

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

Hmm, so are the headers organized alphabetically, or by some other means?
Boost.Python V2 is evolving into a framework, with high-level and
lower-level components. I'd rather organize them according to their use and
category. It seems as though I'll need at least one additional level of
hierarchy to distinguish groups of headers.

-Dave