* 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.
-* Variable Aliases:: Variables that are aliases for other variables.
* File Local Variables:: Handling local variable lists in files.
+* 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.
@end menu
If sufficient application is found for either of these two kinds of
local bindings, we will provide it in a subsequent Emacs version.
-@node Variable Aliases
-@section Variable Aliases
-
- It is sometimes useful to make two variables synonyms, so that both
-variables always have the same value, and changing either one also
-changes the other. Whenever you change the name of a
-variable---either because you realize its old name was not well
-chosen, or because its meaning has partly changed---it can be useful
-to keep the old name as an @emph{alias} of the new one for
-compatibility. You can do this with @code{defvaralias}.
-
-@defun defvaralias alias-var base-var &optional docstring
-This function defines the symbol @var{alias-var} as a variable alias
-for symbol @var{base-var}. This means that retrieving the value of
-@var{alias-var} returns the value of @var{base-var}, and changing the
-value of @var{alias-var} changes the value of @var{base-var}.
-
-If the @var{docstring} argument is non-@code{nil}, it specifies the
-documentation for @var{alias-var}; otherwise, the alias gets the same
-documentation as @var{base-var} has, if any, unless @var{base-var} is
-itself an alias, in which case @var{alias-var} gets the documentation
-of the variable at the end of the chain of aliases.
-
-This function returns @var{base-var}.
-@end defun
-
-@defun indirect-variable variable
-This function returns the variable at the end of the chain of aliases
-of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is
-not defined as an alias, the function returns @var{variable}.
-
-This function signals a @code{cyclic-variable-indirection} error if
-there is a loop in the chain of symbols.
-@end defun
-
-@example
-(defvaralias 'foo 'bar)
-(indirect-variable 'foo)
- @result{} bar
-(indirect-variable 'bar)
- @result{} bar
-(setq bar 2)
-bar
- @result{} 2
-@group
-foo
- @result{} 2
-@end group
-(setq foo 0)
-bar
- @result{} 0
-foo
- @result{} 0
-@end example
-
@node File Local Variables
@section File Local Variables
This section describes the functions and variables that affect
-processing of local variables lists in files. @xref{File variables, ,
+processing of file local variables. @xref{File variables, ,
Local Variables in Files, emacs, The GNU Emacs Manual}, for basic
information about file local variables.
@defopt enable-local-variables
-This variable controls whether to process file local variables lists. A
-value of @code{t} means process the local variables lists
-unconditionally; @code{nil} means ignore them; anything else means ask
-the user what to do for each file. The default value is @code{t}.
+This variable controls whether to process file local variables. A
+value of @code{t} means process them unconditionally; @code{nil} means
+ignore them; anything else means ask the user what to do for each
+file. The default value is @code{t}.
@end defopt
@defun hack-local-variables &optional mode-only
@code{enable-local-variables} has its effect here. However, this
function does not look for the @samp{mode:} local variable in the
@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking
-@code{enable-local-variables} into account.
+@code{enable-local-variables} into account (@pxref{Auto Major Mode}).
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
-specifies a mode and @code{nil} otherwise. It does not set the mode
-nor any other file local variable. It does not check whether a mode
-is specified in the local variables list at the end of the file.
+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.
@end defun
- If a file local variable list could specify a function that would
+ 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. To prevent this, Emacs
-takes care not to allow local variable lists to set such variables.
+takes care not to allow to set such file local variables.
For one thing, any variable whose name ends in @samp{-command},
@samp{-frame-alist}, @samp{-function}, @samp{-functions},
@samp{-hook}, @samp{-hooks}, @samp{-form}, @samp{-forms}, @samp{-map},
@samp{-map-alist}, @samp{-mode-alist}, @samp{-program}, or
-@samp{-predicate} cannot be set in a local variable list. In general,
+@samp{-predicate} cannot be given a file local value. In general,
you should use such a name whenever it is appropriate for the
variable's meaning. The variables @samp{font-lock-keywords},
@samp{font-lock-keywords-[0-9]}, and
-@samp{font-lock-syntactic-keywords} cannot be set in a local variable
-list, either. These rules can be overridden by giving the variable's
+@samp{font-lock-syntactic-keywords} cannot be given file local values either.
+These rules can be overridden by giving the variable's
name a non-@code{nil} @code{safe-local-variable} property. If one
gives it a @code{safe-local-variable} property of @code{t}, then one
can give the variable any file local value. One can also give any
variables listed in @code{ignored-local-variables}:
@defvar ignored-local-variables
-This variable holds a list of variables that should not be
-set by a file's local variables list. Any value specified
-for one of these variables is ignored.
+This variable holds a list of variables that should not be given local
+values by files. Any value specified for one of these variables is
+ignored.
@end defvar
@defun risky-local-variable-p sym &optional val
normally asks for confirmation before handling it.
@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in local variables
+This variable controls processing of @samp{Eval:} in @samp{-*-} lines
+or local variables
lists in files being visited. A value of @code{t} means process them
unconditionally; @code{nil} means ignore them; anything else means ask
the user what to do for each file. The default value is @code{maybe}.
Text properties are also potential loopholes, since their values
could include functions to call. So Emacs discards all text
-properties from string values specified in a file's local variables
-list.
+properties from string values specified for file local variables.
+
+@node Variable Aliases
+@section Variable Aliases
+
+ It is sometimes useful to make two variables synonyms, so that both
+variables always have the same value, and changing either one also
+changes the other. Whenever you change the name of a
+variable---either because you realize its old name was not well
+chosen, or because its meaning has partly changed---it can be useful
+to keep the old name as an @emph{alias} of the new one for
+compatibility. You can do this with @code{defvaralias}.
+
+@defun defvaralias alias-var base-var &optional docstring
+This function defines the symbol @var{alias-var} as a variable alias
+for symbol @var{base-var}. This means that retrieving the value of
+@var{alias-var} returns the value of @var{base-var}, and changing the
+value of @var{alias-var} changes the value of @var{base-var}.
+
+If the @var{docstring} argument is non-@code{nil}, it specifies the
+documentation for @var{alias-var}; otherwise, the alias gets the same
+documentation as @var{base-var} has, if any, unless @var{base-var} is
+itself an alias, in which case @var{alias-var} gets the documentation
+of the variable at the end of the chain of aliases.
+
+This function returns @var{base-var}.
+@end defun
+
+ Variable aliases are convenient for replacing an old name for a
+variable with a new name. @code{make-obsolete-variable} declares that
+the old name is obsolete and therefore that it may be removed at some
+stage in the future.
+
+@defun make-obsolete-variable variable new &optional when
+This function makes the byte-compiler warn that the variable
+@var{variable} is obsolete. If @var{new} is a symbol, it is the
+variable's new name; then the warning message says to use @var{new}
+instead of @var{variable}. If @var{new} is a string, this is the
+message and there is no replacement variable.
+
+If provided, @var{when} should be a string indicating when the
+variable was first made obsolete---for example, a date or a release
+number.
+@end defun
+
+ You can make two variables synonyms and declare one obsolete at the
+same time using the macro @code{define-obsolete-variable-alias}.
+
+@defmac define-obsolete-variable-alias variable new &optional when docstring
+This macro marks the variable @var{variable} as obsolete and also
+makes it an alias for the variable @var{new}. A typical call has the form:
+
+@example
+(define-obsolete-variable-alias 'old-var 'new-var "22.1" "Doc.")
+@end example
+
+@noindent
+which is equivalent to the following two lines of code:
+
+@example
+(defvaralias 'oldvar 'newvar "Doc.")
+(make-obsolete-variable 'old-var 'new-var "22.1")
+@end example
+@end defmac
+
+@defun indirect-variable variable
+This function returns the variable at the end of the chain of aliases
+of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is
+not defined as an alias, the function returns @var{variable}.
+
+This function signals a @code{cyclic-variable-indirection} error if
+there is a loop in the chain of symbols.
+@end defun
+
+@example
+(defvaralias 'foo 'bar)
+(indirect-variable 'foo)
+ @result{} bar
+(indirect-variable 'bar)
+ @result{} bar
+(setq bar 2)
+bar
+ @result{} 2
+@group
+foo
+ @result{} 2
+@end group
+(setq foo 0)
+bar
+ @result{} 0
+foo
+ @result{} 0
+@end example
@node Variables with Restricted Values
@section Variables with Restricted Values