Edit `Introspection'

* doc/ref/goops.texi (Introspection): Make a bit snappier.
  (Classes): Add intro.  Remove "the" and "metaobject" everywhere.
  Remove `class-environment', since I don't know what it's useful for.
  (Instances): Remove implementation notes.
  (Built-in classes): Merge with `Instances'.  Reorder text points.
  (Generic Functions): Add intro.  Remove "the" and "metaobject"
  everywhere.
  (Generic Function Methods): Merge with `Generic Functions'.

doc/ref/goops.texi

@@ -1240,10 +1240,10 @@ actual class C, if C1 comes before C2 in C's class precedence list.
 @node Introspection
 @section Introspection
 
-@dfn{Introspection}, also known as @dfn{reflection}, is the name given
+@dfn{Introspection}, or @dfn{reflection}, means being able to obtain
-to the ability to obtain information dynamically about GOOPS metaobjects.
+information dynamically about GOOPS objects.  It is perhaps best
-It is perhaps best illustrated by considering an object oriented language
+illustrated by considering an object oriented language that does not
-that does not provide any introspection, namely C++.
+provide any introspection, namely C++.
 
 Nothing in C++ allows a running program to obtain answers to the following
 types of question:
@@ -1272,60 +1272,53 @@ GOOPS equivalents --- to be obtained dynamically, at run time.
 * Classes::
 * Slots::
 * Instances::
-* Built-in classes::
 * Generic Functions::
-* Generic Function Methods::
 @end menu
 
 @node Classes
 @subsection Classes
 
+A GOOPS class is itself an instance of the @code{<class>} class, or of a
+subclass of @code{<class>}.  The definition of the @code{<class>} class
+has slots that are used to describe the properties of a class, including
+the following.
+
 @deffn {primitive procedure} class-name class
-Return the name of class @var{class}.
+Return the name of class @var{class}.  This is the value of
-This is the value of the @var{class} metaobject's @code{name} slot.
+@var{class}'s @code{name} slot.
 @end deffn
 
 @deffn {primitive procedure} class-direct-supers class
-Return a list containing the direct superclasses of @var{class}.
+Return a list containing the direct superclasses of @var{class}.  This
-This is the value of the @var{class} metaobject's
+is the value of @var{class}'s @code{direct-supers} slot.
-@code{direct-supers} slot.
 @end deffn
 
 @deffn {primitive procedure} class-direct-slots class
 Return a list containing the slot definitions of the direct slots of
-@var{class}.
+@var{class}.  This is the value of @var{class}'s @code{direct-slots}
-This is the value of the @var{class} metaobject's @code{direct-slots}
 slot.
 @end deffn
 
 @deffn {primitive procedure} class-direct-subclasses class
-Return a list containing the direct subclasses of @var{class}.
+Return a list containing the direct subclasses of @var{class}.  This is
-This is the value of the @var{class} metaobject's
+the value of @var{class}'s @code{direct-subclasses} slot.
-@code{direct-subclasses} slot.
 @end deffn
 
 @deffn {primitive procedure} class-direct-methods class
 Return a list of all the generic function methods that use @var{class}
-as a formal parameter specializer.
+as a formal parameter specializer.  This is the value of @var{class}'s
-This is the value of the @var{class} metaobject's @code{direct-methods}
+@code{direct-methods} slot.
-slot.
 @end deffn
 
 @deffn {primitive procedure} class-precedence-list class
 Return the class precedence list for class @var{class} (@pxref{Class
-Precedence List}).
+Precedence List}).  This is the value of @var{class}'s @code{cpl} slot.
-This is the value of the @var{class} metaobject's @code{cpl} slot.
 @end deffn
 
 @deffn {primitive procedure} class-slots class
-Return a list containing the slot definitions for all @var{class}'s slots,
+Return a list containing the slot definitions for all @var{class}'s
-including any slots that are inherited from superclasses.
+slots, including any slots that are inherited from superclasses.  This
-This is the value of the @var{class} metaobject's @code{slots} slot.
+is the value of @var{class}'s @code{slots} slot.
-@end deffn
-
-@deffn {primitive procedure} class-environment class
-Return the value of @var{class}'s @code{environment} slot.
-[ *fixme*  I don't know what this value is used for. ]
 @end deffn
 
 @deffn procedure class-subclasses class
@@ -1337,6 +1330,7 @@ Return a list of all methods that use @var{class} or a subclass of
 @var{class} as one of its formal parameter specializers.
 @end deffn
 
+
 @node Slots
 @subsection Slots
 
@@ -1435,18 +1429,12 @@ Return @code{#t} if @var{object} is an instance of @var{class} or one of
 its subclasses.
 @end deffn
 
-Implementation notes: @code{is-a?} uses @code{class-of} and
+You can use the @code{is-a?} predicate to ask whether any given value
-@code{class-precedence-list} to obtain the class precedence list for
+belongs to a given class, or @code{class-of} to discover the class of a
-@var{object}.
+given value.  Note that when GOOPS is loaded (by code using the
-
+@code{(oop goops)} module) built-in classes like @code{<string>},
-@node Built-in classes
+@code{<list>} and @code{<number>} are automatically set up,
-@subsection Built-in classes
+corresponding to all Guile Scheme types.
-
-There are built-in classes like @code{<string>}, @code{<list>} and
-@code{<number>} corresponding to all the Guile Scheme types.  You can
-use the @code{is-a?} predicate to ask whether any given value belongs to
-a given class, or @code{class-of} to discover the class of a given
-value.
 
 @lisp
 (is-a? 2.3 <number>) @result{} #t
@@ -1468,34 +1456,37 @@ value.
 @node Generic Functions
 @subsection Generic Functions
 
+A generic function is an instance of the @code{<generic>} class, or of a
+subclass of @code{<generic>}.  The definition of the @code{<generic>}
+class has slots that are used to describe the properties of a generic
+function.
+
 @deffn {primitive procedure} generic-function-name gf
 Return the name of generic function @var{gf}.
 @end deffn
 
 @deffn {primitive procedure} generic-function-methods gf
-Return a list of the methods of generic function @var{gf}.
+Return a list of the methods of generic function @var{gf}.  This is the
-This is the value of the @var{gf} metaobject's @code{methods} slot.
+value of @var{gf}'s @code{methods} slot.
 @end deffn
 
-@node Generic Function Methods
+Similarly, a method is an instance of the @code{<method>} class, or of a
-@subsection Generic Function Methods
+subclass of @code{<method>}; and the definition of the @code{<method>}
+class has slots that are used to describe the properties of a method.
 
 @deffn {primitive procedure} method-generic-function method
-Return the generic function that @var{method} belongs to.
+Return the generic function that @var{method} belongs to.  This is the
-This is the value of the @var{method} metaobject's
+value of @var{method}'s @code{generic-function} slot.
-@code{generic-function} slot.
 @end deffn
 
 @deffn {primitive procedure} method-specializers method
-Return a list of @var{method}'s formal parameter specializers .
+Return a list of @var{method}'s formal parameter specializers .  This is
-This is the value of the @var{method} metaobject's
+the value of @var{method}'s @code{specializers} slot.
-@code{specializers} slot.
 @end deffn
 
 @deffn {primitive procedure} method-procedure method
-Return the procedure that implements @var{method}.
+Return the procedure that implements @var{method}.  This is the value of
-This is the value of the @var{method} metaobject's
+@var{method}'s @code{procedure} slot.
-@code{procedure} slot.
 @end deffn
 
 @deffn generic method-source