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.

5 files changed, 58 insertions, 32 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 93a2971f8c6..6951f2df79d 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -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  <rgm@gnu.org>
 
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 21750b79c93..d3c9ad6aedf 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -5019,14 +5019,16 @@ These translate directly to @code{gv-define-simple-setter}:
 @end defmac
 
 @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 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 @@ 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.
 
-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))
+@end example
+
+You could write this using @code{gv-define-setter} as:
+
+@example
+(gv-define-setter nth (store n x)
+  `(setcar (nthcdr ,n ,x) ,store))
 @end example
 @end defmac
 
diff --git a/etc/NEWS b/etc/NEWS
index 33ec17c1960..76126cf6dda 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -339,8 +339,8 @@ rather than making them unbound.
 *** 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
 +++
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index cfd79fc57ef..ff9684ad175 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,8 @@
 2012-11-07  Glenn Morris  <rgm@gnu.org>
 
+        * 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'.
 
diff --git a/lisp/emacs-lisp/cl.el b/lisp/emacs-lisp/cl.el
index 52567f34278..016967bc713 100644
--- a/lisp/emacs-lisp/cl.el
+++ b/lisp/emacs-lisp/cl.el
@@ -547,13 +547,15 @@ deprecated usage of `symbol-function' in place forms)."  ; bug#12760
 
 (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 @@ for a better and simpler ways to define setf-methods."
 
 (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 @@ Example:
 
 (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)))