diff lispref/variables.texi @ 21682:90da2489c498

*** empty log message ***

--- a/lispref/variables.texi	Mon Apr 20 17:37:53 1998 +0000
+++ b/lispref/variables.texi	Mon Apr 20 17:43:57 1998 +0000
@@ -38,6 +38,8 @@
 * Setting Variables::     Storing new values in variables.
 * Variable Scoping::      How Lisp chooses among local and global values.
 * Buffer-Local Variables::  Variable values in effect only in one buffer.
+* Frame-Local Variables::   Variable values in effect only in one frame.
+* Future Local Variables::  New kinds of local values we might add some day.
 @end menu
 
 @node Global Variables
@@ -73,7 +75,8 @@
 @noindent
 assuming the @code{setq} form shown above has already been executed.
 
-  If you do another @code{setq}, the new value replaces the old one:
+  If you do set the same variable again, the new value replaces the old
+one:
 
 @example
 @group
@@ -96,14 +99,13 @@
 @vindex t
 @kindex setting-constant
 
-  In Emacs Lisp, certain symbols normally evaluate to themselves.
-These include @code{nil} and @code{t}, as well as any symbol whose
-name starts with @samp{:}.
-
-  The symbols @code{nil} and @code{t} @emph{always} evaluate to
-themselves.  These symbols cannot be rebound, nor can their values be
-changed.  Any attempt to change the value of @code{nil} or @code{t}
-signals a @code{setting-constant} error.
+  In Emacs Lisp, certain symbols normally evaluate to themselves.  These
+include @code{nil} and @code{t}, as well as any symbol whose name starts
+with @samp{:}.  These symbols cannot be rebound, nor can their values be
+changed.  Any attempt to set or bind @code{nil} or @code{t} signals a
+@code{setting-constant} error.  The same is true for a symbol whose name
+starts with @samp{:}, except that you are allowed to set such symbol to
+itself.
 
 @example
 @group
@@ -116,6 +118,13 @@
 @end group
 @end example
 
+@tindex keyword-symbols-constant-flag
+@defvar keyword-symbols-constant-flag
+If this variable is @code{nil}, you are allowed to set and bind symbols
+whose names start with @samp{:} as you wish.  This is to make it
+possible to run old Lisp programs which do that.
+@end defvar
+
 @node Local Variables
 @section Local Variables
 @cindex binding local variables
@@ -125,7 +134,7 @@
 
   Global variables have values that last until explicitly superseded
 with new values.  Sometimes it is useful to create variable values that
-exist temporarily---only while within a certain part of the program.
+exist temporarily---only until a certain part of the program finishes.
 These values are called @dfn{local}, and the variables so used are
 called @dfn{local variables}.
 
@@ -143,7 +152,7 @@
 
   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
-previous local values that are shadowed.  To model this behavior, we
+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.
@@ -161,12 +170,12 @@
   A variable can have more than one local binding at a time (for
 example, if there are nested @code{let} forms that bind it).  In such a
 case, the most recently created local binding that still exists is the
-@dfn{current binding} of the variable.  (This is called @dfn{dynamic
-scoping}; see @ref{Variable Scoping}.)  If there are no local bindings,
-the variable's global binding is its current binding.  We also call the
-current binding the @dfn{most-local existing binding}, for emphasis.
-Ordinary evaluation of a symbol always returns the value of its current
-binding.
+@dfn{current binding} of the variable.  (This rule is called
+@dfn{dynamic scoping}; see @ref{Variable Scoping}.)  If there are no
+local bindings, the variable's global binding is its current binding.
+We sometimes call the current binding the @dfn{most-local existing
+binding}, for emphasis.  Ordinary evaluation of a symbol always returns
+the value of its current binding.
 
   The special forms @code{let} and @code{let*} exist to create
 local bindings.
@@ -289,8 +298,7 @@
 
 @example
 @group
-(makunbound 'x)      ; @r{Make the global value}
-                     ;   @r{of @code{x} void.}
+(makunbound 'x)      ; @r{Make the global value of @code{x} void.}
      @result{} x
 @end group
 @group
@@ -304,9 +312,9 @@
 local binding, since all the constructs that create local bindings
 create them with values.  In this case, the voidness lasts at most as
 long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous or global binding is reexposed
-as usual, and the variable is no longer void unless the newly reexposed
-binding was void all along.
+the construct that made it, the previous local or global binding is
+reexposed as usual, and the variable is no longer void unless the newly
+reexposed binding was void all along.
 
 @smallexample
 @group
@@ -439,9 +447,9 @@
 
 If the first character of @var{doc-string} is @samp{*}, it means that
 this variable is considered a user option.  This lets users set the
-variable conventiently using the commands @code{set-variable} and
+variable conveniently using the commands @code{set-variable} and
 @code{edit-options}.  However, it is better to use @code{defcustom}
-instead of @code{defvar}, for user option variables, to specify
+instead of @code{defvar} for user option variables, so you can specify
 customization information.  @xref{Customization}.
 
 Here are some examples.  This form defines @code{foo} but does not
@@ -580,7 +588,7 @@
 @noindent
 This method has several benefits.  First, if the user quits while
 loading the file, the variable is either still uninitialized or
-initialized properly, never in-between.  If it is uninitialized,
+initialized properly, never in-between.  If it is still uninitialized,
 reloading the file will initialize it properly.  Second, reloading the
 file once the variable is initialized will not alter it; that is
 important if the user has run hooks to alter part of the contents (such
@@ -620,11 +628,11 @@
 @end example
 
 @noindent
-This code sets the variable, then alters it, but only if the variable
-had been @code{ni}.  If the user quits just after the @code{setq}, that
-leaves the variable neither correctly initialized nor void nor
-@code{nil}.  Once that happens, reloading the file will not initialize
-the variable; it will remain incomplete.
+This code sets the variable, then alters it, but it does so in more than
+one step.  If the user quits just after the @code{setq}, that leaves the
+variable neither correctly initialized nor void nor @code{nil}.  Once
+that happens, reloading the file will not initialize the variable; it
+will remain incomplete.
 
 @node Accessing Variables
 @section Accessing Variable Values
@@ -673,8 +681,8 @@
 @end group
 @end example
 
-A @code{void-variable} error is signaled if @var{symbol} has neither a
-local binding nor a global one.
+A @code{void-variable} error is signaled if the current binding of
+@var{symbol} is void.
 @end defun
 
 @node Setting Variables
@@ -803,6 +811,7 @@
 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
 is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
 the argument yourself if that is what you want.
+@end defun
 
 Here's a scenario showing how to use @code{add-to-list}:
 
@@ -819,7 +828,6 @@
 foo                       ;; @r{@code{foo} was changed.}
      @result{} (c a b)
 @end example
-@end defun
 
   An equivalent expression for @code{(add-to-list '@var{var}
 @var{value})} is this:
@@ -979,10 +987,11 @@
 works) may help you understand dynamic binding.  This technique is
 called @dfn{deep binding} and was used in early Lisp systems.
 
-  Suppose there is a stack of bindings: variable-value pairs.  At entry
-to a function or to a @code{let} form, we can push bindings onto the stack
-for the arguments or local variables created there.  We can pop those
-bindings from the stack at exit from the binding construct.
+  Suppose there is a stack of bindings, which are variable-value pairs.
+At entry to a function or to a @code{let} form, we can push bindings
+onto the stack for the arguments or local variables created there.  We
+can pop those bindings from the stack at exit from the binding
+construct.
 
   We can find the value of a variable by searching the stack from top to
 bottom for a binding for that variable; the value from that binding is
@@ -1052,18 +1061,22 @@
 @cindex buffer-local variables
 
   Global and local variable bindings are found in most programming
-languages in one form or another.  Emacs also supports another, unusual
-kind of variable binding: @dfn{buffer-local} bindings, which apply only
-to one buffer.  Emacs Lisp is meant for programming editing commands,
-and having different values for a variable in different buffers is an
-important customization method.  (A few variables have bindings that
-are local to a given X terminal; see @ref{Multiple Displays}.)
+languages in one form or another.  Emacs also supports additional,
+unusual kinds of variable binding: @dfn{buffer-local} bindings, which
+apply only in one buffer, and frame-local bindings, which apply only in
+one frame.  Having different values for a variable in different buffers
+and/or frames is an important customization method.
+
+  This section describes buffer-local bindings; for frame-local
+bindings, see the following section, @ref{Frame-Local Variables}.  (A few
+variables have bindings that are local to a X terminal; see
+@ref{Multiple Displays}.)
 
 @menu
 * Intro to Buffer-Local::      Introduction and concepts.
 * Creating Buffer-Local::      Creating and destroying buffer-local bindings.
 * Default Value::              The default value is seen in buffers
-                                 that don't have their own local values.
+                                 that don't have their own buffer-local values.
 @end menu
 
 @node Intro to Buffer-Local
@@ -1082,22 +1095,25 @@
 
   A variable can have buffer-local bindings in some buffers but not in
 other buffers.  The default binding is shared by all the buffers that
-don't have their own bindings for the variable.  If you set the variable
-in a buffer that does not have a buffer-local binding for it, this sets
-the default binding, so the new value is visible in all the buffers that
-see the default binding.
+don't have their own bindings for the variable.  (This includes all
+newly created buffers.)  If you set the variable in a buffer that does
+not have a buffer-local binding for it, this sets the default binding
+(assuming there are no frame-local bindings to complicate the matter),
+so the new value is visible in all the buffers that see the default
+binding.
 
   The most common use of buffer-local bindings is for major modes to change
 variables that control the behavior of commands.  For example, C mode and
 Lisp mode both set the variable @code{paragraph-start} to specify that only
 blank lines separate paragraphs.  They do this by making the variable
 buffer-local in the buffer that is being put into C mode or Lisp mode, and
-then setting it to the new value for that mode.
+then setting it to the new value for that mode.  @xref{Major Modes}.
 
   The usual way to make a buffer-local binding is with
-@code{make-local-variable}, which is what major mode commands use.  This
-affects just the current buffer; all other buffers (including those yet to
-be created) continue to share the default value.
+@code{make-local-variable}, which is what major mode commands typically
+use.  This affects just the current buffer; all other buffers (including
+those yet to be created) will continue to share the default value unless
+they are explicitly given their own buffer-local bindings.
 
 @cindex automatically buffer-local
   A more powerful operation is to mark the variable as
@@ -1107,11 +1123,11 @@
 precisely, the effect is that setting the variable automatically makes
 the variable local to the current buffer if it is not already so.  All
 buffers start out by sharing the default value of the variable as usual,
-but any @code{setq} creates a buffer-local binding for the current
+but setting the variable creates a buffer-local binding for the current
 buffer.  The new value is stored in the buffer-local binding, leaving
-the default binding untouched.  The default value can no longer be
-changed with @code{setq} in this buffer; you need to use
-@code{setq-default} to do that.
+the default binding untouched.  This means that the default value cannot
+be changed with @code{setq} in any buffer; the only way to change it is
+with @code{setq-default}.
 
   @strong{Warning:} When a variable has buffer-local values in one or
 more buffers, you can get Emacs very confused by binding the variable
@@ -1161,7 +1177,8 @@
 buffer-local binding of buffer @samp{b}.
 
   When a file specifies local variable values, these become buffer-local
-values when you visit the file.  @xref{Auto Major Mode}.
+values when you visit the file.  @xref{File Variables,,, emacs, The
+GNU Emacs Manual}.
 
 @node Creating Buffer-Local
 @subsection Creating and Deleting Buffer-Local Bindings
@@ -1209,9 +1226,10 @@
 @end example
 
 Making a variable buffer-local within a @code{let}-binding for that
-variable does not work.  This is because @code{let} does not distinguish
-between different kinds of bindings; it knows only which variable the
-binding was made for.
+variable does not work reliably, unless the buffer in which you do this
+is not current either on entry to or exit from the @code{let}.  This is
+because @code{let} does not distinguish between different kinds of
+bindings; it knows only which variable the binding was made for.
 
 If the variable is terminal-local, this function signals an error.  Such
 variables cannot have buffer-local bindings as well.  @xref{Multiple
@@ -1226,16 +1244,24 @@
 buffer-local, so that any subsequent attempt to set it will make it
 local to the current buffer at the time.
 
+A peculiar wrinkle of this feature is that binding the variable (with
+@code{let} or other binding constructs) does not create a buffer-local
+binding for it.  Only setting the variable (with @code{set} or
+@code{setq}) does so.
+
 The value returned is @var{variable}.
 
-@strong{Note:} It is a mistake to use @code{make-variable-buffer-local}
-for user-option variables, simply because users @emph{might} want to
-customize them differently in different buffers.  Users can make any
-variable local, when they wish to.
+@strong{Warning:} Don't assume that you should use
+@code{make-variable-buffer-local} for user-option variables, simply
+because users @emph{might} want to customize them differently in
+different buffers.  Users can make any variable local, when they wish
+to.  It is better to leave the choice to them.
 
-The main use of @code{make-variable-buffer-local} is when a variable is
-used for internal purposes, and the Lisp program depends on having
-separate values in separate buffers.
+The time to use @code{make-variable-buffer-local} is when it is crucial
+that no two buffers ever share the same binding.  For example, when a
+variable is used for internal purposes in a Lisp program which depends
+on having separate values in separate buffers, then using
+@code{make-variable-buffer-local} can be the best solution.
 @end deffn
 
 @defun local-variable-p variable &optional buffer
@@ -1246,11 +1272,11 @@
 
 @defun buffer-local-variables &optional buffer
 This function returns a list describing the buffer-local variables in
-buffer @var{buffer}.  It returns an association list (@pxref{Association
-Lists}) in which each association contains one buffer-local variable and
-its value.  When a buffer-local variable is void in @var{buffer}, then
-it appears directly in the resulting list.  If @var{buffer} is omitted,
-the current buffer is used.
+buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
+used.)  It returns an association list (@pxref{Association Lists}) in
+which each element contains one buffer-local variable and its value.
+However, when a variable's buffer-local binding in @var{buffer} is void,
+then the variable appears directly in the resulting list.
 
 @example
 @group
@@ -1309,7 +1335,7 @@
 of @code{fundamental-mode-abbrev-table}.
 
 The very first thing this function does is run the normal hook
-@code{change-major-mode-hook} (@pxref{Major Mode Conventions}).
+@code{change-major-mode-hook} (see below).
 
 Every major mode command begins by calling this function, which has the
 effect of switching to Fundamental mode and erasing most of the effects
@@ -1319,6 +1345,15 @@
 @code{kill-all-local-variables} returns @code{nil}.
 @end defun
 
+@defvar change-major-mode-hook
+The function @code{kill-all-local-variables} runs this normal hook
+before it does anything else.  This gives major modes a way to arrange
+for something special to be done if the user switches to a different
+major mode.  For best results, make this variable buffer-local, so that
+it will disappear after doing its job and will not interfere with the
+subsequent major mode.  @xref{Hooks}.
+@end defvar
+
 @c Emacs 19 feature
 @cindex permanent local variable
 A buffer-local variable is @dfn{permanent} if the variable name (a
@@ -1332,7 +1367,8 @@
 
   The global value of a variable with buffer-local bindings is also
 called the @dfn{default} value, because it is the value that is in
-effect except when specifically overridden.
+effect whenever neither the current buffer nor the selected frame has
+its own binding for the variable.
 
   The functions @code{default-value} and @code{setq-default} access and
 change a variable's default value regardless of whether the current
@@ -1345,13 +1381,13 @@
 @c Emacs 19 feature
   The special forms @code{defvar} and @code{defconst} also set the
 default value (if they set the variable at all), rather than any
-buffer-local value.
+buffer-local or frame-local value.
 
 @defun default-value symbol
 This function returns @var{symbol}'s default value.  This is the value
-that is seen in buffers that do not have their own values for this
-variable.  If @var{symbol} is not buffer-local, this is equivalent to
-@code{symbol-value} (@pxref{Accessing Variables}).
+that is seen in buffers and frames that do not have their own values for
+this variable.  If @var{symbol} is not buffer-local, this is equivalent
+to @code{symbol-value} (@pxref{Accessing Variables}).
 @end defun
 
 @c Emacs 19 feature
@@ -1379,49 +1415,49 @@
 @example
 @group
 ;; @r{In buffer @samp{foo}:}
-(make-local-variable 'local)
-     @result{} local
+(make-local-variable 'buffer-local)
+     @result{} buffer-local
 @end group
 @group
-(setq local 'value-in-foo)
+(setq buffer-local 'value-in-foo)
      @result{} value-in-foo
 @end group
 @group
-(setq-default local 'new-default)
+(setq-default buffer-local 'new-default)
      @result{} new-default
 @end group
 @group
-local
+buffer-local
      @result{} value-in-foo
 @end group
 @group
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} new-default
 @end group
 
 @group
 ;; @r{In (the new) buffer @samp{bar}:}
-local
+buffer-local
      @result{} new-default
 @end group
 @group
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} new-default
 @end group
 @group
-(setq local 'another-default)
+(setq buffer-local 'another-default)
      @result{} another-default
 @end group
 @group
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} another-default
 @end group
 
 @group
 ;; @r{Back in buffer @samp{foo}:}
-local
+buffer-local
      @result{} value-in-foo
-(default-value 'local)
+(default-value 'buffer-local)
      @result{} another-default
 @end group
 @end example
@@ -1442,3 +1478,123 @@
 @end group
 @end example
 @end defun
+
+@node Frame-Local Variables
+@section Frame-Local Variables
+
+  Just as variables can have buffer-local bindings, they can also have
+frame-local bindings.  These bindings belong to one frame, and are in
+effect when that frame is selected.  Frame-local bindings are actually
+frame parameters: you create a frame-local binding in a specific frame
+by calling @code{modify-frame-parameters} and specifying the variable
+name as the parameter name.
+
+  To enable frame-local bindings for a certain variable, call the function
+@code{make-variable-frame-local}.
+
+@defun make-variable-frame-local variable
+Enable the use of frame-local bindings for @var{variable}.  This does
+not in itself create any frame-local bindings for the variable; however,
+if some frame already has a value for @var{variable} as a frame
+parameter, that value automatically becomes a frame-local binding.
+
+If the variable is terminal-local, this function signals an error.  Such
+variables cannot have buffer-local bindings as well.  @xref{Multiple
+Displays}.  A few variables that are implemented specially in Emacs
+can be (and usually are) buffer-local, but can never be frame-local.
+@end defun
+
+  Buffer-local bindings take precedence over frame-local bindings.  Thus,
+consider a variable @code{foo}: if the current buffer has a buffer-local
+binding for @code{foo}, that binding is active; otherwise, if the
+selected frame has a frame-local binding for @code{foo}, that binding is
+active; otherwise, the default binding of @code{foo} is active.
+
+  Here is an example.  First we prepare a few bindings for @code{foo}:
+
+@example
+(setq f1 (selected-frame))
+(make-variable-frame-local 'foo)
+
+;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
+(set-buffer (get-buffer-create "b1"))
+(make-local-variable 'foo)
+(setq foo '(b 1))
+
+;; @r{Make a frame-local binding for @code{foo} in a new frame.}
+;; @r{Store that frame in @code{f2}.}
+(setq f2 (make-frame))
+(modify-frame-parameters f2 '((foo . (f 2))))
+@end example
+
+  Now we examine @code{foo} in various contexts.  Whenever the
+buffer @samp{b1} is current, its buffer-local binding is in effect,
+regardless of the selected frame:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer-create "b1"))
+foo
+     @result{} (b 1)
+
+(select-frame f2)
+(set-buffer (get-buffer-create "b1"))
+foo
+     @result{} (b 1)
+@end example
+
+@noindent
+Otherwise, the frame gets a chance to provide the binding; when frame
+@code{f2} is selected, its frame-local binding is in effect:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+foo
+     @result{} (f 2)
+@end example
+
+@noindent
+When neither the current buffer nor the selected frame provides
+a binding, the default binding is used:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer "*scratch*"))
+foo
+     @result{} nil
+@end example
+
+@noindent
+When the active binding of a variable is a frame-local binding, setting
+the variable changes that binding.  You can observe the result with
+@code{frame-parameters}:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+(setq foo 'nobody)
+(assq 'foo (frame-parameters f2))
+     @result{} (foo . nobody)
+@end example
+
+@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-hook}, 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.
+
+