RE: [Axiom-developer] Literate documentation

[Bill Page]

On May 15, 2007 9:48 AM Ralf Hemmecke wrote:
> 
> > 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. :-(

Yes, there are other documents at the main Leo web site that
cover other topics in more detail. See "Beginners Guide" and
"Users Guide" at

http://webpages.charter.net/edreamleo/front.html

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

Good.

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

You must have been feeling "lucky" when you tried this but I am
not too surprised by the result.

When you download something you should keep in mind that "alpha"
usually means that it is a new test version that is likely to
have problems. If it was your intention to test this pre-release
then I suppose that you should send a bug report to the Leo
developers. I had an older version of Leo on my system from about
a year ago and it worked fine. But just for "fun" I downloaded
the current alpha release and tried you example again. I can
confirm that it does indeed hang Leo. In fact this test version
of Leo is not even able to read it's own exported noweb files.

So then I removed leo-4-4-3-alpha-2 and installed leo-4-4-2-1-
final Your example works fine for me using this last stable
release of Leo.

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

If you like I can send the bug report to to th leo-developers
email list.

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

Let's not give up so easily. :-) If you are sufficiently
motivated to give Leo a serious try with Axiom, I am willing
to work with you (and anyone else) to see how far we can get.

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

I believe that the language awareness is configurable.

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

That might be a nice feature to request.

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

No, I don't think that is true.

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

No problem. I think "first impressions" are very important.

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

I have to admit that most users of Leo admit that learning to
use Leo effectively required some additional effort, but they
almost all agree that the effort is worth it.

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

I little more than a year ago I did try importing some Axiom
pamphlet files into Leo. I confirmed what I could do easily
based on the tutorials but I have not actually completed any
project using Leo yet.

What do you say? Are you willing to give it a try with Axiom?

Regards,
Bill Page.