changeset 68867:4ea80a7bd411

* custom.texi (Specifying File Variables, Unsafe File Variables): New nodes, split from File Variables. Document new file local variable behavior.

--- a/man/ChangeLog	Tue Feb 14 01:21:31 2006 +0000
+++ b/man/ChangeLog	Tue Feb 14 01:21:48 2006 +0000
@@ -1,3 +1,9 @@
[phone]  Chong Yidong  <[e-mail]>
+
+	* custom.texi (Specifying File Variables, Unsafe File Variables):
+	New nodes, split from File Variables.  Document new file local
+	variable behavior.
+
 2006-02-13  YAMAMOTO Mitsuharu  <[e-mail]>
 
 	* display.texi (Standard Faces):

--- a/man/custom.texi	Tue Feb 14 01:21:31 2006 +0000
+++ b/man/custom.texi	Tue Feb 14 01:21:48 2006 +0000
@@ -1043,6 +1043,15 @@
 specifications; it automatically makes these variables local to the
 buffer, and sets them to the values specified in the file.
 
+@menu
+* Specifying File Variables:: Specifying file local variables.
+* Unsafe File Variables::     Handling local variables that may not
+                              be safe.
+@end menu
+
+@node Specifying File Variables
+@subsubsection Specifying File Variables
+
   There are two ways to specify local variable values: in the first
 line, or with a local variables list.  Here's how to specify them in the
 first line:
@@ -1170,33 +1179,60 @@
 major mode of a buffer according to the file name and contents,
 including the local variables list if any.  @xref{Choosing Modes}.
 
+@node Unsafe File Variables
+@subsubsection Unsafe File Variables
+
+  File variables create a certain amount of risk; when you visit
+someone else's file, its variables could affect your Emacs in
+arbitrary ways.  A special risk is posed by the @code{eval}
+``variable,'' which can potentially execute arbitrary code, and
+certain actual variables such as @code{load-path}.
+
+  Therefore, whenever Emacs encounters file variables that are not
+known to be safe, it displays the entire list of variables defined in
+that file, and asks you for confirmation before setting them.  You can
+type @samp{y} or @samp{SPC} to apply the local variables list, or
+@samp{n} to ignore it.
+
+  There is a set of file variables and values that are known to be
+safe.  For instance, it is safe to give @code{comment-column} or
+@code{fill-column} any integer value.  If a file specifies only safe
+variable-value pairs, Emacs will not ask for confirmation before
+setting them.  You can also tell Emacs that a set of variable-value
+pairs is safe, by entering @samp{!} at the file variables confirmation
+prompt.  In that case, Emacs will not ask for confirmation if it
+encounters these variable-value pairs in the future.  You can directly
+edit the list of safe variable-value pairs by customizing
+@samp{safe-local-variable-values} (@pxref{Easy Customization}).
+
+  Some variables, such as @code{load-path}, are considered
+@dfn{risky}: there is seldom any reason to specify them as file
+variables, and changing them can be dangerous.  Even if you enter
+@samp{!} at the confirmation prompt, Emacs will not save these values
+for the future.  Therefore, you will be prompted each time the
+variable is encountered.  If you really want to allow such a variable,
+you can avoid the prompt by editing @samp{safe-local-variable-values}.
+
 @findex enable-local-variables
-  The variable @code{enable-local-variables} controls whether to process
-local variables in files, and thus gives you a chance to override them.
-Its default value is @code{t}, which means do process local variables in
-files.  If you set the value to @code{nil}, Emacs simply ignores local
-variables in files.  Any other value says to query you about each file
-that has local variables, showing you the local variable specifications
-so you can judge.
+  The variable @code{enable-local-variables} allows you to change the
+way Emacs processes local variables.  Its default value is @code{t},
+which means the behavior described above.  If you set the value to
+@code{nil}, Emacs simply ignores local variables in files.  Any other
+value says to query you about each file that has local variables, even
+if the variables are known to be safe.
 
 @findex enable-local-eval
-  The @code{eval} ``variable,'' and certain actual variables, create a
-special risk; when you visit someone else's file, local variable
-specifications for these could affect your Emacs in arbitrary ways.
-Therefore, the variable @code{enable-local-eval} controls whether Emacs
-processes @code{eval} variables, as well variables with names that end
-in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
-and certain other variables.  The three possibilities for the variable's
-value are @code{t}, @code{nil}, and anything else, just as for
-@code{enable-local-variables}.  The default is @code{maybe}, which is
-neither @code{t} nor @code{nil}, so normally Emacs does ask for
-confirmation about file settings for these variables.
+  The variable @code{enable-local-eval} controls whether Emacs
+processes @code{eval} variables.  The three possibilities for the
+variable's value are @code{t}, @code{nil}, and anything else, just as
+for @code{enable-local-variables}.  The default is @code{maybe}, which
+is neither @code{t} nor @code{nil}, so normally Emacs does ask for
+confirmation about processes @code{eval} variables.
 
 @findex safe-local-eval-forms
   The @code{safe-local-eval-forms} is a customizable list of eval
 forms which are safe to eval, so Emacs should not ask for
-confirmation to evaluate these forms, even if
-@code{enable-local-variables} says to ask for confirmation in general.
+confirmation to evaluate these forms.
 
 @node Key Bindings
 @section Customizing Key Bindings