(Variables): Clarify introduction.

(Global Variables): Mention that setq is a special form.
(Local Variables): Use active voice.
(Tips for Defining): Mention marking variables as safe.
(Buffer-Local Variables): Mention terminal-local and frame-local
variables together.
(File Local Variables): Copyedits.
(Frame-Local Variables): Note that they are not really useful.
(Future Local Variables): Node deleted.

1 files changed, 65 insertions, 84 deletions

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 7cdec03441..592279d011 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -15,16 +15,15 @@ symbols.
 
   In Lisp, unlike most programming languages, programs are represented
 primarily as Lisp objects and only secondarily as text.  The Lisp
-objects used for variables are symbols: the symbol name is the variable
-name, and the variable's value is stored in the value cell of the
-symbol.  The use of a symbol as a variable is independent of its use as
-a function name.  @xref{Symbol Components}.
+objects used for variables are symbols: the symbol name is the
+variable name, and the variable's value is stored in the value cell of
+the symbol.  The use of a symbol as a variable is independent of its
+use as a function name.  @xref{Symbol Components}.
 
-  The Lisp objects that constitute a Lisp program determine the textual
-form of the program---it is simply the read syntax for those Lisp
-objects.  This is why, for example, a variable in a textual Lisp program
-is written using the read syntax for the symbol that represents the
-variable.
+  The textual form of a Lisp program is given by the read syntax of
+the Lisp objects that constitute the program.  Hence, a variable in a
+textual Lisp program is written using the read syntax for the symbol
+representing the variable.
 
 @menu
 * Global Variables::      Variable values that exist permanently, everywhere.
@@ -42,7 +41,6 @@ variable.
 * File Local Variables::  Handling local variable lists in files.
 * Directory Local Variables:: Local variables common to all files in a directory.
 * Frame-Local Variables:: Frame-local bindings for variables.
-* Future Local Variables::  New kinds of local values we might add some day.
 * 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.
@@ -66,11 +64,12 @@ old one, no trace of the old value remains in the variable.
 
 @noindent
 gives the variable @code{x} the value @code{(a b)}.  Note that
-@code{setq} does not evaluate its first argument, the name of the
-variable, but it does evaluate the second argument, the new value.
+@code{setq} is a special form (@pxref{Special Forms}); it does not
+evaluate its first argument, the name of the variable, but it does
+evaluate the second argument, the new value.
 
-  Once the variable has a value, you can refer to it by using the symbol
-by itself as an expression.  Thus,
+  Once the variable has a value, you can refer to it by using the
+symbol itself as an expression.  Thus,
 
 @example
 @group
@@ -153,11 +152,11 @@ special form explicitly establishes new local values for specified
 variables; these last until exit from the @code{let} form.
 
 @cindex shadowing of variables
-  Establishing a local value saves away the previous value (or lack of
-one) of the variable.  When the life span of the local value is over,
-the previous value is restored.  In the mean time, we say that the
-previous value is @dfn{shadowed} and @dfn{not visible}.  Both global and
-local values may be shadowed (@pxref{Scope}).
+  Establishing a local value saves away the variable's previous value
+(or lack of one).  We say that the previous value is @dfn{shadowed}
+and @dfn{not visible}.  Both global and local values may be shadowed
+(@pxref{Scope}).  After the life span of the local value is over, the
+previous value (or lack of one) is restored.
 
   If you set a variable (such as with @code{setq}) while it is local,
 this replaces the local value; it does not alter the global value, or
@@ -165,10 +164,10 @@ previous local values, that are shadowed.  To model this behavior, we
 speak of a @dfn{local binding} of the variable as well as a local value.
 
   The local binding is a conceptual place that holds a local value.
-Entry to a function, or a special form such as @code{let}, creates the
-local binding; exit from the function or from the @code{let} removes the
-local binding.  As long as the local binding lasts, the variable's value
-is stored within it.  Use of @code{setq} or @code{set} while there is a
+Entering a function, or a special form such as @code{let}, creates the
+local binding; exiting the function or the @code{let} removes the
+local binding.  While the local binding lasts, the variable's value is
+stored within it.  Using @code{setq} or @code{set} while there is a
 local binding stores a different value into the local binding; it does
 not create a new binding.
 
@@ -267,9 +266,9 @@ like ordinary local bindings, but they are localized depending on
 @cindex evaluation error
 @cindex infinite recursion
 This variable defines the limit on the total number of local variable
-bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,,
-Cleaning Up from Nonlocal Exits}) that are allowed before signaling an
-error (with data @code{"Variable binding depth exceeds
+bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,,
+Cleaning Up from Nonlocal Exits}) that are allowed before Emacs
+signals an error (with data @code{"Variable binding depth exceeds
 max-specpdl-size"}).
 
 This limit, with the associated error when it is exceeded, is one way
@@ -635,7 +634,7 @@ The value specifies options for a command.
 @end table
 
   When you define a variable, always consider whether you should mark
-it as ``risky''; see @ref{File Local Variables}.
+it as ``safe'' or ``risky''; see @ref{File Local Variables}.
 
   When defining and initializing a variable that holds a complicated
 value (such as a keymap with bindings in it), it's best to put the
@@ -1091,9 +1090,9 @@ languages in one form or another.  Emacs, however, also supports
 additional, unusual kinds of variable binding, such as
 @dfn{buffer-local} bindings, which apply only in one buffer.  Having
 different values for a variable in different buffers is an important
-customization method.  (A few variables have bindings that are local
-to each terminal; see @ref{Multiple Displays}.  You can also have
-frame-local bindings for variables; see @ref{Frame-Local Variables}.)
+customization method.  (Variables can also have bindings that are
+local to each terminal, or to each frame.  @xref{Multiple Displays},
+and @xref{Frame-Local Variables}.)
 
 @menu
 * Intro to Buffer-Local::      Introduction and concepts.
@@ -1192,7 +1191,7 @@ buffer-local binding of buffer @samp{b}.
 values when you visit the file.  @xref{File Variables,,, emacs, The
 GNU Emacs Manual}.
 
-  A variable cannot be both buffer-local and frame-local
+  A buffer-local variable cannot be made frame-local
 (@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple
 Displays}).
 
@@ -1204,7 +1203,6 @@ This function creates a buffer-local binding in the current buffer for
 @var{variable} (a symbol).  Other buffers are not affected.  The value
 returned is @var{variable}.
 
-@c Emacs 19 feature
 The buffer-local value of @var{variable} starts out as the same value
 @var{variable} previously had.  If @var{variable} was void, it remains
 void.
@@ -1531,12 +1529,18 @@ an ordinary evaluated argument.
   A file can specify local variable values; Emacs uses these to create
 buffer-local bindings for those variables in the buffer visiting that
 file.  @xref{File variables, , Local Variables in Files, emacs, The
-GNU Emacs Manual}, for basic information about file local variables.
-This section describes the functions and variables that affect
-processing of file local variables.
+GNU Emacs Manual}, for basic information about file-local variables.
+This section describes the functions and variables that affect how
+file-local variables are processed.
+
+  If a file-local variable could specify an arbitrary function or Lisp
+expression that would be called later, visiting a file could take over
+your Emacs.  Emacs protects against this by automatically setting only
+those file-local variables whose specified values are known to be
+safe.  Other file-local variables are set only if the user agrees.
 
 @defopt enable-local-variables
-This variable controls whether to process file local variables.
+This variable controls whether to process file-local variables.
 The possible values are:
 
 @table @asis
@@ -1570,7 +1574,7 @@ variables, respectively.
 If the optional argument @var{mode-only} is non-@code{nil}, then all
 this function does is return @code{t} if the @w{@samp{-*-}} line or
 the local variables list specifies a mode and @code{nil} otherwise.
-It does not set the mode nor any other file local variable.
+It does not set the mode nor any other file-local variable.
 @end defun
 
 @defvar file-local-variables-alist
@@ -1593,21 +1597,16 @@ Emacs calls this hook immediately after it finishes applying
 file-local variables stored in @code{file-local-variables-alist}.
 @end defvar
 
-  If a file local variable could specify a function that would
-be called later, or an expression that would be executed later, simply
-visiting a file could take over your Emacs.  Emacs takes several
-measures to prevent this.
-
 @cindex safe local variable
   You can specify safe values for a variable with a
-@code{safe-local-variable} property.  The property has to be
-a function of one argument; any value is safe if the function
-returns non-@code{nil} given that value.  Many commonly encountered
-file variables standardly have @code{safe-local-variable} properties,
-including @code{fill-column}, @code{fill-prefix}, and
-@code{indent-tabs-mode}.  For boolean-valued variables that are safe,
-use @code{booleanp} as the property value.  Lambda expressions should
-be quoted so that @code{describe-variable} can display the predicate.
+@code{safe-local-variable} property.  The property has to be a
+function of one argument; any value is safe if the function returns
+non-@code{nil} given that value.  Many commonly-encountered file
+variables have @code{safe-local-variable} properties; these include
+@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}.
+For boolean-valued variables that are safe, use @code{booleanp} as the
+property value.  Lambda expressions should be quoted so that
+@code{describe-variable} can display the predicate.
 
 @defopt safe-local-variable-values
 This variable provides another way to mark some variable values as
@@ -1615,7 +1614,7 @@ safe.  It is a list of cons cells @code{(@var{var} . @var{val})},
 where @var{var} is a variable name and @var{val} is a value which is
 safe for that variable.
 
-When Emacs asks the user whether or not to obey a set of file local
+When Emacs asks the user whether or not to obey a set of file-local
 variable specifications, the user can choose to mark them as safe.
 Doing so adds those variable/value pairs to
 @code{safe-local-variable-values}, and saves it to the user's custom
@@ -1682,7 +1681,7 @@ such predicates (it's safe if any predicate succeeds), or @code{t}
 
   Text properties are also potential loopholes, since their values
 could include functions to call.  So Emacs discards all text
-properties from string values specified for file local variables.
+properties from string values specified for file-local variables.
 
 @node Directory Local Variables
 @section Directory Local Variables
@@ -1769,11 +1768,15 @@ is updated by @code{dir-locals-set-directory-class}.
   In addition to buffer-local variable bindings (@pxref{Buffer-Local
 Variables}), Emacs supports @dfn{frame-local} bindings.  A frame-local
 binding for a variable is in effect in a frame for which it was
-defined.  Note that you cannot have frame-local bindings for a
-variable that has a buffer-local binding.
+defined.
 
-  To define a frame-specific binding for a variable @var{var} in frame
-@var{frame}, set the @var{var} frame parameter for that frame:
+  In practice, frame-local variables have not proven very useful.
+Ordinary frame parameters are generally used instead (@pxref{Frame
+Parameters}).  The function @code{make-variable-frame-local}, which
+was used to define frame-local variables, has been deprecated since
+Emacs 22.2.  However, you can still define a frame-specific binding
+for a variable @var{var} in frame @var{frame}, by setting the
+@var{var} frame parameter for that frame:
 
 @lisp
   (modify-frame-parameters @var{frame} '((@var{var} . @var{value})))
@@ -1781,34 +1784,12 @@ variable that has a buffer-local binding.
 
 @noindent
 This causes the variable @var{var} to be bound to the specified
-@var{value} in the named @var{frame}.  @xref{Parameter Access,
-modify-frame-parameters}.
-
-@findex make-variable-frame-local@r{, deprecated}
-  Use of @code{make-variable-frame-local} for defining frame-local
-bindings is deprecated since Emacs 22.2.
-
-  To check the frame-specific values of such variables, use
-@code{frame-parameter} (@pxref{Parameter Access, frame-parameter}).
-
-@node Future Local Variables
-@section Possible Future Local Variables
-
-  We have considered the idea of bindings that are local to a category
-of frames---for example, all color frames, or all frames with dark
-backgrounds.  We have not implemented them because it is not clear that
-this feature is really useful.  You can get more or less the same
-results by adding a function to @code{after-make-frame-functions}, set up to
-define a particular frame parameter according to the appropriate
-conditions for each frame.
-
-  It would also be possible to implement window-local bindings.  We
-don't know of many situations where they would be useful, and it seems
-that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
-bindings offer a way to handle these situations more robustly.
-
-  If sufficient application is found for either of these two kinds of
-local bindings, we will provide it in a subsequent Emacs version.
+@var{value} in the named @var{frame}.  To check the frame-specific
+values of such variables, use @code{frame-parameter}.  @xref{Parameter
+Access}.
+
+  Note that you cannot have a frame-local binding for a variable that
+has a buffer-local binding.
 
 @node Variable Aliases
 @section Variable Aliases