Re: CVS, templates, and changes to docs

[Dan Mueth <d-mueth uchicago edu>]

First, let me apologize to all the applet authors (especially Telsa). Over
the last couple weeks, I think I have brought just about every applet doc
(except for the ones drake did) up to the latest template.  I(we) did this
for many reasons.  It was partly to make sure the documents correctly
discuss the FDL license, trademarks, and the application's license (GPL).  
It was partly to standardize the use of many terms and markups which were
being used inconsistantly between documents.  (Here I made the wrong
assumption that everybody read and agreed upon the terminology and markup
of the templates.) And it was partly because we had to find a way to build
the Users Guide's applets chapter out of the applet docs.  (They have to
have a similar appearance, since they are in a single book.  Plus they
really need to be built by a simple Perl script, since the docs are
changing every day.  This meant they all needed a uniform structure.) I'm
sure Telsa would have found a better solution to this problem, but she was
unable to work on this and I was the first sucker Dave found;)

So, I assumed that since the templates had pretty much stabalized and
everybody writing applet docs had seen and used them, this was the agreed
upon layout/markup.  I now see this is not the case.  However, if the
markup and terminology used in the templates is not what we want to use in
our documentation, it should not be in the templates.

Lets do as Sasha (and dcm, and eric, and ...) suggests and make some
official decisions on these things.  We should merge these results into
the Handbook as the official "GDP conventions" holder.  Also, the
templates should be updated to use the correct layout, since we should not
put/leave things in the template(ie. encourage people to use it) unless we
agree that it is the right way.

Dan