Re: Writing Boost Documentation

From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-02-04 11:50:19

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

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

That said, I think different styles would be an excellent idea.  Care 
to contribute a style?

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

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

Bill Kempf