--- Frithjof Schulze <[EMAIL PROTECTED]> 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 _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
