@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
@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.
- All kinds of customization affect only the particular Emacs session
-that you do them in. They are completely lost when you kill the Emacs
-session, and have no effect on other Emacs sessions you may run at the
-same time or later. The only way an Emacs session can affect anything
-outside of it is by writing a file; in particular, the only way to make
-a customization ``permanent'' is to put something in your @file{.emacs}
-file or other appropriate file to do the customization in each session.
-@xref{Init File}.
+ 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 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
argument always turns the mode on, and an explicit zero argument or a
negative argument always turns it off.
- Enabling or disabling some minor modes applies only to the current
-buffer; each buffer is independent of the other buffers. Therefore, you
-can enable the mode in particular buffers and disable it in others. The
-per-buffer 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.
+ Some minor modes are global: while enabled, they affect everything
+you do in the Emacs session, in all buffers. Other minor modes are
+buffer-local; they apply only to the current buffer, so you can enable
+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.
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
Binary Overwrite mode is a variant of Overwrite mode for editing
binary files; it treats newlines and tabs like other characters, so that
they overwrite other characters and can be overwritten by them.
+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
The advantage of Transient Mark mode is that Emacs can display the
region highlighted (currently only when using X). @xref{Mark}.
- 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.
-
@node Variables
@section Variables
@cindex variable
displays something like this:
@smallexample
-fill-column's value is 75
+fill-column's value is 70
Documentation:
*Column beyond which automatic line-wrapping should happen.
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.
shows that group and its contents. This field is a kind of hypertext
link to another group.
- The @code{Emacs} group does not include any user options itself, but
-other groups do. 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
customization buffer:
@smallexample
-Kill Ring Max: [Hide] 30
+Kill Ring Max: [Hide] 60
[State]: this option is unchanged from its standard setting.
Maximum length of kill ring before oldest elements are thrown away.
@end smallexample
- The text following @samp{[Hide]}, @samp{30} in this case, indicates
+ 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
buffer initially hides values that take up several lines. Invoke
Encoding: emacs-mule
[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
Choice: [Value Menu] Encoding/decoding pair:
- Decoding: no-conversion
- Encoding: no-conversion
+ Decoding: raw-text
+ Encoding: raw-text-unix
[INS] [DEL] File regexp: \.tar\'
Choice: [Value Menu] Encoding/decoding pair:
Decoding: no-conversion
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;
@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
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.
+
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:
[ ] Underline: [Value Menu] *
[ ] Overline: [Value Menu] *
[ ] Strike-through: [Value Menu] *
- [ ] Box around text: [Value Menu] Off
+ [ ] 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:
@end smallexample
Each face attribute has its own line. The @samp{[@var{x}]} field
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 Display Types} in the menu you
+appearances for a face, select @samp{Show all display specs} in the menu you
get from invoking @samp{[State]}.
@findex modify-face
@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{customize-saved} to look at the options and faces that you have
+@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.
@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.
@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 outside of 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
@item @code{select}, @code{print}, @code{execute}, @code{backtab}
@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
-@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar},
+@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}
Miscellaneous function keys.
@item @code{f1}, @code{f2}, @dots{} @code{f35}
@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-},
saying whether to execute the command as requested, enable it and
execute it, or cancel. If you decide to enable the command, you are
asked whether to do this permanently or just for the current session.
-Enabling permanently works by automatically editing your @file{.emacs}
-file.
+(Enabling permanently works by automatically editing your @file{.emacs}
+file.) You can also type @kbd{!} to enable @emph{all} commands,
+for the current session only.
The direct mechanism for disabling a command is to put a
non-@code{nil} @code{disabled} property on the Lisp symbol for the
@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
one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
some additional information also.
- Each major mode has its own syntax table (though sometimes related
-major modes share one syntax table) which it installs in each buffer
+ Each major mode has its own syntax table (though related major modes
+sometimes share one syntax table) which it installs in each buffer
that uses the mode. The syntax table installed in the current buffer
is the one that all commands use, so we call it ``the'' syntax table.
loading your init file, and @samp{-u} (or @samp{--user}) to specify a
different user's init file (@pxref{Entering Emacs}).
+@cindex @file{default.el}, the default init file
There can also be a @dfn{default init file}, which is the library
named @file{default.el}, found via the standard search path for
libraries. The Emacs distribution contains no such library; your site
@code{inhibit-default-init} non-@code{nil}, then @file{default} is not
loaded.
+@cindex site init file
+@cindex @file{site-start.el}, the site startup file
Your site may also have a @dfn{site startup file}; this is named
-@file{site-start.el}, if it exists. 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}.
+@file{site-start.el}, if it exists. Like @file{default.el}, Emacs
+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}.
+
+ 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{load-path} (@pxref{Lisp Libraries}) specifies these directories.
+Many sites put these files in the @file{site-lisp} subdirectory of the
+Emacs installation directory, typically
+@file{/usr/local/share/emacs/site-lisp}.
If you have a large amount of code in your @file{.emacs} file, you
should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
@code{nil} stands for `false'.
@item Other Lisp objects:
-Write a single-quote (') followed by the Lisp object you want.
+Write a single-quote (@code{'}) followed by the Lisp object you want.
@end table
@node Init Examples
@item
@cindex loading Lisp libraries automatically
@cindex autoload Lisp libraries
-Tell Emacs to automatically load a Lisp library named @file{mypackage}
-(i.e.@: a file @file{mypackage.elc} or @file{mypackage.el}) when you
-the function @code{myfunction} in that library is called:
+Tell Emacs to find the definition for the function @code{myfunction}
+by loading a Lisp library named @file{mypackage} (i.e.@: a file
+@file{mypackage.elc} or @file{mypackage.el}):
@example
(autoload 'myfunction "mypackage" "Do what I say." t)
@end example
@noindent
-Here the string @code{"Do what I say."} is the function's documentation
-string made available to Emacs even when the package is not loaded
-(e.g., for commands such as @kbd{C-h a}), and @code{t} tells Emacs this
-function is interactive, that is, it can be invoked interactively by
-typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
+Here the string @code{"Do what I say."} is the function's
+documentation string. You specify it in the @code{autoload}
+definition so it will be available for help commands even when the
+package is not loaded. The last argument, @code{t}, indicates that
+this function is interactive; that is, it can be invoked interactively
+by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
+If the function is not interactive, omit the @code{t} or use
+@code{nil}.
@item
Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
Normally Emacs uses the environment variable @env{HOME} to find
@file{.emacs}; that's what @samp{~} means in a file name. But if you
-have done @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.
+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