On Tuesday, May 09, 2006 4:38 PM Norman Ramsey wrote: > ... > I'm afraid you can have 'simple and understandable' or > you can have 'precise'. You can't have both. The man > page represents the usual muddled compromise that provides > neither. >
I don't mean for the following commments to be interpreted as critical but the above statement from someone who has devoted a lot of effort to literate programming concerns me greatly. Perhaps even, this illustrates the one major "fatal flaw" in the whole concept of literate programming and the reason that this methodology is not in wide use so many years after it's invention: Writing *good* documentation is still hard work - harder even than the programming itself - and the first generation of literate programming tools (of which noweb is a prime example) seem to do nothing at all to make this easier. And as Ralf pointed out recently that we have a similar situation right now in the Axiom literate program source files - the information might be there (e.g. in the makefile.pamphlet) but it is not very accessible because it lacks a simple and easily understood overview. Ralf's ALLPROSE (Aldor Literate Programming Support Environemnt) http://www.hemmecke.de/aldor tool is intended to be "a framework for building Aldor libraries and their documentation". Clearly this framework could be extended for use with the Axiom library with it's 1,300 tightly inter- elated algebra files. But I am concerned that it does not address the underlying problem of writing really good and easily accessible documentation. The only literate programming tool that I am aware of that does attempt to address this problem - at least in some limited degree - is Leo. Where relevant I have tried to quote directly from the Leo documentation below but I don't want this to sound like an advertisement. In addition to integrating source code and documentation in the same manner as other literate programming tools, Leo also provides: 1) an outlining (folding) text editor and browser that allows the source code, documentation and project details to be presented in the context of a full outline (overview) of the system. "The outline pane shows your project as an outline. The outline contains all your project's data. An outline consists of nodes. Nodes have two parts, a headline and body text. The outline pane shows headlines. Selecting a headline selects the entire node; the node's body text appears in the body pane. The icon box is a small icon directly to the left of the headline text. If a node contains children, a smaller icon appears to the left of the icon box. This icon contains a + or - symbol. Clicking this expansion box expands or contracts the node." 2) A project manager that provides multiple views of project tasks within a the same outline. Leo's outline is not limited to being strictly hierachical because nodes can be "cloned". "A cloned node is a copy of a node that changes when the original changes. Changes to the children, grandchildren, etc. of a node are simultaneously made to the corresponding nodes contained in all cloned nodes." "Clones allow multiple views of data to exist within a single outline. The ability to create multiple views of data is crucial; you don't have to try to decide what is the 'correct' view of data. You can create as many views as you like, each tailored exactly to the task at hand." "For example, when I begin to fix a bug I first create a view node to represent the bug. I then create a component node (not cloned) that contains the original bug report. I may also create other non-cloned nodes to contain notes and documentation. Next, I go looking throughout Leo's code for nodes that relate in some way to the bug. When I find such a node I clone it and move one of the clones so it becomes a component of the view node for the bug. Note: I can organize the components of the view node as I please. In particular, I can create organizer nodes whose only purpose is to contain groups of component nodes. In other words, the full power of Leo outlines is available within view nodes." I think this is very similar to what Tim Daly has written about the need to view large complex literate programs like Axiom from the point of view of a "crystal" with multiple facets. Although Leo's documentation is quite good: http://webpages.charter.net/edreamleo/front.html the trouble with Leo is that organizing a project to take best advantage of all this involves some considerable effort. I am continuing to try to work up the energy to tackle Axiom with this tool. Regards, Bill Page. _______________________________________________ Axiom-developer mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/axiom-developer
