Re: [boost] Re: Writing Boost Documentation

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-02-03 10:43:55

----- Original Message -----
From: "dave_abrahams" <david.abrahams_at_[hidden]>

> Y'know what? I typed too soon. This material is terrific. I just
> looked at it again, and I don't think there's anything particularly
> daunting about it. I would still like to see more discussion of
> tutorial and example materials, but it's a great start.

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

Also, Bill, there are a number of places where your name and/or email
address appears in the templates. That should probably be replaced with
something more appropriate (e.g. {{author}}).

-Dave