X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/26236f6d9c903a219fb1a1000f7fce17cc2bf5c3..53ba8be73bc3546c067af32feeb377334d0fe872:/lispref/variables.texi

diff --git a/lispref/variables.texi b/lispref/variables.texi
index 097961e98b..f3e81c3ddd 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
-@c   Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2002,
+@c   2003, 2004, 2005, 2006 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/variables
 @node Variables, Functions, Control Structures, Top
@@ -41,8 +41,10 @@ variable.
 * 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
 
 @node Global Variables
@@ -198,18 +200,18 @@ is omitted, @code{nil} is used.
 
 All of the @var{value-form}s in @var{bindings} are evaluated in the
 order they appear and @emph{before} binding any of the symbols to them.
-Here is an example of this: @code{Z} is bound to the old value of
-@code{Y}, which is 2, not the new value of @code{Y}, which is 1.
+Here is an example of this: @code{z} is bound to the old value of
+@code{y}, which is 2, not the new value of @code{y}, which is 1.
 
 @example
 @group
-(setq Y 2)
+(setq y 2)
      @result{} 2
 @end group
 @group
-(let ((Y 1) 
-      (Z Y))
-  (list Y Z))
+(let ((y 1)
+      (z y))
+  (list y z))
      @result{} (1 2)
 @end group
 @end example
@@ -225,13 +227,13 @@ form.  Compare the following example with the example above for
 
 @example
 @group
-(setq Y 2)
+(setq y 2)
      @result{} 2
 @end group
 @group
-(let* ((Y 1)
-       (Z Y))    ; @r{Use the just-established value of @code{Y}.}
-  (list Y Z))
+(let* ((y 1)
+       (z y))    ; @r{Use the just-established value of @code{y}.}
+  (list y z))
      @result{} (1 1)
 @end group
 @end example
@@ -259,18 +261,20 @@ they are localized depending on ``where'' you are in Emacs, rather than
 localized in time.
 
 @defvar max-specpdl-size
+@anchor{Definition of max-specpdl-size}
 @cindex variable limit error
 @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{Nonlocal Exits})
-that are allowed before signaling an error (with data @code{"Variable
-binding depth exceeds max-specpdl-size"}).
+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
+max-specpdl-size"}).
 
 This limit, with the associated error when it is exceeded, is one way
 that Lisp avoids infinite recursion on an ill-defined function.
 @code{max-lisp-eval-depth} provides another limit on depth of nesting.
-@xref{Eval}.
+@xref{Definition of max-lisp-eval-depth,, Eval}.
 
 The default value is 600.  Entry to the Lisp debugger increases the
 value, if there is little room left, to make sure the debugger itself
@@ -518,7 +522,7 @@ The @code{defvar} form returns @var{symbol}, but it is normally used
 at top level in a file where its value does not matter.
 @end defspec
 
-@defspec defconst symbol [value [doc-string]]
+@defspec defconst symbol value [doc-string]
 This special form defines @var{symbol} as a value and initializes it.
 It informs a person reading your code that @var{symbol} has a standard
 global value, established here, that should not be changed by the user
@@ -526,10 +530,10 @@ or by other programs.  Note that @var{symbol} is not evaluated; the
 symbol to be defined must appear explicitly in the @code{defconst}.
 
 @code{defconst} always evaluates @var{value}, and sets the value of
-@var{symbol} to the result if @var{value} is given.  If @var{symbol}
-does have a buffer-local binding in the current buffer, @code{defconst}
-sets the default value, not the buffer-local value.  (But you should not
-be making buffer-local bindings for a symbol that is defined with
+@var{symbol} to the result.  If @var{symbol} does have a buffer-local
+binding in the current buffer, @code{defconst} sets the default value,
+not the buffer-local value.  (But you should not be making
+buffer-local bindings for a symbol that is defined with
 @code{defconst}.)
 
 Here, @code{pi} is a constant that presumably ought not to be changed
@@ -564,7 +568,7 @@ though being declared using @code{defcustom}@footnote{They may also be
 declared equivalently in @file{cus-start.el}.} or by the first character
 of their @code{variable-documentation} property.  If the property exists
 and is a string, and its first character is @samp{*}, then the variable
-is a user option.
+is a user option.  Aliases of user options are also user options.
 @end defun
 
 @kindex variable-interactive
@@ -576,11 +580,12 @@ this feature is largely obsoleted by @code{defcustom}
 (@pxref{Customization}).
 
   @strong{Warning:} If the @code{defconst} and @code{defvar} special
-forms are used while the variable has a local binding, they set the
-local binding's value; the global binding is not changed.  This is not
-what you usually want.  To prevent it, use these special forms at top
-level in a file, where normally no local binding is in effect, and make
-sure to load the file before making a local binding for the variable.
+forms are used while the variable has a local binding (made with
+@code{let}, or a function argument), they set the local-binding's
+value; the top-level binding is not changed.  This is not what you
+usually want.  To prevent it, use these special forms at top level in
+a file, where normally no local binding is in effect, and make sure to
+load the file before making a local binding for the variable.
 
 @node Tips for Defining
 @section Tips for Defining Variables Robustly
@@ -767,7 +772,7 @@ The value of the @code{setq} form is the value of the last @var{form}.
 x                   ; @r{@code{x} now has a global value.}
      @result{} 3
 @group
-(let ((x 5)) 
+(let ((x 5))
   (setq x 6)        ; @r{The local binding of @code{x} is set.}
   x)
      @result{} 6
@@ -784,7 +789,7 @@ second @var{symbol} is set, and so on:
 @group
 (setq x 10          ; @r{Notice that @code{x} is set before}
       y (1+ x))     ;   @r{the value of @code{y} is computed.}
-     @result{} 11             
+     @result{} 11
 @end group
 @end example
 @end defspec
@@ -857,11 +862,16 @@ always affects the most local existing binding.
   One other function for setting a variable is designed to add
 an element to a list if it is not already present in the list.
 
-@defun add-to-list symbol element
+@defun add-to-list symbol element &optional append
 This function sets the variable @var{symbol} by consing @var{element}
 onto the old value, if @var{element} is not already a member of that
 value.  It returns the resulting list, whether updated or not.  The
 value of @var{symbol} had better be a list already before the call.
+Membership is tested using @code{equal}.
+
+Normally, if @var{element} is added, it is added to the front of
+@var{symbol}, but if the optional argument @var{append} is
+non-@code{nil}, it is added at the end.
 
 The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
 is an ordinary function, like @code{set} and unlike @code{setq}.  Quote
@@ -892,6 +902,62 @@ foo                       ;; @r{@code{foo} was changed.}
     (setq @var{var} (cons @var{value} @var{var})))
 @end example
 
+@defun add-to-ordered-list symbol element &optional order
+This function sets the variable @var{symbol} by inserting
+@var{element} into the old value, which must be a list, at the
+position specified by @var{order}.  If @var{element} is already a
+member of the list, its position in the list is adjusted according
+to @var{order}.  Membership is tested using @code{eq}.
+This function returns the resulting list, whether updated or not.
+
+The @var{order} is typically a number (integer or float), and the
+elements of the list are sorted in non-decreasing numerical order.
+
+@var{order} may also be omitted or @code{nil}.  Then the numeric order
+of @var{element} stays unchanged if it already has one; otherwise,
+@var{element} has no numeric order.  Elements without a numeric list
+order are placed at the end of the list, in no particular order.
+
+Any other value for @var{order} removes the numeric order of @var{element}
+if it already has one; otherwise, it is equivalent to @code{nil}.
+
+The argument @var{symbol} is not implicitly quoted;
+@code{add-to-ordered-list} is an ordinary function, like @code{set}
+and unlike @code{setq}.  Quote the argument yourself if that is what
+you want.
+
+The ordering information is stored in a hash table on @var{symbol}'s
+@code{list-order} property.
+@end defun
+
+Here's a scenario showing how to use @code{add-to-ordered-list}:
+
+@example
+(setq foo '())
+     @result{} nil
+
+(add-to-ordered-list 'foo 'a 1)     ;; @r{Add @code{a}.}
+     @result{} (a)
+
+(add-to-ordered-list 'foo 'c 3)     ;; @r{Add @code{c}.}
+     @result{} (a c)
+
+(add-to-ordered-list 'foo 'b 2)     ;; @r{Add @code{b}.}
+     @result{} (a b c)
+
+(add-to-ordered-list 'foo 'b 4)     ;; @r{Move @code{b}.}
+     @result{} (a c b)
+
+(add-to-ordered-list 'foo 'd)       ;; @r{Append @code{d}.}
+     @result{} (a c b d)
+
+(add-to-ordered-list 'foo 'e)       ;; @r{Add @code{e}}.
+     @result{} (a c b e d)
+
+foo                       ;; @r{@code{foo} was changed.}
+     @result{} (a c b e d)
+@end example
+
 @node Variable Scoping
 @section Scoping Rules for Variable Bindings
 
@@ -903,6 +969,7 @@ the others.
 @cindex scope
 @cindex extent
 @cindex dynamic scoping
+@cindex lexical scoping
   Local bindings in Emacs Lisp have @dfn{indefinite scope} and
 @dfn{dynamic extent}.  @dfn{Scope} refers to @emph{where} textually in
 the source code the binding can be accessed.  ``Indefinite scope'' means
@@ -1184,47 +1251,37 @@ 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
-with @code{let}, changing to a different current buffer in which a
-different binding is in effect, and then exiting the @code{let}.  This
-can scramble the values of the buffer-local and default bindings.
-
-  To preserve your sanity, avoid using a variable in that way.  If you
-use @code{save-excursion} around each piece of code that changes to a
-different current buffer, you will not have this problem
-(@pxref{Excursions}).  Here is an example of what to avoid:
+  @strong{Warning:} When a variable has buffer-local or frame-local
+bindings in one or more buffers, @code{let} rebinds the binding that's
+currently in effect.  For instance, if the current buffer has a
+buffer-local value, @code{let} temporarily rebinds that.  If no
+buffer-local or frame-local bindings are in effect, @code{let} rebinds
+the default value.  If inside the @code{let} you then change to a
+different current buffer in which a different binding is in effect,
+you won't see the @code{let} binding any more.  And if you exit the
+@code{let} while still in the other buffer, you won't see the
+unbinding occur (though it will occur properly).  Here is an example
+to illustrate:
 
 @example
 @group
-(setq foo 'b)
+(setq foo 'g)
 (set-buffer "a")
 (make-local-variable 'foo)
 @end group
 (setq foo 'a)
 (let ((foo 'temp))
+  ;; foo @result{} 'temp  ; @r{let binding in buffer @samp{a}}
   (set-buffer "b")
+  ;; foo @result{} 'g     ; @r{the global value since foo is not local in @samp{b}}
   @var{body}@dots{})
 @group
-foo @result{} 'a      ; @r{The old buffer-local value from buffer @samp{a}}
-               ;   @r{is now the default value.}
+foo @result{} 'g        ; @r{exiting restored the local value in buffer @samp{a},}
+                 ; @r{but we don't see that in buffer @samp{b}}
 @end group
 @group
-(set-buffer "a")
-foo @result{} 'temp   ; @r{The local @code{let} value that should be gone}
-               ;   @r{is now the buffer-local value in buffer @samp{a}.}
-@end group
-@end example
-
-@noindent
-But @code{save-excursion} as shown here avoids the problem:
-
-@example
-@group
-(let ((foo 'temp))
-  (save-excursion
-    (set-buffer "b")
-    @var{body}@dots{}))
+(set-buffer "a") ; @r{verify the local value was restored}
+foo @result{} 'a
 @end group
 @end example
 
@@ -1290,8 +1347,10 @@ If the variable is terminal-local, this function signals an error.  Such
 variables cannot have buffer-local bindings as well.  @xref{Multiple
 Displays}.
 
-@strong{Note:} Do not use @code{make-local-variable} for a hook
-variable.  Instead, use @code{make-local-hook}.  @xref{Hooks}.
+@strong{Warning:} do not use @code{make-local-variable} for a hook
+variable.  The hook variables are automatically made buffer-local as
+needed if you use the @var{local} argument to @code{add-hook} or
+@code{remove-hook}.
 @end deffn
 
 @deffn Command make-variable-buffer-local variable
@@ -1302,7 +1361,14 @@ 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.
+@code{setq}), while the variable does not have a @code{let}-style
+binding that was made in the current buffer, does so.
+
+If @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+Subsequently calling @code{makunbound} on @var{variable} will result
+in a void buffer-local value and leave the default value unaffected.
 
 The value returned is @var{variable}.
 
@@ -1325,6 +1391,19 @@ This returns @code{t} if @var{variable} is buffer-local in buffer
 @code{nil}.
 @end defun
 
+@defun local-variable-if-set-p variable &optional buffer
+This returns @code{t} if @var{variable} will become buffer-local in
+buffer @var{buffer} (which defaults to the current buffer) if it is
+set there.
+@end defun
+
+@defun buffer-local-value variable buffer
+This function returns the buffer-local binding of @var{variable} (a
+symbol) in buffer @var{buffer}.  If @var{variable} does not have a
+buffer-local binding in buffer @var{buffer}, it returns the default
+value (@pxref{Default Value}) of @var{variable} instead.
+@end defun
+
 @defun buffer-local-variables &optional buffer
 This function returns a list describing the buffer-local variables in
 buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
@@ -1347,7 +1426,7 @@ then the variable appears directly in the resulting list.
     (mode-name . "Fundamental")
     @dots{}
 @group
-    ;; @r{Next, non-built-in buffer-local variables.} 
+    ;; @r{Next, non-built-in buffer-local variables.}
     ;; @r{This one is buffer-local and void:}
     foobar
     ;; @r{This one is buffer-local and nonvoid:}
@@ -1405,8 +1484,11 @@ variables that major modes set should not be marked permanent.
 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
+major mode.  It is also useful for buffer-specific minor modes
+that should be forgotten if the user changes the 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
 
@@ -1555,11 +1637,16 @@ 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 @var{variable} does not have a default value, then calling this
+command will give it a default value of @code{nil}.  If @var{variable}
+already has a default value, that value remains unchanged.
+
 If the variable is terminal-local, this function signals an error,
 because such variables cannot have frame-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.
+specially in Emacs can be buffer-local, but can never be frame-local.
+
+This command returns @var{variable}.
 @end deffn
 
   Buffer-local bindings take precedence over frame-local bindings.  Thus,
@@ -1655,6 +1742,112 @@ 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.
 
+@node File Local Variables
+@section File Local Variables
+
+  This section describes the functions and variables that affect
+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.  A
+value of @code{t} means to process them, querying the user if unsafe
+variables are encountered; @code{nil} means ignore them; anything else
+means to query the user for each file.  The default value is @code{t}.
+@end defopt
+
+@defun hack-local-variables &optional mode-only
+This function parses, and binds or evaluates as appropriate, any local
+variables specified by the contents of the current buffer.  The variable
+@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 (@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 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 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.  If the property is @code{t},
+setting that variable in a file is always considered safe, regardless
+of the value used.  If the property is a function of one argument,
+then 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}.
+
+@defopt safe-local-variable-values
+This variable provides another way to mark some variable values as
+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
+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
+file.
+@end defopt
+
+@defun safe-local-variable-p sym val
+This function returns non-@code{nil} if it is safe to give @var{sym}
+the value @var{val}, based on the above criteria.
+@end defun
+
+@cindex risky local variable
+  Some variables are considered @dfn{risky}.  A 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} is considered risky.  The
+variables @samp{font-lock-keywords}, @samp{font-lock-keywords}
+followed by a digit, and @samp{font-lock-syntactic-keywords} are also
+considered risky.  Finally, any variable whose name has a
+non-@code{nil} @code{risky-local-variable} property is considered
+risky.
+
+@defun risky-local-variable-p sym
+This function returns non-@code{nil} if @var{sym} is a risky variable,
+based on the above criteria.
+@end defun
+
+  If a variable is risky, it will not be entered automatically into
+@code{safe-local-variable-values} as described above.  Therefore,
+Emacs will always query before setting a risky variable, unless the
+user explicitly allows the setting by customizing
+@code{safe-local-variable-values} directly.
+
+@defvar ignored-local-variables
+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
+completely ignored.
+@end defvar
+
+  The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
+normally asks for confirmation before handling it.
+
+@defopt enable-local-eval
+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}.
+@end defopt
+
+  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.
+
 @node Variable Aliases
 @section Variable Aliases
 
@@ -1666,17 +1859,59 @@ 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}.
 
-@defmacro defvaralias alias-var base-var
-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}.
-@end defmacro
+@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
 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
@@ -1688,8 +1923,10 @@ not defined as an alias, the function returns @var{variable}.
 (setq bar 2)
 bar
      @result{} 2
+@group
 foo
      @result{} 2
+@end group
 (setq foo 0)
 bar
      @result{} 0
@@ -1697,55 +1934,41 @@ 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.
+@node Variables with Restricted Values
+@section Variables with Restricted Values
 
-@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}.
-@end defopt
+  Ordinary Lisp variables can be assigned any value that is a valid
+Lisp object.  However, certain Lisp variables are not defined in Lisp,
+but in C.  Most of these variables are defined in the C code using
+@code{DEFVAR_LISP}.  Like variables defined in Lisp, these can take on
+any value.  However, some variables are defined using
+@code{DEFVAR_INT} or @code{DEFVAR_BOOL}.  @xref{Defining Lisp
+variables in C,, Writing Emacs Primitives}, in particular the
+description of functions of the type @code{syms_of_@var{filename}},
+for a brief discussion of the C implementation.
 
-@defun hack-local-variables &optional force
-This function parses, and binds or evaluates as appropriate, any local
-variables specified by the contents of the current buffer.  The variable
-@code{enable-local-variables} has its effect here.
+  Variables of type @code{DEFVAR_BOOL} can only take on the values
+@code{nil} or @code{t}.  Attempting to assign them any other value
+will set them to @code{t}:
 
-The argument @var{force} usually comes from the argument @var{find-file}
-given to @code{normal-mode}.
-@end defun
-
-  If a file local variable list could specify the a function that will
-be called later, or an expression that will 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.
-
-  For one thing, any variable whose name ends in @samp{-function},
-@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form},
-@samp{-forms}, @samp{-program}, @samp{-command} or @samp{-predicate}
-cannot be set in a local variable list.  In general, you should use such
-a name whenever it is appropriate for the variable's meaning.
-
-  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}:
+@example
+(let ((display-hourglass 5))
+  display-hourglass)
+     @result{} t
+@end example
 
-@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.
+@defvar byte-boolean-vars
+This variable holds a list of all variables of type @code{DEFVAR_BOOL}.
 @end defvar
 
-  The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
-normally asks for confirmation before handling it.
+  Variables of type @code{DEFVAR_INT} can only take on integer values.
+Attempting to assign them any other value will result in an error:
 
-@defopt enable-local-eval
-This variable controls processing of @samp{Eval:} in 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}.
-@end defopt
+@example
+(setq window-min-height 5.0)
+@error{} Wrong type argument: integerp, 5.0
+@end example
+
+@ignore
+   arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e
+@end ignore