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. _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
