This is a port of Clojure to Common Lisp.
We use SBCL as our version of Common Lisp.
We use latex as our markup language.
We use git as our repository.

On Linux, you will need to install certain tools. 

    apt-get install sbcl git-core texlive

The program is implemented as a literate program. A literate program
is a book that contains both the explanation and the source code. The
idea is that you write words to communicate ideas to other people and
then implement these words in lisp to communicate ideas to the machine.

The "quick start" is:

    gcc -o tangle tangle.c
    ./tangle clojlisp.pamphlet Makefile >Makefile
    make
    xpdf clojlisp.pdf &
    emacs clojlisp.pamphlet
        .... loop
        ....    make changes
        ....    type make at the command line
        ....    see changes reflected in the pdf
        ....    play in the lisp command line


In slightly more detail, the idea is that you have a program called
"tangle" which extracts "chunks" from the clojure.pamphlet file.
You can choose any "chunk" in the file. Chunks are in latex chunk
environments which are just pieces of text between

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

To build the tangle program just type:

    gcc -o tangle tangle.c

which compiles the program and creates a command line function called
"tangle". Because it is in the local directory you need to use use
"./tangle" to run it.

The tangle program accepts two arguments, the file and the chunk name,
and outputs the result to standard output. You can redirect this to a
file as in:

    ./tangle clojlisp.pamphlet clojlisp >clojlisp.lisp

which will extract the clojlisp program and put it in the clojlisp.lisp
file.

Most of the build steps are automated in the Makefile.

Working in literate programming is simple. You need an editor and a
command line. Make changes directly to this document using the editor
and then type

    make

This will destroy the old source and rebuild the clojlisp.lisp file.

If you change the Makefile section in the document, which is rare, you
will have to extract it before the changes take effect:

    ./tangle clojlisp.pamphlet Makefile >Makefile

If you are working in Linux it is very effective to use emacs with a
split screen. Start a command line in one buffer and a shell in the
other buffer. If you start xdvi running in the background you will
immediately see the ``printed'' form of the document every time you
switch to the xdvi window.

    xdvi clojlisp.dvi &


The same trick can be used with the PDf file instead. Both xdvi and
xpdf will update automatically when the file is changed on disk.

    xpdf clojlisp.pdf &

Resist the urge to edit the clojlisp.lisp file.  It is only there for
the computer. Edit this file directly. Be sure to write words to
communicate your ideas just as you would when writing a book.  The
machine code is secondary and intended to make the ideas concrete.

To run the clojlisp command line, type:

    sbcl
    (load "clojlisp.lisp")
    (in-package "CLOJLISP")
    (clojlisp)

Note that the clojlisp function knows almost nothing so you have to 
fully qualify every symbol. Try:

    (common-lisp::+ 2 3)

To quit SBCL from the clojlisp function type:

    (sb-ext:quit)

Questions and comments should be directed to:

    Tim Daly <[email protected]>