> 1. LaTeX does not have standard markup specific to software
> documentation, such as examples or argument lists. I had
> to define new LaTeX commands to get what I wanted.
I don't generally typeset code since the actual code is quoted
in the text. The documents I write are alternating code/text
sequences. So far I haven't had to write any latex macros and
I've been using noweb/latex/lisp for a few years now.
>
> 2. LaTeX is hard to read in source form. I had to switch to
> the rendered PDF just to see what I had written.
I guess. I'm way too familiar with it now. However when I'm working
I generally run xdvi on the dvi file. The xdvi program automatically
rereads the dvi file every time it gets the focus so all of my changes
are instantly reflected in the xdvi window.
I generally change 10 lines or so, rerun the makefile to
tangle/weave/latex/test and then rinse-and-repeat. Sort of a
'continuous development' style. This leaves the program and
documentation always 'up to date' and tested on the latest
test cases (which are also in the literate program file).
>
> 3. Noweb/LaTeX is sub-optimal for generating HTML, which is
> the primary format in which I read documentation these
> days. Noweb's built-in l2h filter is limited, and
> LaTeX2HTML is a disaster.
The wiki website seems to do ok. Contact Bill Page for his tricks:
"Page, Bill" <[EMAIL PROTECTED]> for his tricks. He's the
wiki magician.
>
> 4. Building the code and documentation from the literate
> source is a complicated, multi-step process. My Makefile
> is getting longer than the code itself.
really? Here is my complete 'standard' makefile for 'tpd.pamphlet'.
I usually embed it (with name changes) in every pamphlet file as
the default stanza.
TANGLE=/usr/local/bin/NOTANGLE
WEAVE=/usr/local/bin/NOWEAVE
LATEX=/usr/bin/latex
LISP=/sei/lisp
MAKEINDEX=/usr/bin/makeindex
all: code doc run
code: tpd.pamphlet
${TANGLE} -Rlisp tpd.pamphlet >tpd.lisp
doc:
${WEAVE} -t8 -delay tpd.pamphlet >tpd.tex
${LATEX} tpd.tex 2>/dev/null 1>/dev/null
${MAKEINDEX} tpd.idx
${LATEX} tpd.tex 2>/dev/null 1>/dev/null
run:
cat tpd.lisp | ${LISP}
remake:
${TANGLE} -t8 tpd.pamphlet >Makefile.tpd
All I do is run emacs in 2 buffer mode (ctrl-x 2) with the pamphlet
file in the lower window and a shell in the upper window. I start
" xdvi tpd.dvi & " so it runs in parallel and then I'm good to work.
You'll also note that the Makefile has a suffix of the working file:
make -f Makefile.tpd
That way I can have many different projects running at once.
I'm not advocating 'using my tools' or 'do it my way'. Work
in whatever way is best for you.
I AM advocating writing literate programs. Writing for people
is much harder than writing for the machine but ultimately it
is people who use your code and who need to maintain it. At
this point in my life I've written uncountably many lines of
Lisp code only to watch it die. I believe that literate programming
will help the code live.
How many programs have you written that have died?
Why do academics end up with 100 papers published in journals
and programmers end up with nothing?
Why aren't there journals that accept literate lisp programs?
With referees? At conferences?
How many times have you seen papers presented giving "results"
of programs you can't see and can't run? Why isn't the code
embedded in the paper?
Is the lisp garden going to turn into a javadoc-like, developer-only,
collection of code snippets? Or are we going to write thoroughly
documented, carefully structured programs that can be maintained
and modified?
Assume that the lisp garden eventually reproduces the java library
functionality. I have the sources for the java library. There is
nothing in these sources that is written 'for the person'. The
sources are all 'for the machine' or 'for the developer'. But
what about trying to understand whole subsystems like the SQL
commands, or the networking commands, or the swing commands?
Will we do the same thing with Lisp? Why? It should be the case
that the whole X3J13 document is interwoven with the actual code
that implements it. If I REALLY want to know how setf forms work
then I can read both the standard description and the actual
implementation code in the same chapter.
Why isn't the CLIM spec woven into the CLIM implementation code?
Why can't I look for how a line is drawn and see both the spec
and the implementation in the same place?
Why can't I learn about garbage collection by reading the source
code of my lisp implementation? Why doesn't it contain the text
of the book "Garbage Collection: Algorithms for Automatic Dynamic
Memory Management" for the algorithm used?
How come there is not "paper" on hashtables that contains the lisp
code so I can just drag-and-drop it onto my running lisp and have
a new hash table implementation with the documentation that explains
the theory?
It's the late 90s... we should be able to do this.
(throw 'soapbox-exit nil)
_______________________________________________
Gardeners mailing list
[email protected]
http://www.lispniks.com/mailman/listinfo/gardeners
