[Axiom-developer] examples

[Bill Page]

Tim,

I have successfully downloaded your 3 sample pamphlet
files and completed the recommended exercises. So far
everything seems to be working ok for me win cygwin
under Windows XP just as you describe. It seems to me
that this should work quite well.

Let me know when you have the user id for access to
CVS.

Thanks.

Bill Page.

> -----Original Message-----
> From: address@hidden 
> [mailto:address@hidden On Behalf Of root
> Sent: Friday, November 01, 2002 9:58 PM
> To: Bill Page; Robert Morelli; Philippe Toffin; 
> address@hidden
> Cc: address@hidden; address@hidden
> Subject: Re: [Axiom-mail] Status
> 
> 
> 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
> 
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> Axiom-mail mailing list
> address@hidden 
> http://mail.nongnu.org/mailman/listinfo/axiom-> mail
>