I'm a bit reluctant to get into this, because I'm new to clojure (and don't know the backstory of this post), but an old hand at literate programming (I recently did a podcast interview with Donald Knuth on LP). I'll be interested in the results of your survey.
Larry On Wed, Oct 26, 2011 at 3:06 PM, <d...@axiom-developer.org> wrote: > 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 -- *Off the Beaten Path in Technology http://otbeatenpath.wordpress.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
