William, > My parametric linear equation package IS documented: in a published > paper in the Journal of Symbolic computation, and in the source code. > It is not in a pamphlet style or what you call "literate with Knuth > technology.
> You have spent time to convert my IBM script to LaTeX, in the hope > I will expand it to a pamphlet. (and I haven't). Yes, I spent approximately 3 weeks of evenings recasting your paper into latex hoping to lower your "personal cost" of contributing it and its ideas as documentation. Despite that effort you still objected. That's fine. It is your choice to contribute or not. I didn't demand that you do, I simply tried to make it straightforward. I've done other "behind the scenes" work, including rewriting Barry's thesis, which has yet to bear fruit (due to lack of time as Barry has quite generously agreed to let his work be used in pamphlets). > But have you tried to read the paper? If you did not (and I believe > you did not) then what good would a pamphlet do? A pamphlet form would document the ideas for the future users of Axiom in a form we can use. There are thousands of mathematics textbooks but not many that explain the theory and the computational mathematics, in context with a particular implementation and its choices. A pamphlet is not just a copy of the paper. It should explain the "why" of the code in the context of the theory. We need to know not just the theory but how specific Axiom code implements it, what are its design constraints, what are its limitations, etc. I did read your paper, in detail, along with converting it. But my primary focus at the time was making it into latex. The effort was not for me but for people who might need to understand your code. If my goal was to document your code rather than recast your paper I would have spend considerably more time trying to understand the mathematics. For instance, I documented dhmatrix by understanding how they work. I helped Scott use them as the basis for the pictures in the Jenks book. I just started documenting the quaternions (see the new quat.spad). You'll recall I sent you some private links related to the theory of exterior and geometric algebras that I found during the course of understanding quaternions. I'm still studying those papers for the mathematics and hope to expand the quaternion and octonions domains in a more general setting. Indeed, if I could find the time there are some wonderful ideas that need to be reduced to working code. We've had discussions about your new algebra work, which I believe I do understand. But not to the level of being able to reduce the ideas to code. You do and you can. The point I'm trying to make is that I believe I could have understood the beginnings of your algebra on differential polynomials from a pamphlet you wrote using your paper. But my time was spent "on making the machinery work", which is needed rather than using my time to understand the algebra to the point where I could document it (which would have been a pleasant luxury). You're clearly much more qualified to explain your own work. That said, you have recently agreed to allow me to use the paper I converted as the basis for a pamphlet form of your work. Since you disagree so strongly about making pamphlets perhaps we can compromise. I'll make an effort to understand your algebra and an effort to write a pamphlet form. All I ask is that you have the patience to review it, explain what I don't understand, and correct the nonsense. Perhaps when you've seen it done you'll be more convinced of the power of literate programming. > I respect your philosophy of literate programming, and I only ask you > to repect that there are other ways to make code (and theory) > understandable. Of course there are other ways to make code understandable. But other code, e.g. Microsoft Word, won't give the same answers in 100 years. So there is a qualitative difference between computational mathematics and any other code being written. Almost all commercial code dies. All of the projects I've worked on have died "in the belly of the corporation". I believe that this fate awaits Mathematica and Maple, a topic which we've discussed. It certainly happened to Macsyma and would have happened to Scratchpad, but for the very generous efforts of Mike Dewar and other people at NAG. I've been trying hard to get Derive put into a "dead code safe", hoping that TI will agree to release the code if they lose interest in it. But getting the code is not enough. I've talked to the developers of Mathematica and Maple. The kernel code of those systems are very, very poorly documented by the programmers estimates. Yet I've attended ISSAC talks about the super-speed numerics at the heart of the system. I do not know but I'd bet that the only existing documentation will be the few pages of text from that paper. Due to publication constraints an ISSAC paper cannot address any real details about the code, the choice of data structures, or the relation of that code to the theory. That would take a pamphlet file. The point is that if Mathematica or Maple dies and if the failing company would release the code it is unlikely that the code will be brought back to life without the involvement of the original developer(s). (Of course code is now considered "intellectual property" (a non-legal concept but...) and is considered a real asset of the company. So if a company should go bankrupt they cannot "give away" the code. They need to sell it to recover the asset's value. I was quoted a price of $250k dollars for the source code for Macsyma. I don't have that kind of money.) Yet even in the unlikely circumstance that they do give it away you'll have a million lines of C code with clearly chosen variable names and no documentation. Thus we are faced with a choice. Do we let systems simply die and then invest the thousands of manyears of work to build new ones so the cycle repeats? Or do we invest in the code and try to make it "live" in a way that new users can learn about the concepts and their specific implementation? If we do that it requires the effort of the original developers to communicate with the future generations in specific detail. > Is literate programming the panacea? Would pamphlets help? We do not know for sure. But I firmly believe they will and this project is an experiment on that thesis, among other goals. So while there are many ways to write clear code (e.g. variable name choices) and various ways of documenting (ISSAC papers, textbooks, specification documents, Rational relation diagrams, ...) I believe that Knuth "got it right". He produced high quality, nearly bug free code with deep documentation. He placed his focus on writing for people rather than writing for the machine. And his program, Tex, has outlasted many other similar tools, even those backed by big money like IBM script. > As Donnie Brasco said in the namesake movie, let's "forget about it". Drop the debate but not the fundamental goal. There really is a guiding philosophy behind the choices that informs decisions about the quality of a proposed direction. All that said, I again apologize for being sarcastic. When the fundamentals of the project are being questioned I need to be quite clear when a debate misses the point. "Reducto ad sarcasm" is not a proper way to debate and I'm sorry that I fell to that level. I hold you in high personal esteem and I regret that mistake. Mea culpa. Tim _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer
