Re: [Axiom-developer] Literate programming

[daly]

On Thu, 2011-10-27 at 20:11 -0400, Larry Johnson wrote:
> 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).

Knuth's invention of literate programming is one of the unrecognized
pearls of computer science. I have yet to see a programming team that
has an Editor-in-Chief who does patch-review for clarity, sentence
structure, punctuation, relevance, location in the book, proper
citations and index terms, etc. Maybe someday.

> 
> 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".

Any means of publication can be the medium for literate programming.
As I rule I prefer Latex but anything will do.

All you need is a distinguished means of quoting and naming the
chunks. In html this could be as simple as:
   <pre id="somename">
      your code
   </pre>
and you need a program, often called "tangle", to extract the chunk
   tangle mywebpage.html somename >mysomename.file

The machinery of literate programming is dirt simple. 
Poof! You're done. 

The hardest part of literate programming is the mindset.

In order to do literate programming you need to change your focus
from traditional programming to writing for humans and, as a side
effect, writing for the machine.

> 
> 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.

Java has taken the PDP 11/40 sand files to their logical extreme where
we have wired the name of the tiny file to the name of the tiny object.
We have packaged the automobile into a crate with labeled bags of
screws, hoses, switches, etc. and are expected to understand the car.

Clojure is a very early adoptive, open minded community willing to 
challenge old assumptions. It helps to highlight what those old
assumptions are, as Rich has done for Lisp, since they can be 
difficult to see and hard to displace. I am hoping the community
will disrupt the tiny-files, javadoc, IDE, code-for-the-machine,
mindset and start communicating with humans. Rich has great ideas
in Clojure and all we get is the dried bones of source code.

We can do so much better.

Tim Daly