Programming Pearls 2nd Edition Pdf Github

[Flaviano Bada]

Literateprogramming can take various forms. I am working on a survey

of literate software. I came across an interesting non-latex example

worth sharing: -script/documentation/docs/nodes.htmlNotice 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

da...@literatesoftware.com

I recall that at some point you described your setup for doing Clojure

literate programming, and if I recall correctly, you were primarily

working in LaTeX, relying on incremental compilation to test little

snippets of code as you wrote them.Have there been any new developments on the literate programming /

Clojure front, in terms of tools that leverage existing build tools,

test suites, generating meaningful line numbers for stack traces and

debugging?

Yes, the idea is to write a literate version of Clojure, see

similar in style to "Lisp in Small Pieces". (The effort has been

stalled temporarily while I try to find new employment.)>From the above document you extract the Makefile, type 'make'

and end up with the newly formatted PDF and a running REPL.

So any edits to the document text are immediately reflected in

the PDF and any edits to the code are immediately reflected in

the compiled results.

>

> Have there been any new developments on the literate programming /

> Clojure front, in terms of tools that leverage existing build tools,

> test suites, generating meaningful line numbers for stack traces and

> debugging?

>

The question is ill-posed in sense that literate programming is not

a tool or technology but a change in mindset. To quote Knuth: I believe that the time is ripe for significantly better documentation

of programs, and that we can best achieve this by considering programs

to be works of literature. Hence, my title "Literate Programming". Let us change our traditional attitude to the construction of

programs: Instead of imagining that our main task is to instruct

a computer what to do, let us concentrate rather on explaining to

human beings what we want a computer to do.

-- Donald Knuth "Literate Programming (1984) CSLI 1992 pg. 99So imagine a world where the eloquence of Rich Hickey was expressed in

book form. Imagine the whole immutability lecture written down and

decorated with the actual running code as illustration. Imagine that

the original authors clearly explained software transactional memory

and illustrated it with the actual code. Imagine a discussion of

argument destructuring with running code illustrations.How many more people would be able to dive into the details of Clojure

to maintain and modify the code? How many people would find it much

easier to understand prototypes, defrecords, macros, and all of the

other struggles that populate the current email forums? How are

infinite sequences supported and what code supports it? What does

NIL mean and why was it defined that way?We do not capture the ideas. We do not rewrite the explanations to

clarify the fine points of confusion. We do not illustrate how the

ideas of Red-Black tries are moved "from ideas to implementation".

We do not communicate the ideas to each other. We code for the machine.So we end up with the traditional "tree of sand" pile of little files.

In order to overcome this we construct tools (IDEs) that know how to

navigate this pile, tools to store the changes (SVN, git, hg), tools

to put the sandpiles together (#include), tools to build guardrails,

tools, tools, tools... (You can, of course, keep each chapter and

section and subsection in separate files and "include" them in the

book.)Now imagine that the "book" is multimedia where you can include

animation (watch the tree balance), video, and a running REPL.

Think Khan Academy for Clojure.This community is willing to overthrow the traditional ideas of lisp

in order to make progress on a new path. Yet we continue to structure

the development as though we worked on a PDP 11/40 with 4k file size

limits. We continue to let the most valuable information which is the

meat of Clojure disappear while we keep only the code, the bones of

Clojure.Open the source code. Stare at it. Ask yourself if you understand

exactly why it was needed, why it is structured that way, what would

happen if you changed it and what else depends on this code. Imagine

your job is to maintain and modify it but Rich is not available for

questions and answers.Ultimately that is what matters. In the long term the code will be

the only remaining artifact after Rich leaves the project. Look at

Sourceforge and you will see thousands of dead projects that will

never be picked up because they are just trees of code, dead code.

Et tu, Clojure?Literate programming is about making code live.

I like Clojure and I really want it to live.Think long term. Imagine a better way.Tim Daly

So imagine a world where the eloquence of Rich Hickey was expressed in

book form. Imagine the whole immutability lecture written down and

decorated with the actual running code as illustration. Imagine that

the original authors clearly explained software transactional memory

and illustrated it with the actual code. Imagine a discussion of

argument destructuring with running code illustrations.

How many more people would be able to dive into the details of Clojure

to maintain and modify the code? How many people would find it much

easier to understand prototypes, defrecords, macros, and all of the

other struggles that populate the current email forums? How are

infinite sequences supported and what code supports it? What does

NIL mean and why was it defined that way?

We do not capture the ideas. We do not rewrite the explanations to

clarify the fine points of confusion. We do not illustrate how the

ideas of Red-Black tries are moved "from ideas to implementation".

We do not communicate the ideas to each other. We code for the machine.

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

>

>

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

your code

and you need a program, often called "tangle", to extract the chunk

tangle mywebpage.html somename >mysomename.fileThe 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.

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

3a8082e126