Re: [Gcl-devel] Documentation strings.

[Camm Maguire]

Greetings!

"Mike Thomas" <address@hidden> writes:

> Hi Camm.
> 
> | It will at best take a month or two to resolve this.  So we have a
> | choice -- should we wait, or pull the document (gcl.texi, not the
> | gcl-si and gcl-tk .texi documents) pending resolution and release what
> | we have?
> 
> I think this problem is a good reason to consider fixing the builtin
> document string mechanism in 2.7.0.  Those macros (DEFUN_NEW, DEFUN, DEFVAR)
> offer us the twin advantages of primitive but effective literate programming
> and online documentation.
> 
> One way of approaching this without too much pain might be to ask that each
> one of us, when working on a particular function definition, also update the
> documentation string.
> 

Mike this is a good idea, worthy of discussion.  Literate programming
is great!  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.  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.

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.

Take care,

> Cheers
> 
> Mike Thomas
> 
> 
> 
> 
> 
> _______________________________________________
> Gcl-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/gcl-devel
> 
> 
> 

-- 
Camm Maguire                                            address@hidden
==========================================================================
"The earth is but one country, and mankind its citizens."  --  Baha'u'llah