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 _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer
