[Axiom-developer] (no subject)

[daly]

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