Re: [Plplot-devel] Documentation files

[Alan W. I. <ir...@be...>]

Rafael, since we are agreed on everything here, and nobody else has
commented I think we should go ahead and start implementing while our ideas
are fresh. Other comments in context below....Alan

On 2004-02-06 14:09+0100 Rafael Laboissiere wrote:

> * Alan W. Irwin <ir...@be...> [2004-02-04 12:41]:
>
> > -----------The following files should be deleted.
> >
> > * CHANGES
> >
> > Completely out of date, and ChangeLog should be used instead.
>
> Agreed.

OK. I will remove this file fairly soon unless somebody objects.

>
> > * TODO.AM-LT
> >
> > This file is partially out of date.  Anything still relevant should be put
> > into PROBLEMS or ToDo (see comments on those below).
>
> Into ToDo, I would say.  I have to review its contents, anyway.

OK. I don't think anybody else is concerned with this file so I would say
go ahead the next chance you get.

>
> > -----------The following files should be kept.
> >
> > * ChangeLog

> I used cvsreport (http://www.nongnu.org/cvsreport/), whcih can output both
> text and html formats.  The ChangeLog of the last release announcement
> (http://plplot.sf.net/announce/announce-plplot-5.3.0.txt) is actually an
> ASCII file.

One other issue should be mentioned.  Should we have a ChangeLog that just
goes back to the previous release or should it stretch back to the very
first commit?  Having the full ChangeLog would be sort of neat since this is
one of the longer-lived open-source projects in the world with a proud
history.  However, I am willing to follow whatever model most other projects
use here if it is different from one complete ChangeLog. So I bring up the
complete ChangeLog just as an idea, and I suggest you go ahead and implement
whatever you like as a make target any developer can execute.

>
> > * FAQ
> >
> > This is grossly out-of-date and misleading.  We do need a FAQ, but it should
> > be relevant.  Both cvs and website forms should be made available.
>
> Agreed.

Could you start the ball rolling here with a make target that creates the
website version and plplot tree text version from one source file?
Hopefully, there is one item in the old FAQ that is still valid that you
could use for an initial template.

Should this file (or an improved version of it) be moved into the
> doc direcotry?

No opinion.

>
> > * NEWS
> >
> > This is out of date.  The last updates simply took part of the release
> > announcement (or all of it?) for each release, but even that maintenance
> > stopped at 5.1.0.  I think a better approach is to completely replace the
> > current contents of this file with a series of one-line dated overviews of
> > major events, e.g.,
> >
> > 2004-02-2004: PLplot version 5.3.0 was released (with a link to the release
> > announcement.)
> >
> > Both cvs and website forms should be made available.
>
> Agreed.

Could you start the ball rolling here with a make target that creates the
website version and plplot tree text version from one source file?  The
first item in that source file should be something like the above line with
correct date rather than the above gibberish.

Alan

__________________________
Alan W. Irwin
email: ir...@be...
phone: 250-727-2902

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the PLplot scientific plotting software
package (plplot.org), the Yorick front-end to PLplot (yplot.sf.net), the
Loads of Linux Links project (loll.sf.net), and the Linux Brochure Project
(lbproject.sf.net).
__________________________

Linux-powered Science
__________________________