* variables.texi (File Local Variables): Document new file local

	variable behavior.

2 files changed, 63 insertions, 34 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index b396e8b3ee7..250d5450608 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2006-02-13  Chong Yidong  <cyd@stupidchicken.com>
+
+        * variables.texi (File Local Variables): Document new file local
+        variable behavior.
+
 2006-02-10  Kim F. Storm  <storm@cua.dk>
 
         * eval.texi (Function Indirection): Add NOERROR to indirect-function.
diff --git a/lispref/variables.texi b/lispref/variables.texi
index 32a6e9b7873..8b54d02758e 100644
--- a/lispref/variables.texi
+++ b/lispref/variables.texi
@@ -1752,9 +1752,9 @@ information about file local variables.
 
 @defopt enable-local-variables
 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}.
+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
@@ -1773,46 +1773,70 @@ It does not set the mode nor any other file local variable.
 
   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.
+visiting a file could take over your Emacs.  Emacs takes several
+measures to prevent this.
+
+@cindex safe local variable
+  When Emacs encounters a file local variable whose safety is not
+guaranteed, it asks the user whether or not to obey the file variable
+specifications.  If the user says no, Emacs ignores @emph{all} the
+file variables specified in that file.  A variable can be marked as
+@dfn{safe} by setting its @code{safe-local-variable} property.  If the
+property is @code{t}, that variable is always considered safe,
+regardless of the value assigned to it.  The
+@code{safe-local-variable} property can also be a a function taking
+exactly one argument.  In that case, Emacs considers it safe to give
+the variable a certain value if the function returns non-@code{nil}
+when called with that value as argument.  Many commonly-encountered
+file variables possess @code{safe-local-variable} by default,
+including @code{fill-column}, @code{fill-prefix}, and
+@code{indent-tabs-mode}.
+
+@defopt safe-local-variable-values
+This variable provides another way to mark variables as safe.  It is a
+list of cons cells @var{(var . val)}, where @var{var} is a variable
+name and @var{val} is a value of that variable that is safe.
+
+When Emacs asks the user whether or not to obey a set of file variable
+specifications, the user can choose to mark them as safe.  This 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
 
-  For one thing, any variable whose name ends in any of
-@samp{-command}, @samp{-frame-alist}, @samp{-function},
+@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} 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}:
+@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 it by editing @code{safe-local-variable-values}
+via Customize.
 
 @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
-ignored.
+completely ignored.
 @end defvar
 
-@defun risky-local-variable-p sym &optional val
-If @var{val} is non-@code{nil}, returns non-@code{nil} if giving
-@var{sym} a file local value of @var{val} would be risky, for any of
-the reasons stated above.  If @var{val} is @code{nil} or omitted, only
-returns @code{nil} if @var{sym} can be safely assigned any file local
-value whatsoever.
-@end defun
-
   The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs
 normally asks for confirmation before handling it.