[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
- To: Moon at SCRC-TENEX
- From: Kent M. Pitman <KMP at MIT-MC>
- Date: Mon, 30 Aug 1982 04:37:00 -0000
- Cc: Common-Lisp at SU-AI
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
* 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
* 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
... 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.