Document setf-local, defvar-local, and some doc updates for setf.

* doc/lispref/edebug.texi (Specification List): setf is no longer CL-only.

* doc/lispref/lists.texi (List Elements, List Variables): Clarify descriptions
of push and pop for generalized variables.

* doc/lispref/variables.texi (Creating Buffer-Local): Document setq-local and
defvar-local.
(Setting Generalized Variables): Arrange table alphabetically.

1 files changed, 24 insertions, 9 deletions

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index fb98b3cd035..c8451527d4f 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1262,6 +1262,13 @@ needed if you use the @var{local} argument to @code{add-hook} or
 @code{remove-hook}.
 @end deffn
 
+@defmac setq-local variable value
+This macro creates a buffer-local binding in the current buffer for
+@var{variable}, and gives it the buffer-local value @var{value}.  It
+is equivalent to calling @code{make-local-variable} followed by
+@code{setq}.  @var{variable} should be an unquoted symbol.
+@end defmac
+
 @deffn Command make-variable-buffer-local variable
 This function marks @var{variable} (a symbol) automatically
 buffer-local, so that any subsequent attempt to set it will make it
@@ -1297,6 +1304,14 @@ on having separate values in separate buffers, then using
 @code{make-variable-buffer-local} can be the best solution.
 @end deffn
 
+@defmac defvar-local variable value &optional docstring
+This macro defines @var{variable} as a variable with initial value
+@var{value} and @var{docstring}, and marks it as automatically
+buffer-local.  It is equivalent to calling @code{defvar} followed by
+@code{make-variable-buffer-local}.  @var{variable} should be an
+unquoted symbol.
+@end defmac
+
 @defun local-variable-p variable &optional buffer
 This returns @code{t} if @var{variable} is buffer-local in buffer
 @var{buffer} (which defaults to the current buffer); otherwise,
@@ -1948,7 +1963,6 @@ Attempting to assign them any other value will result in an error:
 @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
 
@@ -1958,7 +1972,6 @@ 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.
@@ -2006,14 +2019,16 @@ so there is no performance penalty for using it in compiled code.
 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
+aref      cddr      symbol-function
+car       elt       symbol-plist
+caar      get       symbol-value
+cadr      gethash
+cdr       nth
+cdar      nthcdr  
 @end smallexample
 
 @item
-The following Emacs-specific functions are also @code{setf}-able:
+A call to any of the following Emacs-specific functions:
 
 @smallexample
 default-value                 process-get
@@ -2030,8 +2045,8 @@ process-filter
 @end itemize
 
 @noindent
-Using any forms other than these in the @var{place} argument to
-@code{setf} will signal an error.
+@code{setf} signals an error if you pass a @var{place} form that it
+does not know how to handle.
 
 @c And for cl-lib's cl-getf.
 Note that for @code{nthcdr}, the list argument of the function must