[Axiom-developer] Literated eigen.spad.pamphlet

[Bill Page]

On Frithjof Schulze September 23, 2006 6:24 AM wrote:
> ... 
> 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.

http://wiki.axiom-developer.org/axiom--test--1/src/algebra/EigenSpad

Great job! I am really glad that you invested time in doing this
work. I think it is excellent contributioin ot Axiom. I hope that
this work by you, Kai and Cliff is part of a trend ... :-)

> 
> 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?
>

The first thing I would strongly suggest is that if you make
extensive changes like this to a pamphlet then you *should* add
your name as an author. We do want to recognize people for the
contributions they make. Ultimately perhaps, the authors/editors
of these pamphlets might wish to add them to their personal list
of papers and publications. In many cases these contributions
should count as research.

Of course getting the details right is important but just getting
started is sometimes the hardest part. But I didn't find any problems
in what you wrote and I learned several things about the Axiom eigen
package that I didn't know before. Thanks.

> Three 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?

I think references are important. Use web references if you can.
I suggest using hyperref to add clickable links directly in the
LaTeX source.

> 
> 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.

I think including a short section on notation in each pamphlet
would be good enough for now.

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

Starting with just a heuristic description is fine. If you are
able to make some formal definitions and add a theorem or two
that might make the mathematician more comfortable :-) but it
is not necessary at this point - especially if you can find some
basic references.

Regards,
Bill Page.