[Axiom-mail] Re: Free and Open Source Axiom exists

[root]

Lupo,

Literate programming is something of a stretch to start using.
It's like object oriented programming used to be. It seems like a
lot of work for nothing and horribly inefficient.

If all else fails, when you build the system you will find all of
the sources without the tex documentation in the axiom/int/* subdirectories.
And, in the final system, the mnt/linux/src/algebra directory contains
the spad files in their original form.

The key problem that literate programming solves, as I point out in the
README, is that it is not sufficient to just point someone at the code
(especially algebra code) and say "read it". You need to have the associated
research and theory.

If you know TeX then the literate programming is a trivial extension.
You make a Tex file, add inline code with a special tag, and save it 
as a pamphlet file, thus:

In file foo.pamphlet:

\documentstyle                     <== make a tex document
\begin{document}                   <== with all the usual stuff
\section{foo}                      <== including anything tex likes
This explains the following code   <== with your own text
<<fooname>>=                       <== define "chunk" fooname
  (defun foo () )                  <== with any code
@                                  <== end it with an @ in column 1
This explains more code            <== more tex
<<barname>>=                       <== define chunk barname
  <<fooname>>                      <== you can reference other chunks
  (foo x)                          <== and write new code
@                                  <== end it with an @
<<*>>                              <== this is the thing "notangle" expands
  <<barname>>                      <== barname will be expanded
  <<fooname>>                      <== as will anything else in order
@                                  <== end it with an @
\end{document}                     <== and now you have a literate program


noweave foo.pamphlet >foo.tex      <== extract a tex document, quoting code
notangle foo.pamphlet >foo.lisp    <== extract only the <<*>> expansion

It is really quite simple but it allows you to document your code with
the full power of Tex, keeps the documentation and code together, and
allows you to explain the code in logical order but expand it in compiler
required order. Plus you can write readable math inline.

Axiom is lightly documented so far. I've only had time to rewrite the
system into this new style (notice there are no C, lisp, spad, or
Makefile files). The Makefile.dvi files explain how the build process
works. 

If you look at dhmatrix.spad.pamphlet you'll see an example of the
use of literate programming. The text comes, with permission, from
Richard Paul's Ph.D. thesis. I wrote the embedded code. Run xdvi
on dhmatrix.spad.dvi and see if you think the results are worth it.

Tim