From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-01-24 10:30:04
--- In boost_at_y..., "David Abrahams" <david.abrahams_at_r...> wrote:
>
> ----- Original Message -----
> From: "bill_kempf" <williamkempf_at_h...>
>
>
> > The "hello lib" section is the "overview.html" template. I think
it
> > really does cover what you want, but quite likely the template and
> > the description need some work to make this more obvious.
> >
> > BTW, if you're not so fond of the structural document then do you
> > truly like the header.html template? Something is not quite
meshing
> > there.
>
> It's a question of emphasis. At least the header templates contain
a section
> for happy-friendly docs, but the structure document doesn't even
mention
> them.
The "summary" specifications in the structure document directly
relate to the (minimal) happy-friendly section in the header.html
template. So it sounds to me like your object isn't so much what's
there, but what's not *obviously* there. The structure document was
taken nearly verbatim from the standard, so it's admittedly not
overly clear on some of these points. Can we clean up the way
structure.html is written to give the emphasis you want?
Note: I still think there's room for even more happy-friendly
documentation than is currently accounted for in any of the
documentation or the templates. That was at least part of the reason
for posting this in the rough draft form it's in.
> I would need to expand on the overview section a lot, but it's a
place
> to start. Also, the reference manual section is absolutely
neccessary and
> it's great to have templates to work from. I got the impression
that there's
> a lot in the structure document which isn't directly implied by your
> templates.
I'm not sure I know what you mean by this last sentence. If you said
it the other way around it would make more sense to me :). The
templates are an attempt to codify *everything* stated in both the
structure documentation as well as the design documentation. The
header.html template has some holes, as I originally stated, since I
can find no examples of how to format certain things to use as a
starting point (for example, macros, values, etc.).
Bill Kempf