Re: documentation strings

[Hoehle, Joerg-C. <Joe...@t-...>]

[taken from clisp-devel to clisp-lisp, where IMHO it'S a better fit]

Bruno Haible wrote:
>I think that doc strings with just 1 to 3 lines of text are an =
obsolete
>concept. It doesn't convey enough information. Better use URLs into =
the
>ANSI CL doc or into clisp's impnotes.html. So that SLIME can then mark
>them clickable.
You've been splitting your screen with one half for Netscape for too =
long :)
I don't need to look up the CLHS when all I need is a remainder of the =
syntax of do-symbols. Packages to point to http information have been =
around for long enough.
Even CLISP has a clhs file as part of its core.

I had a related idea:
a separate file would
(dolist
  (setf (documentation <cl-symbols>) xyz)
to point to a user-defined location, i.e. a local copy of the CLHS or =
impnotes or so.

The user could run this as part of his config.lisp,
or the function could even be run anytime the user sees fit (i.e. be =
part of the image, instead of being loaded once and then thrown away, =
like the timezone.lisp file).

Another variation on this could be for DOCUMENTATION to build the =
string at call-time??

Anyway, if such a mapping were included in the clisp image, I could =
make slime display that in apropos in addition to the documentation =
string (if available).
Well, slime or hyperspec.el probably have independent means for that, =
so CLHS support need not be built into clisp itself. It's EXT symbols =
that need documentation.

Actually, gclcvs annoys me by pulling CLHS information from its info =
file into the Lisp session. Even more so when it deviates from CLHS (or =
does not yet fully implement ANSI).


But that idea is most suitable to CLHS symbols. Symbols from EXT would =
need to know about where to find the best-fitted impnotes. Some people =
prefer the split version, others the full one. =
http://clisp.cons.org/impnotes/... would not work from behind a =
firewall, or offline.

Summary: I see a trivial possibility to add documentation URLs for CLHS =
symbols (CLISP already has all that' needed), but somehow harder for =
symbols from EXT (yet the same idea could apply, if one knows where to =
link to).

Regards,
	J=C3=B6rg H=C3=B6hle.