comparison lispref/variables.texi @ 83311:c016d82bf02b

Merged from [e-mail]--gnu-2005 (patch 423-434) Patches applied: * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-423 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-424 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-425 Remove "-face" suffix from gnus faces * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-426 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-427 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-428 Remove "-face" suffix from MH-E faces * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-429 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-430 Remove "-face" suffix from cc-mode faces * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-431 Remove "-face" suffix from eshell faces * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-432 Remove "-face" suffix from ediff faces * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-433 Update from CVS * [e-mail]--gnu-2005/emacs--cvs-trunk--0--patch-434 Update from CVS git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-351

83310:e58cb448e07c

  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 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 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 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
symbol, including the above, a @code{safe-local-variable} property
that is a function taking exactly one argument.  In that case, giving
a variable with that name a file local value is only allowed if the
function returns non-@code{nil} when called with that value as
argument.

  In addition, any variable whose name has a non-@code{nil}
@code{risky-local-variable} property is also ignored.  So are all
variables listed in @code{ignored-local-variables}:

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

83311:c016d82bf02b

  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 to set such file local variables.

  For one thing, any variable whose name ends in any of
@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 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} followed by a
digit, and @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 symbol, including the above, a @code{safe-local-variable}
property that is a function taking exactly one argument.  In that
case, giving a variable with that name a file local value is only
allowed if the function returns non-@code{nil} when called with that
value as argument.

  In addition, any variable whose name has a non-@code{nil}
@code{risky-local-variable} property is also ignored.  So are all
variables listed in @code{ignored-local-variables}:

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 new-alias base-variable &optional docstring
This function defines the symbol @var{new-alias} as a variable alias
for symbol @var{base-variable}. This means that retrieving the value of
@var{new-alias} returns the value of @var{base-variable}, and changing the
value of @var{new-alias} changes the value of @var{base-variable}.

If the @var{docstring} argument is non-@code{nil}, it specifies the
documentation for @var{new-alias}; otherwise, the alias gets the same
documentation as @var{base-variable} has, if any, unless
@var{base-variable} is itself an alias, in which case @var{new-alias} gets
the documentation of the variable at the end of the chain of aliases.

This function returns @var{base-variable}.
@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 obsolete-name current-name &optional when
This function makes the byte-compiler warn that the variable
@var{obsolete-name} is obsolete.  If @var{current-name} is a symbol, it is
the variable's new name; then the warning message says to use
@var{current-name} instead of @var{obsolete-name}.  If @var{current-name}
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 obsolete-name current-name &optional when docstring
This macro marks the variable @var{obsolete-name} as obsolete and also
makes it an alias for the variable @var{current-name}.  It is
equivalent to the following:

@example
(defvaralias @var{obsolete-name} @var{current-name} @var{docstring})
(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when})
@end example
@end defmac

@defun indirect-variable variable
This function returns the variable at the end of the chain of aliases