[Axiom-developer] Literate Programming

[daly]

The latest changeset introduces two related changes, gclweb and
axiom.sty.  Together these changes allow optional syntactic changes to
pamphlets.  These changes will completely eliminate the need to weave
files since now a pamphlet file can be a valid latex file. Tangle is
the only remaining command and it will eventually be an option on
)compile, etc. If you don't care then these changes don't affect you.



src/interp/gclweb.lisp

The src/interp/gclweb.lisp file introduces the ability to extract code
from pamphlet files while inside Axiom. The short description is that
gclweb will now automatically distinguish the type of chunk style
(latex or noweb) based on the chunk name. It is a first step to a native
understanding of pamphlet files. Future work involves integrating it
into commands like )compile and adding commands like )tangle. 

To tangle a file from within Axiom:

  )lisp (tangle "filename.pamphlet" "<<chunkname>>")
  
which is noweb syntax. Output goes to the console. You can direct the
output to a file with the optional third argument:

  )lisp (tangle "filename.pamphlet" "<<chunkname>>" "filename.spad")


If you use the new latex chunk environment the syntax is:

  )lisp (tangle "filename.pamphlet" "chunkname")
  )lisp (tangle "filename.pamphlet" "chunkname" "filename.spad")

gclweb distinguishes the input syntax by looking at the first character
of the chunkname. If it is a '<' then noweb is used, otherwise latex.





src/doc/axiom.sty.pamphlet

This introduces the new chunk environment. This is a completely
compatible change and has no impact on existing pamphlets. The
new syntax makes pamphlet files = tex files so there is no need
to use weave. The gclweb change has a compatible tangle function
which can be invoked from inside Axiom.

Noweb syntax of:

  <<chunkname>>=
    your code goes here
  @

can also be written as:

  \begin{chunk}{chunkname}
    your code goes here
  \end{chunk}

The new syntax is entirely optional.


One new feature of the latex chunk style is that latex commands
work within the chunk. To get typeset mathematics use \( and \)

-- This will typeset in a chunk \( x^2+\epsilon \)
-- And you can format things {\bf bold}

Tim