Alex, Heow, When I got the source code of Axiom from NAG I was getting back code I had written at IBM 15 years earlier. I found the source code hard to understand even though I strive to write dirt simple code.
In addition, the algebra implementation code was completely divorced from the supporting research or theory and, in most cases, did not even have regression tests or examples. While struggling with this code I spent some time trying to understand why it was so hard to get to know the system. I grant that Axiom is quite large (about 1 million things-of-code) but it has a limited domain. Two things opened my eyes. First, I spent time reading Knuth and his comments on literate programming. Second, I found the book "Lisp in Small Pieces" by Christian Queinnec. This book show that it is possible to fully explain a very complex piece of software in a readable fashion. The ultimate realization was that in order to survive, to allow people to maintain, to understand, and to extend Axiom the system needed to be literate. I initially restructured Axiom to use a latex-based file format combined with noweb (Norman Ramsey) to create pamphlet files. This was marginally effective but ultimately proved to be "thinking in the small". The pamphlet idea is too weak to be useful. Axiom is now in the process of becoming fully literate. All of the code is being organized into books. There are currently 18 volumes, 9 of which already contain their full subsystems, organized as follows: Volume 0: Axiom Jenks and Sutor This is the reconstructed Jenks and Sutor volume. Volume 1: Axiom Tutorial This is the tutorial volume ISBN 1-411-66587-X. Hardcopy is available from Amazon.com or Lulu.com Volume 2: Axiom Users Guide This is a more detailed explanation with current information for Axiom users. Volume 3: Axiom Programmers Guide This is information about the language and algebra hierarchy for Spad language programmers. Volume 4: Axiom Developers Guide This is a collection of useful information for developers. Volume 5: Axiom Interpreter This is the source code and explanation for the interpreter. Volume 6: Axiom Command This covers the axiom commands, sman, and some other system related issues. Volume 7: Axiom Hyperdoc This is the source and explanation of the X11 hyperdoc subsystem. Volume 7.1: Axiom Hyperdoc Pages This is the source and pages for Hyperdoc. Volume 8: Axiom Graphics This is the source and explanation of the X11 graphics subsystem. Volume 9: Axiom Compiler This is the source and explanation of the spad compiler. Volume 10: Axiom Algebra Implementation This is a multi-volume set covering the algebra. The first volume deals with implementation issues. Volume 10.1: Axiom Algebra Theory This volume gives background theory for various algebra topics. Volume 10.2: Axiom Algebra Categories This is the source code for all of the categories. Volume 10.3: Axiom Algebra Domains This is the source code for all of the domains. Volume 10.4: Axiom Algebra Packages This is the source code for all of the packages. Volume 11: Axiom Browser This is the source and explanation of the new Firefox browser front end. Volume 12: Axiom Crystal This is the design documents and internals for the crystal interface. Ulitmately each of these books will contain more words than source code. The "golden standard" I am trying to achieve is the level that is found in Queinnec's book. You should be able to sit down with a particular volume and read it like a story. You should be able to sit down and read the theory behind a particular domain as well as implementation details, category constraints, and performance issues. This is an ongoing process since these are living documents. Axiom stands in an interesting spot in history as one of the first full fruits of the collision of mathematics and computer science. It is important that future generations can read, understand, maintain, and modify this work. If this effort succeeds then Axiom will live. Tim _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
