-To understand a program, be the machine. -To understand text, be human. -Write for your audience. +--Tim Daly April, 2013 -+To understand a program, be the machine.
+
+To understand text, be human.
+Write for your audience.
Write Literate Programs. -
+
-In my life as an artchitect, I find that the single thing which inhibits ++--Christopher Alexander, May 1996 in (Patterns of Software, Gabriel) ++In my life as an artchitect, I find that the single thing which inhibits young professionals, new students most severely, is their acceptance of standards that are too low. If I ask a student whether her design is as good as Chartres, she often smiles tolerantly at me as if to say, "Of -course not, that isn't what I am trying to do...I could never do that." -
+
-Then, I express my disagreement, and tell her: "That standard must be +course not, that isn't what I am trying to do...I could never do that." ++Then, I express my disagreement, and tell her: "That standard must be our standard. If you are going to be a builder, no other standard is -worthwhile." -
---Christopher Alexander, May 1996 in (Patterns of Software, Gabriel) -
+worthwhile." +
The best programming language is English. Everything else is notation.-
-I believe that the time is ripe for significantly better documentation of +-+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" -
+
- +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. +computer to do. +
-Step away from the machine. -Literate programming has nothing to do with tools -or style. It has very little to do with programming. -One of the hard transitions to literate programming is "literate thinking". +-+Step away from the machine.
+Literate programming has nothing to do with tools or style.
+It has very little to do with programming.
+One of the hard transitions to literate programming is "literate thinking". +
-The hardest part of literate programming is the documentation. +-+The hardest part of literate programming is the documentation. +
-The effect of this simple shift of emphasis can be so profound as to change +-+The effect of this simple shift of emphasis can be so profound as to change one's whole approach to programming. Under the literate programming paradigm, the central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the computer to behave in a particular way. It is the difference between performing and exposing -a magic trick. +a magic trick. +
-Another thing I've been enjoying lately is literate programming. +-+Another thing I've been enjoying lately is literate programming. Amazingly it turns out to be faster to write a literate program than -an ordinary program because debugging takes almost no time. +an ordinary program because debugging takes almost no time. +
-The conversation is much more direct if the Design Concept per se, -rather than derivative representatives or partial details, is the focus. +-+The conversation is much more direct if the Design Concept per se, +rather than derivative representatives or partial details, is the focus. +
-We are banning the old notion of literate programming that I used when -developing TeX82 because documentation has proven to be too much of a pain. +-+We are banning the old notion of literate programming that I used when +developing TeX82 because documentation has proven to be too much of a pain. +
++-- Knuth, Donald + +The Tex tuneup of 2014 ++The index to Digital Typography lists eleven pages where the importance +of stability is stressed, and I urge all maintainers of Tex and Metafont +to read them again every few years. Any object of nontrivial complexity +is non-optimum, in the sense that it can be improved in some way (while +still remaining non-optimum); therefore there's always a reason to change +anything that isn't trivial. But one of Tex's principal advantages is +the fact that it does not change -- except for serious flaws whos +correction is unlikely to affect more than a very tiny number of +archival documents. +
+
-Once upon a time I took great care to ensure that TeX82 would be +-+Once upon a time I took great care to ensure that TeX82 would be truly archival so that results obtainable today would produce the same output 50 years from now but that was manifestly foolish. Let's face it, who is going to care one whit for what I do today after even 5 years have elapsed, let alone 50. Life is too short to re-read anything anymore in the internet age. Nothing over 30 months old is trustworthy or interesting. - +
- --+
Yet to me, literate programming is certainly the most important thing that came out of the TeX project. Not only has it enabled me to write and maintain programs faster and more reliably than ever before, and @@ -259,61 +297,57 @@ methodology that I've ever heard of. The complexity was simply too daunting for my limited brain to handle; without literate programming, the whole enterprise would have flopped miserably.
-
If people discover nice ways to use the newfangled multithreaded machines, I would expect the discovery to come from people who routinely use literate programming. Literate programming is what you need to rise above the ordinary level of achievement. But I don't believe in forcing ideas on anybody. -
- +
--+
An abbot of the Seven-Clawed Blind Eagle Clan was tallying the deliverables of the temple monks, when he noticed that a monk of the Laughing Monkey Clan had produced no design documents. -
-+
+"What if a problem were discovered in our production system?" the abbot asked the monk. "How would the cause be understood by any besides yourself?" -
-+
+"The code itself should be examined," said the monk. "The Document is a sickly beast, easily subject to the Three Plagues of Error: omission, obfuscation, and obsolescence." -
-+
+The abbot reported this to the Java master, who said: "Have the monk balance on one foot with his staff outstretched, every day from dusk to midnight. If he can say a word to please me I will revoke the punishment, but not otherwise." -
-+
+"Is there such a word?" asked the abbot. -
-+
+"It is difficult to be certain," reflected the master. "Yesterday I was pleased by the sound of a cricket chirping after the first three drops of rain. The day before, the plashing of milk in a pail returned me to a pleasant memory of my youth. Perhaps the answer lies in the fragrance of a white lotus that drifted once in a pond below my window." -
+