More general edits for cl.texi Appendices

doc/misc/cl.texi

@@ -4479,25 +4479,27 @@ referenced by @code{cl-return} or @code{cl-return-from} inside the block.
 @appendix Common Lisp Compatibility
 
 @noindent
-Following is a list of all known incompatibilities between this
+The following is a list of all known incompatibilities between this
 package and Common Lisp as documented in Steele (2nd edition).
 
 The word @code{cl-defun} is required instead of @code{defun} in order
 to use extended Common Lisp argument lists in a function.  Likewise,
 @code{cl-defmacro} and @code{cl-function} are versions of those forms
 which understand full-featured argument lists.  The @code{&whole}
-keyword does not work in @code{defmacro} argument lists (except
+keyword does not work in @code{cl-defmacro} argument lists (except
 inside recursive argument lists).
 
 The @code{equal} predicate does not distinguish
 between IEEE floating-point plus and minus zero.  The @code{cl-equalp}
 predicate has several differences with Common Lisp; @pxref{Predicates}.
 
-@c FIXME no longer provided by cl.
+@c FIXME consider moving to lispref
+@ignore
 The @code{setf} mechanism is entirely compatible, except that
 setf-methods return a list of five values rather than five
 values directly.  Also, the new ``@code{setf} function'' concept
 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
+@end ignore
 
 The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
 with no @var{obarray} argument.  In Common Lisp, this form would
@@ -4630,7 +4632,7 @@ However, the Emacs parser does not understand colons and just
 treats them as part of the symbol name.  Thus, while @code{mapcar}
 and @code{lisp:mapcar} may refer to the same symbol in Common
 Lisp, they are totally distinct in Emacs Lisp.  Common Lisp
-programs which refer to a symbol by the full name sometimes
+programs that refer to a symbol by the full name sometimes
 and the short name other times will not port cleanly to Emacs.
 
 Emacs Lisp does have a concept of ``obarrays'', which are
@@ -4917,8 +4919,9 @@ Common Lisp defines three macros, @code{define-modify-macro},
 @code{defsetf}, and @code{define-setf-method}, that allow the
 user to extend generalized variables in various ways.
 In Emacs, these are obsolete, replaced by various features of
-@file{gv.el} in Emacs 24.3.
-@c FIXME details.
+@file{gv.el} in Emacs 24.3.  Many of the implementation
+details in the following are out-of-date.
+@c FIXME this whole section needs updating.
 
 @defmac define-modify-macro name arglist function [doc-string]
 This macro defines a ``read-modify-write'' macro similar to
@@ -4987,7 +4990,7 @@ Otherwise, the above expansion would not obey the rules for the way
 @code{setf} is supposed to behave.
 
 As a special (non-Common-Lisp) extension, a third argument of @code{t}
-to @code{defsetf} says that the @code{update-fn}'s return value is
+to @code{defsetf} says that the return value of @code{update-fn} is
 not suitable, so that the above @code{setf} should be expanded to
 something more like
 
@@ -5010,7 +5013,7 @@ suite of setf methods, are:
 @defmac defsetf access-fn arglist (store-var) forms@dots{}
 This is the second, more complex, form of @code{defsetf}.  It is
 rather like @code{defmacro} except for the additional @var{store-var}
-argument.  The @var{forms} should return a Lisp form which stores
+argument.  The @var{forms} should return a Lisp form that stores
 the value of @var{store-var} into the generalized variable formed
 by a call to @var{access-fn} with arguments described by @var{arglist}.
 The @var{forms} may begin with a string which documents the @code{setf}
@@ -5026,7 +5029,7 @@ For example, the simple form of @code{defsetf} is shorthand for
 
 The Lisp form that is returned can access the arguments from
 @var{arglist} and @var{store-var} in an unrestricted fashion;
-macros like @code{setf} and @code{cl-incf} which invoke this
+macros like @code{cl-incf} that invoke this
 setf-method will insert temporary variables as needed to make
 sure the apparent order of evaluation is preserved.
 
@@ -5043,6 +5046,7 @@ This is the most general way to create new place forms.  When
 a @code{setf} to @var{access-fn} with arguments described by
 @var{arglist} is expanded, the @var{forms} are evaluated and
 must return a list of five items:
+@c FIXME Is this still true?
 
 @enumerate
 @item
@@ -5058,12 +5062,12 @@ A list of exactly one @dfn{store variable} (generally obtained
 from a call to @code{gensym}).
 
 @item
-A Lisp form which stores the contents of the store variable into
+A Lisp form that stores the contents of the store variable into
 the generalized variable, assuming the temporaries have been
 bound as described above.
 
 @item
-A Lisp form which accesses the contents of the generalized variable,
+A Lisp form that accesses the contents of the generalized variable,
 assuming the temporaries have been bound.
 @end enumerate
 
@@ -5079,7 +5083,8 @@ temporary variables.  In the setf-methods generated by
 @code{defsetf}, the second return value is simply the list of
 arguments in the place form, and the first return value is a
 list of a corresponding number of temporary variables generated
-by @code{cl-gensym}.  Macros like @code{setf} and @code{cl-incf} which
+@c FIXME I don't think this is true anymore.
+by @code{cl-gensym}.  Macros like @code{cl-incf} that
 use this setf-method will optimize away most temporaries that
 turn out to be unnecessary, so there is little reason for the
 setf-method itself to optimize.
@@ -5090,12 +5095,14 @@ This function returns the setf-method for @var{place}, by
 invoking the definition previously recorded by @code{defsetf}
 or @code{define-setf-method}.  The result is a list of five
 values as described above.  You can use this function to build
-your own @code{cl-incf}-like modify macros.  (Actually, it is
-@c FIXME?
-better to use the internal functions @code{cl-setf-do-modify}
-and @code{cl-setf-do-store}, which are a bit easier to use and
-which also do a number of optimizations; consult the source
-code for the @code{cl-incf} function for a simple example.)
+your own @code{cl-incf}-like modify macros.
+@c These no longer exist.
+@ignore
+(Actually, it is better to use the internal functions
+@code{cl-setf-do-modify} and @code{cl-setf-do-store}, which are a bit
+easier to use and which also do a number of optimizations; consult the
+source code for the @code{cl-incf} function for a simple example.)
+@end ignore
 
 The argument @var{env} specifies the ``environment'' to be
 passed on to @code{macroexpand} if @code{get-setf-method} should
@@ -5103,12 +5110,14 @@ need to expand a macro in @var{place}.  It should come from
 an @code{&environment} argument to the macro or setf-method
 that called @code{get-setf-method}.
 
+@c FIXME No longer true.
 See also the source code for the setf-method for
 @c Also @code{apply}, but that is commented out.
 @code{substring}, which works by calling @code{get-setf-method} on a
 simpler case, then massaging the result.
 @end defun
 
+@c FIXME does not belong here any more, maybe in lispref?
 Modern Common Lisp defines a second, independent way to specify
 the @code{setf} behavior of a function, namely ``@code{setf}
 functions'' whose names are lists @code{(setf @var{name})}