My comments on Chapter 1

[Sonya E. Keene <skeene@STONY-BROOK.SCRC.Symbolics.COM>]

In general, the spec seems to be coming together nicely.   I think it
reads better than it used to, and the tone is quite consistent
throughout.

----------------

I found it somewhat distracting that hyphenated functions are split
across lines.  

1-7, second group of bullets, bullet #2:   

"appropriately named" should be deleted; it implies that there is a
heuristic that makes up an appropriate name for the accessor generic 
functions.

1-7, second to last paragraph

Fix typo "unitialized".  Actually, I suggest deleting the sentence
containing the typo.   The sentence is:  "When an uninitialized slot is
read, the generic function uninitialized-slot is invoked."    That's too
much detail for the overview; it bypasses describing the default
behavior, which would be more appropriate for an overview.   In any
case, I believe the previous sentence is sufficient.

1-10, second paragraph under "Inheritance of Slots and Slot Options"

The last clause says "all instances of C access that single slot"; I
suggest saying instead "all instances of C can access that single slot"
or "that single slot is accessible to all instances of C."   

1-13, regarding the default method for update-instance-structure

I like Moon's suggestion that the default method doesn't do the work.
But if that suggestion is not accepted, we should mention that users
should write after-methods unless they want to prevent the default
method from occurring.   This could go at the end of the fourth
paragraph.   Also it would be better to move the sentence beginning
"Methods for update-instance-structure can be defined..." from the 3rd
paragraph to the 4th, where the rest of the discussion about writing
methods is.    

1-15

I agree with Moon that a better name is "Changing the Class of an
Instance".    I also think it's confusing to use the terminology "old
class" and "new class" here, because the terms are used very differently
in the previous section.    In the previous section "old class" meant
"that class that is now obsolete".   Here it means "the previous class
of the instance".   Here the "old class" is still current; it isn't
obsolete.      I think new terminology could make it more clear what the
difference is between "changing the class of an instance" and
"redefining a class" -- how about using C-1 and C-2 terminology.   That
makes it more clear that C-1 is not "old" or "obsolete" in any way; it's
just a class like any other. 

Last paragraph:   add "The default primary method for class-changed does
nothing." near the end of the paragraph.  

1-17, Figure 1-1

The column header "Superclasses" doesn't make it clear that the order of
these classes is from most to least specific.    In my draft of this the
column header was "Class Precedence List", which did make this clear.    

1-19, First Example

Should state explicitly that the goal is to determine the CPL for the 
class pie. 

1-21, 3rd paragraph

"Ordinary functions and generic functions are called with identical 
syntax."    I can't remember for sure, but I believe we decided that
generic functions must have at least one required argument.   If so,
this is one (minor) syntactic difference between ordinary and generic
functions.  

1-21, 4th paragraph

Last sentence implies you need to evaluate a set of forms (a set of
defmethods and possibly a defgeneric) to produce a generic function
object, whereas really the evaluation of only one such form would do it.  

1-21, last sentence

What is meant by "defgeneric (etc) are said to define a generic
function"?   Unless you define "define", this is too vague to mean
anything.   And if "define" means "create a g-f object", then defmethod
ought to be mentioned too.  

1-22, second paragraph, last sentence

Regarding exporting names of generic functions from packages, the clause
"if it is part of an external interface" implies there is a way to
actually specify an external interface.   I suggest replacing that
phrase with "if desired".

1-22, fifth paragraph, last sentence

I suggest replacing "The lambda-list of the generic function is defined
to be congruent with the lambda-list of the new method." with "The
lambda-list of the generic function is derived from the lambda-list of
the new method"

1-22, second to last paragraph

Typo:  "specifying a names of"   

1-25, second to last paragraph

"it is rare to find a vector used as a qualifier" -- The tone of this
clause is inconsistent with the usual factual, dry tone of the spec.
Since it doesn't add anything to what was already said, we should delete
it. 

1-26, last paragraph

Change "not by all methods" to "not by all methods for the generic
function".    

1-29, last paragrpah

Split up this too-long sentence into two or more sentences.  

1-30, Standard Method Combination

I think the standard method combination should have a name, such as
"standard-method-combination".    That name should be able to be given
to the :method-combination option to defgeneric, etc.   It should be
noted as one of the Built-in Method Combination types.   Just because it
is the default doesn't mean that it shouldn't have a name.    

1-31

We don't say here what happens if a generic function is called and 
there is no applicable method at all.   Presumably an error is signaled.

1-32, first bullet, last sentence

Replace this sentence with "Use of the function call-next-method is
supported in :around methods."

1-32, second bullet 

Add this sentence "Use of the function call-next-method is not 
supported in primary methods."

1-32, third paragraph (excluding bullets)

It looks weird to have the close paren alone on the line.   Bad line
break.