Re: [Axiom-developer] Literated VMLISP.LISP.PAMPHLET

[Ralf Hemmecke]

Kai,

I don't much understand lisp, but what you did in literating the code is 
just super.

On 09/21/2006 05:51 PM, Kai Kaminski wrote:
> Hi,
>
> I've 'literated' VMLISP.LISP.PAMPHLET (the result is attached), which
> contains compatibility/utility code. In particular, I did the
> following:
>
> 1) I gave most functions their own chunk. Sometimes I put several
>    functions in a single chunk, mostly because they didn't need
>    individual documentation. For example there are a lot of aliases. I
>    put most of them in a single chunk.

For a first approximation that is OK, but I don't believe that the chunk 
names should agree with the names of the functions. If literate 
programming is done in that way, it doesn't add any value.

Not only the documentation around the function should describe the idea 
behind the code also the chunk names should should tell what the code is 
used for. So you would have

<<compute a Groebner basis>>=
<<initialize basis and critical pairs>>
while not empty criticalPairs repeat {
    <<take a critical pair>>
    <<compute the S-polynomial>>
    h := <<reduce the S-polynomial with respect to current basis>>
    if not zero? h then {
        <<update basis and critical pairs>>
    }
}
@

That's the essence of the GB-algorithm. And literate programs should 
convey this essence.

I admid that for LISP it's proably harder to put it into that style, but 
I guess, we are all learning what exactly LP is while we make 
experiences with real code.

> 2) I added/removed blank lines and comments. The latter only if they
>    appeared to be useless. Otherwise I just kept them.
>
> 3) I *did not* change the capitalization/formatting of code. At least
>    not intentionally.
>
> 4) I *did* change the order of function definitions. This was
>    necessary since I put several functions within a single chunk.
>
> 5) I *did not* delete any code that wasn't commented out.

[snip]

> 8) I built Axiom using the new version. The build didn't finish, but
>    it failed in the same spot as with the old one (algebra: compiling
>    ahyp.spad). Cliff (CY) apparently succeeded building Axiom with the
>    new file.

[snip]

I think since you are not deleting or modifying code, you should just 
check, whether the notangled .lisp file is identical to the one from the 
monolithic chunk. It should be no problem to achive this. Then you are 
sure that the compilation will run through.

Good luck for all your work to come. Axiom will benefit from it.
Acually we need more people like Kai.

Ciao
Ralf