login  home  contents  what's new  discussion  bug reports     help  links  subscribe  changes  refresh  edit

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

  1. store this file somewhere (e.g. /tmp/autodoc.lisp.pamphlet)
  2. get noweb-2.10a.tgz:
            cd /tmp
            mkdir noweb
            cd noweb
            wget http://daly.axiom-developer.org/noweb-2.10a.tgz
    
  3. untar noweb:
            tar -zxf noweb-2.10a.tgz
    
  4. 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.
    
  5. 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                
    
  6. get axiom.sty:
            wget http://daly.axiom-developer.org/axiom.sty
    
  7. modify the Makefile to point at your lisp command and your notangle and noweave commands.
  8. 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.




  Subject:   Be Bold !!
  ( 13 subscribers )  
Please rate this page: