I see that my Literate Programming session is beginning to gain some traction. I would encourage you to bring examples. We can discuss the merits and possibly gain some new insights. If nothing else, please sign up for the Literate Software session at Clojure-Conj. I promise to keep it short.
Literate programming can take various forms. I am working on a survey of literate software. I came across an interesting non-latex example worth sharing: http://jashkenas.github.com/coffee-script/documentation/docs/nodes.html Notice how well they have documented an apparently simple line as in: exports.Base = class Base The Base is an abstract base class for all nodes in the syntax tree. Each subclass implements the compileNode method, which performs the code generation for that node. To compile a node to JavaScript, call compile on it, which wraps compileNode in some generic extra smarts, to know when the generated code needs to be wrapping up in a closure. An options hash is passed and cloned throughout, containing information about the environment from higher in the tree (such as if a returned value is being requested by the surrounding function), information about the current scope, and indentation level. Notice how this is not only giving trivial information (e.g. Base is an abstract base class) but WHY it exists (..as a base for all nodes in the syntax tree). It gives operational information (to compile a node..) as well as information about the effect (..which wraps...). It shows how global information is used (An options hash..) and WHY (containing information about the environment...) Code only tells you HOW something is done at the time it is done. It's like having a recipe without an idea what you would make. If our standards of documentation were raised to this level then large systems like Axiom, Clojure, and ClojureScript would be much easier to maintain and modify in the long term. If you want your code to live beyond you, make it literate. Tim Daly d...@literatesoftware.com -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en