[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 2.0.0.0 (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?
Ralf
- [Axiom-developer] Literate documentation, daly, 2007/05/14
- Re: [Axiom-developer] Literate documentation, C Y, 2007/05/14
- RE: [Axiom-developer] Literate documentation, Bill Page, 2007/05/14
- Re: [Axiom-developer] Literate documentation, Ralf Hemmecke, 2007/05/15
- RE: [Axiom-developer] Literate documentation, Bill Page, 2007/05/15
- Re: [Axiom-developer] Literate documentation, Ralf Hemmecke, 2007/05/15
- RE: [Axiom-developer] Literate documentation, Bill Page, 2007/05/15
- Re: [Axiom-developer] Literate documentation, Ralf Hemmecke, 2007/05/15
- Re: [Axiom-developer] Literate documentation,
Ralf Hemmecke <=
- RE: [Axiom-developer] Literate documentation, Bill Page, 2007/05/18
- Re: [Axiom-developer] Literate documentation, Ralf Hemmecke, 2007/05/18
- RE: [Axiom-developer] Literate documentation, Bill Page, 2007/05/19
- Re: [Axiom-developer] Literate documentation, Ralf Hemmecke, 2007/05/19
- Re: [Axiom-developer] Literate documentation, C Y, 2007/05/19
- Aldor -> Lisp/C was: Re: [Axiom-developer] Literate documentation, Ralf Hemmecke, 2007/05/19
- RE: [Axiom-developer] Literate documentation, Bill Page, 2007/05/20
- RE: [Axiom-developer] Literate documentation, C Y, 2007/05/18
[Axiom-developer] RE: Literate documentation, Bill Page, 2007/05/15