[Axiom-developer] noweb vs. leo

[Page, Bill]

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.