RE: [Axiom-developer] Issues with documentation revisions

[Bill Page]

On August 13, 2006 8:12 PM William Sit wrote:
> 
> > Simon Michael wrote:
> > ...
> > See
> > http://zwiki.org/MathActionTests (and subtopics).
> > 
> 
> I visited the page above and found Tim Daly's AutoDocPamphlet.
> It was a rather simple pamphlet but I found the documentation
> difficult to follow. As an exercise, I totally revised the
> documentation (with a few minor editing of the lisp code, which
> I don't think was for production use).

As a matter of style I agree completely with all of William Sitt's
changes. I think this is a good example of the fact that the
existence of literate programming tools does not guarrantee either
good documentation or good programming. Writing and programming
both involve issues of objective skills and subjective styles. It
is very hard to say in advance what really "works" but it is not
so hard to decide after the fact.

> This experience raised a few issues, in particular, that revising
> documentation may accidentally change the code because the code may
> be editorially revised as well. For details see NewAutodocPamphlet
> by following the link above or read the pdf file from 
> http://zwiki.org/NewAutodocPamphlet
> 

I think this is an important point. I believe that noweb as a literate
programming environment is actually too flexible and generic. It does
not in and of itself encourage good style (either writing or
programming) and without some additional editing tools (such as one
might find as emacs modes) it does not even respect the distinction
between code chunks and documentation.

There is at least one better tool than noweb: Leo

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

I believe that many of the design features of Leo would be beneficial
to the Axiom project.

Regards,
Bill Page.