[Emacs-diffs] /srv/bzr/emacs/emacs-24 r110803: More cl-lib and gv doc updates

[Glenn Morris]

------------------------------------------------------------
revno: 110803
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-11-07 00:56:16 -0800
message:
  More cl-lib and gv doc updates
  
  * lisp/emacs-lisp/cl.el (define-setf-expander, defsetf)
  (define-modify-macro): Doc fixes.
  
  * doc/misc/cl.texi (Obsolete Setf Customization):
  Give defsetf gv.el replacements.
  
  * etc/NEWS: Related edit.
modified:
  doc/misc/ChangeLog
  doc/misc/cl.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/emacs-lisp/cl.el

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-11-07 08:28:34 +0000
+++ b/doc/misc/ChangeLog        2012-11-07 08:56:16 +0000
@@ -2,7 +2,7 @@
 
        * cl.texi (Obsolete Setf Customization):
        Revert defsetf example to the more correct let rather than prog1.
-       Give define-modify-macro gv.el replacement.
+       Give define-modify-macro and defsetf gv.el replacements.
 
 2012-11-06  Glenn Morris  <address@hidden>
 

=== modified file 'doc/misc/cl.texi'
--- a/doc/misc/cl.texi  2012-11-07 08:28:34 +0000
+++ b/doc/misc/cl.texi  2012-11-07 08:56:16 +0000
@@ -5019,14 +5019,16 @@
 @end defmac
 
 @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 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}
-method (analogous to the doc string that appears at the front of a
-function).
+This is the second, more complex, form of @code{defsetf}.
+It can be replaced by @code{gv-define-setter}.
+
+This form of @code{defsetf} is rather like @code{defmacro} except for
+the additional @var{store-var} 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} method (analogous to the doc
+string that appears at the front of a function).
 
 For example, the simple form of @code{defsetf} is shorthand for
 
@@ -5041,11 +5043,18 @@
 setf-method will insert temporary variables as needed to make
 sure the apparent order of evaluation is preserved.
 
-Another example drawn from the standard package:
+Another standard example:
 
 @example
 (defsetf nth (n x) (store)
-  (list 'setcar (list 'nthcdr n x) store))
+  `(setcar (nthcdr ,n ,x) ,store))
address@hidden example
+
+You could write this using @code{gv-define-setter} as:
+
address@hidden
+(gv-define-setter nth (store n x)
+  `(setcar (nthcdr ,n ,x) ,store))
 @end example
 @end defmac
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-11-07 08:32:34 +0000
+++ b/etc/NEWS  2012-11-07 08:56:16 +0000
@@ -339,8 +339,8 @@
 *** The following methods of extending `setf' are obsolete
 (use features from gv.el instead):
 `define-modify-macro' (use `gv-letplace')
-`defsetf' (use `gv-define-simple-setter', or FIXME)
-`define-setf-expander' (use FIXME)
+`defsetf' (use `gv-define-simple-setter' or `gv-define-setter')
+`define-setf-expander' (use `gv-define-setter' or `gv-define-expander')
 
 ** Compilation mode
 +++

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-11-07 04:37:07 +0000
+++ b/lisp/ChangeLog    2012-11-07 08:56:16 +0000
@@ -1,5 +1,8 @@
 2012-11-07  Glenn Morris  <address@hidden>
 
+       * emacs-lisp/cl.el (define-setf-expander, defsetf)
+       (define-modify-macro): Doc fixes.
+
        * emacs-lisp/gv.el (gv-letplace): Fix doc typo.
        (gv-define-simple-setter): Update doc of `fix-return'.
 

=== modified file 'lisp/emacs-lisp/cl.el'
--- a/lisp/emacs-lisp/cl.el     2012-11-07 03:14:27 +0000
+++ b/lisp/emacs-lisp/cl.el     2012-11-07 08:56:16 +0000
@@ -547,13 +547,15 @@
 
 (defmacro define-setf-expander (name arglist &rest body)
   "Define a `setf' method.
-This method shows how to handle `setf's to places of the form (NAME ARGS...).
-The argument forms ARGS are bound according to ARGLIST, as if NAME were
-going to be expanded as a macro, then the BODY forms are executed and must
-return a list of five elements: a temporary-variables list, a value-forms
-list, a store-variables list (of length one), a store-form, and an access-
-form.  See `gv-define-expander', `gv-define-setter', and `gv-define-expander'
-for a better and simpler ways to define setf-methods."
+This method shows how to handle `setf's to places of the form
+\(NAME ARGS...).  The argument forms ARGS are bound according to
+ARGLIST, as if NAME were going to be expanded as a macro, then
+the BODY forms are executed and must return a list of five elements:
+a temporary-variables list, a value-forms list, a store-variables list
+\(of length one), a store-form, and an access- form.
+
+See `gv-define-expander', and `gv-define-setter' for better and
+simpler ways to define setf-methods."
   (declare (debug
             (&define name cl-lambda-list cl-declarations-or-string def-body)))
   `(progn
@@ -566,23 +568,31 @@
 
 (defmacro defsetf (name arg1 &rest args)
   "Define a `setf' method.
-This macro is an easy-to-use substitute for `define-setf-expander' that works
-well for simple place forms.  In the simple `defsetf' form, `setf's of
-the form (setf (NAME ARGS...) VAL) are transformed to function or macro
-calls of the form (FUNC ARGS... VAL).  Example:
+This macro is an easy-to-use substitute for `define-setf-expander'
+that works well for simple place forms.
+
+In the simple `defsetf' form, `setf's of the form (setf (NAME
+ARGS...) VAL) are transformed to function or macro calls of the
+form (FUNC ARGS... VAL).  For example:
 
   (defsetf aref aset)
 
+You can replace this form with `gv-define-simple-setter'.
+
 Alternate form: (defsetf NAME ARGLIST (STORE) BODY...).
-Here, the above `setf' call is expanded by binding the argument forms ARGS
-according to ARGLIST, binding the value form VAL to STORE, then executing
-BODY, which must return a Lisp form that does the necessary `setf' operation.
-Actually, ARGLIST and STORE may be bound to temporary variables which are
-introduced automatically to preserve proper execution order of the arguments.
-Example:
+
+Here, the above `setf' call is expanded by binding the argument
+forms ARGS according to ARGLIST, binding the value form VAL to
+STORE, then executing BODY, which must return a Lisp form that
+does the necessary `setf' operation.  Actually, ARGLIST and STORE
+may be bound to temporary variables which are introduced
+automatically to preserve proper execution order of the arguments.
+For example:
 
   (defsetf nth (n x) (v) `(setcar (nthcdr ,n ,x) ,v))
 
+You can replace this form with `gv-define-setter'.
+
 \(fn NAME [FUNC | ARGLIST (STORE) BODY...])"
   (declare (debug
             (&define name
@@ -639,8 +649,12 @@
 
 (defmacro define-modify-macro (name arglist func &optional doc)
   "Define a `setf'-like modify macro.
-If NAME is called, it combines its PLACE argument with the other arguments
-from ARGLIST using FUNC: (define-modify-macro incf (&optional (n 1)) +)"
+If NAME is called, it combines its PLACE argument with the other
+arguments from ARGLIST using FUNC.  For example:
+
+  (define-modify-macro incf (&optional (n 1)) +)
+
+You can replace this macro with `gv-letplace'."
   (declare (debug
             (&define name cl-lambda-list ;; should exclude &key
                      symbolp &optional stringp)))