Re: Boost Documentation Template questions

From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-02-11 14:35:39

--- In boost_at_y..., "David Abrahams" <david.abrahams_at_r...> wrote:
> 
> ----- Original Message -----
> From: "bill_kempf" <williamkempf_at_h...>
> 
> 
> > > 1. No provision for templates. Is it intended that class 
templates
> > go in the
> > > "Classes" section and that function templates go in 
the "functions"
> > section?
> >
> > Yes.  This was the structure/design used by the standard.  If this
> > doesn't work we can create more sections, or if all that's needed 
is
> > to explicitly state this in the documentation I can make that
> > change.  Which do you think is needed?
> 
> Mostly the latter, for now. Also, I'd like to know the purpose 
of "types".
> Is that for unions and typedefs?

I'd like to know this to ;).  It's taken directly from the standard 
(17.3.1.1/3).  It's one of the things I had asked about when posting 
the templates the first time, but for which I received no response.

> > > 2. No provision for concept definitions.
> >
> > In Boost.Threads I've just been using a general document page, and
> > for that you can borrow the template for the Overview section.
> > However, it would probably be beneficial to have a full template 
for
> > these.  If you need a template quickly then could you create one 
and
> > check it in?
> 
> I don't know where the stuff lives in CVS. If I'm about to start on 
a
> template, I'll let you know. Otherwise, it's up to you.

It's in boost/more/writingdoc (and boost/more/writingdoc/template). 
If you get around to it then just let me know.  Otherwise I'll let 
you know if I get to a point where I can work on it.

> > BTW, thanks for the reports.  They'll help in cleaning this stuff 
up
> > before the next actual release, when those who might not be 
willing
> > to live with the growing pains could simply give up on using the
> > templates.
> 
> No prob. Here's the latest. I'm documenting some granular headers. 
It's
> looking like this so far:
> 
> call.hpp
>     Functions
>         call
> class.hpp
>     Classes
>         class_
> class_fwd.hpp
>     Classes
>         class_
> copy_const_reference.hpp
>     Classes
>         copy_const_reference
> copy_non_const_reference.hpp
>     Classes
>         copy_non_const_reference
> default_call_policies.hpp
>     Classes
>         default_call_policies
>         default_result_converter
> 
>     ...
> 
> I've always been taught (and agreed) that an outline item should 
always have
> more than one sub-item. In that light I'm not sure this approach is 
working
> out so well. Remember that the standard documentation suits the 
standard
> headers, which bring massive amounts of diverse code together.

I'm open to alternatives.  Document writing isn't my forte... but 
that's precisely why I wanted templates to use and came up with what 
we have so far.
 
> Also, I'm starting to get really hungry for some automation. Just 
massageing
> the templates into shape can be really tedious and error-prone.

Yes, I'd agree with that.  A python script could easily be written to 
automate this, provided the {{...}} replacement sections used well 
known documented names.  Other then that, I'm not sure what else we 
can do, but if anyone has any ideas I'd love to hear them!

Bill Kempf