RE: [Gcl-devel] Documentation strings.

[Mike Thomas]

Hi Camm.

| To my understanding, however, the standard lisp
| implementation/idea of docstrings is that they would reside in the
| running core.  This would greatly enlarge our lisp image, even if the
| strings are compressed.

This is a good point I had overlooked, however I was really not thinking of
providing the amount of infomation available in the info files/ANSI
specification (or for example the Axiom documentation), but rather basic
usage information - arguments, keywords etc and a program provided
boilerplate reference for further details in the (hopefully) forthcoming
ANSI doc eg "For further details try (info* "compile")." or "Read relevant
ANSI section? (y/n) [n]".  The actual docstring would, for example, be
suitable for floating ballon help at some point in the future.

|  Then of course there is the issue of those
| wishing to read the docs outside of lisp, i.e. in a browser or info
| reader.  Perhaps we could write and store the docs inline in the
| source in this way, but export them from the core to external files as
| we do now.

Agreed.

| IMHO, a good piece of documentation looks not like the typical doc
| string, but rather like a manpage, or a page of the existing
| hyperspec.  Syntax, brief description, long description, examples,
| errors, see also, etc.  Putting this together is a lot of work, of
| course.  It would be great if the lisp community did not have to
| reinvent the wheel for the overlapping subset of each implementation
| n times.
|
| I am hopeful that the issue in question regarding dpANS can be
| resolved favorably.

I agree with these sentiments.  As an aside, I was particularly impressed
with the man pages provided with OpenBSD.  Very well done and worth a look
if you ever get the opportunity; they have a strict approach to system
documentation and design which has paid off handsomely.

Cheers

Mike Thomas.