[Axiom-developer] Literate Programming

[daly]

> 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