@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@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
@cindex customization
This chapter talks about various topics relevant to adapting the
-behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference
-Manual} for how to make more far-reaching changes. @xref{X Resources},
+behavior of Emacs in minor ways.
+@iftex
+See @cite{The Emacs Lisp Reference Manual}
+@end iftex
+@ifnottex
+@xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
+Reference Manual},
+@end ifnottex
+for how to make more far-reaching changes. @xref{X Resources},
for information on using X resources to customize Emacs.
Customization that you do within Emacs normally affects only the
@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 settings.
* Variables:: Many Emacs commands examine Emacs variables
to decide what to do; by setting variables,
you can control their functioning.
* Key Bindings:: The keymaps say what command each key runs.
By changing them, you can "redefine keys".
-* Keyboard Translations::
- If your keyboard passes an undesired code
- for a key, you can tell Emacs to
- substitute another code.
* Syntax:: The syntax table controls how words and
- expressions are parsed.
+ expressions are parsed.
* Init File:: How to write common customizations in the
@file{.emacs} file.
@end menu
that Auto Fill mode is on.
Append @code{-mode} to the name of a minor mode to get the name of a
-command function that turns the mode on or off. Thus, the command to
-enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
+command that turns the mode on or off. Thus, the command to
+enable or disable Auto Fill mode is called @code{auto-fill-mode}. These
commands are usually invoked with @kbd{M-x}, but you can bind keys to them
if you wish. With no argument, the function turns the mode on if it was
off and off if it was on. This is known as @dfn{toggling}. A positive
the mode in certain buffers and not others.
For most minor modes, the command name is also the name of a
-variable which directly controls the mode. The mode is enabled
-whenever this variable's value is non-@code{nil}, and the minor-mode
-command works by setting the variable. For example, the command
-@code{outline-minor-mode} works by setting the value of
-@code{outline-minor-mode} as a variable; it is this variable that
-directly turns Outline minor mode on and off. To check whether a
-given minor mode works this way, use @kbd{C-h v} to ask for
-documentation on the variable name.
-
- These minor-mode variables provide a good way for Lisp programs to turn
-minor modes on and off; they are also useful in a file's local variables
-list. But please think twice before setting minor modes with a local
-variables list, because most minor modes are matter of user
-preference---other users editing the same file might not want the same
-minor modes you prefer.
-
- The buffer-local minor modes include Abbrev mode, Auto Fill mode,
-Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents mode,
-Outline minor mode, Overwrite mode, and Binary Overwrite mode.
+variable. The variable's value is non-@code{nil} if the mode is
+enabled and @code{nil} if it is disabled. Some minor-mode commands
+work by just setting the variable. For example, the command
+@code{abbrev-mode} works by setting the value of @code{abbrev-mode} as
+a variable; it is this variable that directly turns Abbrev mode on and
+off. You can directly set the variable's value instead of calling the
+mode function. For other minor modes, you need to either set the
+variable through the Customize interface or call the mode function to
+correctly enable or disable the mode. To check which of these two
+possibilities applies to a given minor mode, use @kbd{C-h v} to ask
+for documentation on the variable name.
+
+ For minor mode commands that work by just setting the minor mode
+variable, that variable provides a good way for Lisp programs to turn
+minor modes on and off; it is also useful in a file's local variables
+list (@pxref{File Variables}). But please think twice before setting
+minor modes with a local variables list, because most minor modes are
+a matter of user preference---other users editing the same file might
+not want the same minor modes you prefer.
+
+ The most useful buffer-local minor modes include Abbrev mode, Auto
+Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents
+mode, Outline minor mode, Overwrite mode, and Binary Overwrite mode.
Abbrev mode allows you to define abbreviations that automatically expand
as you type them. For example, @samp{amd} might expand to @samp{abbrev
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
In Binary Overwrite mode, digits after @kbd{C-q} specify an
octal character code, as usual.
- The following minor modes normally apply to all buffers at once.
-Since each is enabled or disabled by the value of a variable, you
-@emph{can} set them differently for particular buffers, by explicitly
-making the corresponding variables local in those buffers.
-@xref{Locals}.
+ Here are some useful minor modes that normally apply to all buffers
+at once. Since Line Number mode and Transient Mark mode can be
+enabled or disabled just by setting the value of the minor mode
+variable, you @emph{can} set them differently for particular buffers,
+by explicitly making the corresponding variable local in those
+buffers. @xref{Locals}.
Icomplete mode displays an indication of available completions when
you are in the minibuffer and completion is active. @xref{Completion
will get an error. This means you must either set the mark, or
explicitly ``reactivate'' it, before each command that uses the region.
The advantage of Transient Mark mode is that Emacs can display the
-region highlighted (currently only when using X). @xref{Mark}.
-
-@node Variables
-@section Variables
-@cindex variable
-@cindex option, user
-@cindex user option
-
- A @dfn{variable} is a Lisp symbol which has a value. The symbol's
-name is also called the name of the variable. A variable name can
-contain any characters that can appear in a file, but conventionally
-variable names consist of words separated by hyphens. A variable can
-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 require 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, as any
-Lisp program must, but the most interesting variables for you are the
-ones that exist for the sake of customization. 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. These
-variables are called @dfn{user options}. Most user options are
-documented in this manual, and appear in the Variable Index
-(@pxref{Variable Index}).
-
- One example of a variable which is a user option is @code{fill-column}, which
-specifies the position of the right margin (as a number of characters from
-the left margin) to be used by the fill commands (@pxref{Filling}).
-
-@menu
-* Examining:: Examining or setting one variable's value.
-* Easy Customization::
- Convenient and easy customization of variables.
-* Hooks:: Hook variables let you specify programs for parts
- of Emacs to run on particular occasions.
-* Locals:: Per-buffer values of variables.
-* File Variables:: How files can specify variable values.
-@end menu
-
-@node Examining
-@subsection Examining and Setting Variables
-@cindex setting variables
-
-@table @kbd
-@item C-h v @var{var} @key{RET}
-Display the value and documentation of variable @var{var}
-(@code{describe-variable}).
-@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
-Change the value of variable @var{var} to @var{value}.
-@end table
-
- To examine the value of a single variable, use @kbd{C-h v}
-(@code{describe-variable}), which reads a variable name using the
-minibuffer, with completion. It displays both the value and the
-documentation of the variable. For example,
-
-@example
-C-h v fill-column @key{RET}
-@end example
-
-@noindent
-displays something like this:
-
-@smallexample
-fill-column's value is 70
-
-Documentation:
-*Column beyond which automatic line-wrapping should happen.
-Automatically becomes buffer-local when set in any fashion.
-@end smallexample
-
-@noindent
-The star at the beginning of the documentation indicates that this
-variable is a user option. @kbd{C-h v} is not restricted to user
-options; it allows any variable name.
-
-@findex set-variable
- The most convenient way to set a specific user option is with @kbd{M-x
-set-variable}. This reads the variable name with the minibuffer (with
-completion), and then reads a Lisp expression for the new value using
-the minibuffer a second time. For example,
-
-@example
-M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
-@end example
-
-@noindent
-sets @code{fill-column} to 75.
-
- @kbd{M-x set-variable} is limited to user option variables, but you can
-set any variable with a Lisp expression, using the function @code{setq}.
-Here is a @code{setq} expression to set @code{fill-column}:
-
-@example
-(setq fill-column 75)
-@end example
-
- To execute an expression like this one, go to the @samp{*scratch*}
-buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
-Interaction}.
-
- Setting variables, like all means of customizing Emacs except where
-otherwise stated, affects only the current Emacs session.
+region highlighted. @xref{Mark}.
@node Easy Customization
-@subsection Easy Customization Interface
+@section Easy Customization Interface
+
+@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
- A convenient way to find the user option variables that you want to
-change, and then change them, is with @kbd{M-x customize}. This
-command creates a @dfn{customization buffer} with which you can browse
-through the Emacs user options in a logically organized structure,
-then edit and set their values. You can also use the customization
-buffer to save settings permanently in your @file{~/.emacs} file
-(@pxref{Init File}).
-
-The appearance of the example buffers in the following is typically
-different under a window system where faces can be used to indicate the
-active fields and other features.
+ 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 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.
-* Changing an Option:: How to edit a value and set an option.
-* Saving Customizations:: Details of saving customizations.
+* 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
- options, faces, or groups.
+ variables, faces, or groups.
+* Custom Themes:: How to define collections of customized options
+ that can be loaded and unloaded together.
@end menu
@node Customization Groups
-@subsubsection Customization Groups
+@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].
-Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm
- [State]: this option is unchanged from its standard setting.
-How to ask for confirmation when leaving Emacs. [More]
-
Editing group: [Go to Group]
Basic text editing facilities.
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 and faces
-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 view the structure of customization groups on a larger scale
-with @kbd{M-x customize-browse}. This command creates a special kind of
-customization buffer which shows only the names of the groups (and
-options 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, option 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 option, 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 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 an Option
-@subsubsection Changing an Option
+@node Changing a Variable
+@subsection Changing a Variable
- Here is an example of what a user option 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] 60
- [State]: this option is unchanged from its standard setting.
+Kill Ring Max: [Hide Value] 60
+ [State]: STANDARD.
Maximum length of kill ring before oldest elements are thrown away.
@end smallexample
- The text following @samp{[Hide]}, @samp{60} in this case, indicates
-the current value of the option. If you see @samp{[Show]} instead of
-@samp{[Hide]}, it means that the value is hidden; the customization
+ The text following @samp{[Hide Value]}, @samp{60} in this case, indicates
+the current value of the variable. If you see @samp{[Show Value]} instead of
+@samp{[Hide Value]}, it means that the value is hidden; the customization
buffer initially hides values that take up several lines. Invoke
-@samp{[Show]} to show the value.
+@samp{[Show Value]} to show the value.
- The line after the option name indicates the @dfn{customization state}
-of the option: 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
-option's documentation string. If there are more lines of
-documentation, this line ends with @samp{[More]}; invoke this 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.
+variable's documentation string. If there are more lines of
+documentation, this line ends with a @samp{[More]} button; invoke that
+to show the full documentation string.
- 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]: you have edited the value as text, but not set the option.
+[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 option variable. To do
-that, you must @dfn{set} the option. 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 option changes visibly when you set it:
+ The state of the variable changes visibly when you set it:
@smallexample
-[State]: you have set this option, but not saved it for future sessions.
+[State]: SET for current session only.
@end smallexample
You don't have to worry about specifying a value that is not valid;
-setting the option 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,
-command name, or anything else for which completion is defined, you can
-type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
-
- Some options have a small fixed set of possible legitimate values.
-These options 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.
-
- Some options have values with complex structure. For example, the
+ 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, 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
is how it appears in the customization buffer:
@smallexample
-File Coding System Alist: [Hide]
+File Coding System Alist: [Hide Value]
[INS] [DEL] File regexp: \.elc\'
Choice: [Value Menu] Encoding/decoding pair:
Decoding: emacs-mule
Decoding: undecided
Encoding: nil
[INS]
- [State]: this option is unchanged from its standard setting.
-Alist to decide a coding system to use for a file I/O operation. [Hide]
+ [State]: STANDARD.
+Alist to decide a coding system to use for a file I/O @r{@dots{}}
+ operation. [Hide Rest]
The format is ((PATTERN . VAL) ...),
where PATTERN is a regular expression matching a file name,
@r{[@dots{}more lines of documentation@dots{}]}
@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 option value
-@cindex customized options, saving
- Setting the option changes its value in the current Emacs session;
+@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 option, invoke @samp{[State]} and select the @samp{Save for
+save the variable, invoke @samp{[State]} and select the @samp{Save for
Future Sessions} operation. This works by writing code so as to set
-the option variable again each time you start Emacs (@pxref{Saving
+the variable again, each time you start Emacs (@pxref{Saving
Customizations}).
- You can also restore the option to its standard value by invoking
+ You can also restore the variable to its standard value by invoking
@samp{[State]} and selecting the @samp{Erase Customization} operation.
-There are actually three reset operations:
+There are actually four reset operations:
@table @samp
-@item Reset
-If you have made some modifications and not yet set the option,
+@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 Reset to Saved
-This restores the value of the option to the last saved value,
+This restores the value of the variable to the last saved value,
and updates the text accordingly.
@item Erase Customization
-This sets the option to its standard value, and updates the text
-accordingly. This also eliminates any saved value for the option,
+This sets the variable to its standard value, and updates the text
+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
-This sets the option to a previous value that was set in the
+@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 the variable, which discards the customized value,
+and then reset it, which discards the customized value,
you can get the customized value back again with this operation.
@end table
customization. Use the @samp{Add Comment} item from the
@samp{[State]} menu to create a field for entering the comment. The
comment you enter will be saved, and displayed again if you again view
-the same option in a customization buffer, even in another session.
+the same variable in a customization buffer, even in another session.
The state of a group indicates whether anything in that group has been
-edited, set or saved. You can select @samp{Set for Current Session},
-@samp{Save for Future Sessions} and the various kinds of @samp{Reset}
-operation for the group; these operations on the group apply to all
-options in the group and its subgroups.
+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] [Reset to Saved] [Erase Customization] [Finish]
+ [Undo Edits] [Reset to Saved] [Erase Customization] [Finish]
@end smallexample
@vindex custom-buffer-done-function
@noindent
Invoking @samp{[Finish]} either buries or kills this customization
buffer according to the setting of the option
-@code{custom-buffer-done-function}; the default is to bury the buffer.
-Each of the other fields performs an operation---set, save or
-reset---on each of the items in the buffer that could meaningfully be
-set, saved or reset.
+@code{custom-buffer-done-kill}; the default is to bury the buffer.
+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
-@subsubsection Saving Customizations
+@subsection Saving Customizations
@vindex custom-file
The customization buffer normally saves customizations in
@file{~/.emacs}. If you wish, you can save customizations in another
file instead. To make this work, your @file{~/.emacs} should set
-@code{custom-file} to the name of that file. Emacs loads the file
-right after your @file{.emacs} if you did not load it already. For
-example:
+@code{custom-file} to the name of that file. Then you should load the
+file by calling @code{load}. For example:
@example
-(setq custom-file "~/.emacs-custom")
+(setq custom-file "~/.emacs-custom.el")
+(load custom-file)
@end example
- The variable @code{custom-file} is useful if you want to have
-different customizations for different Emacs versions:
+ You can also use @code{custom-file} to specify different
+customization files for different Emacs versions, like this:
@example
-(if (< emacs-major-version 21)
- ;; @r{Emacs 20 customization.}
- (setq custom-file "~/.custom-20.el")
- ;; @r{Emacs 21 customization.}
- (setq custom-file "~/.custom-21.el"))
+(cond ((< emacs-major-version 21)
+ ;; @r{Emacs 20 customization.}
+ (setq custom-file "~/.custom-20.el"))
+ ((and (= emacs-major-version 21) (< emacs-minor-version 4))
+ ;; @r{Emacs 21 customization, before version 21.4.}
+ (setq custom-file "~/.custom-21.el"))
+ ((< emacs-major-version 22)
+ ;; @r{Emacs version 21.4 or later.}
+ (setq custom-file "~/.custom-21.4.el"))
+ (t
+ ;; @r{Emacs version 22.1 or later.}
+ (setq custom-file "~/.custom-22.el")))
+
+(load custom-file)
@end example
If Emacs was invoked with the @option{-q} or @option{--no-init-file}
customizations you might have on your init file.
@node Face Customization
-@subsubsection Customizing Faces
+@subsection Customizing Faces
@cindex customizing faces
@cindex bold font
@cindex italic font
@cindex fonts and faces
- In addition to user options, some customization groups also include
-faces. When you show the contents of a group, both the user options and
+ In addition to variables, some customization groups also include
+faces. When you show the contents of a group, both the variables and
the faces in the group appear in the customization buffer. Here is an
example of how a face looks:
@smallexample
-Custom Changed Face:(sample) [Hide]
- [State]: this face is unchanged from its standard setting.
+Custom Changed Face:(sample) [Hide Face]
+ [State]: STANDARD.
Face used when the customize item has been changed.
-Parent groups: => Custom Magic Faces
+Parent groups: [Custom Magic Faces]
Attributes: [ ] Font Family: *
[ ] Width: *
[ ] Height: *
[ ] 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.
-
- On a black-and-white display, the colors you can use for the
-background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
-and @samp{gray3}. Emacs supports these shades of gray by using
-background stipple patterns instead of a color.
+@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
+specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
+(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
+green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a
+black-and-white display, the colors you can use for the background are
+@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and
+@samp{gray3}. Emacs supports these shades of gray by using background
+stipple patterns instead of a color.
Setting, saving and resetting a face work like the same operations for
-options (@pxref{Changing an Option}).
+variables (@pxref{Changing a Variable}).
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
to clear out the attribute.
@node Specific Customization
-@subsubsection Customizing Specific Items
+@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 option,
-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-option @key{RET} @var{option} @key{RET}
-Set up a customization buffer with just one option, @var{option}.
+@item M-x customize-variable @key{RET} @var{variable} @key{RET}
+Set up a customization buffer with just one variable, @var{variable}.
@item M-x customize-face @key{RET} @var{face} @key{RET}
Set up a customization buffer with just one face, @var{face}.
@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 options, 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 options, 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 options 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 options 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-option
- If you want to alter a particular user option variable with the
-customization buffer, and you know its name, you can use the command
-@kbd{M-x customize-option} and specify the option name. This sets up
-the customization buffer with just one option---the one that you asked
-for. Editing, setting and saving the value work as described above, but
-only for the specified option.
+@findex customize-variable
+ If you want to alter a particular variable with the customization
+buffer, and you know its name, you can use the command @kbd{M-x
+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 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
Likewise, you can modify a specific face, chosen by name, using
@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 option variables, faces, and other groups, all appear
-as well. However, these subgroups' own contents start out hidden. You
-can show their contents in the usual way, by invoking @samp{[Show]}.
+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 options, faces 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 in the
-customization buffer (but that takes a long time).
+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} 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.
+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 and faces that you have
-saved. Use @kbd{M-x customize-customized} to look at the options and
-faces 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 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 @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
+ 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 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
+@cindex variable
+@cindex option, user
+@cindex user option
+
+ A @dfn{variable} is a Lisp symbol which has a value. The symbol's
+name is also called the name of the variable. A variable name can
+contain any characters that can appear in a file, but conventionally
+variable names consist of words separated by hyphens. A variable can
+have a documentation string which describes what kind of value it should
+have and how the value will be used.
+
+ 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 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.
+* Hooks:: Hook variables let you specify programs for parts
+ of Emacs to run on particular occasions.
+* Locals:: Per-buffer values of variables.
+* File Variables:: How files can specify variable values.
+@end menu
+
+@node Examining
+@subsection Examining and Setting Variables
+@cindex setting variables
+
+@table @kbd
+@item C-h v @var{var} @key{RET}
+Display the value and documentation of variable @var{var}
+(@code{describe-variable}).
+@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
+Change the value of variable @var{var} to @var{value}.
+@end table
+
+ To examine the value of a single variable, use @kbd{C-h v}
+(@code{describe-variable}), which reads a variable name using the
+minibuffer, with completion. It displays both the value and the
+documentation of the variable. For example,
+
+@example
+C-h v fill-column @key{RET}
+@end example
+
+@noindent
+displays something like this:
+
+@smallexample
+fill-column's value is 70
+
+Documentation:
+*Column beyond which automatic line-wrapping should happen.
+Automatically becomes buffer-local when set in any fashion.
+@end smallexample
+
+@noindent
+The star at the beginning of the documentation indicates that this
+variable is a user option. @kbd{C-h v} is not restricted to user
+options; it allows any variable name.
+
+@findex set-variable
+ The most convenient way to set a specific user option variable is
+with @kbd{M-x set-variable}. This reads the variable name with the
+minibuffer (with completion), and then reads a Lisp expression for the
+new value using the minibuffer a second time (you can insert the old
+value into the minibuffer for editing via @kbd{M-n}). For example,
+
+@example
+M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
+@end example
+
+@noindent
+sets @code{fill-column} to 75.
+
+ @kbd{M-x set-variable} is limited to user option variables, but you can
+set any variable with a Lisp expression, using the function @code{setq}.
+Here is a @code{setq} expression to set @code{fill-column}:
+
+@example
+(setq fill-column 75)
+@end example
+
+ To execute an expression like this one, go to the @samp{*scratch*}
+buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
+Interaction}.
+
+ Setting variables, like all means of customizing Emacs except where
+otherwise stated, affects only the current Emacs session. The only
+way to alter the variable in future sessions is to put something in
+the @file{~/.emacs} file to set it those sessions (@pxref{Init File}).
@node Hooks
@subsection Hooks
are not called at all. The documentation of each abnormal hook variable
explains in detail what is peculiar about it.
- The recommended way to add a hook function to a hook (either normal or
-abnormal) is by calling @code{add-hook}. You can use any valid Lisp
-function as the hook function, provided it can handle the proper number
-of arguments (zero arguments, in the case of a normal hook). Of course,
-not every Lisp function is @emph{useful} in any particular hook.
+ You can set a hook variable with @code{setq} like any other Lisp
+variable, but the recommended way to add a hook function to a hook
+(either normal or abnormal) is by calling @code{add-hook}. You can
+specify any valid Lisp function as the hook function, provided it can
+handle the proper number of arguments (zero arguments, in the case of
+a normal hook). Of course, not every Lisp function is @emph{useful}
+in any particular hook.
For example, here's how to set up a hook to turn on Auto Fill mode
when entering Text mode and other modes based on Text mode:
``asking for trouble.'' However, the order is predictable: the most
recently added hook functions are executed first.
+ If you play with adding various different versions of a hook
+function by calling @code{add-hook} over and over, remember that all
+the versions you added will remain in the hook variable together. You
+can clear out individual functions with @code{remove-hook}, or do
+@code{(setq @var{hook-variable} nil)} to remove everything.
+
@node Locals
@subsection 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
+@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:
You can also specify the coding system for a file in this way: just
specify a value for the ``variable'' named @code{coding}. The ``value''
must be a coding system name that Emacs recognizes. @xref{Coding
-Systems}.
+Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a
+particular Lisp file. @xref{Enabling Multibyte}.
The @code{eval} pseudo-variable, described below, can be specified in
the first line as well.
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: ***
that the file is intended as input for. The example above is for a
language where comment lines start with @samp{;;; } and end with
@samp{***}; the local values for @code{comment-start} and
-@code{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 @code{mode} really sets the major mode,
-and a value for the variable @code{eval} is simply evaluated as an
-expression and the value is ignored. @code{mode} and @code{eval} are
-not real variables; setting variables named @code{mode} and @code{eval}
-in any other context has no special meaning. @emph{If @code{mode} is
-used to set a major mode, it should be the first ``variable'' in the
-list.} Otherwise, the entries that precede it in the list of the local
-variables are likely to be ignored, since most modes kill all local
-variables as part of their initialization.
-
- You can use the @code{mode} ``variable'' to set minor modes as well as
-major modes; in fact, you can use it more than once, first to set the
-major mode and then to set minor modes which are specific to particular
-buffers. But most minor modes should not be specified in the file in
-any fashion, because they represent user preferences.
+@code{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.
+
+ If you write a multi-line string value, you should put the prefix
+and suffix on each line, even lines that start or end within the
+string. They will be stripped off for processing the list. If you
+want to split a long string across multiple lines of the file, you can
+use backslash-newline, which is ignored in Lisp string constants.
+Here's an example of doing this:
+
+@example
+# Local Variables:
+# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
+# -Dmumble=blaah"
+# End:
+@end example
+
+ Some ``variable names'' have special meanings in a local variables
+list. Specifying the ``variable'' @code{mode} really sets the major
+mode, while any value specified for the ``variable'' @code{eval} is
+simply evaluated as an expression (its value is ignored). A value for
+@code{coding} specifies the coding system for character code
+conversion of this file, and a value of @code{t} for @code{unibyte}
+says to visit the file in a unibyte buffer. These four ``variables''
+are not really variables; setting them in any other context has no
+special meaning.
+
+ @emph{If @code{mode} is used to set a major mode, it should be the
+first ``variable'' in the list.} Otherwise, the entries that precede
+it will usually be ignored, since most modes kill all local variables
+as part of their initialization.
+
+ You can use the @code{mode} ``variable'' to set minor modes as well
+as the major modes; in fact, you can use it more than once, first to
+set the major mode and then to set minor modes which are specific to
+particular buffers. But most minor modes should not be specified in
+the file at all, regardless of how, because they represent user
+preferences.
For example, 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
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 option @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 option'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
Function keys send input events just as character keys do, and keymaps
can have bindings for them.
- On many terminals, typing a function key actually sends the computer a
+ On text terminals, typing a function key actually sends the computer a
sequence of characters; the precise details of the sequence depends on
which function key and on the model of terminal you are using. (Often
the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
symbol whose function definition is the following keymap; the effect is
the same, but it provides a command name for the prefix key that can be
used as a description of what the prefix key is for. Thus, the binding
-of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
+of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function
definition is the keymap for @kbd{C-x} commands. The definitions of
@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
the global map, so these prefix keys are always available.
@vindex minibuffer-local-ns-map
@vindex minibuffer-local-completion-map
@vindex minibuffer-local-must-match-map
+@vindex minibuffer-local-filename-completion-map
+@vindex minibuffer-local-must-match-filename-map
The minibuffer has its own set of local keymaps; they contain various
completion and exit commands.
@item
@code{minibuffer-local-must-match-map} is for strict completion and
for cautious completion.
+@item
+@code{minibuffer-local-filename-completion-map} and
+@code{minibuffer-local-must-match-filename-map} are like the two
+previous ones, but they are specifically for file name completion.
+They do not bind @key{SPC}.
@end itemize
@node Rebinding
@end example
@noindent
-This example uses a string constant containing one character, @kbd{C-z}.
-The single-quote before the command name, @code{shell}, marks it as a
+This example uses a string constant containing one character,
+@kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The
+single-quote before the command name, @code{shell}, marks it as a
constant symbol rather than a variable. If you omit the quote, Emacs
would try to evaluate @code{shell} immediately as a variable. This
probably causes an error; it certainly isn't what you want.
- Here is another example that binds a key sequence two characters long:
+ Here is another example that binds the key sequence @kbd{C-x M-l}:
@example
-(global-set-key "\C-xl" 'make-symbolic-link)
+(global-set-key "\C-x\M-l" 'make-symbolic-link)
@end example
To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
@end example
You can use a vector for the simple cases too. Here's how to
-rewrite the first three examples above, using vectors to bind
-@kbd{C-z}, @kbd{C-x l}, and @kbd{C-x @key{TAB}}:
+rewrite the first six examples above to use vectors:
@example
(global-set-key [?\C-z] 'shell)
@noindent
As you see, you represent a multi-character key sequence with a vector
-by listing each of the characters within the square brackets that
+by listing all of the characters in order within the square brackets that
delimit the vector.
Language and coding systems can cause problems with key bindings
key.
A key sequence which contains function key symbols (or anything but
-@acronym{ASCII} characters) must be a vector rather than a string. The vector
-syntax uses spaces between the elements, and square brackets around the
-whole vector. Thus, to bind function key @samp{f1} to the command
-@code{rmail}, write the following:
+@acronym{ASCII} characters) must be a vector rather than a string.
+Thus, to bind function key @samp{f1} to the command @code{rmail},
+write the following:
@example
(global-set-key [f1] 'rmail)
(global-set-key [H-M-right] 'forward-word)
@end example
+@cindex keypad
+ Many keyboards have a ``numeric keypad'' on the right hand side.
+The numeric keys in the keypad double up as cursor motion keys,
+toggled by a key labeled @samp{Num Lock}. By default, Emacs
+translates these keys to the corresponding keys in the main keyboard.
+For example, when @samp{Num Lock} is on, the key labeled @samp{8} on
+the numeric keypad produces @code{kp-8}, which is translated to
+@kbd{8}; when @samp{Num Lock} is off, the same key produces
+@code{kp-up}, which is translated to @key{UP}. If you rebind a key
+such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too.
+However, if you rebind a @samp{kp-} key directly, that won't affect
+its non-keypad equivalent.
+
+ Emacs provides a convenient method for binding the numeric keypad
+keys, using the variables @code{keypad-setup},
+@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and
+@code{keypad-numlock-shifted-setup}. These can be found in the
+@samp{keyboard} customization group (@pxref{Easy Customization}). You
+can rebind the keys to perform other tasks, such as issuing numeric
+prefix arguments.
+
@node Named ASCII Chars
@subsection Named @acronym{ASCII} Control Characters
@key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
-started out as names for certain @acronym{ASCII} control characters, used so often
-that they have special keys of their own. Later, users found it
+started out as names for certain @acronym{ASCII} control characters,
+used so often that they have special keys of their own. For instance,
+@key{TAB} was another name for @kbd{C-i}. Later, users found it
convenient to distinguish in Emacs between these keys and the ``same''
-control characters typed with the @key{CTRL} key.
-
- Emacs distinguishes these two kinds of input, when the keyboard
-reports these keys to Emacs. It treats the ``special'' keys as function
-keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed},
-@code{escape}, and @code{delete}. These function keys translate
-automatically into the corresponding @acronym{ASCII} characters @emph{if} they
-have no bindings of their own. As a result, neither users nor Lisp
-programs need to pay attention to the distinction unless they care to.
+control characters typed with the @key{CTRL} key. Therefore, on most
+modern terminals, they are no longer the same, and @key{TAB} is
+distinguishable from @kbd{C-i}.
+
+ Emacs can distinguish these two kinds of input if the keyboard does.
+It treats the ``special'' keys as function keys named @code{tab},
+@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
+@code{delete}. These function keys translate automatically into the
+corresponding @acronym{ASCII} characters @emph{if} they have no
+bindings of their own. As a result, neither users nor Lisp programs
+need to pay attention to the distinction unless they care to.
If you do not want to distinguish between (for example) @key{TAB} and
@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
Since this puts a non-@acronym{ASCII} character in the @file{.emacs},
-you should specify for that file a coding system that supports
-that character. @xref{Init Syntax}.
+you should specify a coding system for that file that supports the
+character in question. @xref{Init Syntax}.
-@strong{Warning:} if you change the keyboard encoding, such that the code that
-@kbd{C-q} inserts becomes different, you'll need to edit the
-Lisp expression accordingly.
-
-@strong{Warning:} @kbd{C-q} will insert the wrong code if you visit
-the file @file{.emacs} in a unibyte buffer, so don't do that.
+@strong{Warning:} if you change the keyboard encoding, or change
+between multibyte and unibyte mode, or anything that would alter which
+code @kbd{C-q} would insert for that character, you'll need to edit
+the Lisp expression accordingly, to use the character code generated
+by @kbd{C-q} in the new mode.
@node Mouse Buttons
@subsection Rebinding Mouse Buttons
Emacs also supports triple-click events whose names start with
@samp{triple-}. Emacs does not distinguish quadruple clicks as event
types; clicks beyond the third generate additional triple-click events.
-However, the full number of clicks is recorded in the event list, so you
-can distinguish if you really want to. We don't recommend distinct
-meanings for more than three clicks, but sometimes it is useful for
-subsequent clicks to cycle through the same set of three meanings, so
-that four clicks are equivalent to one click, five are equivalent to
-two, and six are equivalent to three.
+However, the full number of clicks is recorded in the event list, so
+if you know Emacs Lisp you can distinguish if you really want to
+(@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}).
+We don't recommend distinct meanings for more than three clicks, but
+sometimes it is useful for subsequent clicks to cycle through the same
+set of three meanings, so that four clicks are equivalent to one
+click, five are equivalent to two, and six are equivalent to three.
Emacs also records multiple presses in drag and button-down events.
For example, when you press a button twice, then move the mouse while
@vindex double-click-fuzz
The variable @code{double-click-fuzz} specifies how much the mouse
-can move between clicks still allow them to be grouped as a multiple
+can move between clicks and still allow them to be grouped as a multiple
click. Its value is in units of pixels on windowed displays and in
units of 1/8 of a character cell on text-mode terminals; the default is
3.
@item vertical-scroll-bar
The mouse was in a vertical scroll bar. (This is the only kind of
scroll bar Emacs currently supports.)
+@item menu-bar
+The mouse was in the menu bar.
+@item header-line
+The mouse was in a header line.
@ignore
@item horizontal-scroll-bar
The mouse was in a horizontal scroll bar. Horizontal scroll bars do
@kbd{M-x}. Disabling a command has no effect on calling it as a
function from Lisp programs.
-@node Keyboard Translations
-@section Keyboard Translations
-
- Some keyboards do not make it convenient to send all the special
-characters that Emacs uses. The most common problem case is the
-@key{DEL} character. Some keyboards provide no convenient way to type
-this very important character---usually because they were designed to
-expect the character @kbd{C-h} to be used for deletion. On these
-keyboards, if you press the key normally used for deletion, Emacs handles
-the @kbd{C-h} as a prefix character and offers you a list of help
-options, which is not what you want.
-
-@cindex keyboard translations
-@findex keyboard-translate
- You can work around this problem within Emacs by setting up keyboard
-translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into
-@kbd{C-h}, as follows:
-
-@example
-;; @r{Translate @kbd{C-h} to @key{DEL}.}
-(keyboard-translate ?\C-h ?\C-?)
-
-;; @r{Translate @key{DEL} to @kbd{C-h}.}
-(keyboard-translate ?\C-? ?\C-h)
-@end example
-
- Keyboard translations are not the same as key bindings in keymaps
-(@pxref{Keymaps}). Emacs contains numerous keymaps that apply in
-different situations, but there is only one set of keyboard
-translations, and it applies to every character that Emacs reads from
-the terminal. Keyboard translations take place at the lowest level of
-input processing; the keys that are looked up in keymaps contain the
-characters that result from keyboard translation.
-
- On a window system, the keyboard key named @key{DELETE} is a function
-key and is distinct from the @acronym{ASCII} character named @key{DEL}.
-@xref{Named ASCII Chars}. Keyboard translations affect only @acronym{ASCII}
-character input, not function keys; thus, the above example used on a
-window system does not affect the @key{DELETE} key. However, the
-translation above isn't necessary on window systems, because Emacs can
-also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
-normally treats @key{BACKSPACE} as @key{DEL}.
-
- For full information about how to use keyboard translations, see
-@ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.
-
@node Syntax
@section The Syntax Table
@cindex syntax table
@cindex rebinding keys, permanently
@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 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 Options}).
+ When Emacs is started, it normally loads a Lisp program from the
+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
+Options}).
+
+ You can also use @file{~/.emacs.d/init.el} as the init file. Emacs
+tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}.
@cindex @file{default.el}, the default init file
There can also be a @dfn{default init file}, which is the library
finds this file via the standard search path for Lisp libraries.
Emacs loads this library before it loads your init file. To inhibit
loading of this library, use the option @samp{--no-site-file}.
-@xref{Initial Options}.
+@xref{Initial Options}. We recommend against using
+@file{site-start.el} for changes that some users may not like. It is
+better to put them in @file{default.el}, so that users can more easily
+override them.
You can place @file{default.el} and @file{site-start.el} in any of
the directories which Emacs searches for Lisp libraries. The variable
@code{nil}.
@item
-Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
+Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
+(@pxref{Init Rebinding}).
@example
(global-set-key "\C-xl" 'make-symbolic-link)
@example
(put 'narrow-to-region 'disabled nil)
@end example
+
+@item
+Adjusting the configuration to various platforms and Emacs versions.
+
+Users typically want Emacs to behave the same on all systems, so the
+same init file is right for all platforms. However, sometimes it
+happens that a function you use for customizing Emacs is not available
+on some platforms or in older Emacs versions. To deal with that
+situation, put the customization inside a conditional that tests whether
+the function or facility is available, like this:
+
+@example
+(if (fboundp 'blink-cursor-mode)
+ (blink-cursor-mode 0))
+
+(if (boundp 'coding-category-utf-8)
+ (set-coding-priority '(coding-category-utf-8)))
+@end example
+
+@noindent
+You can also simply disregard the errors that occur if the
+function is not defined.
+
+@example
+(condition case ()
+ (set-face-background 'region "grey75")
+ (error nil))
+@end example
+
+A @code{setq} on a variable which does not exist is generally
+harmless, so those do not need a conditional.
@end itemize
@node Terminal Init
@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. But 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 currently pretending
-to be. The idea is that you should get your own editor customizations
-even if you are running as the super user.
+ 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
+currently pretending to be. The idea is that you should get your own
+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