[Aimmath-developers] File headers, cvs doc'n, ...

[Greg G. <gr...@ma...>]

> On Monday, 28 April 2003 5:27 PM, Gustav wrote:
> GG> One other thing I'd like to see is version Id strings
> GG> at the top of each file.
> > That sounds like a very good idea. Would you be able to add these
> > strings to all the files and commit them?

Dear team,

(Welcome Chris ... I see you have been added to the developers list).
I finally got around to adding the Id strings to all the .mpl and .java
files, yesterday (Monday 5 May). Other files for now don't have them.
The Id version strings are only really useful in files which have some
likelihood of changing, and should of course, not be added to generated
files like .class files.

On Fri, 2 May 2003 12:14:54 +0100, Gustav wrote:
> I am looking forward to reading your cvs documentation. I think a
> good place
> to put it would be the DocManager on SourceForge. You have privileges to
> place and edit documentation there (in fact I have given all of us this
> privilege).

I submitted a file there of about 13 lines (basically as a test). It seems
this has to go through some approval process. So I didn't see it on the
system for a while. I think I might create the file in plain text and
put it a directory dev/ on the system as I had first suggested I might.
I have a perl script I wrote that converts an appropriately formatted
text file to HTML. If it seems useful I might add that script into
another directory etc/. Anyway, once I have the file with the content I want
and a version of it appropriately HTML-marked-up (as DocManager really
requires it) I'll change the documentation file from `pending' to `active'.

> GG> A few months back, I sent some info. on what I called a Trig package.
> GG> I'm thinking that I could add that into the distribution, along with
> GG> sample quiz files. In fact, I think Neil's sample quiz files could
also
> GG> be included on Sourceforge.
>
> I don't think that sample question files should go into cvs because they
do
> not really be developed by us as a team. Rather the important thing is
that
> they should be easily accessible by the non-developers.

The Trig package I mentioned comprises a few .mpl files
(aim/{Trig.mpl,GGUtil0.mpl}) as well as a number of examples. It was
based on Neil's Diff.mpl and examples. It was only after I saw how Neil
had used the Diff.mpl (and Int.mpl) functions in his examples that I
realised the usefulness of those Diff.mpl (and Int.mpl) functions.
Thus I see those sample questions as an important part of the documentation
of Diff.mpl (and Int.mpl).

This is also the case with my Trig package. The sample questions I have
help to explain what the functions in aim/{Trig.mpl,GGUtil0.mpl} are for.
Now that we have the aim-tth distribution on Sourceforge, I will add/commit
these files after changing the name of the latter to say aim/Util2.mpl.
In light of the view that sample quiz questions like those mentioned above
should be considered part of the documentation, perhaps you could have
another look at the proposed directory structure and the concept of a
ROOT path for includes that I submitted previously:

> > We should think about a standard directory for
> > these: example perhaps with subdirectories. This brings up another idea.
> > Perhaps we could have some notion of a ROOT path for includes. Let's
> > say at the AIM (= ROOT) level we have directories:
> >
> >   AIM/
> >      dev/    # information etc. useful for developers, howtos etc.
> >      etc/    # scripts for packaging etc.
> >      example/# sample quiz files
> >      images/ # not present at Sourceforge
> >      WEB_INF/
> >
> > Does that sound reasonable.

A word on the images/ directory ... Neil had a few triangle .gifs that
I found useful in my own quiz files. I think others might find them
useful too, and there may well be other .gifs of general utility.
Again, it would be useful to have a ROOT path concept for images.

On Fri May 2 20:14:42 2003, Neil wrote:
> SourceForge gives us space for a web site as well as the CVS
> repository.  I think we should move everything from
> aim.shef.ac.uk/aimsource to SourceForge, including my sample
> questions, and any questions that anyone else wants to contribute.
> I will volunteer to do this. In the longer term, I think we should set
> up mechanisms so that questions offered for public distribution are
> stored and managed on the authors' AIM servers rather than on a
> central site.

This of course is the other reason for having sample questions.
Having a directory where one can `drop in' such questions and
some sort of ROOT path concept, would make it easy to include such
questions. It would also be good to have some sort of manifest
(README) for such question files that lists the name of the quiz
file, with a brief description and any keywords it might contain.
A script that peels this information from the quiz files would
be the way to do it ... another candidate for etc/ ... I can
put together such a script in perl. I think the sample questions
ought to have its own special directory outside the WEB-INF/root
tree. Thoughts?

  Regards,
  Greg