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

[Kai Kaminski]

Ralf Hemmecke <address@hidden> writes:

>> Not quite. This whole BL*H thing is thoroughly confusing. I'll just
>> give you the real code (kind of).
>>
>> File1:
>>
>> (defmacro alias-for-foo (...)
>>   [code generating code calling foo])
>>
>> (defun bar (...)
>>   ...)
>>
>> (defun define-function (alias function)
>>   (setf (symbol-function alias) function))
>>
>> (define-function alias-for-bob #'bob)
>>
>> End of File1
>>
>> FOO and BOB are functions defined elsewhere. Now I wanted to put all
>> (most) aliases in a single chunk since they don't deserve individual
>> documentation. Hence the first and last forms above go into a single
>> chunk:
>>
>> <<aliases>>=
>> (defmacro alias-for-foo (...)
>>   [code generating code calling foo])
>>
>> (define-function alias-for-bob #'bob)
>> @
>
> Hmmm, I am not sure I can support that approach. For two reasons.
>
> 1) Most probably the aliases come in the documentation without links
> to the code they refer to. (Though that can be done.)
I'm not quite sure what exactly you're getting at.

> 2) You separate code that belongs together. Don't you think?
I suppose you mean that an alias definition should be next to the
definition of the function that it's an alias for? Like

<<foo>>=

(defun foo (...)
  ...)

(define-function alias-for-foo #'foo)
@

That's what I thought at first, but then it occured to me that

1) Aliases in general aren't terribly useful. The only exception I can
   think of is the following. Suppose you have an operation acting on
   objects of type FOO, say COMPARE-FOOS. Now it happens that the
   definition of that function is

     (defun compare-foos (&rest foos)
       (apply #'equal foos))

   In this case it is acceptable to create COMPARE-FOOS, because it
   captures a different concept. This is also useful if you later
   change the implementation of objects of type FOO, and you can't
   just compare them with EQUAL. In that case you simply change the
   implementation of COMPARE-FOOS. If you'd use EQUAL directly, you'd
   have to check each and every EQUAL in your source to figure out
   wether it has to be adapted to the new implementation of FOOs.

   Other than that I don't see any justification for aliases.

2) To be useful in the sense described above, an alias needs a good
   name. Almost all the aliases in VMLISP.LISP.PAMPHLET have terrible
   names. Here is a small sample:

     (defmacro absval (x)
       `(abs ,x))

     (defmacro intp (x)
       `(integerp ,x))

     (define-function 'U-CASE #'upcase)
     (define-function 'LC2UC #'upcase)
     (define-function 'L-CASE #'downcase)

     (define-function 'EVA1 #'eval) ;EVA1 and VMLISP EVAL make lexicals visible
     (define-function 'EVALFUN #'eval) ;EVALFUN drops lexicals before evaluating
     (define-function 'EVA1FUN #'EVALFUN)

     (define-function 'vm/ #'quotient)

   Note that apparently a single function can act differently
   depending on what it's called.

   I believe that all the aliases in the 'Aliases' section should be
   removed or at least renamed. I admit to being inconsistent, as
   there are many aliases that are not in that list, even though I
   often made a comment pointing out that they should be removed. One
   example is MAKE-VEC, which is defined as

     (defun make-vec (n)
       (make-array n))

   I'm not sure why this one got through. Another example is DSETQ,
   which is an alias for DODSETQ.

The 'Aliases' section contains only those aliases that I think should
be removed from Axiom. It so happens that almost all the aliases in
VMLISP.LISP.PAMPHLET qualify.

> Why would it make sense to list all the abbreviations on one section
> (even without documenation)?
Because they're all obsolete. That section is a list of things to
remove. Since that requires changing a lot of code (trivially), I
didn't do it (yet; I'm actually waiting for Tim's opinion on this,
before I go ahead and get rid of them). 

>> Thanks for taking the time to discuss - admittedly boring - details.
>
> I don't think that it is "boring". I am sure that most of us have no
> real experience what the best LP style in Axiom would be. Otherwise I
> would have seen a "Conventions" page that explains how to write good
> literate programs. It's not totally clear, at least not for me.
Not to me, either. When I read your first response to my VMLISP.LISP
conversion I actually thought about that. I was going to suggest that
you put up the example you gave (the Groebner basis fragment).

> But all our experiences must be collected some day on the wiki or
> another document to help newcomers with this LP style in Axiom. It's
> important.
It is. That doesn't really make discussing the intricate details of
chunking exciting, though. ;-)

Kai