RE: [Axiom-developer] Literate documentation

[Bill Page]

Ralf,

On May 18, 2007 1:50 PM you wrote:
> 
> I've just stumbled over the following section in LEO's User
> Guide.

Yes, I was going to specifically recommend that you read this
section.

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

As far as I recall, our current exchange about Leo originated
in my reply to Tim's post concerning "Knuth's literate style":

http://lists.nongnu.org/archive/html/axiom-developer/2007-05/msg00158.html

I mentioned Leo as an example of a literate programming style
that specifically does *not* aim simply to product a single
linear monolithic document (or book). As your quote above from
the Leo user's guide shows, this is not what the developers of
Leo have in mind. This is not to say that Leo cannot be used to
produce such a thing if it is actually desirable. Leo has both
a "weave" command which should in principle (but currently does
not) produce from an imported noweb format file, exactly the same
result as running noweave on that file. But the point of view
Leo is that that the outline view is more powerful and more
flexible than that and so the woven result is of considerable
lesser importance.

In particular this was a follow-up to comments from Waldek,
Gaby, and me that were critical of the creation of
'bookvol5.pamphlet' as literate documentation of the Axiom
interpreter. We all expressed the opinion that 'bookvol5' was
more difficult to appreciate even than the original code.

Of course this is from a "programmers point of view" which
might not be the same as someone new just starting to use
Axiom and trying to understand how it works. But I think
programmers still need literate documentation, the question
is just what form this should take. I am saying that the
Knuth-style "book" is not a particularly good form of
documentation for a programmer.

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

I presume you meant to write: "does *not* convince me to use
LEO ..."?

But of course Leo is intended to be a tool used by humans.
Tools that allow one to navigate online using a web browser
through svn revisions and change logs is another such tool
intended to be used by humans.

The question is: given current (web) technology and current
programming practices, what form should a "literate program"
take?

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

I think you are right. It is apparently viewed by many people
who use it as a kind of high level integrated development
environment (IDE) that supports literature programming.

Regards,
Bill Page.