[Axiom-developer] An idea - Axiom Survey Team

[C Y]

This idea came out of some IRC discussions between myself and Kai a
little while back, and I thought we might as well bring it to the list.
 One of the drawbacks to the current Axiom codebase is that while the
existing pamphlets can indeed be processed by noweave and notangle,
they are not literate in the sense of having code chunks and
documentation woven together and being reorganized for human
consumption.  (At least, most of them - there are a few exceptions.)

While many of us lack the technical skills to be able to decode the
actual source code and document what it does, an alternative which can
still be useful is to take the mostly monolithic code chunks in the
existing pamphlet files and break them down into something more
managable.  Even if for the most part the people doing this can't add
useful comments, they can introduce a more literate program like
structure to the file and clear the way for more skilled programmers
who will deal with these files in the future.

The approach is simple - select one pamphlet file, and re-configure the
<*> chunk (usually the only chunk in a file aside from the license)
into more discrete components as per dhmatrix and other such files.  Of
course the breakdown made might be something other than the final,
optimal structure used during documentation but it should at least help
start the process.  If the person surveying the file has some idea as
to the functionality of some parts they can go ahead and introduce
documentation, but that is not essential - the idea is to make use of
anyone who might be less skilled at reading old lisp and boot code but
would still like to further the progress of Axiom.  Hence the name
Axiom Survey - it is not intended to be an in-depth exploration and
comprehension of the source code, just a first pass that helps those
who will follow.

As a more or less arbitrary starting point, we picked the
i-*.boot.pamphlet files in the interp directory.  I've broken down a
few of them into smaller chunks, although I haven't really added much
in the way of documentation as yet.  I created diff -Naur patches, but
it's almost needless since the only change is the literate structure
and there is no logic change to be explained.  They seem to build OK so
I'm hoping that means I didn't let any code slip through the cracks.

Does this sound like a useful project to put in motion?  With luck it
will be an aid to those who are skilled enough to understand the code,
and at the same time it will help introduce people to the Axiom
codebase.

Cheers,
CY

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com

axiomsurveypatches-092006.tar.gz
Description: 1549528795-axiomsurveypatches-092006.tar.gz