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

[Frithjof Schulze]

Hey,

Kai Kaminski <address@hidden> wrote:

> 
> I've 'literated' VMLISP.LISP.PAMPHLET (the result is attached), which
> contains compatibility/utility code.

I tried the same with eigen.spad.pamphlet. As a beginning I structured
the file, commented the functions I understand (although sometimes what
I wrote seems rather obvious) and began to write a little about the
theory. 

I put the file in the wiki-source, so hopefully somebody comes up with
some kind of criticism. This is just a first try and I welcome
tips/ideas what to change. Hopefully I didn't made any content related
errors?

Tree additional questions concerning the literate source I have by now:

    How much theory belongs in a pamphlet? For example after a nice
    description what the gröberner basis algorithm does, is it important
    why it terminates? Or is a reference here enough? 

    If every file should be as elaborate as dhmatrix.spad, shouldn't one
    have a central point where the notation and foundations stuff gets
    clarified? Else, one would have to introduce the notation of
    vectors, matrics etc. again in every file that uses them. Maybe one
    should have a latex-style-convention in the wiki.

    How formal should a pamphlet be? Rather a heuristically description
    what happens (with reference) or better Definiton, Theorem ... ? 

Frithjof