[no subject]

[Kent M. Pitman <KMP at MIT-MC>]

    Date: Thursday, 26 August 1982, 03:25-EDT
    From: David A. Moon <Moon at SCRC-TENEX>
    To:   Common-Lisp at SU-AI
    Re:   Access to documentation strings

    ... I don't think we need a separate function to get the brief
    documentation, it's just (SUBSEQ doc 0 (POSITION #\Return doc)).... 
-----
This same sort of argument is what brought us cute little idioms like
(APPEND X NIL), (SUBST NIL NIL X), (PROG2 NIL X ...), etc.

I think it's worthwhile to provide two fields of the documentation for the
following reasons: 

* Abstraction. A documentation string should be just what it sounds like: a
  string which is not intrinsically interesting to the machine -- just
  something which can be typed at an intelligent entity (eg, a human) to
  provide insight into something.

  It should, as such, have no structure which is not explicit in its
  representation. If there's something magic about the first line and the
  remaining lines, that distinction should be apparent in the
  representation.

* Simplicity. It's a useful case which documentation code might want to do 
  frequently. The user should not be bothered with string-hacking if all he 
  wants to do is get documentation. Might as well make the common case easy.

* Efficiency. Not so much a concern on a large address space machine, but
  still worth considering: Consing should not be required to access a
  documentation string. Experience with Emacs has shown that in certain
  space-critical situations, it's a win to be able to access documentation
  when the rest of the world has ceased to run because of lack of free
  space so you can find the function you need in order to correct the
  problem.
-----
    ... The pre-defined object types are DEFUN for a function, special form, or
    macro; DEFVAR for a global variable, parameter, or constant; DEFSTRUCT
    for a structure....
-----
I would rather see the object types relate to the intended use of the
definition rather than the form used to create the use. eg, MACRO and DEFMACRO
both create the same type of object; indeed, if you do one and then the
other the documentation should overwrite one another just as a (MACRO ...)
and (DEFMACRO ...) form would overwrite each other in LispM lisp. Similarly
for variables: I would feel uncomfortable about giving something a DEFVAR
type documentation if I had not DEFVAR'd it. Suppose I had DEFCONST'd it or
just SETQ'd it. Isn't that good enough? I'd rather see the names be something
like :VARIABLE, :MACRO, :FUNCTION, :STRUCTURE, :SPECIAL-FORM, etc.
rather than the name of the typical form that would create the documentation 
type as currently proposed.
-kmp