Re: [Axiom-developer] Literate documentation

[Ralf Hemmecke]

> I believe noweb is first of all an external format for Leo.
> To get a noweb file from Leo you use export. Leo does however
> implement some things that seem motivated by noweb.

Hi Bill,

I've just stumbled over the following section in LEO's User Guide.

How Leo Changes the Notion of Literate Programming
==================================================
Leo changes the theory and practice of literate programming as follows:

1. *Leo reduces the need for comments.* In particular, bridge or 
transition phrases are almost always unnecessary in a Leo outline. One 
never needs to say something like, "having just finished with topic x, 
we turn now to topic y." Leo's outlines tend to be far less chatty than 
flat literate programs.

2. *Leo reduces the need for printed listings.* Experience with the 
Weave command shows that an outline can easily become unintelligible 
when printed, no matter how "beautiful" the typeset printout is. No 
printed listing can be as clear as Leo's outline view.

3. *Leo reduces the need for indices and tables of contents.* You could 
say the entire outline is a table of contents. Moreover, sections must 
always be defined in a descendant of the node containing the section 
reference, so there is very little need for an index.

4. *Leo shows that outline structure is more powerful than narrative.* 
Indeed, narrative style creates severe maintenance problems. The 
narrative is soon forgotten, and when that happens it becomes difficult 
to find anything. The few times I have tried narrative organization I 
soon regretted it: things just weren't where I expected them to be.

5. *Leo shows that traditional literate programming encourages a too 
creative approach to programming.* A dictionary is a better model for 
programs than a novel. Leo's outlines provide a more regular 
organization, while providing space for the most lengthy discussions 
when those discussions are required.



In particular, if I read (4) I come to the conclusion that using LEO 
might rather be counterproductive to our pamphlet idea.

The declared goal in Axiom is to write documentation that is readable by 
humans. I am not an experienced LEO user, but all I see does convince me 
to use LEO in order to produce an article+code about some mathematical idea.

LEO is, in my eyes, very code focused. Am I wrong?

Ralf