Just stumbled on this blog note:
http://pyre.third-bit.com/blog/archives/863.html
The book, Beautiful Code, includes an essay by Matz. Looks like it
should be an all round good read.
Cheers
Chris
Hi,
In message “Re: [slightly OT] New O’Reilly book features Matz”
on Tue, 13 Mar 2007 07:37:18 +0900, “Robert D.”
[email protected] writes:
|Matz if you read this, are we in for some pleasant surprises regarding
|“Literate Programming” in Ruby 2.0+, or did I miss interpret the title
|of your essay ;)?
|Good thing to have you in there 
I am against “literate programming” in a sense Don Knuth did in his
Web system. I guess the title means good code share same attributes
with good essays: readable, understandable, and beautiful.
By the way, I didn’t make up the title. 
matz.
On 3/12/07, ChrisH [email protected] wrote:
Just stumbled on this blog note: http://pyre.third-bit.com/blog/archives/863.html
The book, Beautiful Code, includes an essay by Matz. Looks like it
should be an all round good read.Cheers
Chris
Very interesting.
Matz if you read this, are we in for some pleasant surprises regarding
“Literate Programming” in Ruby 2.0+, or did I miss interpret the title
of your essay ;)?
Good thing to have you in there
Cheers
Robert
Hi,
In message “Re: [slightly OT] New O’Reilly book features Matz”
on Thu, 15 Mar 2007 12:25:32 +0900, James Edward G. II
[email protected] writes:
|> I am against “literate programming” in a sense Don Knuth did in his
|> Web system.
|
|Can you expand on what you mean by that Matz? I’m just curious.
Knuth’s Web is the system he developed for literate programming (it’s
not World Wide Web, just coincidence). One can generate both document
for the algorithm and working code to compile (Pascal in original Web)
from one source with special mark-up.
He’s idea is retrieving programs from document. Mine is making
programs to tell what they do, by choosing proper programming
languages.
matz.
Yukihiro M. wrote:
Knuth’s Web is the system he developed for literate programming (it’s
not World Wide Web, just coincidence). One can generate both document
for the algorithm and working code to compile (Pascal in original Web)
from one source with special mark-up.He’s idea is retrieving programs from document. Mine is making
programs to tell what they do, by choosing proper programming
languages.matz.
I agree with you in your assessment of the original version of “literate
programming”. It was intended to get the programmer to create the
documentation hand in hand with the code. However, literate programming
has evolved into a concept I find very appealing – so called
“reproducible research.” As practiced by the bio-informatics community
in the R language, the core concept is something called a compendium. A
compendium is a software package, which contains all of the code and
data required to reproduce the research, including the tools to write
the paper. The way it’s done in R, and the way it could be done in Ruby,
the author creates a collection of source and data files. The literate
programming process of weaving produces the document – in the case of
R, this includes running R scripts that do the analysis, create the
figures, and so on.
I think what I really would like to see is some combination of
test/behavior driven development and reproducible research. In short,
the programmer develops the tests, the software and the documentation
concurrently.
–
M. Edward (Ed) Borasky, FBG, AB, PTA, PGS, MS, MNLP, NST, ACMC(P)
http://borasky-research.blogspot.com/
If God had meant for carrots to be eaten cooked, He would have given
rabbits fire.
On Mar 14, 2007, at 10:03 PM, Yukihiro M. wrote:
|of your essay ;)?
|Good thing to have you in thereI am against “literate programming” in a sense Don Knuth did in his
Web system.
Can you expand on what you mean by that Matz? I’m just curious.
James Edward G. II
On Thu, Mar 15, 2007 at 03:16:47PM +0900, Yukihiro M. wrote:
Knuth’s Web is the system he developed for literate programming (it’s
not World Wide Web, just coincidence). One can generate both document
for the algorithm and working code to compile (Pascal in original Web)
from one source with special mark-up.He’s idea is retrieving programs from document. Mine is making
programs to tell what they do, by choosing proper programming
languages.
In other words: literate programming is “documentation as code”, and
your preference is “code as documentation”. Yes?
I tend to share that preference. I’ve looked into “literate
programming” a little bit, and found it unnecessarily byzantine in
practice.
Chad P. wrote:
|Can you expand on what you mean by that Matz? I’m just curious.
In other words: literate programming is “documentation as code”, and
your preference is “code as documentation”. Yes?I tend to share that preference. I’ve looked into “literate
programming” a little bit, and found it unnecessarily byzantine in
practice.
It’s also, as it’s usually practiced, rather dependent on the literate
programmer knowing another of Knuth’s inventions – TeX/Metafont and the
common open source implementations thereof. Just about everybody with a
formal CS background and everybody who expects to publish in
peer-reviewed journals is forced to learn this stuff anyhow. The LyX
document processor makes it (just barely) possible for someone without
TeX (LaTeX, to be precise) knowledge to do literate programming.
I am actually hacking away on a project called Rameau to bring
reproducible research to Ruby – more the other way around, actually –
to apply the pragmatic automation of Ruby to the processes of
reproducible research. I haven’t spent too much time on it recently, but
I’ll assume neither you nor Matz is interested in volunteering to join
it when I get more of it laid down and start looking for help.
ObHeroWorship: Donald Knuth is probably one of the smartest guys in this
business. He probably, for better or worse, invented the term “computer
science”. And, believe it or not, he was first published, as a high
school student, in the 1950s in Mad Magazine: “The Potrzebie System of
Weights and Measures”. Sadly, they never published my contribution
along a similar vein back then, a parody of Scientific American. :(.
–
M. Edward (Ed) Borasky, FBG, AB, PTA, PGS, MS, MNLP, NST, ACMC(P)
http://borasky-research.blogspot.com/
If God had meant for carrots to be eaten cooked, He would have given
rabbits fire.
Hi,
In message “Re: [slightly OT] New O’Reilly book features Matz”
on Thu, 15 Mar 2007 17:11:20 +0900, Chad P.
[email protected] writes:
|In other words: literate programming is “documentation as code”, and
|your preference is “code as documentation”. Yes?
To be precise, “literate programming as in Knuth’s Web” is
“documentation as code”. I think the concept “literate programming”
is much broader than Web, and in one sense “code as documentation” can
be literate programming as well.
Besides that, Web was a great tool considering the age of its birth.
matz.
On 16 Mar 2007, at 00:04, Yukihiro M. wrote:
|in the R language, the core concept is something called a
|figures, and so on.
matz.
There are some example compendiums here:
http://www.bioconductor.org/docs/papers/2003/Compendium
and this paper is a good introduction:
“M. Edward (Ed) Borasky” [email protected] writes:
I am actually hacking away on a project called Rameau to bring
reproducible research to Ruby – more the other way around,
actually – to apply the pragmatic automation of Ruby to the
processes of reproducible research. I haven’t spent too much time
on it recently, but I’ll assume neither you nor Matz is interested
in volunteering to join it when I get more of it laid down and
start looking for help.
Ed: I’d be interested in playing/helping with Rameau - have you
released anything yet?
Alex G.
Bioinformatics Center
Kyoto University
|In other words: literate programming is “documentation as code”, and
|your preference is “code as documentation”. Yes?To be precise, “literate programming as in Knuth’s Web” is
“documentation as code”. I think the concept “literate programming”
is much broader than Web, and in one sense “code as documentation” can
be literate programming as well.
I read somewhere that a statistical analysis revealed commented code
takes longer to debug than uncommented code, and the reason was that
comments frequently describe what the code is supposed to do rather
than what it actually does.
Documentation considered harmful.
Hi,
In message “Re: [slightly OT] New O’Reilly book features Matz”
on Thu, 15 Mar 2007 15:47:48 +0900, “M. Edward (Ed) Borasky”
[email protected] writes:
|programming". It was intended to get the programmer to create the
|documentation hand in hand with the code. However, literate programming
|has evolved into a concept I find very appealing – so called
|“reproducible research.” As practiced by the bio-informatics community
|in the R language, the core concept is something called a compendium. A
|compendium is a software package, which contains all of the code and
|data required to reproduce the research, including the tools to write
|the paper. The way it’s done in R, and the way it could be done in Ruby,
|the author creates a collection of source and data files. The literate
|programming process of weaving produces the document – in the case of
|R, this includes running R scripts that do the analysis, create the
|figures, and so on.
|
|I think what I really would like to see is some combination of
|test/behavior driven development and reproducible research. In short,
|the programmer develops the tests, the software and the documentation
|concurrently.
Interesting idea. Where can I find more information for compendium
(in R)?
matz.
On 3/15/07, Yukihiro M. [email protected] wrote:
To be precise, “literate programming as in Knuth’s Web” is
“documentation as code”. I think the concept “literate programming”
is much broader than Web, and in one sense “code as documentation” can
be literate programming as well.
Hey,
Thanks for sharing your thoughts on this issue, Matz. I think your
philosophy shows in Ruby’s design and I’m looking forward to your
essay and the book in general.
For more on Knuth’s ideas about writing and “literate” programs, see
this (just discovered) PDF:
http://tex.loria.fr/typographie/mathwriting.pdf
via:
http://wadler.blogspot.com/2007/03/three-ways-to-improve-your-writing.html
Keith
Re: literate programming
On Mar 17, 2007, at 4:56 AM, Xavier N. wrote:
Some friend of mind said by then “it’s a beautiful idea that just
does not work”.
I disagree. I offer Wolfram Research’s Mathematica front end with its
notebook interface as an example. My personal experience is that it
works very well as a literate programming environment.
It takes a lot of engineering effort to produce a literate
programming environment that is relatively easy to use. The
developers of such an environment must seamlessly combine a technical-
grade word processor with a software IDE. IMO, Wolfram has been able
to pull this off.
Regards, Morton
Morton G. wrote:
It takes a lot of engineering effort to produce a literate programming
environment that is relatively easy to use. The developers of such an
environment must seamlessly combine a technical-grade word processor
with a software IDE. IMO, Wolfram has been able to pull this off.Regards, Morton
As have the good folks at the open source Axiom project. Axiom’s base
modus operandi is literate programming. I haven’t used Mathematica –
it’s always been way too expensive for the amount of time I spend doing
symbolic math. But I do have a Derive license ($200US) and of course
have both Maxima and Axiom on my Linux systems.
As for a “technical-grade word processor”, there are two similar but
different ones in the open-source world, TeXmacs and LyX. LyX is easier
to use than TeXmacs and actually has hooks for literate programming
built in, although it’s not as seamless as Mathematica. TeXmacs is more
powerful – you can open it up and insert sessions of a number of
languages, including R, Axiom, Maxima, Guile (Scheme) and Python. A Ruby
session interface for TeXmacs would make a great Summer of Code project
(hint hint looking for an opportunity to mentor someone hint hint). 
I tried hard to do an immersion in literate programming both using
Perl and Ruby (via noweb), and finally gave up. I summarised the
reasons here:
http://www.advogato.org/person/fxn/diary.html?start=236
Some friend of mind said by then “it’s a beautiful idea that just
does not work”.
– fxn