Re: [Axiom-developer] Literate Programming -- Knuth interview

[daly]

On Fri, 2011-11-18 at 20:24 -0800, C Y wrote: 
> Tim, 
> 
> 
> 
> That's quite an interesting example!  Is there a license on it?  I can
> see that being useful in a lot of scenarios as an introduction to the
> idea of literate programming.
> 
> 
> Cheers,
> CY
> 
License? Nope.

You have my permission to use it in any fashion anywhere,
at any time, for any purpose.

It would be fun to create a viral-literate license that
required you to write all your published programs that way :-)

I posted the example to the Clojure mailing list and got 
a response which I include here.

On Fri, 2011-11-18 at 20:02 -0800, Daniel Jomphe wrote:
> On Friday, November 18, 2011 7:17:08 AM UTC-5, TimDaly wrote:
>         Many of you asked me to show an example of a literate
>         program and demonstrate the use of the tangle function.
>         
>         I usually use Latex for literate work but I've done
>         this example using HTML and <pre id="foo"> tags.
>         
>         I've written a self-referential literate program that
>         explains the details of the tangle function in literate
>         form. You can find the web page at
>         
>         http://daly.literatesoftware.com/lithtml/litprog.html
>         
> I have read your literate program, and must recognize that I know how
> tangle works even though I didn't want to really read the source code.
> I read your prose all the way through. I still haven't read the source
> code; 

In fact, that's the whole point. You don't read the equations in a
calculus textbook either. You read the words. The equations are icons.
If you understood the text and "spoke" mathematics you could probably
write the equations.

In programming we can reach the same level of literacy. Reading just
the words in the literate version it should be possible to recreate
the program in your favorite language. Note that you would be creating
a different program with different design decisions but the same 
functionality. 

> I didn't feel the need to read it. Were I to maintain your program,
> I'd have more than enough confidence to start hacking the code right
> now.

One thing worth trying would be to code the same program in Clojure.

The tangle program is conceptually very simple but there are a lot
of low level design decisions that I would make differently. For
example, there are loops in the C program which would go away.

Would you map read or would you slurp? Mapping a read function allows
transforming "& lt;" to < at read time. This does not matter in the C
program because the buffer is mutable but it would matter in Clojure.

Would you use the Clojure pattern language to find the <pre> tags?
Would you be able to parse out the string from the id? C encourages
character-level hacking but Clojure would be much more powerful.

> 
> 
> I think this speaks very positively about literate programming. What
> remains to be seen is how much (or not) I'm going to practice it in
> the future.

If you do try to rewrite it in Clojure please post the program. I 
would be very interested to see how Clojure's concise syntax and
semantics get reflected in your design decisions.

The tangle program in Clojure might turn out to be a single
s-expression of only a few lines. The code density would be a
huge win but a literate version would still have to have the
vitals of the story. Remember that the key test for a literate
program is the "independence test". Someone can read it without
talking to you, understand how it works, and be able to change it.

> 
> 
> What do you think of marginalia? It's a bit the reverse of tangle; it
> assembles all those 70's files together into this book you might want
> to read. Is it sound or not? Have your thoughts changed from what you
> wrote in [1]?
> 
> 
> [1] http://goo.gl/cXWzF

Literate programming is a mindset, not a tool. You can write a 
literate program in anything, including marginalia.

That said, I have yet to see a Clojure program that lays out a story
so I can sit and read it. For a real challenge, if you try to write
tangle in Clojure, try writing the story in marginalia. I'm sure
Fogus would welcome the feedback.


The readability aspect is a real feature. Heck, you could even give 
your programs to a company so they could read them BEFORE the job
interview. I would strongly favor hiring someone who could 
communicate, who cared about code quality, and who could improve
the company's maintenance headache in the long term. A Literate
Clojure programmer would be a real gotta-hire person. Companies
use many programming languages but all programmers really do need
good communication skills. 


In the long view, it would be sweet if the Clojure reader knew how
to read a literate program. Just call "(literate-load file chunk)" 
and you get the same effect as if you had tangled the program to 
a file.

With literate-load available you would be able to write all of
your Clojure code in a literate style, making Clojure much 
easier to understand, maintain, and modify.



Tim Daly





> 
> 

> 
> 
> 
>