Documentation strings and function.

[Kent M Pitman <KMP@SCRC-STONY-BROOK.ARPA>]

Although I would not argue in favor of such an interpretation, I think you'd
have a tough time arguing that the restriction on p67 refers to anything other
than functions defined by DEFUN.

Both the description of DEFUN on p67 (which you cite) and the description of 
LAMBDA on p60 (which you don't comment on) use the same confusing syntax
description:
  ...
  {declaration | documentation-string}*
  ...
Well, ok, they don't. p60 refers to documentation-string and p67 refers to a
doc-string. (-: Maybe only a doc-string is constrained the way you suggest but
a documentation-string is not. :-)

[On an unrelated issue that I noticed on the same page, p67 should clearly
 say that 
  (DEFUN name lambda-list {declaration|doc-string}* {form}*)
 causes the symbol NAME to be a global name for the function specified by
 the lambda expression
  (LAMBDA lambda-list {declaration|doc-string}* (BLOCK name {form}*))
 Otherwise, the ability of RETURN-FROM to work in a DEFUN seems just a little
 too magical, and suggests that LAMBDA or DEFUN somehow interacts with RETURN-FROM
 in some strange way that we don't ever explain.]

Anyway, I think that multiple doc strings should not be undefined and that we
should relax that restriction. They would be especially to people (like myself) 
who get grossed out by The Indentation Problem as illustrated in:

(DEFUN FOO (X Y)
  "This is a very long documentation string which when printed out
   seems to have an obscure amount of indentation on its second and
   third line even though it looked nicely lined up in the source."
  ...)

or:

(DEFUN FOO (X Y)
  "This is a very long documentation string which when printed out
has no problem about indentation for the subsequent lines, but when
viewed in the source looks pretty yucky."
  ...)

I'd prefer:

(DEFUN FOO (X Y)
  "This is how we might allow a very long documentation string to be"
  "typed in in order to let it look good in the source and also to"
  "let it look good when obtained later, perhaps as a single string with"
  "newlines inserted between each of the pieces.")

This would also be handy for defmacro, since you could prefix or postfix
documentation strings in the expansion without worrying about whether the
user was also going to supply a documentation string that elaborated on
the standardly provided documentation.