RE: [Axiom-developer] Knuth's literate style

[Bill Page]

On May 14, 2007 2:11 PM Tim Daly wrote:
> 
> An interesting reference worth purchasing, checking out from 
> a library, or stealing from a friend... In any case, it helps
> to have looked at it carefully at least once as there are many
> features here:
> 
> Knuth, Donald E. "TEX, The Program" Addison Wesley, 1986
> ISBN 0-201-13437-3
> 
> It will help set the baseline for a discussion of literate 
> documentation. This is my current target, modulo using latex-
> compatible chunk syntax to eliminate the WEAVE step. 
> 
> The stated plan is to have a literate version of the interpreter,
> the compiler, the hyperdoc, the graphics and the algebra.
> 
> Knuth clearly intended that this be a readable document for
> someone interested in TEX. Note that the program has survived
> and is widely used despite a thousand other ways to typeset.
> 
> The fact that TEX lives is interesting. I used another 
> competing program call SCRIPT, which was the IBM-sponsored
> mark-up language. There have been many, many others which
> haven't survived. I believe that the documentation (and the
> side benefits of cleaning up the program to publish) is vital.
> 

I agree with all that but I think it is relevant to point out
that TeX has not really survived the development of the World
Wide Web - and interesting irony considering the coincidence
of names. The current generation of web developers clear view
TeX and LaTeX as anachronisms.

> We've all stated our "positions" on this so I'm not looking
> for more restatements. I'm asking for concrete examples of
> other existing documentation for other programs so we can
> "compare and contrast". Does anyone know of another example
> of literate programming?  Can we build a bibliography of these
> references?

Are already several very good (and I think well balanced)
introductions to literate programming on the web. For example:

http://en.wikipedia.org/wiki/Literate_programming

http://www.literateprogramming.com/links.html

One of the links at the site above is to a fairly recent project
that publishes the source code of the project as a literate
program in book form:

http://www.pbrt.org

I don't know how successful (or not) "Physically Based Rendering"
is because (or in spite of) it's use of this "book-style"
literate programming.

Personally I am much more in tune with the review of literate
programming by Kurt Nørmark given here:

Literate Programming - Issues and Problems

http://www.cs.auc.dk/~normark/litpro/issues-and-problems.html

In particular I like the following point:

"Paper is not the main program medium.

In Knuth's work, beautiful literate programs were woven from
ugly mixes of markups in combined program and documentation
files. The literate program was directly targeted towards paper
and books. Of obvious reasons, programmers do not very often
print their programs on paper.
...
The development of the Internet in more recent years makes it
attractive to provide for presentation of 'literate programs'
on the Internet. We can think of a World Wide Web browser as
a new attractive program medium for program presentation. This
is already a fact within the Java culture (although the Javadoc
approach has only little to do with the ideals of literate
programming). We can even imagine 'World Wide program development
efforts' via Internet browsers."

Of course I also need to mention (again) Leo:

http://webpages.charter.net/edreamleo/front.html

Leo, of course is written using Leo as the literate programming
environment.

Leo organizes code and documentation in web-like structure that
permits easy navigation and bundles this with an outlining editor
that allows one to focus on one area of code or documentation in
the larger context of the whole project. It also allows one to
define multiple views of the same documentation and code. This
helps people to collaborate more easily in spite of having
different goals and different a emphasis, e.g. Axiom system
developer versus Axiom library developer or Axiom user versus
Axiom developer etc.

Leo allows users to have an integrated view of the whole project
while permitting them to edit and manipulate individual files
that are compatible with conventional build tools, e.g. make,
and source code control systems like CVS. Edits to these files
are automatically "untangled" back into the literate programming
environment.

Here are a few supporting quotes from the Leo website:

"Leo extends, completes and simplifies literate programming

"I've tried Literate Programming tools off and on for more than
10 years, mainly because the promise was so great. I've abandoned
them every time because working with the various Cweb-like tools
was so awkward. Leo changes all that. The most important benefits
promised by Literate Programming are realized by using Leo, without
the awkwardness of the other tools." -- Dave Hein

"[Leo] has enabled me to use Literate Programming in production
for the first time. When I figured out I could do it in plain text
and export to DocBook for automated typesetting, I was on my way.
Because I only do business and utility software, I don't need the
sophistication of LaTeX markup. Writing the documentation and the
code in the same outline at the same time improves the whole product.
Being able to automatically export both with just two key presses
(tangle and export-to-DocBook) is a real luxury." -- Michael Dawson

I wanted to thank you for the effort you've put into Leo. It looks
fantastic. I've always though that Literate Programming was a good
idea, but the tools were completely un-workable. -- Bob Hustead

Etc. etc.

Regards,
Bill Page.