Re: [Axiom-developer] Literate documentation

[Ralf Hemmecke]

> It's not a movie but you might want to try:
>
> http://www.3dtree.com/ev/e/sbooks/leo/sbframetoc_ie.htm

Thank you. However, what I read there looked more like reading something 
about outlines. That looks (at first glance) like a better noweb that 
doesn't put much emphasis on the documentation part. :-(

When I want to read a literate program, I want to read something like 
Clifford has done in his cl-web.

OK, then I thought, well, it seems that one can use LEO on top of noweb 
files, ie, use LEO to see outlines of my noweb files. Well, so I tried.

Downloaded and installed LEO (not into /usr/local, since I don't easily 
let programs run as root, but into $HOME/LEO). I started it and had to 
get the debian package python-tk. Restart.

Then the first thing I tried was to import a noweb file. I used 
leo-4-4-3-alpha-2 on the following file (dont put the %--- line into the 
file but keep the final empty line.

%---BEGIN asfiles.pl.nw
<<*>>=
Here is the code
@

%---END asfile.pl.nw

LEO hangs itself up. I seem to be unlucky. Unfortunately, I am not a 
python programmer myself so that I could dig into the problem.

I now give up for the second time. The empty line at the end seems not 
the only problem.

I know that LEO has some good ideas, especially I like the cloning 
stuff, but I cannot appreciate LEO not only for the reason that it 
doesn't let me import my files.

1) In contrast to mmm-mode+font-lock in emacs, it doesn't highlight the 
code appropriately, (in particular Aldor and LaTeX is not supported and 
I don't know how to fix that).

2) The section names in the lower window are no hyperllinks. (OK, I 
don't have that in Emacs, but since in my current working style, I view 
a hyperlinked .dvi file with inverse search enabled, I would lose that 
if I switch to LEO.

3) I am not sure whether this is really true, but I have the impression 
that LEO likes *one* documentation + *one* code chunk per section. I 
felt like I am documenting code chunks.
The idea of writing for human beings is (personal opinion) a bit 
blurred. (Don't criticize me. I have not long enough tested LEO and I 
believe the "clone" idea is a good one.---So anyone who says something 
else is probably right.)



I don't think that I will change too quickly to LEO.

Sorry Bill, what are your experiences with LEO? Have you used it for a 
small project?

Ralf