[no subject]

[David A. Moon <Moon at SCRC-TENEX at MIT-MC>]

    Date: 30 August 1982 00:37-EDT
    From: Kent M. Pitman <KMP at MIT-MC>

    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.

There is some sense to this.  We could make it be allowed to be either a
string or a list of two strings, if we don't feel that a carriage return is
enough structure.

    * 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.
This is absurd.

    * 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.
This is more absurd.


    -----
	... 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.

You didn't read my message carefully enough.  All functions are of type
DEFUN, it doesn't matter what macro you defined them with.  Common Lisp
allows the same name in the space of functions to be both a special form
and a macro; but surely if they didn't have the same documentation there
would be hell to pay!

The types can't be keywords because that interferes with user
extensibility, since all keywords are in the same package.  In the Lisp
machine we chose the name of the most prominent defining form for no
really strong reason, just because it seems senseless to make up a whole
new set of names for this when there are already reasonably mnemonic
names in existence.  Otherwise, especially when you have users defining
their own types, you find you are using the same names as the defining
forms but with the DEF prefix taken off, and you have the problem of
trying to guess whether DEFUN maps into FUN or FUNCTION or UN.