I work a lot with FWEB by John Krommes. I find the system very helpful
in maintaining and organising complex codes which do a lot of
complex mathematics. Being rather fed up with F77, F90, C, and the like
I'm now trying to move towards Lisp - however, I couldn't find anything
that would weave and tangle Lisp.web files. Admittedly the tangling part
is of lesser importance in case of Lisp, since Lisp programs don't
suffer the level of unreadability characteristic of Pascal, C, or F77.
Still Lisp programs need to be annotated like any other program and
to be able to do so using all power of TeX and have annotations and Lisp
living all on the same file would be rather desirable.
What do Lisp programmers do if they want to annotate and publish their
codes? I've heard of Scheme Web, but it was a rather miniature version
of WEB, and it catered for Scheme only - I am not even sure that it knew
how to format Scheme. I think that was left to the user.
Any help will be greatly appreciated.
Happy Lisping,
Gustav
--
Zdzislaw Gustav Meglicki, ······@arp.anu.edu.au,
Automated Reasoning Program - CISR, and Plasma Theory Group - RSPhysS,
The Australian National University, G.P.O. Box 4, Canberra, A.C.T., 2601,
Australia, fax: (Australia)-6-249-0747, tel: (Australia)-6-249-0158
> What do Lisp programmers do if they want to annotate and publish their
> codes? ...
As far as I can tell, most lisp programmers don't use anything like
WEB. After I read about literate programming (in CACM programming
pearls?) I started using a very simple approximation for lisp code.
This is described below. I'd be interested in hearing what other
people out there think of it. I'll be happy to discuss this and
alternative solutions.
Basically I maintain "the" source as a lisp file, i.e., it can be
loaded into lisp without change. (I tend to read files into lisp a
lot more often than latex.) The documentation is all inside #|...|#.
In order to compile it as a latex file there is a very small amount of
preprocessing needed. Basically you just have to delete all
occurrences of lisp balanced comment delimiters (#| and |#). I also
replace tabs with spaces, since I use tabs in the lisp source and
latex doesn't seem to understand them. (I still have mode lines in my
source, so I also get rid of those.)
Here's a shell script:
# file lisp-tex:
# lisp-tex foo reads foo.lisp and writes foo.tex
# removes 1st line (mode line), deletes all #|'s and |#'s,
# expands tabs (for tex)
#
# echo adds a cr - sed throws out anything after the last cr
#
(tail +2 $1.lisp; echo "") | sed 's/#|//g\
s/|#//g' | expand > $1.tex
The result is meant to be included in a larger document, which defines
(among other things) the comment and code macros. Comment is useful
for including stuff in the source that is not included in the latex
output. (Is that sacrilege? I don't do it very often.) Code is used
for formatting code. Typically several such files will be included as
chapters of the same latex document. Here are the macro definitions I
currently use:
\newcommand{\comment}[1]{}
% --- all this is tricky stuff for the code command ---
\def\uncatcodespecials{\def\do##1{\catcode`##1=12 } \dospecials}
\def\setupverbatim{\tt \spaceskip=0pt % Make sure we get fixed tt spacing
\obeylines \uncatcodespecials
\obeyspaces \verbatimdefs}
% This macro turns on verbatim mode until \endverbatim is seen.
\def\xverbatim{\begingroup \setupverbatim \catcode`\{=1\catcode`\}=2
\parskip=0pt plus .05\baselineskip \parindent=0pt
\catcode`\ =13 \catcode`\^^M=13 \catcode`\\=0}
{\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }}
\gdef\verbatimgobble#1^^M{}}
% This defines \xendverbatim to end the group which begins with \xverbatim
\let\xendverbatim=\endgroup
\newcommand{\code}[0]{\xverbatim\footnotesize\tt\helpcode}
\def\helpcode#1{#1\xendverbatim}
I got someone else to write \code - I'm not a tex hacker. I've adjusted
it so that on my normal size page I can get 80 columns of code. I'm not
all that interested in formatting the code beyond the usual indentation.
The code macro does permit latex commands inside it, which is sometimes
nice, but on the other hand it means you have to watch out for backslashes
in your code. (Also braces.) Fortunately these don't appear very often
in lisp code.
The issue of presenting things in a different order to the reader and
the compiler seems less serious in lisp than in other languages.
However I have on occasion wanted to do that. I don't have a good
solution. I guess you could always define some area of the text as a
latex macro and then put a call to it where you want it to appear in
the documentation. I have not actually done that. I've also found it
very helpful to tell my editor (gnu emacs) to treat braces as matching
delimiters in lisp mode. (I generally edit these files in lisp mode.)
Here's what my source files look like:
;;; -*- Mode: LISP; Package: (FOO); Syntax: Common-Lisp -*-
#|
\comment{
This is a lisp source file which is translated into source for a
document preparation system by ... [standard explanation]
}
This is the latex documentation.
Here's some code:
\code{|#
(in-package "FOO")
(defun foo (x)
(list 1 x))
#|}
Here's some more documentation.
Here's some more code:
\code{|#
(defun bar (x)
(list 2 x))
#|}
Those lines separating the code from documentation are a little
painful to maintain - it would certainly be easier if they were
single characters (no chance of accidentally corrupting them).
However that would make the result harder to load into lisp.
(I know, I could use read macros, but that would be another
requirement imposed on the lisp environment. This way the file
can be read into any standard lisp environment.) On the other
hand, it's occasionally useful to exclude some of the code from
the documentation, and that can be done by using the word comment
instead of code. (I know, that could be another single character.)
The only other thing is that you have to end the file with an end
of comment delimiter, like so:
#|
In article <············@manuel.anu.edu.au> ······@arp.anu.edu.au (Zdzislaw Meglicki) writes:
>What do Lisp programmers do if they want to annotate and publish their
>codes?
I couple of years ago I did a few hundred pages of lecture notes
for Lisp programming -- using LaTeX and XLISP and JOVE (on PC's,
obviously). A very low-budget but usable environment.
Basically, I just established a convention in the LaTeX, something like:
\begin{comment}
...
\end{comment}
to delimit comment sections, and
\begin{code}
...
\end{code}
to delimit code sections. A 20-line perl script would extract
the lisp and rework the comments enough to feed both to XLISP.
Of course, it did no formatting of the lisp code (just used verbatim,
essentially), but I found that adequate -- the editor would do the
indenting properly. And no reordering or module definitions, but that
is rarely necessary in Lisp, either. This gives about 10% of Web, at about
0.1% of the cost. Quite usable, considering the effort that went
into it.
--
Prof. Neal Holtz, Dept. of Civil Eng., Carleton University, Ottawa, Canada
Internet: ······@civeng.carleton.ca Ph: (613)788-2600x5797 Fax: (613)788-3951
I've used a program called SchemeTeX, which does basically what people
have already described: let code live in a verbatim environment, and
format the comments as normal text. It appears that with Scheme there
is rarely need to move text from one place to another, mostly because
Scheme source usually consists of several small procedures that can be
given to the interpreter or compiler just about in any order. Also,
displaying code in some fancy manner (as in displaying a = in C code
as a backward arrow) does not work all that well with Scheme, or lisp
in general.
I've modified SchemeTeX a bit to use the GNU Latexinfo format, which
is somewhere between Texinfo and LaTeX. This enabled me to make an
Emacs info file out of my source code. With some Elisp hackery I got
automatic indexing of functions etc., which was quite nice. There was
one (rather serious) drawback: in order to modify a procedure in the
info file, one had to modify it in the original file, run the
SchemeTeX->info converter and reload the file. This is not practical
during the inital development phase of a program, although it would be
nice afterwards.
I do not use SchemeTeX anymore, but that does not mean that there was
something wrong with it. Maybe if I had put more effort into the tools
I built, things might be different. As of now, I really don't have
anything that I could distribute.
--
Pertti Kellom\"aki (TeX format) # These opinions are mine,
Tampere Univ. of TeXnology # ALL MINE !
Software Systems Lab # (but go ahead and use them, if you like)
I've been using a program called "definitions" written by John
McDonald at UW. It scans the source code for function, generic
function, method, structure, object, variable, parameter, etc.
defintions and formats the information inherent in the documentation
string, declarations etc. to make a user manual. He extends the
syntax of declare to provide a :returns declaration. Thus:
(defun glue-names (n1 n2)
(declare (type Symbol n1 n2)
(:returns (type Symbol n1-n2)))
"Creates and returns a new symbol by concatenating print names of
<n1> and <n2> resulting in: <n1>-<n2>"
(intern (concatenate 'string (symbol-name n1) "-" (symbol-name n2))))
Turns into something like:
\DefNameBox{rga-utils:glue-names}{Function}
\beginDocumentation
Creates and returns a new symbol by concatenating print names of
\<n1\> and \<n2\> resulting in: \<n1\>-\<n2\>\endDocumentation
\Usage{\cd{(rga-utils:glue-names n1 n2)}}\endUsage
\beginArguments
\argument{\cd{n1}}\typeArg{\cd{Symbol}}\endArg
\argument{\cd{n2}}\typeArg{\cd{Symbol}}\endArg
\endArguments
\beginReturn
\singleReturn \complexReturn{\cd{n1-n2}}\midReturn{\cd{Symbol}}\endcReturn
\endReturn
\Source{ /users/almond/lisp/rga-utils/utils.lisp}
\endDefinition
(John uses a slightly different LaTeX format, I use a TeX format with
a lot of macro definitions which allows me to control the look,
spacing, etc.)
The result goes through a list of definition objects which can be
sorted and filtered (removing unexported symbols or methods for
generic functions). The result is an alphabetical reference manual.
I'm quite happy with it.
Russell Almond
Statistical Sciences, Inc.
1700 Westlake Ave., N Suite 500
Seattle, WA 98109
(206) 283-8802
······@statsci.com