Errata for 87-002

[David A. Moon <Moon@STONY-BROOK.SCRC.Symbolics.COM>]

Here is my first draft of the errata sheet for the 87-002 documents.
This doesn't get into things that need to be explained better in a major
way, nor into things that are controversial, only things where what the
document says is obviously in error.  I'll send out the other things
separately.  Comments, corrections, and additions are of course highly
welcome.  I tried to find everything but no doubt overlooked some errors.

1-4 seventh paragraph: The distinguished class T is mentioned but I don't
think its characteristics are ever described in the document, except by
implication.  Add the sentence:
  T has no superclasses and is a superclass of every class except itself.

1-6 last paragraph: At the end of the second sentence:  change "lexically
available" to "lexically available as if they were variables".

1-10: Replace the last sentence with "There is also a method
for {\bf setf} of {\tt C2-S3} that writes the value of {\tt S3}."

1-11 second paragraph: The vague word "access" is used without definition.
Add the sentence: "In this context, an instance is said to be
accessed when a generic function is called with the instance as an
argument that is used for method selection, or when {\bf slot-value}
is called with the instance as its first argument."

1-11 third paragraph: Remove the sentence "The function {\bf change-class}
is called when the number of instance variables changes or when the name of
any instance variable changes" since there is no such concept as "instance
variable" in this standard.  Replace it with the sentence:
"When a class is redefined in such a way that the set of local slots
accessible to an instance of the class is changed, or the order of slots
in storage is changed, updating an instance of the class calls the function
{\bf change-class}."

1-11 fourth paragraph: Delete the entire paragraph, it isn't true.  Replace
it with this paragraph:
  Because the class C-sub-O does not have a name, writing a method for
  class-changed that is specialized to a particular C-sub-O
  must be done through the functional interface, using add-method rather
  than defmethod.

1-11 fifth paragraph third sentence: Change "Each slot of the new version"
to "Each local slot of the new version".  Last sentence: Delete "For
local slots," since we are only talking about local slots anyway.

1-11 last paragraph: Change "the value of that slot will be the same
in both instances" to "the value of that slot is unchanged".  Since only
one instance is involved, we can't say "both instances."

1-11 last paragraph:  Break the paragraph after the third sentence so local
slots and shared slots are discussed in separate paragraphs.  Clarify that
the paragraph discussing shared slots refers to what happens at the time
the class is redefined, and shared slots are not affected by updating an
instance nor by the values of local slots.

1-12 last paragraph: Change "Whether {\bf defclass} is allowed to change
the metaclass" to "Whether {\bf defclass} is allowed to change the
metaclass, and whether redefining a class updates existing instances,".

1-18 first paragraph under "Introduction to setf Generic Functions":
Change "(setf (generic-function-name arguments) new-value)"
to "(setf (function-name arguments) new-value)" because the base
function does not have to be generic, in fact it does not even have to
be defined.

1-18 last paragraph: The term "parameter specifier" is used in a way that
is inconsistent with its use by CLtL and there are a couple of typographical
problems.  Replace the entire paragraph with:
  Each method has a {\bit specialized lambda-list}, which determines
  when that method can be selected.  A specialized lambda-list is like
  an ordinary lambda-list except that a {\bit specialized parameter} may occur
  instead of the name of a parameter.  A specialized parameter is a list,
  {\tt ({\it variable-name parameter-specializer-name\/})}.  Every
  parameter specializer name is a Common Lisp type specifier, but the only
  Common Lisp type specifiers that are valid as parameter specializer names
  are the following:

1-19: Delete the first line "In short..." since the two bulleted items are
now introduced by the preceding paragraph.

1-19 fourth paragraph, beginning "Only required parameters can be specialized": 
The term "parameter specifier" is misused again.  Replace the paragraph with:
  Only required parameters can be specialized, and each required parameter
  must have an associated parameter specializer.  For notational simplicity,
  ordinary lambda-list syntax can be used, that is, a parameter name can be
  used instead of a specialized parameter.  In this case the parameter
  specializer defaults to the class named {\bf t}, the class of all objects.

1-19 fifth paragraph: Change "when the class of each required argument"
to "when each required argument".

1-19, seventh, eighth, and tenth paragraphs, discussing the relationship of
parameter specializers to type specifiers: Change "parameter specializer"
to "parameter specializer name" throughout these paragraphs, to be
consistent with the terminology used in earlier paragraphs.

1-19 tenth paragraph: Change "always part of the generic function"
to "always applicable".

1-19 last paragraph fourth sentence: Change "cons" to "list".

1-22 second paragraph: Change "the specializers must be quoted objects
(otherwise" to "the specializers must be equal (otherwise".

1-23 first line: Change "defmacro" to "defmethod".

1-25 sixth paragraph: Change "All {\bf :around} methods run before any
primary methods run." to "All {\bf :around} methods run before any
non-{\bf :around} methods run."

2-5 Values paragraph: Replace the whole sentence with
"The value is {\it generic-function}." to clarify that the value
is EQ to the argument.

2-8 Purpose paragraph:  Add the sentences "The generic function
{\bf change-class} is invoked automatically by the system after
{\bf defclass} has been used to redefine an existing class.
It can also be explicitly invoked by the user."

2-8 Values paragraph: Replace the whole sentence with
"The value is {\it instance}." to clarify that the value
is EQ to the argument.

2-11 Purpose paragraph:  Delete the sentences "The generic function
{\bf change-class} is invoked automatically by the system after
{\bf defclass} has been used to redefine an existing class.
It can also be explicitly invoked by the user."  Add the sentence
"The function {\bf class-changed} is called only by
the function {\bf change-class}."

2-11 second Arguments paragraph: Delete the second sentence.  It lost
its intended meaning as a result of previous editing.

2-11 first Remarks paragraph: Delete this.  It contradicts an
example on page 2-8 and it isn't true.

2-11 second Remarks paragraph: Some occurrences of change-class should be
class-changed and there are a couple of terminological problems ("copy",
"part").  Replace the paragraph with:
  The arguments to {\bf class-changed} are computed by {\bf change-class}.
  The first argument is an instance of the original class
  created to hold the old slot values temporarily.
  This argument has dynamic extent within {\bf class-changed},
  and therefore it is an error to reference it in any way
  once {\bf class-changed} returns.

2-15 last line:  Delete this.  Defclass has no effect on the value cells
of symbols.

2-17 second paragraph: Delete ", from their superclasses, and so on".

2-17 :allocation bullet: Change "in the class instance" to "in each
instance".

2-18 first bullet (:type).  There is no discussion of the meaning and
enforcement of :type.  Add the following (stolen from CLtL p.310):
  This specifies that the contents of the slot will always be of the
  specified data type.  This is entirely analogous to the declaration of a
  variable or function; indeed, it effectively declares the result type of
  the reader generic function when applied to an object of this class.  An
  implementation may or may not choose to check the type of the new object
  when initializing or assigning to a slot.

2-18 :accessor-prefix, :reader-prefix bullets: Change "These ... functions
are interned" to "These ... function names are interned".

2-26 short-form-option syntax: Delete the :order clause.

2-27 fourth bullet: Delete it.

2-29 first paragraph: Replace the next to last sentence with:  "If {\bf
:description} is not specified, a default description is generated based on
the variable name and the qualifier patterns, and on whether this
method-group includes the unqualified methods."

2-33 third paragraph: Change "If no generic function is currently named by
the symbol {\it name\/}" to "If {\tt (fboundp {\it name\/})} is {\bf nil}"
to match the terminology used on page 2-21.

2-34 first paragraph: Change "primary (in this case, unqualified) methods"
to "unqualified methods".

2-34 second paragraph: Same problem with "parameter specifier" as on 1-18.
Replace the first two sentences of the paragraph with:
  The {\it specialized-lambda-list\/} argument is like an ordinary function
  lambda-list except that required parameter names can be replaced by
  specialized parameters.  A specialized parameter is a list of the form
  {\tt ({\it variable-name parameter-specializer-name\/})}.
[This paragraph duplicates information found elsewhere so perhaps it
should be shortened.]

2-35 syntax for specialized-setf-lambda-list: Change "specializer" to
"parameter-specializer-name".

2-38 fourth Arguments paragraph: Change "If the first argument is a symbol"
to "If the first argument is a symbol that names a class".

2-38 last Arguments paragraph: Change "If the first argument is a symbol"
to "If the first argument is a symbol that has a setf generic function
associated with it".

2-39 last Arguments paragraph: Change "second" to "errorp".

2-41 second Purpose paragraph: Delete "to the top level".

2-46 second Purpose paragraph first sentence: It was not intended to
guarantee that the returned value is a list with certain objects in its car
and cdr.  Add the phrase "or a form with equivalent effect" at the end of
the sentence.

2-47 Values paragraph: same as the preceding.

2-48 second Purpose paragraph: Delete "to the top level".

2-53 last Arguments paragraph: Change "second" to "errorp".
Change (twice) "If there is no such method" to
"If {\it generic-function} does not know {\it method}".

2-53 Values paragraph: Replace the whole sentence with
"The value is {\it generic-function}." to clarify that the value
is EQ to the argument.

2-55 last paragraph first sentence: Delete "or a superclass".

2-55 last paragraph fourth sentence: Change "not a subclass of the
specified class" to "not the specified class or a subclass of the
specified class".

2-55 last paragraph fifth sentence: Change "superclass of the instance" to
"superclass of the actual class of the instance" and change "different"
to "smaller".

2-56 second paragraph: Change "using the accessor function" to "calling the
accessor function", "is used to access" to "is called to access", and
"accesses the slots by using" to "accesses the slots by calling".

2-56 Values paragraph: Change "value" to "values" to clarify that the
body can return multiple values.