[daly]

Curiously I think you missed the more important point of the post. The literate programming insight is clearly more valuable as a "take-away" idea.

Literate programming has the potential to allow a program to "live". Certainly it allows a program to outlive the authors. Most programs no longer have the original authors available. Look at the thousands of dead programs on sites like Sourceforge. Or consider the number of commercial programs that are no longer maintained by the authors.

Your program should be written to pass the "Hawaii test". That is, you give a new hire your literate source code, send them on a fully paid trip to Hawaii for two weeks. When they come back they should be able to maintain and modify the program as well as the original authors.

Literate programming is not documentation. It is a form of communication. You need to motivate code you introduce. You need a good story line. You need to get it past an editor-in-chief.

See "Lisp in Small Pieces" for a great literate program example.

Tim Daly [e-mail]