Slashdot Mirror
Literate Programming and Leo
jko9 writes "First proposed almost 20 years ago by Donald Knuth, the idea of Literate Programming is basically that of making program documentation primary, and embedding code in the documentation, rather than vice versa. Despite some obvious
advantages apparent to anyone who has struggled to understand a poorly
documented program, literate programming never really caught on.
That all could change, however, with the release of a new program called Leo,
written by Edward K. Ream.
Leo supports standard literate programming
languages like noweb and
CWEB, but with a crucial
difference - Leo adds outlines. The effect is striking: overall
organization of a program is always visible and explicit. Much of the narrative of the documentation gets placed in the outline, making documentation simpler, and allowing viewers to approach the code at various levels of detail. Screenshots and tutorials for Leo are here - if
that site gets slashdotted, you can download the visual tutorials in .chm
form or html form from Leo's
Sourceforge site. Leo is an open source program written in Python. Any current practioners of Literate Programming techniques out there? People
who have tried it and given it up? Can the addition of outlines to Literate
Programming make it more powerful / popular?"
Userland Frontier/ Radio is exactly that.
It has an object database with script objects, outlines, and other bits that mimics a file system. The scripts are presented as outlines, one method per window.
Since scripts are outlines, you can expand and collapse bits to show what you're working on. I find it painful to go back to a flat file text editor, even a good one.
Something I didn't put in the original notice but now regret that I left out - Leo has another new feature more difficult to describe, but that which solves the problem that several people have mentioned about not wanting to abandon an existing text editor or tool. Leo can embed an outline structure in comments, so that one programmer can work with the file in JBuilder or EMacs, and a third programmer can still work with the program(s) in Leo. In effect, Leo is a meta-text editor. When Leo opens an outline containing a file that has been edited with another editor, all of the edits are retained. This is a further extension of LP because you are getting code read back into the documentation, which means that LP techniques can be used for understanding and/or teaching existing programs. It also means that Leo allows LP to be a secondary technique to add additional structure and documentation, rather than necessarily being the primary technique. This is explained in more detail in the tutorials and Leo docs.
.NET, but this ability to separate the outline from the program is something new, as far as I know. Also, unmentioned in the original article is the idea of having clone nodes, which means your outline can put the same code section into different branches simultaneously.
It is true that there are other IDEs that allow folding, e.g. Visual Studio
Actually, it was completeness and consistency that Godel tackled, and he proved it (rather than implied it). Complete = all true statements have a proof. Consistent = p & ~p is not a theorem of the system. This is for all systems strong enough to support the Peano axioms (and some weaker systems, I believe). However, 1st order logic is both complete and consistent.
Programs are not stored in 'flat text files', at least not unless 'flat text' also includes XML. Programs follow a particular structure and syntax which can be automatically checked and parsed, just like any particular XML format.
... construct. Or you could have exactly the same logical structure using { and } instead. XML or non-XML is mostly a red herring.
Think about it. You could have a programming language with a
Some very weird languages like Unlambda or Forth might qualify as 'flat text', but almost all languages used today have a hierarchical tree structure in each file.
-- Ed Avis ed@membled.com
A lot of people seem to feel qualified to comment about Leo after just reading the original slashdot article. Most have no clue about what Leo is or isn't. I've spent seven years working on Leo. I'm getting pretty annoyed about people commenting about Leo without even taking seven minutes to play with it.
Leo really isn't all that much about either literate programming or documentation. I explain what Leo is in my posting, "The creator's view of Leo."
Edward K. Ream
I'm not a big fan of abusing Java's interfaces (an interface for each implementation hierarchy), but in a big project that has to be properly documented and strictly specified, this would seem to help.
The interface is after all closer to the specification level, so your documentation can be strictly about the specification. Then you can let the programmers code, document and freeze the implementation independently from the interfaces.
Since an interface doesn't have any implementation sourcecode, writers could be trusted with the files, and since the interface API per se is frozen at design, they can keep modifying the Javadocs without affecting the coders.
If the writers have to modify the API per se and recompile an interface, they are changing the specification (re-design) and of course the coders are forced to adapt their code to those changes.
But otherwise there would be no need to "split the source" and then "merge". All you would have to do is provide the Javadocs for your interfaces (plus a manual based on this, perhaps) and the Javadocs for your implementation (if implementation details are to be exposed, such as efficiency guarantees, etc).
If anything, I would think the split would improve documentation.
Freedom is the freedom to say 2+2=4, everything else follows...