This is CLWEB, a literate programming system for Common Lisp. This file
describes how to get started with CLWEB; it is not a user manual or an
introduction to literate programming in general. A full user manual is
forthcoming; in the meantime, please see the CWEB user manual by Knuth
and Levy, or Knuth's "Literate Programming" (CSLI: 1992).

In the examples that follow, a dollar sign ($) represents a Unix shell
prompt, and a star (*) represents a Lisp prompt.

The first thing to do is to compile and load the CLWEB system:

    $ lisp
    * (compile-file "clweb")
    ; compiling file "/home/alex/src/clweb/clweb.lisp"
    ; [compilation messages elided]
    #P"/home/alex/src/clweb/clweb.fasl"
    NIL
    NIL
    * (load "clweb")
    T
    * (use-package "CLWEB")
    T

Now suppose you wanted to weave the CLWEB program itself. You might say:

    * (weave "clweb")
    ; weaving WEB from #P"clweb.clw"
    ; 0
    ; *1 2 3
    ; *4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
    ; *23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
    ;  42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
    ;  61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
    ;  80 81 82 83 84 85 86 87 88
    ; *89 90 91 92 93 94
    ; *95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
    ;  110 111 112 113 114 115 116 117 118 119 120 121 122 123
    ;  124 125 
    #P"/home/alex/src/clweb/clweb.tex"
    * ^Z
    $ tex clweb
    This is TeX, Version 3.141592 (Web2C 7.5.4)
    (./clweb.tex (./clwebmac.tex
    (/usr/pkg/share/texmf-dist/tex/plain/base/cwebmac.tex)) *1 [1] *4 [2] [3]
    [4] [5] [6] [7] *23 [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18]
    [19] [20] [21] [22] [23] [24] [25] [26] [27] [28] [29] *89 [30] [31] [32]
    *95 [33] [34] [35] [36] [37] [38] [39] [40] [41] [42] )
    Output written on clweb.dvi (42 pages, 137808 bytes).
    Transcript written on clweb.log.
    $

The numbers that WEAVE prints are the section numbers the weaver sees; the
ones preceded by stars are the `starred', or major, sections. TeX also
prints the starred section numbers along with the page numbers in square
brackets.

To use CLWEB for your own projects, you need to have the file `clwebmac.tex'
somewhere in TeX's search path. One way to do this (on the author's system,
anyway) is to install a copy of or a symlink to the version included in the
distribution in a directory like `~/texmf/tex/plain'; see the documentation
for your TeX distribution for more information, esp. the Kpathsea library.

The CLWEB tangler can be used in two different ways: to produce a compiled
file that can be used with LOAD, or to load the contents of a CLWEB file
directly into a running Lisp image. In the first case, you would use
TANGLE-FILE:

    * (compile-file "clweb")
    ; tangling WEB from #P"clweb.clw"
    ; compiling file "/home/alex/src/clweb/clweb.lisp":
    ; [compilation messages elided]
    #P"/home/alex/src/clweb/clweb.fasl"
    NIL
    NIL
    *

You should now have a fresh copy of `clweb.lisp' and `clweb.fasl'. You
shouldn't ever edit the former directly; it's only an intermediate file.

During development, the other mode of tangling is often more useful:

    * (load-web "clweb")
    T
    * 

The tangled contents of `clweb.clw' have now been loaded directly into the
Lisp environment.

Currently, CLWEB runs under SBCL, Allegro Common Lisp, and Clozure Common
Lisp. Reports of the experience of attempting to run the system under other
Common Lisp implementations would be welcome, along with any other
questions, bug-reports, patches, comments, or suggestions; please email
them to Alex Plotnick <[email protected]>.

The author gratefully acknowledges the encouragement and support of Ross
Shaull, who made him believe that at least one other person in the world
thought this might be a good idea, and of Richard Kreuter, for his many
suggestions for improving both the commentary and code of the system, as
well as for his work on SBCL.