[Axiom-developer] (no subject)

[daly]

Kai,

As I mentioned 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.

Attached is a simple, stripped down pamphlet file that uses lisp.

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.

Let me know if you need more detail or can't get it to work.

===================================================================
\documentclass{article}
\usepackage{axiom}
\begin{document}
\title{Autodoc}
\author{Tim Daly}
\maketitle
\begin{abstract}
We want to generate the reference information from axiom source
files automatically.
\end{abstract}
\eject
\tableofcontents
\eject
By design the chunk name has 3 fields. 
The first field is one of \{category, domain, package\}.
The second field is the abbreviation.
The third field is the full name.
This routine will return two lists, the first is the list of
abbreviations and the second is the list of full names.

We keep looping until we run out of input, at which point we
throw out of the loop and catch it here.
<<until done>>=
  (catch 'done
@
We open the source file
<<open source file>>=
   (with-open-file (in sourcefile)
@
We read each line, trimming off trailing spaces
<<for each line do>>=
    (loop
     (setq expr (read-line in nil 'done))
     (when (eq expr 'done) (throw 'done nil))
     (setq expr (string-trim '(#\space) expr))
@
We look for lines that begin with a chunk name that
starts with package, domain, or category and end with an
equal sign (which indicates a chunk definition).
<<when package domain or category definition>>=
     (when 
      (and (> (length expr) 4)
           (or
            (string= "@<<pa" (subseq expr 0 4))
            (string= "@<<do" (subseq expr 0 4))
            (string= "@<<ca" (subseq expr 0 4)))
           (char= (elt expr (1- (length expr))) #\=))
@
We remove the 3 characters, two $>$ and an $=$ which make up the chunk name.
<<remove the trailing chunk characters>>=
      (setq expr (subseq expr 0 (- (length expr) 3)))
@
We get the third field from the string which is the long name.
<<capture the long name>>=
      (setq point (position #\space expr :from-end t :test #'char=))
@
We get the second field from the string which is the abbreviation.
<<capture the abbreviation>>=
      (setq mark
       (position #\space 
        (string-right-trim '(#\space)
         (subseq expr 0 (1- point))) :from-end t))
      (push (string-trim '(#\space) (subseq expr mark point)) names)))))
@
<<srcabbrevs>>=
(defun srcabbrevs (sourcefile)
 (let (in expr start end names longnames)
<<until done>>
<<open source file>>
<<for each line do>>
<<when package domain or category definition>>
<<remove the trailing chunk characters>>
<<capture the long name>>
      (format t "~a ~a ~a~%" expr point longnames)
<<capture the abbreviation>>
  (values names longnames))))

@
\section{Doit}
<<doit>>=
(srcabbrevs "/new/patch38/src/algebra/acplot.spad.pamphlet")

@
\section{Autodoc}
<<autodoc>>=
<<srcabbrevs>>
<<doit>>
@
\section{Makefile}
<<*>>=
TANGLE=/usr/local/bin/notangle -t8 
WEAVE=/usr/local/bin/noweave -delay
LISP=/new/patch38/obj/linux/bin/lisp

all: code doc run

code: autodoc.lisp.pamphlet
        @${TANGLE} -Rautodoc autodoc.lisp.pamphlet >autodoc.lisp

doc: autodoc.lisp.pamphlet
        @${WEAVE} autodoc.lisp.pamphlet >autodoc.tex
        @latex autodoc.tex
        @latex autodoc.tex

run: autodoc.lisp
        @cat autodoc.lisp | ${LISP}

remake:
        @${TANGLE} autodoc.lisp.pamphlet >Makefile

@
\eject
\begin{thebibliography}{99}
\bibitem{1} nothing
\end{thebibliography}
\end{document}


Tim