Re: [Axiom-developer] Developers and Axiom (was Re: typo in src/boot/Makefile.pamphlet)

[root]

CY writes:

>                                         I would like to have a better
> editing environment for pamphlets, and I have somewhere the beginnings
> of a literate-document Emacs mode based on work by Jay and Ralf. 

and another private email writes:

> I've been looking at a number of literate programming tools for
> lisp/scheme (narrowing to l2t and the Scheme Elucidator), but ultimately
> neither does what I want - the former actually seems to eschew the main
> benefit of literate programming by separating code from its commentary;
> the latter cannot deal at all with local definitions or modules (though I
> think I can see how to fix this, the time required is likely more than I
> have). So I've come back to noweb.

so this is the method i use and i find it very productive:

noweb is a trivial idea really. 
 1) create a latex file that explains the program
 2) embed the source code for each program chunk into the latex file
    surrounded by the "chunk definition tag"

    <<any string>>=
        code
    @
 
 3) call the resulting file foo.pamphlet
 4) to get the documentation do:
     
     noweave foo.pamphlet >foo.tex
     latex foo.tex
     xdvi foo.dvi

    all noweave really does is change the chunks into verbatim blocks.

 5) to get the program do

     notangle foo.pamphlet >foo.c
     gcc foo.c

    all notangle really does is collect the chunk definitions in a hashtable
    on the first passs and then recursively expand them on the second pass.

in general i find the most effective way to work is:

 a) start emacs

emacs -nw 

 b) (split the screen in two) this gives you two buffers 
    at once on the screen the "C-x o" visits the "other buffer" 
    so you can switch back and forth

C-x 2 

 c) edit the foo.pamphlet file

C-x C-f foo.pamphlet

 d) start a shell in the other buffer

C-x 0
M-x shell

 e) now you have half the screen visiting the foo.pamphlet file
    and the other half of the screen running a shell in an emacs buffer.

    The general editing sequence is as follows:
   
    edit the file, 
    C-x C-s to save the changes, 
    C-x o to switch to the shell
    run notangle 
    run noweave

 f) but we can simplify this process considerably.

    1) we want to see the changes in the document as we make them.
       to so this use xdvi to visit the foo.dvi file thus:

xdvi foo.dvi &

       xdvi has the property that if it is running and the dvi file
       has changed it will automatically reread the dvi file and 
       display the changes. this means that every time we save the
       file and run latex we only need to click on the xdvi window
       and we see the new text immediately.

    2) create a makefile that automatically does all the work. call it
       Makefile.foo:

in Makefile.foo
=====================================================================

all: doc code test

doc:
        noweave -t8 -delay foo.pamphlet >foo.tex
        latex foo.tex
        latex foo.tex
        

code:
        notangle -R"code" foo.pamphlet >foo.c
        gcc -o foo foo.c

test:
        notangle -R"test" foo.pamphlet >testcase
        foo testcase

=====================================================================

    make -f Makefile.foo 

    * this extracts the documentation and updates the dvi file
      (which we can see immediately by clicking on xdvi)
    * this extracts the code and compiles it
    * this runs the newly compiled code on the test cases

Note that the code in the literate program is assumed to be expanded
under the tag <<code>>= but you could make it anything by changing
the notangle line.

Note that the test cases in the literate program are assumed to be
expanded under the tag <<test>> but you could make it anything by
changing the notangle line



     3) now the real magic happens with emacs....

        in emacs it is possible to set the "compile" command or
        you can use a "command line macro". i use the macro approach.

        in emacs you can record a whole set of keystrokes and make
        them into a command line macro that you can execute with "C-x e"

        after i've changed the source file i want to 
          a) save the changes (C-x C-s)
          b) switch to the shell buffer (C-x o)
          c) make -f Makefile.foo to run the makefile
          d) switch back to my program to continue editing.

        using the command line macro i can have this all happen in 1 keystroke
   
        to create a command line macro you type "C-x (" to start recording
        and "C-x )" to stop recording.

        so, with a split screen and the cursor in your code buffer and
        the shell in the other buffer do:

        C-x (                 <== start recording
        C-x C-s               <== save the changes
        C-o                   <== switch to the shell
        M-x >                 <== go to the end of the shell buffer
        make -f Makefile.foo  <== run make
        C-x o                 <== switch back to the code buffer
        C-x )                 <== stop recording

and now you have all the magic because "C-x e" does it all.
       
 do forever
   type your changes to your literate program, 
   type "C-x e" to noweave, latex, notangle, compile, test, and update xdvi
   click on xdvi to see the changes

i find it extremely productive. i run "C-x e" every 10 lines of changes
(about once every minute or two) so i know that the latest change will
compile, latex, and run the test cases properly.

t