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

[C Y]

--- Frithjof Schulze <address@hidden> 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. 

Excellent!  Thank you!

> 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 check is whether it builds correctly.  Or as Bill suggested,
check the notangle result against that of the previous file.

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

I don't know if there's a good answer to this.  My personal feeling is
that as much relevant information should be there as the author has
time to add, since many people may not be able to get to the referenced
articles without being at a university, but it's a judgement call -
obviously you don't want the entire life history of the major
researchers in the field as part of the pamphlet.  

I guess my response would be don't worry - just write what you think
best, and it can always be improved.  As long as the content is
accurate, it's going to be an improvement over what we have now!

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

Again, that's a judgement call.  I personally think it should go
something like this:

a)  In the files that implement vectors, matrix logic, and tensors a
full discussion should be present of the issues of syntax concerning
defining, displaying, and representing those objects according to major
mathematical conventions.

b)  In more specific files, a brief discussion of the points relevant
to the case in question along with a link to the main pamphlet(s) on
the issue would make sense.  If some specific conventions or syntax are
defined for the given topic, that should be discussed in the pamphlet. 
Also subject specific conventions which are not part of the wider
mathematical conventions should be covered.

Again, that's just me.  But a full treatment of a subject isn't
necessary when proposing a change - incremental improvements are also
welcome!
 
>     How formal should a pamphlet be? Rather a heuristically
>     description what happens (with reference) or better Definiton,
>     Theorem ... ? 

I don't think we're going to be universal on that right now - just
write as you prefer, and if at some point we decide on a general
convention we can go back and retool the pamphlets to all conform.  At
this point it is far more critical to get good, accurate literate
content - we don't want to drive away contributions due to style
nitpicks.  Those kinds of things can be fixed later.

My 2c,

CY

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com