@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
-@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Customization, Quitting, Amusements, Top
@chapter Customization
@menu
* Minor Modes:: Each minor mode is one feature you can turn on
independently of any others.
-* Easy Customization:: Convenient way to browse and change user options.
+* Easy Customization:: Convenient way to browse and change settings.
* Variables:: Many Emacs commands examine Emacs variables
to decide what to do; by setting variables,
you can control their functioning.
Font-Lock mode automatically highlights certain textual units found in
programs, such as comments, strings, and function names being defined.
-This requires a window system that can display multiple fonts.
+This requires a graphical display that can show multiple fonts.
@xref{Faces}.
ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
@samp{^}, @samp{/} and @samp{~} combine with the following letter, to
produce an accented letter in the ISO Latin-1 character set. The
newer and more general feature of input methods more or less
-supersedes ISO Accents mode. @xref{Single-Byte Character Support}.
+supersedes ISO Accents mode. @xref{Unibyte Mode}.
Outline minor mode provides the same facilities as the major mode
called Outline mode; but since it is a minor mode instead, you can
@node Easy Customization
@section Easy Customization Interface
-@cindex user option
- Emacs has many @dfn{user options} which have values that you can set
-in order to customize various commands. Many user options are
-documented in this manual. Most user options are actually Lisp
-variables (@pxref{Variables}), so their names appear in the Variable
-Index (@pxref{Variable Index}). The rest are faces and their
-attributes (@pxref{Faces}).
+@cindex settings
+ Emacs has many @dfn{settings} which have values that you can specify
+in order to customize various commands. Many are documented in this
+manual. Most settings are @dfn{user options}---that is to say, Lisp
+variables (@pxref{Variables})---so their names appear in the Variable
+Index (@pxref{Variable Index}). The other settings are faces and
+their attributes (@pxref{Faces}).
@findex customize
@cindex customization buffer
- You can browse interactively through the user options and change
-some of them using @kbd{M-x customize}. This command creates a
-@dfn{customization buffer}, which offers commands to navigate through
-a logically organized structure of the Emacs user options; you can
-also use it to edit and set their values, and to save settings
-permanently in your @file{~/.emacs} file (@pxref{Init File}).
+ You can browse interactively through settings and change them using
+@kbd{M-x customize}. This command creates a @dfn{customization
+buffer}, which offers commands to navigate through a logically
+organized structure of the Emacs settings; you can also use it to edit
+and set their values, and to save settings permanently in your
+@file{~/.emacs} file (@pxref{Init File}).
The appearance of the example buffers in this section is typically
-different under a window system, since faces are then used to indicate
-the active fields and other features.
+different under a graphical display, since faces are then used to indicate
+buttons, links and editable fields.
@menu
-* Groups: Customization Groups. How options are classified in a structure.
-* Browsing: Browsing Custom. Browsing and searching for options and faces.
-* Changing a Variable:: How to edit a value and set an option.
+* Groups: Customization Groups. How settings are classified in a structure.
+* Browsing: Browsing Custom. Browsing and searching for settings.
+* Changing a Variable:: How to edit an option's value and set the option.
* Saving Customizations:: Specifying the file for saving customizations.
* Face Customization:: How to edit the attributes of a face.
* Specific Customization:: Making a customization buffer for specific
@subsection Customization Groups
@cindex customization groups
- For customization purposes, user options are organized into
-@dfn{groups} to help you find them. Groups are collected into bigger
-groups, all the way up to a master group called @code{Emacs}.
+ For customization purposes, settings are organized into @dfn{groups}
+to help you find them. Groups are collected into bigger groups, all
+the way up to a master group called @code{Emacs}.
@kbd{M-x customize} creates a customization buffer that shows the
top-level @code{Emacs} group and the second-level groups immediately
@smallexample
/- Emacs group: ---------------------------------------------------\
- [State]: visible group members are all at standard settings.
+ [State]: visible group members are all at standard values.
Customization of the One True Editor.
See also [Manual].
line.
@cindex editable fields (customization buffer)
-@cindex active fields (customization buffer)
+@cindex buttons (customization buffer)
+@cindex links (customization buffer)
Most of the text in the customization buffer is read-only, but it
-typically includes some @dfn{editable fields} that you can edit. There
-are also @dfn{active fields}; this means a field that does something
-when you @dfn{invoke} it. To invoke an active field, either click on it
-with @kbd{Mouse-1}, or move point to it and type @key{RET}.
-
- For example, the phrase @samp{[Go to Group]} that appears in a
-second-level group is an active field. Invoking the @samp{[Go to
-Group]} field for a group creates a new customization buffer, which
-shows that group and its contents. This field is a kind of hypertext
-link to another group.
-
- The @code{Emacs} group includes a few user options itself, but
-mainly it contains other groups, which contain more groups, which
-contain the user options. By browsing the hierarchy of groups, you
-will eventually find the feature you are interested in customizing.
-Then you can use the customization buffer to set the options
-pertaining to that feature. You can also go straight to a particular
-group by name, using the command @kbd{M-x customize-group}.
+typically includes some @dfn{editable fields} that you can edit.
+There are also @dfn{buttons} and @dfn{links}, which do something when
+you @dfn{invoke} them. To invoke a button or a link, either click on
+it with @kbd{Mouse-1}, or move point to it and type @key{RET}.
+
+ For example, the phrase @samp{[State]} that appears in
+a second-level group is a button. It operates on the same
+customization buffer. The phrase @samp{[Go to Group]} is a kind
+of hypertext link to another group. Invoking it creates a new
+customization buffer, which shows that group and its contents.
+
+ The @code{Emacs} group includes a few settings, but mainly it
+contains other groups, which contain more groups, which contain the
+settings. By browsing the hierarchy of groups, you will eventually
+find the feature you are interested in customizing. Then you can use
+the customization buffer to set that feature's settings. You can also
+go straight to a particular group by name, using the command @kbd{M-x
+customize-group}.
@node Browsing Custom
@subsection Browsing and Searching for Options and Faces
@findex customize-browse
-You can use @kbd{M-x customize} to browse the groups and options, but
-often @kbd{M-x customize-browse} is a more efficient alternative.
-That is because it lets you view the structure of customization groups
-on a larger scale. This command creates a special kind of
-customization buffer which shows only the names of the groups (and
-variables and faces), and their structure.
+
+ @kbd{M-x customize-browse} is another way to browse the available
+settings. This command creates a special customization buffer which
+shows only the names of groups and settings, and puts them in a
+structure.
In this buffer, you can show the contents of a group by invoking
@samp{[+]}. When the group contents are visible, this button changes to
@samp{[-]}; invoking that hides the group contents.
- Each group, variable, or face name in this buffer has an active field
-which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
-that active field creates an ordinary customization buffer showing just
-that group and its contents, just that variable, or just that face.
-This is the way to set values in it.
+ Each setting in this buffer has a link which says @samp{[Group]},
+@samp{[Option]} or @samp{[Face]}. Invoking this link creates an
+ordinary customization buffer showing just that group and its
+contents, just that user option, or just that face. This is the way
+to change settings that you find with @kbd{M-x customize-browse}.
- If you can guess part of the name of the options you are interested
-in, then sometimes @kbd{M-x customize-apropos} can be another useful
-way to search for options. However, unlike @code{customize} and
-@code{customize-browse}, @code{customize-apropos} can only find
-options that are loaded in the current Emacs session. @xref{Specific
-Customization,, Customizing Specific Items}.
+ If you can guess part of the name of the settings you are interested
+in, @kbd{M-x customize-apropos} is another way to search for settings.
+However, unlike @code{customize} and @code{customize-browse},
+@code{customize-apropos} can only find groups and settings that are
+loaded in the current Emacs session. @xref{Specific Customization,,
+Customizing Specific Items}.
@node Changing a Variable
@subsection Changing a Variable
- Here is an example of what a variable looks like in the
-customization buffer:
+ Here is an example of what a variable (a user option) looks like in
+the customization buffer:
@smallexample
Kill Ring Max: [Hide Value] 60
buffer initially hides values that take up several lines. Invoke
@samp{[Show Value]} to show the value.
- The line after the option name indicates the @dfn{customization state}
-of the variable: in the example above, it says you have not changed the
-option yet. The word @samp{[State]} at the beginning of this line is
-active; you can get a menu of various operations by invoking it with
-@kbd{Mouse-1} or @key{RET}. These operations are essential for
-customizing the variable.
+ The line after the variable name indicates the @dfn{customization
+state} of the variable: in the example above, it says you have not
+changed the option yet. The @samp{[State]} button at the beginning of
+this line gives you a menu of various operations for customizing the
+variable.
The line after the @samp{[State]} line displays the beginning of the
variable's documentation string. If there are more lines of
-documentation, this line ends with @samp{[More]}; invoke this to show
-the full documentation string.
+documentation, this line ends with a @samp{[More]} button; invoke that
+to show the full documentation string.
- To enter a new value for @samp{Kill Ring Max}, move point to the value
-and edit it textually. For example, you can type @kbd{M-d}, then insert
-another number.
-
- When you begin to alter the text, you will see the @samp{[State]} line
-change to say that you have edited the value:
+ To enter a new value for @samp{Kill Ring Max}, move point to the
+value and edit it textually. For example, you can type @kbd{M-d},
+then insert another number. As you begin to alter the text, you will
+see the @samp{[State]} line change to say that you have edited the
+value:
@smallexample
[State]: EDITED, shown value does not take effect until you set or @r{@dots{}}
save it.
@end smallexample
-@cindex setting option value
- Editing the value does not actually set the variable. To do
-that, you must @dfn{set} it. To do this, invoke the word
-@samp{[State]} and choose @samp{Set for Current Session}.
+@cindex settings, how to set
+ Editing the value does not actually set the variable. To do that,
+you must @dfn{set} the variable. To do this, invoke the
+@samp{[State]} button and choose @samp{Set for Current Session}.
The state of the variable changes visibly when you set it:
@end smallexample
You don't have to worry about specifying a value that is not valid;
-setting the variable checks for validity and will not really install an
-unacceptable value.
+the @samp{Set for Current Session} operation checks for validity and
+will not install an unacceptable value.
@kindex M-TAB @r{(customization buffer)}
@findex widget-complete
- While editing a value or field that is a file name, directory name,
+ While editing a field that is a file name, directory name,
command name, or anything else for which completion is defined, you
can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)
Some variables have a small fixed set of possible legitimate values.
-These variables don't let you edit the value textually. Instead, an
-active field @samp{[Value Menu]} appears before the value; invoke this
-field to edit the value. For a boolean ``on or off'' value, the active
-field says @samp{[Toggle]}, and it changes to the other value.
-@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
-take effect when you use the @samp{Set for Current Session} operation.
+These variables don't let you edit the value textually. Instead, a
+@samp{[Value Menu]} button appears before the value; invoke this
+button to change the value. For a boolean ``on or off'' value, the
+button says @samp{[Toggle]}, and it changes to the other value.
+@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the
+changes take real effect when you use the @samp{Set for Current
+Session} operation.
Some variables have values with complex structure. For example, the
value of @code{file-coding-system-alist} is an association list. Here
@noindent
Each association in the list appears on four lines, with several
-editable or ``active'' fields. You can edit the regexps and coding
+editable fields and/or buttons. You can edit the regexps and coding
systems using ordinary editing commands. You can also invoke
-@samp{[Value Menu]} to switch to a kind of value---for instance, to
-specify a function instead of a pair of coding systems.
+@samp{[Value Menu]} to switch to a different kind of value---for
+instance, to specify a function instead of a pair of coding systems.
To delete an association from the list, invoke the @samp{[DEL]} button
for that item. To add an association, invoke @samp{[INS]} at the
@kindex S-TAB @r{(customization buffer)}
@findex widget-forward
@findex widget-backward
- Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
-moving through the customization buffer. @key{TAB}
-(@code{widget-forward}) moves forward to the next active or editable
-field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
-previous active or editable field.
+ Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful
+for moving through the customization buffer. @key{TAB}
+(@code{widget-forward}) moves forward to the next button or editable
+field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to
+the previous button or editable field.
Typing @key{RET} on an editable field also moves forward, just like
@key{TAB}. We set it up this way because people often type @key{RET}
when they are finished editing a field. To insert a newline within an
editable field, use @kbd{C-o} or @kbd{C-q C-j}.
-@cindex saving variable value
-@cindex customized variables, saving
+@cindex saving a setting
+@cindex settings, how to save
Setting the variable changes its value in the current Emacs session;
@dfn{saving} the value changes it for future sessions as well. To
save the variable, invoke @samp{[State]} and select the @samp{Save for
There are actually four reset operations:
@table @samp
-@item Reset to Current
+@item Undo Edits
If you have made some modifications and not yet set the variable,
this restores the text in the customization buffer to match
the actual value.
@item Erase Customization
This sets the variable to its standard value, and updates the text
-accordingly. This also eliminates any saved value for the option,
+accordingly. This also eliminates any saved value for the variable,
so that you will get the standard value in future Emacs sessions.
-@item Use Backup Value
+@item Set to Backup Value
This sets the variable to a previous value that was set in the
customization buffer in this session. If you customize a variable
and then reset it, which discards the customized value,
The state of a group indicates whether anything in that group has been
edited, set or saved.
- Near the top of the customization buffer there are two lines
-containing several active fields:
+ Near the top of the customization buffer there are two lines of buttons:
@smallexample
[Set for Current Session] [Save for Future Sessions]
- [Reset to Current] [Reset to Saved] [Erase Customization] [Finish]
+ [Undo Edits] [Reset to Saved] [Erase Customization] [Finish]
@end smallexample
@vindex custom-buffer-done-function
Invoking @samp{[Finish]} either buries or kills this customization
buffer according to the setting of the option
@code{custom-buffer-done-kill}; the default is to bury the buffer.
-Each of the other fields performs an operation---set, save or
-reset---on each of the options in the buffer that could meaningfully
-be set, saved or reset. They do not operate on options whose values
-are hidden, nor on subgroups.
+Each of the other buttons performs an operation---set, save or
+reset---on each of the settings in the buffer that could meaningfully
+be set, saved or reset. They do not operate on settings whose values
+are hidden, nor on subgroups not visible in the buffer.
@node Saving Customizations
@subsection Saving Customizations
[ ] Inherit: *
@end smallexample
- Each face attribute has its own line. The @samp{[@var{x}]} field
+ Each face attribute has its own line. The @samp{[@var{x}]} button
before the attribute name indicates whether the attribute is
-@dfn{enabled}; @samp{X} means that it is. You can enable or disable the
-attribute by invoking that field. When the attribute is enabled, you
-can change the attribute value in the usual ways.
+@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]}
+means that it's disabled. You can enable or disable the attribute by
+clicking that button. When the attribute is enabled, you can change
+the attribute value in the usual ways.
For the colors, you can specify a color name (use @kbd{M-x
list-colors-display} for a list of them) or a hexadecimal color
A face can specify different appearances for different types of
display. For example, a face can make text red on a color display, but
use a bold font on a monochrome display. To specify multiple
-appearances for a face, select @samp{Show all display specs} in the menu you
-get from invoking @samp{[State]}.
+appearances for a face, select @samp{For All Kinds of Displays} in the
+menu you get from invoking @samp{[State]}.
@findex modify-face
Another more basic way to set the attributes of a specific face is
@node Specific Customization
@subsection Customizing Specific Items
- Instead of finding the options you want to change by moving down
-through the structure of groups, you can specify the particular variable,
-face, or group that you want to customize.
+ Instead of finding the setting you want to change by navigating the
+structure of groups, here are other ways to specify the settings that
+you want to customize.
@table @kbd
@item M-x customize-variable @key{RET} @var{variable} @key{RET}
@item M-x customize-group @key{RET} @var{group} @key{RET}
Set up a customization buffer with just one group, @var{group}.
@item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
-Set up a customization buffer with all the variables, faces and groups
-that match @var{regexp}.
+Set up a customization buffer with all the settings and groups that
+match @var{regexp}.
@item M-x customize-changed-options @key{RET} @var{version} @key{RET}
-Set up a customization buffer with all the variables, faces and groups
+Set up a customization buffer with all the settings and groups
whose meaning has changed since Emacs version @var{version}.
@item M-x customize-saved
-Set up a customization buffer containing all variables and faces that you
+Set up a customization buffer containing all settings that you
have saved with customization buffers.
@item M-x customize-customized
-Set up a customization buffer containing all variables and faces that you
-have customized but not saved.
+Set up a customization buffer containing all settings that you have
+customized but not saved.
@end table
@findex customize-variable
customize-variable} and specify the variable name. This sets up the
customization buffer with just one variable---the one that you asked
for. Editing, setting and saving the value work as described above,
-but only for the specified variable. Minibuffer completion is very
-handy if you only know part of the name. However, it only finds
+but only for the specified variable. Minibuffer completion is handy
+if you only know part of the name. However, this command can only see
options that have been loaded in the current Emacs session.
@findex customize-face
@findex customize-group
You can also set up the customization buffer with a specific group,
using @kbd{M-x customize-group}. The immediate contents of the chosen
-group, including user options, faces, and other groups, all appear
+group, including variables, faces, and other groups, all appear
as well (even if not already loaded). However, the subgroups' own
contents are not included.
@findex customize-apropos
To control more precisely what to customize, you can use @kbd{M-x
-customize-apropos}. You specify a regular expression as argument; then
-all @emph{loaded} options, faces and groups whose names match this
+customize-apropos}. You specify a regular expression as argument;
+then all @emph{loaded} settings and groups whose names match this
regular expression are set up in the customization buffer. If you
-specify an empty regular expression, this includes @emph{all} groups,
-options and faces (but that takes a long time).
+specify an empty regular expression, this includes @emph{all} loaded
+groups and settings---which takes a long time to set up.
-@findex customize-changed-options
+@findex customize-changed
When you upgrade to a new Emacs version, you might want to customize
-new options and options whose meanings or default values have changed.
-To do this, use @kbd{M-x customize-changed-options} and specify a
-previous Emacs version number using the minibuffer. It creates a
-customization buffer which shows all the options (and groups) whose
-definitions have been changed since the specified version. (Not just
-those that are already loaded.)
+new settings and settings whose meanings or default values have
+changed. To do this, use @kbd{M-x customize-changed} and
+specify a previous Emacs version number using the minibuffer. It
+creates a customization buffer which shows all the settings and groups
+whose definitions have been changed since the specified version, loading
+them if necessary.
@findex customize-saved
@findex customize-customized
- If you change option values and then decide the change was a
-mistake, you can use two special commands to revisit your previous
-changes. Use @kbd{M-x customize-saved} to look at the options that
-you have saved. Use @kbd{M-x customize-customized} to look at the
-options that you have set but not saved.
+ If you change settings and then decide the change was a mistake, you
+can use two special commands to revisit your previous changes. Use
+@kbd{M-x customize-saved} to look at the settings that you have saved.
+Use @kbd{M-x customize-customized} to look at the settings that you
+have set but not saved.
@node Custom Themes
@subsection Customization Themes
@cindex custom themes
-@dfn{Custom themes} are collections of customized options that can be
-enabled or disabled as a unit. You can use Custom themes to switch
-quickly and easily between various collections of settings, and to
-transfer such collections from one computer to another.
+ @dfn{Custom themes} are collections of settings that can be enabled
+or disabled as a unit. You can use Custom themes to switch quickly
+and easily between various collections of settings, and to transfer
+such collections from one computer to another.
@findex customize-create-theme
-To define a Custom theme, use the command
-@kbd{M-x customize-create-theme}, which brings up a buffer named
-@samp{*New Custom Theme*}. At the top of the buffer is an editable
-field where you can specify the name of the theme. To add a
-customization option to the theme, click on the @samp{INS} button to
-open up a field where you can insert the name of the option. The
-current value of that option is applied to the theme. After adding as
-many options as you like, click on @samp{Done} to save the Custom
-theme.
+ To define a Custom theme, use @kbd{M-x customize-create-theme},
+which brings up a buffer named @samp{*New Custom Theme*}. At the top
+of the buffer is an editable field where you can specify the name of
+the theme. Click on the button labelled @samp{Insert Variable} to add
+a variable to the theme, and click on @samp{Insert Face} to add a
+face. You can edit these values in the @samp{*New Custom Theme*}
+buffer like in an ordinary Customize buffer. To remove an option from
+the theme, click on its @samp{State} button and select @samp{Delete}.
@vindex custom-theme-directory
-Saving a Custom theme named @var{foo} writes its definition into the
-file @file{@var{foo}-theme.el}, in the directory @file{~/.emacs.d/}
-(you can specify the directory by setting
-@code{custom-theme-directory}).
+ After adding the desired options, click on @samp{Save Theme} to save
+the Custom theme. This writes the theme definition to a file
+@file{@var{foo}-theme.el} (where @var{foo} is the theme name you
+supplied), in the directory @file{~/.emacs.d/}. You can specify the
+directory by setting @code{custom-theme-directory}.
+
+ You can view and edit the settings of a previously-defined theme by
+clicking on @samp{Visit Theme} and specifying the theme name. You can
+also import the variables and faces that you have set using Customize
+by visiting the ``special'' theme named @samp{user}. This theme, which
+records all the options that you set in the ordinary customization
+buffer, is always enabled, and always takes precedence over all other
+enabled Custom themes. Additionally, the @samp{user} theme is
+recorded in your @file{.emacs} file, rather than a
+@file{user-theme.el} file.
+
+@vindex custom-enabled-themes
+ Once you have defined a Custom theme, you can use it by customizing
+the variable @code{custom-enabled-themes}. This is a list of Custom
+themes that are @dfn{enabled}, or put into effect. If you set
+@code{custom-enabled-themes} using the Customize interface, the theme
+definitions are automatically loaded from the theme files, if they
+aren't already. If you save the value of @code{custom-enabled-themes}
+for future Emacs sessions, those Custom themes will be enabled
+whenever Emacs is started up.
+
+ If two enabled themes specify different values for an option, the
+theme occurring earlier in @code{custom-enabled-themes} takes effect.
@findex load-theme
@findex enable-theme
@findex disable-theme
-You can load the themes you've previously defined with the command
-@code{load-theme}. It prompts for a theme name in the minibuffer,
-then loads that theme if it isn't already loaded. It also
-@dfn{enables} the theme, which means putting its settings into effect.
-An enabled theme can be @dfn{disabled} with the command
-@kbd{M-x disable-theme}; this returns the options specified in the
-theme to their original values. To re-enable the theme, use the
-command @kbd{M-x enable-theme}.
-
-To enable a Custom theme named @var{foo} whenever Emacs is started up,
-add the line @code{(load-theme '@var{foo})} to your @file{.emacs} file
-(@pxref{Init File}).
-
-Enabling a custom theme does not disable the themes already enabled;
-instead, they are all enabled together. If two enabled Custom themes
-specify different values for an option, the last theme to be enabled
-takes effect.
-
-The options that you set in the ordinary customization buffer
-(@pxref{Easy Customization}) are also considered part of a Custom
-theme, called @samp{user}. The @samp{user} theme is always enabled,
-and always takes precedence over all other enabled Custom themes.
-Additionally, the @samp{user} theme is recorded in your @file{.emacs}
-file, rather than a @file{user-theme.el} file.
+ You can temporarily enable a Custom theme with @kbd{M-x
+enable-theme}. This prompts for a theme name in the minibuffer, loads
+the theme from the theme file if necessary, and enables the theme.
+You can @dfn{disabled} any enabled theme with the command @kbd{M-x
+disable-theme}; this returns the options specified in the theme to
+their original values. To re-enable the theme, type @kbd{M-x
+enable-theme} again. If a theme file is changed during your Emacs
+session, you can reload it by typing @kbd{M-x load-theme}. (This also
+enables the theme.)
@node Variables
@section Variables
have a documentation string which describes what kind of value it should
have and how the value will be used.
- Lisp allows any variable to have any kind of value, but most variables
-that Emacs uses need a value of a certain type. Often the value should
-always be a string, or should always be a number. Sometimes we say that a
-certain feature is turned on if a variable is ``non-@code{nil},'' meaning
-that if the variable's value is @code{nil}, the feature is off, but the
-feature is on for @emph{any} other value. The conventional value to use to
-turn on the feature---since you have to pick one particular value when you
-set the variable---is @code{t}.
+ Emacs Lisp allows any variable (with a few exceptions) to have any
+kind of value, but most variables that Emacs uses need a value of a
+certain type. Often the value should always be a string, or should
+always be a number. Sometimes we say that a certain feature is turned
+on if a variable is ``non-@code{nil},'' meaning that if the variable's
+value is @code{nil}, the feature is off, but the feature is on for
+@emph{any} other value. The conventional value to use to turn on the
+feature---since you have to pick one particular value when you set the
+variable---is @code{t}.
Emacs uses many Lisp variables for internal record keeping, but the
-most interesting variables for a non-programmer user are those that
-are also @dfn{user options}, the variables that are meant for users to
-change. Each user option that you can set with the customization
-buffer is (if it is not a face) in fact a Lisp variable. Emacs does
-not (usually) change the values of these variables; instead, you set
-the values, and thereby alter and control the behavior of certain
-Emacs commands. Use of the customization buffer is explained above
-(@pxref{Easy Customization}); here we describe other aspects of Emacs
-variables.
+most interesting variables for a non-programmer user are those meant
+for users to change---the @dfn{user options}.
+
+ Each user option that you can set with the customization buffer is
+in fact a Lisp variable. Emacs does not (usually) change the values
+of these variables; instead, you set the values, and thereby alter and
+control the behavior of certain Emacs commands. Use of the
+customization buffer is explained above (@pxref{Easy Customization});
+here we describe other aspects of Emacs variables.
@menu
* Examining:: Examining or setting one variable's value.
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
+@menu
+* Specifying File Variables:: Specifying file local variables.
+* Safe File Variables:: Making sure file local variables are safe.
+@end menu
+
+@node Specifying File Variables
+@subsubsection Specifying File Variables
+
+ There are two ways to specify file local variable values: in the first
line, or with a local variables list. Here's how to specify them in the
first line:
in the @samp{-*-} line first, and @emph{everything} in the local
variables list afterward.
-Here is an example of a local variables list:
+ Here is an example of a local variables list:
@example
;;; Local Variables: ***
major mode of a buffer according to the file name and contents,
including the local variables list if any. @xref{Choosing Modes}.
-@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.
-
-@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.
-
-@findex safe-local-eval-forms
+@node Safe File Variables
+@subsubsection Safety of File Variables
+
+ File-local variables can be dangerous; when you visit someone else's
+file, there's no telling what its local variables list could do to
+your Emacs. Improper values of the @code{eval} ``variable,'' and
+other variables such as @code{load-path}, could execute Lisp code you
+didn't intend to run.
+
+ Therefore, whenever Emacs encounters file local variable values that
+are not known to be safe, it displays the file's entire local
+variables list, and asks you for confirmation before setting them.
+You can type @kbd{y} or @key{SPC} to put the local variables list into
+effect, or @kbd{n} to ignore it. When Emacs is run in batch mode
+(@pxref{Initial Options}), it can't really ask you, so it assumes the
+answer @samp{n}.
+
+ Emacs normally recognizes certain variables/value pairs as 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 does not ask for confirmation before
+setting them. Otherwise, you can tell Emacs to record that all the
+variable/value pairs in the file are safe, by typing @kbd{!} at the
+confirmation prompt. When Emacs encounters these variable/value pairs
+subsequently, in the same file or others, it will assume they are
+safe.
+
+@vindex safe-local-variable-values
+@cindex risky variable
+ Some variables, such as @code{load-path}, are considered
+particularly @dfn{risky}: there is seldom any reason to specify them
+as local variables, and changing them can be dangerous. Even if you
+enter @kbd{!} at the confirmation prompt, Emacs will not record any
+values as safe for these variables. If you really want to record safe
+values for these variables, do it directly by customizing
+@samp{safe-local-variable-values} (@pxref{Easy Customization}).
+
+@vindex enable-local-variables
+ The variable @code{enable-local-variables} allows you to change the
+way Emacs processes local variables. Its default value is @code{t},
+which specifies the behavior described above. If it is @code{nil},
+Emacs simply ignores all file local variables. Any other value says
+to query you about each file that has local variables, without trying
+to determine whether the values are known to be safe.
+
+@vindex enable-local-eval
+ 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.
+
+@vindex 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
@cindex startup (init file)
When Emacs is started, it normally loads a Lisp program from the
-file @file{.emacs} or @file{.emacs.el} in your home directory. We
-call this file your @dfn{init file} because it specifies how to
+file @file{.emacs} or @file{.emacs.el} in your home directory
+(see @ref{General Variables, HOME}, if you don't know where that is).
+We call this file your @dfn{init file} because it specifies how to
initialize Emacs for you. You can use the command line switch
@samp{-q} to prevent loading your init file, and @samp{-u} (or
@samp{--user}) to specify a different user's init file (@pxref{Initial
@node Find Init
@subsection How Emacs Finds Your Init File
- Normally Emacs uses the environment variable @env{HOME} to find
-@file{.emacs}; that's what @samp{~} means in a file name. If
-@file{.emacs} is not found inside @file{~/} (nor @file{.emacs.el}),
-Emacs looks for @file{~/.emacs.d/init.el} (which, like
-@file{~/.emacs.el}, can be byte-compiled).
+ Normally Emacs uses the environment variable @env{HOME}
+(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what
+@samp{~} means in a file name. If @file{.emacs} is not found inside
+@file{~/} (nor @file{.emacs.el}), Emacs looks for
+@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
+byte-compiled).
However, if you run Emacs from a shell started by @code{su}, Emacs
tries to find your own @file{.emacs}, not that of the user you are
editor customizations even if you are running as the super user.
More precisely, Emacs first determines which user's init file to use.
-It gets the user name from the environment variables @env{LOGNAME} and
+It gets your user name from the environment variables @env{LOGNAME} and
@env{USER}; if neither of those exists, it uses effective user-ID.
If that user name matches the real user-ID, then Emacs uses @env{HOME};
otherwise, it looks up the home directory corresponding to that user