Literate programming (the program as a textbook) looks very interesting, 
but it didn't work for me because it is based on a fundamental 
misunderstanding: A textbook teaches a stable and well understood subject. 
A program is neither. (But it will be interesting to study simon's ref. to 
darcs.)


In the early eighties, a colleague and I did a substantial development job 
using literate programming. The program itself was a success, but literate 
programming was a flop.

We started from a very powerful multimedia authoring tool. We added three 
new media: Smalltalk class and method definitions + workspaces.

We could print the document with its embedded code; we could compile the 
document and even run tests that were specified in the document. The 
project was to develop the OS-like core of a  family of applications.  It 
is still alive more than 20 years later.

Literate programming worked beautifully for many months. We wrote a 
textbook describing our program, including descriptions of why we did 
things in a special way and why some tempting optimizations were very 
dangerous. We were doing pair programming and found that we were very 
motivated to write down what we were doing while we were doing it. The next 
day was too late.

But after more than a hundred pages of literate programming, we found that 
we needed to do some refactoring. But that would require a rewrite of 
several chapters in our book. We just couldn't do it. The program changes 
were fairly small, the book changes substantial. Even the main chapters had 
to be rearranged. We ended up with adding appendixes with overrides on 
previously written stuff. A total mess. (We even wrote an OOPSLA paper 
reporting it: T. Reenskaug and A. L. Skaar. An environment for literate 
smalltalk programming. ACM SIGPLAN Notices, 24(10):337--345, October 1989.)

Don Knuth dreamt about a program that was like a textbook. He even wrote 
one. But in general, the analogy doesn't hold. A textbook is written over a 
well known theme. The substance is stable, the presentation is new. A 
program is not stable in this sense; its substance is a moving target. So 
the textbook metaphor simply does not apply. Has anybody tried to modify 
Knuth's original program?

Cheers
--Trygve


At 10:19 31.08.2006, Klaus wrote:
>Hi Hans-Martin,
>
>I am very interested in having code as (integrated) part of a document.
>The following describes minimally what I want from a document+with+code, a
>"... two-phased approach that continuously synchronizes between a data
>modeling view and a view on an object-oriented implementation". There we
>see
>
>- a domain analysis view, represented by a data modeling diagram
>- implementation objects, related to OO programs at code-time
>- population objects, derived from the former, containing actual data for
>running
>
>Found at
>- http://prog.vub.ac.be/progsite/Person.php?rdid=25070
>
>I wouldn't care if this where called literate programming or so, as long
>as round-trip engineering allowed me to put comments anywhere I want :)
>
>/Klaus
>
>On Thu, 31 Aug 2006 07:41:16 +0200, Hans-Martin Mosner <hmm at heeg.de> wrote:
>>A long time ago, when I re-implemented a big chunk of TeX in VisualWorks
>>to create a WYSIWYG TeX editor (WysiTeX), we tried to do something like
>>literate programming in Smalltalk. My idea was that a Smalltalk literate
>>program could not possibly have the form of a linear book, since
>>Smalltalk programs are essentially not linear, so we tried to create a
>>hyperlinked documentation (using a collaborative hypertext editor also
>>written in VisualWorks). I was not really satisfied with the result - it
>>did not have the close linkage to the code, and I don't think that an
>>outsider would have been able to grok our code with the help of this doc
>>bettern than without it.
>>
>>That said, I still feel that something like that would be needed. Since
>>working with Objectory a number of years ago, I became enamoured with
>>the idea of traceability - having explicit links between analysis,
>>design and code. Objectory was a little too waterfallish, an agile tool
>>would probably have to look a bit different, but still I think that a
>>really good development environment should be able to keep all this
>>information in one place, allowing me to create and follow links, to
>>store document files, drawings, diagrams as well as runtime, building
>>and test code in one place, with version history all over the place, too.
>>
>>I know that such a system would not help me much in writing better
>>method comments (that's still a matter of discipline which I'm a bit
>>lacking) but it would probably allow me to create overview documents
>>which allow others to get into the code much more easily.
>>
>>Cheers,
>>Hans-Martin


-- 

Trygve Reenskaug      mailto: trygver at ifi.uio.no
Morgedalsvn. 5A       http://heim.ifi.uio.no/~trygver
N-0378 Oslo           Tel: (+47) 22 49 57 27
Norway