(emacs)File Variables


Prev: Locals Up: Variables

Local Variables in Files
------------------------

   A file can specify local variable values for use when you edit the
file with Emacs.  Visiting the file checks for local variables
specifications; it automatically makes these variables local to the
buffer, and sets them to the values specified in the file.

   There are two ways to specify local variable values: in the first
line, or with a local variables list.  Here's how to do this with the
first line:

     -*- mode: MODENAME; VAR: VALUE; ... -*-

You can specify any number of variables/value pairs in this way, each
pair with a colon and semicolon as shown above.  The major mode should
come first, if it is mentioned at all.  Here is an example that
specifies Lisp mode and sets two variables with numeric values:

     ;; -*-Mode: Lisp; fill-column: 75; comment-column: 50; -*-

   A "local variables list" goes near the end of the file, in the last
page.  (It is often best to put it on a page by itself.)  The local
variables list starts with a line containing the string `Local
Variables:', and ends with a line containing the string `End:'.  In
between come the variable names and values, one set per line, as
`VARIABLE: VALUE'.  The VALUEs are not evaluated; they are used
literally.

   Here is an example of a local variables list:

     ;;; Local Variables: ***
     ;;; mode:lisp ***
     ;;; comment-column:0 ***
     ;;; comment-start: ";;; "  ***
     ;;; comment-end:"***" ***
     ;;; End: ***

   As you see, each line starts with the prefix `;;; ' and each line
ends with the suffix ` ***'.  Emacs recognizes these as the prefix and
suffix based on the first line of the list, by finding them surrounding
the magic string `Local Variables:'; so it automatically discards them
from the other lines of the list.

   The usual reason for using a prefix and/or suffix is to embed the
local variables list in a comment, so it won't confuse other programs
that the file is intended as input for.  The example above is for a
language where comment lines start with `;;; ' and end with `***'; the
local values for `comment-start' and `comment-end' customize the rest
of Emacs for this unusual syntax.  Don't use a prefix (or a suffix) if
you don't need one.

   Two "variable names" have special meanings in a local variables
list: a value for the variable `mode' really sets the major mode, and a
value for the variable `eval' is simply evaluated as an expression and
the value is ignored.  `mode' and `eval' are not real variables;
setting such variables in any other context has no such effect.  If
`mode' is used in a local variables list, it should be the first entry
in the list.

   The start of the local variables list must be no more than 3000
characters from the end of the file, and must be in the last page if the
file is divided into pages.  Otherwise, Emacs will not notice it is
there.  The purpose of this is so that a stray `Local Variables:' not
in the last page does not confuse Emacs, and so that visiting a long
file that is all one page and has no local variables list need not take
the time to search the whole file.

   You may be tempted to try to turn on Auto Fill mode with a local
variable list.  That is a mistake.  The choice of Auto Fill mode or not
is a matter of individual taste, not a matter of the contents of
particular files.  If you want to use Auto Fill, set up major mode
hooks with your `.emacs' file to turn it on (when appropriate) for you
alone (Note: Init File.).  Don't try to use a local variable list
that would impose your taste on everyone.

   The variable `enable-local-variables' controls whether to process
local variables lists, and thus gives you a chance to override them.
Its default value is `t', which means to process local variables lists.
If you set the value to `nil', Emacs simply ignores local variables
lists.  Any other value says to query you about each local variables
list, showing you the local variables list to consider.

   The `eval' "variable" creates special risks, so there is a separate
variable `enable-local-eval' to control whether Emacs processes `eval'
variables, as well variables with names that end in `-hook', `-hooks',
`-function' or `-functions'.  The three possibilities for the value are
`t', `nil', and anything else, just as for `enable-local-variables'.
The default is `maybe', which is neither `t' nor `nil', so normally
Emacs queries about `eval' variable settings.

   Use the command `normal-mode' to reset the local variables and major
mode of a buffer according to the file name and contents, including the
local variables list if any.  Note: Choosing Modes.


automatically generated by info2www