Documentation and error messages

[Guy.Steele at CMU-10A]

I am a bit concerned about a couple of issues relating to English prose
that the LISP spits out to one.  I am primarily concerned that messages
be of an appropriate length and level of detail for the situation.
(No, I am *not* about to propose variables MSGLEVEL and MSGLENGTH!
But something perhaps close to that.)

First, some people have recognized a need for both short and long
forms of documentation for functions, variables, and other things.
For APROPOS applications or a quick reminder, a line or a sentence
is sufficient, and you don't want APROPOS to belch 100 3-paragraph
descriptions at you instead of 100 lines.  On the other hand, for
DESCRIBE and so on, one wants to see a relatively detailed description.

Here is a quicky solution: in DEFUN, for example, let more than one
documentation string appear, in order of increasing detail, thus:
(DEFUN LENGTH (X)
  "Returns the length of the argument as an integer."
  "LENGTH accepts any sequence (a list or a one-dimensional array)
   and returns its length as a non-negative integer (in fact, as a
   fixnum).  If the argument is an array with a fill pointer, LENGTH
   returns the size of the active region of the array, not that of
   the total memory allocated for the array."
  (TYPECASE ...))

This solution is not great.

There is a similar problem with error messages, trying to strike a
balance between conciseness and helpfulness.  It would be better if
it were possible to signal an error with up to three different
messages: a short (one-line) error message, a longer discourse
explaining the nature of the error and possible likely causes,
and a description of how to recover from the error if it is
possible, particularly in the case of correctable errors.  For certain
software that I want to be useable by non-experts, I would be willing
to define a separate function for each possible error, just so that
I would feel free to write lots of helpful information about an
error condition.  Here's an example of what I have in mind:
(DEFUN UNBOUND-VARIABLE-ERROR (VAR)
  (HERROR ("~S unbound variable" VAR)
    ("The special variable ~S is currently unbound (has no value).
      Perhaps the variable ~S is supposed to have a value and does not,
      or perhaps the name of the correct variable was misspelled."
     VAR VAR)
    ("If you return a correction value, it should be the correct symbol
      naming the variable whose value should be used.  If ther name was
      correctly spelled, give that variable a value first and then return
      that name by typing ~:@C.  Otherwise, return the correct name for
      the variable." #\Hyper-Return)))

Maybe I've gone overboard here, but I want it to be possible to
provide a great amount of on-line help to the user so he doesn't
have to scurry to the manual.  On the other hand, the first thing you
see should be short and crisp, to avoid annoying knowledgeable users.

Comments?
--Guy