Edit detail for Pamphlet Files revision 1 of 1

changed:
-
**Based on an email from Tim Daly on June 27, 2005 1:24 AM:**

It is important to the long term goals of the project that we document
the new work we are doing. The original developers, including myself,
did not do a good job documenting the system which makes it very
difficult to maintain and modify. Going forward we don't want to
continue making the same mistake. For that reason the open source
version of Axiom uses [Literate Programming] and all source code
and documentation is contained in pamphlet files.

Still, literate programming in Axiom is rather unexplored ground. If you get
an idea of the best way to do something in a pamphlet, just put it in the 
SandboxPamphletStyle.

A simple, stripped down pamphlet file that uses lisp is shown in
[Pamphlet Example]. What you see is a thumbnail image of the first
page of the final result. Click 'pdf' or 'dvi' to see the full
document and click 'edit' to see the actual source code.
 
This document contains the explanation of the lisp code, it contains
the source code for the lisp, and it contains a Makefile to build itself.

You need to extract the Makefile before you can use it. This is done with
the 'notangle' command from noweb. Once you've extracted the Makefile all
you ever need to type is 'make' and everything is automatically rebuilt.
That way you can write a new paragraph, add new code and type 'make'.

As this was literally ripped out of my local working environment it's
not likely that it will run the first time but it should be close.

To use this file you need to 

0 store this file somewhere (e.g. /tmp/autodoc.lisp.pamphlet)

1 get noweb-2.10a.tgz::

        cd /tmp
        mkdir noweb
        cd noweb
        wget http://daly.axiom-developer.org/noweb-2.10a.tgz

2 untar noweb::

        tar -zxf noweb-2.10a.tgz

3 make noweb::

        ./awkname gawk
        make all install

  this will install a few commands, two of which you need.
  One is called 'notangle' and the other is 'noweave'.
  Be sure they show up on your path.

4 extract the makefile using 'notangle'. (notangle is a command 
  to extract code from a pamphlet. noweave is a command to 
  extract latex from a pamphlet)::

        cd /tmp
	notangle autodoc.lisp.pamphlet >Makefile                

5 get axiom.sty::

        wget http://daly.axiom-developer.org/axiom.sty

6 modify the Makefile to point at your lisp command and
  your notangle and noweave commands.

7 build the document and run the lisp code

        make

If you do::

        xdvi autodoc.dvi &
        emacs autodoc.lisp.pamphlet
           (and start an emacs subshell)
        then you can modify the file 
             type make
             and switch the focus to the xdvi window which will
             automatically refresh with the new changes.

It's a very fast way to develop a pamphlet file.

        xdvi autodoc.dvi &
        emacs autodoc.lisp.pamphlet
           (and start an emacs subshell)
        then you can modify the file 
             type make
             and switch the focus to the xdvi window which will
             automatically refresh with the new changes.