[Axiom-developer] Re: [Axiom-mail] Status

[root]

All,

Be sure you've subscribed to the axiom-developer mailing list as I'll only
be copying the list from now on so we can journal the discussions. I urge
you to actually try these instructions because it will make sure that we
share the same ability to create, use and view pamphlets. If these
instructions don't work for you let me know because we need to make
sure you've got a proper environment set up.

I've uploaded 3 examples of literate programming to illustrate styles.

An Algebra Example:

The first is called dhmatrix.pamphlet. The instructions for use are:

1)  wget http://home.earthlink.net/~jgg964/dhmatrix.pamphlet
2)  notangle dhmatrix.pamphlet >dhmatrix.spad
3)  noweave dhmatrix.pamphlet >dhmatrix.tex
4)  latex dhmatrix.tex
5)  latex dhmatrix.tex
6)  xdvi dhmatrix.dvi

step (1) will fetch the file. (wget is a useful utility for fetching
   files given by a url. how you actually get the file is up to you)
step (2) will read the pamphlet file and create a spad file.
   spad is the algebra language of Axiom. This file is extracted from
   the pamphlet file and when diff'ed against the original source
   shows no difference (an important point since we don't want to
   introduce errors by wrapping the original source files into a
   literate style).
step (3) will extract the tex output from the pamphlet file. notice
   that the dhmatrix.tex file has commands like \documentclass 
   prepended automatically by noweb. This is, in general, not what
   we want so normally we will use the -delay parameter to noweave.
   However for this particular example I am experimenting with the
   ability to collect many pamphlets into a booklet and I deliberately
   left off the \documentclass, etc. The default behavior of noweb
   works in this case.
step (4) and (5) read the dhmatrix.tex file and create dhmatrix.dvi
   We need to latex it twice to get the cross-references right. I
   don't believe there are any cross-references in this file yet but
   I do this by habit.
step (6) will let us view the dhmatrix.dvi file. You could also use
   other utilities like dvips to create a postscript file or dvipdf
   to create a pdf file. I tend to work directly from the dvi file.

The dhmatrix.pamphlet file is an example of documenting the algebra
code. The original dhmatrix.spad file (which I wrote) was taken from
Richard Paul's Ph.D. thesis which became a book (Robot Manipulators).
Richard gave me permission to quote from his thesis for documenting
the domain. There is much more work to be done but this pamphlet was
written as a first experiment.

In general I hope to search out primary sources for the algebra
that lives in Axiom and either get permission to directly quote
the relevant paper or study the paper and write a new pamphlet.
There is a large piece of work to track down the original works.

The next piece of algebra documentation is to use Barry Trager's
Ph.D. thesis to document the integration code. I have his thesis
and permission to use it for documentation purposes. There is a
long leap from the thesis to the code so I have a fair bit of
background research I need to do before I can write up the 
pamphlet. The original thesis is 85 pages.



A MAKEFILE Example:

The second file I've uploaded is actually from the sources we'll
be using. It is a Makefile in the Codemist Common Lisp (CCL) subtree.
The instructions are:

1)  wget http://home.earthlink.net/~jgg964/Makefile.pamphlet
2)  notangle -t8 Makefile.pamphlet >Makefile
3)  noweave -delay Makefile.pamphlet >Makefile.tex
4)  latex Makefile.tex
5)  latex Makefile.tex
6)  xdvi -expert -s 3 Makefile.dvi

step (1) will fetch the file.
step (2) will read the pamphlet file and create the Makefile. Notice
   the -t8 (tabs every 8 spaces) parameter to notangle. In general we
   will need this parameter and it doesn't hurt to have it if there are
   no tabs so we will use it all the time.
step (3) noweave will read the pamphlet file and create the tex output.
   Notice the -delay option to noweave. We have included the \documentstyle
   and other header information in the pamphlet file already. The -delay
   option allows us to do this. Unless the file is going to be included
   as part of a larger document (like the algebra file above) we will
   generally write our own document headers.
steps (4) and (5) are latex->dvi done twice to get reference right.
   You are certain to get a complaint about a missing noweb.sty file
   because this Makefile was ripped out of the real source tree.
   For demo purposes you can modify the line in the original pamphlet
   file from:
\usepackage{/home/axiomgnu/new/mnt/linux/bin/tex/noweb}
   to:
\usepackage{noweb}
   and rerun the command. I would ask you to resist the urge to 
   change the tex file directly as you need to think of the pamphlet
   file as the source and everything else as machine-generated files.
step (6) invokes xdvi with -expert (which eliminates the buttons as
   I know the keyboard commands) and -s 3 (which gives sufficient
   magnification so I can read it).

This makefile shows a documentation style for Makefiles in general.

Makefiles are generally very verbose in their stanzas because we will
not be doing compiles in the same directories as the source files nor
will we be depending on default stanzas to do compiles. 

We need to document the various stanzas and any special options that
we might add to the compile commands. Look for the TPD string which
I use to ifdef any changes I made to the original C sources. This
shows up as a -DTPD on the compile line for that particular stanza.

Also note that the end of the Makefile.tex contains references to
other pamphlets. The reason for these to support a future plan. We'd
like to be able to accept new code, particularly algebra code, that
we can add to the system in a reasonably automated fashion. The 
references will give us this connection. I expect to expand the
format later. These are only placeholders.

The other reason for the references is that the commands are not
actually documented in the Makefile. The Makefile only documents
build information and other special instructions. For instance,
in another Makefile (not shown here) you need to build a special
Axiom library before you build the C code. While the Makefiles
know this it would be easy for a human to overlook. Instructions
on how to use a particular command as well as documentation on
the C code that implements the command do not belong in the Makefile
but reside in the pamphlet file for the command itself.

Makefiles will also contain information about what a particular
directory contains and why it exists in the source tree.



A Non-Axiom Example:

This is an example using Java to show how to build a stand-alone
command and its Makefile

1)  wget http://home.earthlink.net/~jgg964/Magman.pamphlet
2)  notangle -t8 Magman.pamphlet >Makefile
3)  make

This illustrates a couple of useful points. First, the default
output of running notangle is the stanza marked <<*>>= in the
original source file. In Magman.pamphlet this is the Makefile.
If you read the dvi file that gets generated (or read the
generated Makefile if you must (sigh)) you will see that we
use the -R feature of notangle. The -R flag will extract particular
tags from the pamphlet file. So, if this were C code we could embed
the .h file, the .c file, and the associated Makefile into the pamphlet 
and send them as one file.

Another point is that this pamphlet file has real mathematics and
real references in it. We will need this to explain sections of Axiom.
In the long term plan we want people to submit papers to an Axiom 
Journal that includes the mathematics and executable code. That way
reviewers can test the code, readers can understand the code, the
system can import the code and maintainers can update the code.

This code is not related to Axiom but is here to illustrate the
embedded Makefile and mathematics points. If you don't have Java 
this will fail but that is not important. Note that we mix Java
C and Makefile in the same pamphlet file.

Tim