Phil Gyford

Jo Walsh started a discussion about what literate programming is, how practical it is, what we can do with it. Although it’s interesting stuff, it was a small group and I kept drifting off as people grasped at the vagaries. So these notes only really capture the less vague moments when I was also paying more attention.

Wanting to capture as much metadata about a project’s creation process as possible. Perl has POD, which is good enough for a lot of purposes. Perl isn’t ideal for a literate programming approach because of its statement ordering [think I’ve got this right…].

Ben: But I find the procedural structure of Perl helps, as it’s like a story, a narrative. With tanlging and weaving, you don’t want that for creating documentation. Perl is closer to the stucture of linear documentation.

Noweb - A Simple, Extensible Tool for Literate Programming.

Literate programming.

Tangling is to take the code and comments(?) and turn it into documentation, weaving turns it into a formatted document [I may be so wrong here].

Ben channelling Knuth: Computer programs should be written for the benefit of other human beings, not for computers, who can handle it.

[Everyone seems to be working out what literate programming actually is, or what it’s for.]

Webb: Tests give you some kind of narrative as they describe how to use the code.

Someone: You should write the documentation before the code, and even write the tests before you write the code.

Schuyler: Documentation’s also about why things were done a certain way, not just what’s been done.

Ben: Writes books - gets paid for the documentation, not the code, and the code has to be understandable, not necessarily optimised.

[…]

Webb: Wikis are great because you can see what other pages link to a page. A good IDE is like that, showing where a function is called from. Something like that for documentation would be good.

[From literateprogramming.com, Ross Williams: Instead of writing code containing documentation, the literate programmer writes documentation containing code. No longer does the English commentary injected into a program have to be hidden in comment delimiters at the top of the file, or under procedure headings, or at the end of lines. Instead, it is wrenched into the daylight and made the main focus. The “program” then becomes primarily a document directed at humans, with the code being herded between “code delimiters” from where it can be extracted and shuffled out sideways to the language system by literate programming tools.]

Ben: The Perl Cookbook was written in POD.