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. _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer