Ralf, On May 18, 2007 1:50 PM you wrote: > > I've just stumbled over the following section in LEO's User > Guide.
Yes, I was going to specifically recommend that you read this section. > > How Leo Changes the Notion of Literate Programming > ================================================== > Leo changes the theory and practice of literate programming > as follows: > > 1. *Leo reduces the need for comments.* In particular, bridge > or transition phrases are almost always unnecessary in a Leo > outline. One never needs to say something like, "having just > finished with topic x, we turn now to topic y." Leo's outlines > tend to be far less chatty than flat literate programs. > > 2. *Leo reduces the need for printed listings.* Experience with > the Weave command shows that an outline can easily become > unintelligible when printed, no matter how "beautiful" the > typeset printout is. No printed listing can be as clear as > Leo's outline view. > > 3. *Leo reduces the need for indices and tables of contents.* > You could say the entire outline is a table of contents. > Moreover, sections must always be defined in a descendant > of the node containing the section reference, so there is > very little need for an index. > > 4. *Leo shows that outline structure is more powerful than > narrative.* Indeed, narrative style creates severe maintenance > problems. The narrative is soon forgotten, and when that happens > it becomes difficult to find anything. The few times I have > tried narrative organization I soon regretted it: things just > weren't where I expected them to be. > > 5. *Leo shows that traditional literate programming encourages > a too creative approach to programming.* A dictionary is a > better model for programs than a novel. Leo's outlines provide > a more regular organization, while providing space for the most > lengthy discussions when those discussions are required. > > --- > > In particular, if I read (4) I come to the conclusion that > using LEO might rather be counterproductive to our pamphlet > idea. > As far as I recall, our current exchange about Leo originated in my reply to Tim's post concerning "Knuth's literate style": http://lists.nongnu.org/archive/html/axiom-developer/2007-05/msg00158.html I mentioned Leo as an example of a literate programming style that specifically does *not* aim simply to product a single linear monolithic document (or book). As your quote above from the Leo user's guide shows, this is not what the developers of Leo have in mind. This is not to say that Leo cannot be used to produce such a thing if it is actually desirable. Leo has both a "weave" command which should in principle (but currently does not) produce from an imported noweb format file, exactly the same result as running noweave on that file. But the point of view Leo is that that the outline view is more powerful and more flexible than that and so the woven result is of considerable lesser importance. In particular this was a follow-up to comments from Waldek, Gaby, and me that were critical of the creation of 'bookvol5.pamphlet' as literate documentation of the Axiom interpreter. We all expressed the opinion that 'bookvol5' was more difficult to appreciate even than the original code. Of course this is from a "programmers point of view" which might not be the same as someone new just starting to use Axiom and trying to understand how it works. But I think programmers still need literate documentation, the question is just what form this should take. I am saying that the Knuth-style "book" is not a particularly good form of documentation for a programmer. > The declared goal in Axiom is to write documentation that > is readable by humans. I am not an experienced LEO user, but > all I see does convince me to use LEO in order to produce an > article+code about some mathematical idea. > I presume you meant to write: "does *not* convince me to use LEO ..."? But of course Leo is intended to be a tool used by humans. Tools that allow one to navigate online using a web browser through svn revisions and change logs is another such tool intended to be used by humans. The question is: given current (web) technology and current programming practices, what form should a "literate program" take? > LEO is, in my eyes, very code focused. Am I wrong? > I think you are right. It is apparently viewed by many people who use it as a kind of high level integrated development environment (IDE) that supports literature programming. Regards, Bill Page. _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
