[Axiom-developer] Re: noweb vs. leo

[Ralf Hemmecke]

Hi Bill,

> 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.

How can a framework "enforce" good documentation? But you won't believe, 
I thought a bit about it. For example, you won't get all the nice 
hyperlinking if you don't follow some rules/conventions. And if a file 
is not mentioned in a \sourcefile{...} command, you don't even see the 
documentation of the file at all, but rather you get a section that 
tells you about "undocumented files". Of course, I cannot "enforce" any 
good documentation, but at least there is some penalty if you don't 
follow the rules.

The actual bad thing is that people are so spoiled by quickly hacking in 
code and making things run that they (yes sometimes also me) forget 
about the long term future.

> 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.

I've recently looked at LEO. I tend to like the idea of different views 
(or different facets of the crystal, as Tim would say). But I also had 
the impression that LEO does not enforce literate programming. It just 
supports it, as far as I can say. Still, LEO might help Axiom in getting 
 its code organised. The problem actually is that people would have to 
get used to this kind of software. So I am, in fact, not too 
over-optimistic.

And there is still some point I don't quite see clearly. LEO allows to 
"clone" documentation so that it could be used in another view. My 
question would be who actually defines what and "atomic documentation 
piece" is? What happens if some documentation changes that is used 
somewhere else? There are lots of questions... and almost no time :-(

Ralf