[Axiom-developer] documentation

[Tim Daly]

Stephen,

> Aren't they in the doc directory?

The pdf files are there but the tex sources are not.
Pdf is basically a binary, dead-end format.

I want to write an Axiom version of the tex that has axiom source
code spread all over the file. For instance, in the dotguide file
there is an example of how to create a simple digraph. To incorporate
this into axiom I'd rewrite the section to show what the related
axiom functions are (including their implementation), as well as
the output of an axiom session (which would automatically become
a regression test case). That way the documentation covers both
the source (as it is extracted), the testing (also extracted) and
the end user documentation (automatically built). Besides the
existing documentation I'd be writing a discussion of the design
decisions and the implementation details. That way future maintainers
can understand and maintain the code, tests, and docs all in one place.

You can fetch files from the Axiom website to see what I mean:

cvs -d:ext:address@hidden:/cvsroot/axiom co 
axiom/src/algebra/dhmatrix.spad.pamphlet

I extract code and docs using a tool called noweb
(http://www.eecs.harvard.edu/~nr/noweb) written by Norman Ramsey at
Harvard. It is a language-agnostic version of Knuth's Web literate
programming tool.

I can write all of this documentation from scratch but it's just
so much easier to start with existing work and slice and dice it.

Tim