Move generalized variable documentation from misc/cl.texi to lispref

* doc/lispref/variables.texi (Generalized Variables): New section,
adapted from misc/cl.texi.

* doc/lispref/elisp.texi (Top): Add Generalized Variables to menu.

* doc/lispref/lists.texi (List Elements, List Variables):
Mention generalized variables.

* doc/misc/cl.texi (Control Structure): Update for setf now being in core.
(Setf Extensions): Rename from Basic Setf.  Move much of the
former content to lispref/variables.texi.
(Modify Macros): Move pop, push details to lispref/variables.texi.
(Customizing Setf): Copyedits for setf etc being in core.
(Modify Macros, Efficiency Concerns, Porting Common Lisp):
Further namespaces updates.

4 files changed, 118 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 03922f2c02f..aea26248452 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,5 +1,11 @@
 2012-10-27  Glenn Morris  <rgm@gnu.org>
 
+        * variables.texi (Generalized Variables): New section,
+        adapted from misc/cl.texi.
+        * elisp.texi (Top): Add Generalized Variables to menu.
+        * lists.texi (List Elements, List Variables):
+        Mention generalized variables.
+
         * lists.texi (List Elements): Typo fix.
 
 2012-10-27  Chong Yidong  <cyd@gnu.org>
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 1d1dab8faac..06a2ebfcaf8 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -486,6 +486,7 @@ Variables
 * Variable Aliases::        Variables that are aliases for other variables.
 * Variables with Restricted Values::  Non-constant variables whose value can
                                         @emph{not} be an arbitrary Lisp object.
+* Generalized Variables::   Extending the concept of variables.
 
 Scoping Rules for Variable Bindings
 
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index eaef8cc1f8a..09948caaa13 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -236,6 +236,10 @@ This is in contrast to @code{cdr}, which signals an error if
 @defmac pop listname
 This macro is a way of examining the @sc{car} of a list,
 and taking it off the list, all at once.
+@c FIXME I don't think is a particularly good way to do it,
+@c but generalized variables have not been introduced yet.
+(In fact, this macro can act on generalized variables, not just lists.
+@xref{Generalized Variables}.)
 
 It operates on the list which is stored in the symbol @var{listname}.
 It removes this element from the list by setting @var{listname}
@@ -682,6 +686,10 @@ to modify a list which is stored in a variable.
 @defmac push newelt listname
 This macro provides an alternative way to write
 @code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
+@c FIXME I don't think is a particularly good way to do it,
+@c but generalized variables have not been introduced yet.
+(In fact, this macro can act on generalized variables, not just lists.
+@xref{Generalized Variables}.)
 
 @example
 (setq l '(a b))
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 1c0abcb8e66..1ffb1f7ffcb 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -41,6 +41,7 @@ representing the variable.
 * Variable Aliases::            Variables that are aliases for other variables.
 * Variables with Restricted Values::  Non-constant variables whose value can
                                         @emph{not} be an arbitrary Lisp object.
+* Generalized Variables::       Extending the concept of variables.
 @end menu
 
 @node Global Variables
@@ -1946,3 +1947,105 @@ Attempting to assign them any other value will result in an error:
 (setq undo-limit 1000.0)
 @error{} Wrong type argument: integerp, 1000.0
 @end example
+
+@c FIXME?  Not sure this is the right place for this section.
+@node Generalized Variables
+@section Generalized Variables
+
+A @dfn{generalized variable} or @dfn{place form} is one of the many places
+in Lisp memory where values can be stored.  The simplest place form is
+a regular Lisp variable.  But the @sc{car}s and @sc{cdr}s of lists, elements
+of arrays, properties of symbols, and many other locations are also
+places where Lisp values are stored.
+
+@c FIXME?  Not sure this is a useful analogy...
+Generalized variables are analogous to ``lvalues'' in the C
+language, where @samp{x = a[i]} gets an element from an array
+and @samp{a[i] = x} stores an element using the same notation.
+Just as certain forms like @code{a[i]} can be lvalues in C, there
+is a set of forms that can be generalized variables in Lisp.
+
+The @code{setf} macro is the most basic way to operate on generalized
+variables.  The @code{setf} form is like @code{setq}, except that it
+accepts arbitrary place forms on the left side rather than just
+symbols.  For example, @code{(setf (car a) b)} sets the car of
+@code{a} to @code{b}, doing the same operation as @code{(setcar a b)},
+but without having to remember two separate functions for setting and
+accessing every type of place.
+
+@defmac setf [place form]@dots{}
+This macro evaluates @var{form} and stores it in @var{place}, which
+must be a valid generalized variable form.  If there are several
+@var{place} and @var{form} pairs, the assignments are done sequentially
+just as with @code{setq}.  @code{setf} returns the value of the last
+@var{form}.
+@end defmac
+
+The following Lisp forms will work as generalized variables, and
+so may appear in the @var{place} argument of @code{setf}:
+
+@itemize
+@item
+A symbol naming a variable.  In other words, @code{(setf x y)} is
+exactly equivalent to @code{(setq x y)}, and @code{setq} itself is
+strictly speaking redundant given that @code{setf} exists.  Many
+programmers continue to prefer @code{setq} for setting simple
+variables, though, purely for stylistic or historical reasons.
+The macro @code{(setf x y)} actually expands to @code{(setq x y)},
+so there is no performance penalty for using it in compiled code.
+
+@item
+A call to any of the following standard Lisp functions:
+
+@smallexample
+car            cdr            nth            nthcdr
+caar           cadr           cdar           cddr
+aref           elt            get            gethash
+symbol-function        symbol-value          symbol-plist
+@end smallexample
+
+@item
+The following Emacs-specific functions are also @code{setf}-able:
+
+@smallexample
+default-value                 process-get
+frame-parameter               process-sentinel
+terminal-parameter            window-buffer
+keymap-parent                 window-display-table
+match-data                    window-dedicated-p
+overlay-get                   window-hscroll
+overlay-start                 window-parameter
+overlay-end                   window-point
+process-buffer                window-start
+process-filter
+@end smallexample
+@end itemize
+
+@noindent
+Using any forms other than these in the @var{place} argument to
+@code{setf} will signal an error.
+
+Note that for @code{nthcdr} and @code{getf}, the list argument
+of the function must itself be a valid @var{place} form.  For
+example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself
+to 7.
+@c The use of @code{nthcdr} as a @var{place} form is an extension
+@c to standard Common Lisp.
+
+@c FIXME I don't think is a particularly good way to do it,
+@c but these macros are introduced before gvs are.
+The macros @code{push} (@pxref{List Variables}) and @code{pop}
+(@pxref{List Elements}) can manipulate generalized variables,
+not just lists.  @code{(pop @var{place})} removes and returns the first
+element of the list stored in @var{place}.  It is analogous to
+@code{(prog1 (car @var{place}) (setf @var{place} (cdr @var{place})))},
+except that it takes care to evaluate all subforms only once.
+@code{(push @var{x} @var{place})} inserts @var{x} at the front of
+the list stored in @var{place}.  It is analogous to @code{(setf
+@var{place} (cons @var{x} @var{place}))}, except for evaluation of the
+subforms.  Note that @code{push} and @code{pop} on an @code{nthcdr}
+place can be used to insert or delete at any position in a list.
+
+The @file{cl-lib} library defines various extensions for generalized
+variables, including additional @code{setf} places.
+@xref{Generalized Variables,,, cl, Common Lisp Extensions}.