My two favorite articles on Literate Programming are both from Donald Knuth's book *Literate Programming*. One is "Computer Programming as an Art", and the other is "Literate Programming". When I was preparing to interview Knuth a bit over a year ago I re-read the entire book. I expected it to be a somewhat outdated description of WEB, TANGLE, and WEAVE. On the contrary it was wonderfully timeless. When I mentioned that to Knuth he sort of grumbled something to the effect of "Well, yes, some things in computer science have a long shelf life" (that's a paraphrase, but it was something like that).
I haven't been working with it for awhile, but I did a somewhat primitive modification to the XML Docbook markup language (I just added a few appropriate tags for "tangling" the executable source code, and "weaving" the well formatted article documenting the code) which I used as the source language, then wrote a tangle and weave in perl. I got the idea from Norman Walsh's article Literate Programming in XML which can be found at http://nwalsh.com/docs/articles/xml2002/lp/paper.html The advantage of this was that given the array of tools for rendering Docbook "weaving" was a piece of cake, and perl had a good range of modules for doing the "tangle". As I stated, I'm very new to clojure, but I've always been fascinated with LP, and I'm very happy to see this discussion going on here. Larry On Wed, Oct 26, 2011 at 10:49 PM, jaime <xiejianm...@gmail.com> wrote: > is there a place introducing (e.g. overview) more about Literate? have > no ideas about this stuff. > > On Oct 27, 3:06 am, 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
