[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110776: More general edits for cl.texi Appendices

[Glenn Morris]

------------------------------------------------------------
revno: 110776
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Sat 2012-11-03 11:23:38 -0700
message:
  More general edits for cl.texi Appendices
modified:
  doc/misc/cl.texi

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-11-03 17:56:30 +0000
+++ b/doc/misc/cl.texi  2012-11-03 18:23:38 +0000
@@ -4479,25 +4479,27 @@
 @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}.
 
address@hidden FIXME no longer provided by cl.
address@hidden FIXME consider moving to lispref
address@hidden
 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 address@hidden function'' concept
 (typified by @code{(defun (setf foo) @dots{})}) is not implemented.
address@hidden 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 @@
 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 @@
 @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
address@hidden in Emacs 24.3.
address@hidden FIXME details.
address@hidden in Emacs 24.3.  Many of the implementation
+details in the following are out-of-date.
address@hidden 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 @@
 @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 @@
 @defmac defsetf access-fn arglist (store-var) address@hidden
 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 @@
 
 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 @@
 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:
address@hidden FIXME Is this still true?
 
 @enumerate
 @item
@@ -5058,12 +5062,12 @@
 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 @@
 @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
address@hidden 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 @@
 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
address@hidden 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.
address@hidden These no longer exist.
address@hidden
+(Actually, it is better to use the internal functions
address@hidden 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.)
address@hidden 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 @@
 an @code{&environment} argument to the macro or setf-method
 that called @code{get-setf-method}.
 
address@hidden 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
 
address@hidden 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 address@hidden
 functions'' whose names are lists @code{(setf @var{name})}