[Axiom-developer] [Pamphlet Files] (new)

[Bill Page]

Changes http://wiki.axiom-developer.org/PamphletFiles/diff
--
**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.

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.

--
forwarded from http://wiki.axiom-developer.org/address@hidden