[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Axiom-developer] Literate documentation

From: Ralf Hemmecke
Subject: Re: [Axiom-developer] Literate documentation
Date: Fri, 18 May 2007 19:49:46 +0200
User-agent: Thunderbird (X11/20070326)

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?


reply via email to

[Prev in Thread] Current Thread [Next in Thread]