@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
+@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Customization, Quitting, Amusements, Top
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.
+Manual} 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
particular Emacs session that you do it in--it does not persist
between sessions unless you save the customization in a file such as
-@file{.emacs} or @file{.Xdefaults} that will change future sessions.
-@xref{Init File}. In the customization buffer, if you use a
-command to save customizations for future sessions, this actually
-works by editing @file{.emacs} for you.
+@file{.emacs} or @file{.Xdefaults} that will affect future sessions.
+@xref{Init File}. In the customization buffer, when you save
+customizations for future sessions, this actually works by editing
+@file{.emacs} for you.
@menu
* Minor Modes:: Each minor mode is one feature you can turn on
minor modes you prefer.
The buffer-local minor modes include Abbrev mode, Auto Fill mode,
-Auto Save mode, Font-Lock mode, ISO Accents mode, Outline minor mode,
-Overwrite mode, and Binary Overwrite 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
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.
-@xref{Single-Byte Character Support}.
+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}.
Outline minor mode provides the same facilities as the major mode
called Outline mode; but since it is a minor mode instead, you can
@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. (Not all Emacs user options are included in this
-structure as of yet, but we are adding the rest.)
+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
* 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.
* Face Customization:: How to edit the attributes of a face.
* Specific Customization:: Making a customization buffer for specific
options, faces, or groups.
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 most
-of them are in other groups. By examining various groups, you will
-eventually find the options and faces that belong to the feature you
-are interested in customizing. Then you can use the customization
-buffer to set them. You can go straight to a particular group by name
-using the command @kbd{M-x customize-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}.
@findex customize-browse
You can view the structure of customization groups on a larger scale
@cindex saving option value
@cindex customized options, saving
Setting the option changes its value in the current Emacs session;
-@dfn{saving} the value changes it for future sessions as well. This
-works by writing code into your @file{~/.emacs} file so as to set the
-option variable again each time you start Emacs. To save the option,
-invoke @samp{[State]} and select the @samp{Save for Future Sessions}
-operation.
-
- If Emacs was invoked with the @option{-q} or @option{--no-init-file}
-options (@pxref{Initial Options}), it will not let you save your
-customizations in your @file{~/.emacs} init file. This is because
-saving customizations from such a session would wipe out all the other
-customizations you might have on your init file.
+@dfn{saving} the value changes it for future sessions as well. To
+save the option, 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
+Customizations}).
You can also restore the option to its standard value by invoking
-@samp{[State]} and selecting the @samp{Erase Customization}
-operation. There are actually three reset operations:
+@samp{[State]} and selecting the @samp{Erase Customization} operation.
+There are actually three reset operations:
@table @samp
@item Reset
This sets the option to its standard value, and updates the text
accordingly. This also eliminates any saved value for the option,
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
+customization buffer in this session. If you customize a variable
+and then reset the variable, which discards the customized value,
+you can get the customized value back again with this operation.
@end table
@cindex comments on customized options
reset---on each of the items in the buffer that could meaningfully be
set, saved or reset.
+@node Saving Customizations
+@subsubsection 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:
+
+@example
+(setq custom-file "~/.emacs-custom")
+@end example
+
+ The variable @code{custom-file} is useful if you want to have
+different customizations for different Emacs versions:
+
+@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"))
+@end example
+
+ If Emacs was invoked with the @option{-q} or @option{--no-init-file}
+options (@pxref{Initial Options}), it will not let you save your
+customizations in your @file{~/.emacs} init file. This is because
+saving customizations from such a session would wipe out all the other
+customizations you might have on your init file.
+
@node Face Customization
@subsubsection Customizing Faces
@cindex customizing faces
example of how a face looks:
@smallexample
-Custom Changed Face: (sample) [Hide]
+Custom Changed Face:(sample) [Hide]
[State]: this face is unchanged from its standard setting.
-Parent groups: [Custom Magic Faces]
-Attributes: [ ] Font family: [Value Menu] *
- [ ] Width: [Value Menu] *
- [ ] Height: [Value Menu] *
- [ ] Weight: [Value Menu] *
- [ ] Slant: [Value Menu] *
- [ ] Underline: [Value Menu] *
- [ ] Overline: [Value Menu] *
- [ ] Strike-through: [Value Menu] *
- [ ] Box around text: [Value Menu] *
- [ ] Inverse-video: [Value Menu] *
- [X] Foreground: [Value Menu] Color: white (sample)
- [X] Background: [Value Menu] Color: blue (sample)
- [ ] Stipple: [Value Menu] *
- [ ] Inherit:
+Face used when the customize item has been changed.
+Parent groups: => Custom Magic Faces
+Attributes: [ ] Font Family: *
+ [ ] Width: *
+ [ ] Height: *
+ [ ] Weight: *
+ [ ] Slant: *
+ [ ] Underline: *
+ [ ] Overline: *
+ [ ] Strike-through: *
+ [ ] Box around text: *
+ [ ] Inverse-video: *
+ [X] Foreground: white (sample)
+ [X] Background: blue (sample)
+ [ ] Stipple: *
+ [ ] Inherit: *
@end smallexample
Each face attribute has its own line. The @samp{[@var{x}]} field
@findex customize-face
Likewise, you can modify a specific face, chosen by name, using
-@kbd{M-x customize-face}.
+@kbd{M-x customize-face}. By default it operates on the face used
+on the character after point.
@findex customize-group
You can also set up the customization buffer with a specific group,
makes these hooks abnormal is that there is something peculiar about the
way its functions are called---perhaps they are given arguments, or
perhaps the values they return are used in some way. For example,
-@code{find-file-not-found-hooks} (@pxref{Visiting}) is abnormal because
+@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
as soon as one hook function returns a non-@code{nil} value, the rest
are not called at all. The documentation of each abnormal hook variable
explains in detail what is peculiar about it.
@cindex shell scripts, and local file variables
In shell scripts, the first line is used to identify the script
-interpreter, so you cannot put any local variables there. To accomodate
+interpreter, so you cannot put any local variables there. To accommodate
for this, when Emacs visits a shell script, it looks for local variable
specifications in the @emph{second} line.
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. If @code{mode} is used to
-set a major mode, it should be the first ``variable'' in the list.
+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
defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
repeat count of forty.
-@c widecommands
@table @kbd
@item C-x (
Start defining a keyboard macro (@code{start-kbd-macro}).
macro to change that line and leave point at the start of the next line.
Then repeating the macro will operate on successive lines.
- After you have terminated the definition of a keyboard macro, you can add
-to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
-to plain @kbd{C-x (} followed by retyping the whole definition so far. As
-a consequence it re-executes the macro as previously defined.
+ When a command reads an argument with the minibuffer, your
+minibuffer input becomes part of the macro along with the command. So
+when you replay the macro, the command gets the same argument as
+when you entered the macro. For example,
+
+@example
+C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x )
+@end example
+
+@noindent
+defines a macro that copies the current line into the buffer
+@samp{foo}, then returns to the original buffer.
You can use function keys in a keyboard macro, just like keyboard
keys. You can even use mouse events, but be careful about that: when
invoked the keyboard macro, it also necessarily exits the keyboard macro
as part of the process.
+ After you have terminated the definition of a keyboard macro, you can add
+to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
+to plain @kbd{C-x (} followed by retyping the whole definition so far. As
+a consequence it re-executes the macro as previously defined.
+
@findex edit-kbd-macro
@kindex C-x C-k
You can edit a keyboard macro already defined by typing @kbd{C-x C-k}
this way makes it a valid command name for calling with @kbd{M-x} or for
binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
specify a name that has a prior definition other than another keyboard
-macro, an error message is printed and nothing is changed.
+macro, an error message is shown and nothing is changed.
@findex insert-kbd-macro
Once a macro has a command name, you can save its definition in a file.
key sequences are inconvenient to use.
As a user, you can redefine any key; but it is usually best to stick
-to key sequences that consist of @kbd{C-c} followed by a letter.
-These keys are ``reserved for users,'' so they won't conflict with any
-properly designed Emacs extension. The function keys @key{F5} through
-@key{F9} are also reserved for users. If you redefine some other key,
-your definition may be overridden by certain extensions or major modes
-which redefine the same key.
+to key sequences that consist of @kbd{C-c} followed by a letter (upper
+or lower case). These keys are ``reserved for users,'' so they won't
+conflict with any properly designed Emacs extension. The function
+keys @key{F5} through @key{F9} are also reserved for users. If you
+redefine some other key, your definition may be overridden by certain
+extensions or major modes which redefine the same key.
@node Prefix Keymaps
@subsection Prefix Keymaps
@example
(global-set-key "\C-x\t" 'indent-rigidly)
+@end example
+
+ These examples show how to write some other special ASCII characters
+in strings for key bindings:
+
+@example
+(global-set-key "\r" 'newline) ;; @key{RET}
+(global-set-key "\d" 'delete-backward-char) ;; @key{DEL}
+(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC}
@end example
When the key sequence includes function keys or mouse button events,
the character as it would appear in a string.
Here are examples of using vectors to rebind @kbd{C-=} (a control
-character not in ASCII), @kbd{H-a} (a Hyper character; ASCII doesn't
-have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
+character not in ASCII), @kbd{C-M-=} (not in ASCII because @kbd{C-=}
+is not), @kbd{H-a} (a Hyper character; ASCII doesn't have Hyper at
+all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
keyboard-modified mouse button):
@example
(global-set-key [?\C-=] 'make-symbolic-link)
+(global-set-key [?\M-\C-=] 'make-symbolic-link)
(global-set-key [?\H-a] 'make-symbolic-link)
(global-set-key [f7] 'make-symbolic-link)
(global-set-key [C-mouse-1] 'make-symbolic-link)
@end example
- You can use a vector for the simple cases too. Here's how to rewrite
-the first three examples, above, using vectors:
+ 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}}:
@example
(global-set-key [?\C-z] 'shell)
(global-set-key [?\C-x ?l] 'make-symbolic-link)
(global-set-key [?\C-x ?\t] 'indent-rigidly)
+(global-set-key [?\r] 'newline)
+(global-set-key [?\d] 'delete-backward-char)
+(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
@end example
+@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
+delimit the vector.
+
@node Function Keys
@subsection Rebinding Function Keys
@node Non-ASCII Rebinding
@subsection Non-ASCII Characters on the Keyboard
+@cindex rebinding non-ASCII keys
+@cindex non-ASCII keys, binding
If your keyboard has keys that send non-ASCII characters, such as
accented letters, rebinding these keys is a bit tricky. There are two
(global-set-key [@var{decimal-code}] 'some-function)
@end example
-If you bind 8-bit characters like this in your init file, you my find it
+If you bind 8-bit characters like this in your init file, you may find it
convenient to specify that it is unibyte. @xref{Enabling Multibyte}.
@node Mouse Buttons
events, if it has no binding).
@vindex double-click-time
- The variable @code{double-click-time} specifies how long may elapse
-between clicks that are recognized as a pair. Its value is measured
-in milliseconds. If the value is @code{nil}, double clicks are not
-detected at all. If the value is @code{t}, then there is no time
-limit.
+ The variable @code{double-click-time} specifies how much time can
+elapse between clicks and still allow them to be grouped as a multiple
+click. Its value is in units of milliseconds. If the value is
+@code{nil}, double clicks are not detected at all. If the value is
+@code{t}, then there is no time limit. The default is 500.
+
+@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
+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.
The symbols for mouse events also indicate the status of the modifier
keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
@end example
If the value of the @code{disabled} property is a string, that string
-is included in the message printed when the command is used:
+is included in the message displayed when the command is used:
@example
(put 'delete-region 'disabled
the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
edits @file{.emacs} to enable a command permanently. @xref{Init File}.
+ If Emacs was invoked with the @option{-q} or @option{--no-init-file}
+options (@pxref{Initial Options}), it will not edit your
+@file{~/.emacs} init file. This is because editing the init file from
+such a session might overwrite the lines you might have on your init
+file which enable and disable commands.
+
Whether a command is disabled is independent of what key is used to
invoke it; disabling also applies if the command is invoked using
@kbd{M-x}. Disabling a command has no effect on calling it as a