> Just soliciting opinions -- would well documented GCL > 1) carry function documentation strings around in the image > accessible via describe > 2) have info pages searchable by describe > 3) have lisp comments in the source > 4) be written in pamphlet
Yes, to all of the above, although you might have guessed that :-) > How to integrate with the lisp functions apropos, documentation, etc.? It might be worthwhile to put URL references in the lisp documentation strings rather than have the documentation directly in the in-core string. That way you could describe a function and then follow a link. For most functions you could probably just link to the hyperspec URL. Or, alternatively you could put info link information there so people using emacs can just go to the info link. You already have the .info files. It appears to me that there is a subtle "mindset" that leads you to write > 3) have lisp comments in the source > 4) be written in pamphlet as though these were somehow unrelated. The "literate" view is a shift from "be written in pamphlets" to "pamphlets written for humans with embedded lisp". Perhaps that's what you meant by (4) and I missed it. If you look at "Lisp in Small Pieces" you'll see an example of what I'd consider the ideal version of GCL documentation. One way to approach such an effort would be to do individual pamphlets that explain the sgc garbage collection algorithm, for example, and then another explaining tail recursion, C library relocation, etc. If these get written while you're working on sections of code rather than as a huge "lump" of documentation the task can be done in manageable chunks (pun intended). Individual user-level functions can be documented by many different people (in theory) because all that would be required is to paraphrase the standard and explain any GCL-specific details. Tim _______________________________________________ Axiom-developer mailing list Axiom-developer@nongnu.org http://lists.nongnu.org/mailman/listinfo/axiom-developer