Documentation and error messages

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

    Date:  7 October 1982 0137-EDT (Thursday)
    From: Guy.Steele at CMU-10A

    First, some people have recognized a need for both short and long
    forms of documentation for functions, variables, and other things.

    Here is a quicky solution: in DEFUN, for example, let more than one
    documentation string appear, in order of increasing detail....
    This solution is not great.
No it's not.  But it would be acceptable.  I think I still prefer
special-casing the first line over this solution, even though it means that
the short documentation string really has to be short (to fit on a line).
The extra complexity doesn't seem to buy anything, and isn't enough
complexity to do anything really hairy.

    There is a similar problem with error messages, trying to strike a
    balance between conciseness and helpfulness....
Your suggested schemes for this fit much more nicely into the Lisp machine
"New error system" than into the bare Lisp you're trying to put them into.
Since Common Lisp is not prepared to adopt such a hairy error system right
now, I suggest that this issue be dropped until next year, rather than
trying to standardize on some kludge.  I certainly do not propose that it
be dropped forever.

    Date: Thursday, 7 October 1982  13:16-EDT
    From: Scott E. Fahlman <Fahlman at Cmu-20c>

    These fit nicely into Moon's proposal
    for documentation retrieval: in addition to having a DEFUN documentation
    accessor, we would also have a SHORT-DEFUN.
No!  No!  No!  Absolutely not.  That word "DEFUN" is telling you how to
interpret the name of the thing whose documentation you are retrieving;
it is the name of a "name space".  It is 100% wrong to multiply the number
of name spaces by the number of kinds of documentation you might want, and
have as many symbols for documentation as we used to have for sequence
functions.  The level of documentation you want should be a separate
argument to the DOCUMENTATION function.

    (Actually, like many
    others, I prefer FUNCTION and VARIABLE to DEFUN and DEFVAR, but that is
    a separate issue.)
In case I haven't stated my case on this before, I will again, and I'll try to
be crystal clear.  I agree with you.  FUNCTION is better than DEFUN, and
VARIABLE is better than DEFVAR.  The problem is that this does not generalize
well to the many other things you would like to document.  Many classes of
named thing that you can define do not have a name for the class, separate
from the name of the defining special form, except perhaps by deleting the
three letters "DEF" from the latter name.  Furthermore if you have names used
only for this, there is a serious problem with remembering abbreviations.  You
probably won't have much trouble remembering whether it's a VARIABLE or a VAR,
and might even be able to remember whether it's a STRUCTURE or a STRUCT, but
when there are 10 or 20 of these, you will not be able to remember two sets of
names for the same thing.  It's even worse when you put in packages.
Also, don't forget that this naming system necessarily has to be extensible to
user-defined classes of things.


This discussion worries me.  The problem is that it looks like we are getting
away from language design per se, and trying to design a standard user
interface.  Certainly you want some standardization there, on the simple
things that everybody understands and agrees on.  But the whole user interface
field can be an impenetrable morass.  There are issues of personal taste and
esthetics.  The ground rules for many user interface issues are dictated
entirely by implementation considerations, such as whether you support only
bitmap terminals, only fast displays, or all kinds of terminals.  Even worse,
they are dictated by what sort of users your system is intended for.  It can
be extremely difficult to come to any sort of agreement on this kind of thing,
because everyone has a different unstated set of assumptions (model in their
head) for what the discussion is about.

In any case I am certain that the Common Lisp working group, or whatever we
are called, is barely able to keep the language design orderly, and certainly
does not have the resources to design a user interface, too.


I feel quite strongly that we need to buckle down and finish the job of
getting a standard language defined, and not get diverted into a lot of
side-issues.  I want to start serious planning of how the Lisp machine system
is going to make the transition to Common Lisp, and there are still an
enormous number of loose ends as well as areas where the language has diverged
from the Colander edition of the manual, but has not yet reached a final
conclusion.  Once we have several actual, working Common Lisp implementations
and the ability to exchange code routinely, we will be in a much better
position to work constructively on user interfaces and other things at that
level.