xemacs.info: File Variables

Variables

Locals

Back to Software Index

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

   A file can contain a "local variables list", which specifies the
values to use for certain Emacs variables when that file is edited.
Visiting the file checks for a local variables list and makes each
variable in the list local to the buffer in which the file is visited,
with the value specified in the file.

   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.

   The line which starts the local variables list does not have to say
just `Local Variables:'.  If there is other text before `Local
Variables:', that text is called the "prefix", and if there is other
text after, that is called the "suffix".  If a prefix or suffix are
present, each entry in the local variables list should have the prefix
before it and the suffix after it.  This includes the `End:' line.  The
prefix and suffix are included to disguise the local variables list as
a comment so the compiler or text formatter  will ignore it.  If you do
not need to disguise the local variables list as a comment in this way,
there is no need to include a prefix or a suffix.

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

   Here is an example of a local variables list:
     ;;; Local Variables: ***
     ;;; mode:lisp ***
     ;;; comment-column:0 ***
     ;;; comment-start: ";;; "  ***
     ;;; comment-end:"***" ***
     ;;; End: ***

   Note that the prefix is `;;; ' and the suffix is ` ***'.  Note also
that comments in the file begin with and end with the same strings.
Presumably the file contains code in a language which is enough like
Lisp for Lisp mode to be useful but in which comments start and end
differently.  The prefix and suffix are used in the local variables
list to make the list look like several lines of comments when the
compiler or interpreter for that language reads the file.

   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 is twofold: a stray `Local Variables:' not in the
last page does not confuse Emacs, and Emacs never needs to search a
long file that contains no page markers and has no local variables list.

   You may be tempted to turn on Auto Fill mode with a local variable
list.  That is inappropriate.  Whether you use Auto Fill mode or not is
a matter of personal 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 working with the file.

   XEmacs allows you to specify local variables in the first line of a
file, in addition to specifying them in the `Local Variables' section
at the end of a file.

   If the first line of a file contains two occurences of ``-*-'', Emacs
uses the information between them to determine what the major mode and
variable settings should be.  For example, these are all legal:

     	;;; -*- mode: emacs-lisp -*-
     	;;; -*- mode: postscript; version-control: never -*-
     	;;; -*- tags-file-name: "/foo/bar/TAGS" -*-

   For historical reasons, the syntax ``-*- modename -*-'' is allowed
as well; for example, you can use:

     	;;; -*- emacs-lisp -*-

   The variable `enable-local-variables' controls the use of local
variables lists in files you visit.  The value can be `t', `nil', or
something else.  A value of `t' means local variables lists are obeyed;
`nil' means they are ignored; anything else means query.

   The command `M-x normal-mode' always obeys local variables lists and
ignores this variable.