Add "Writing Docs" to CVS (Was Re: numeric_cast - is this really right?)

From: bill_kempf (williamkempf_at_[hidden])
Date: 2002-02-08 11:23:58

> I would love if Bjorn could write the documentation for me. The 
ideas are
> already explained in the sources, so it is just a matter of 
formalizing and
> formatting it, perhaps using the new stuff submitted by Bill Kempf.
> I would also like Bjorn to take a close look (as closer as 
possible) to the
> way range checking is performed when mixing float/integer and
> singed/unsigned types, since that's really tricky.

OK, I've received little criticisms for the uploaded documentation, 
and the few responses have been positive.  More over, there are at 
least 3 people I know of who are starting to use the templates today, 
despite the fact that it was only posted for comments.  Sooo...

Is there real interest in these templates for general use (I assume 
so since people ARE using them)?  If so, should I place the files in 
CVS where any developer with CVS write access can tweak things in 
order to "finalize" the documents/templates before the next release?

Related to this, what are the key areas that need work in the 
documentation/templates?  Ones I'm aware of:

1) Need to add more detail about tutorials/examples, including 
possible templates.

2) The index template either needs work to create a single template 
usable for both very large libraries and for smaller libraries, or we 
need multiple templates (or possibly an XML DTD and XSLT transforms 
to generate various index styles).

3) Reference documentation needs a little more fleshing out for some 
sections, such as macros, types, etc.

4) It might be helpful to include a page describing tools that can 
help, such as tidy, HTML validators, editors, etc.

5) A History page template and design documentation should be added.

Bill Kempf