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

[Kai Kaminski]

Ralf Hemmecke <address@hidden> writes:

> 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.
Most of the functions in VMLISP.LISP.PAMPHLET are really short and
it's hard to see how they could benefit from splitting them up
further. Sometimes functions don't really need individual
documentation, eg. aliases, and it makes sense to stick them
together.

There are a few fairly long and complicated functions, and those
should probably be split up into multiple chunks. Unfortunately, I
have no idea what they do. They are not documented at all and they are
written in a peculiar style.

> 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.
Sure. If only I knew what the code does.

> 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.
Actually there is a Lisp specific problem here. Often Lisp code
doesn't rely as much on side effects. Also every Lisp statement is an
expression with a value, which is used a lot. Finally people tend to
use lots of small functions. What is the difference between

(defun bar (...)
  (blah blub))

(defun foo (...)
  (let ((...))
    (bar ...)))

and

<<foo>>=
(defun foo (...)
  (let ((...))
    <<do-bar>>))
@

<<do-bar>>=
(blah blub)
@
  
>> 4) I *did* change the order of function definitions. This was
>>    necessary since I put several functions within a single chunk.
>>
>> 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.
>
> 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.
I couldn't, since I reordered code. There's not really a good way
around that, I believe.

Kai