@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.
- 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
@cindex Overwrite mode
@cindex mode, Overwrite
-@findex overwrite-mode
-@findex binary-overwrite-mode
Overwrite mode causes ordinary printing characters to replace existing
text instead of shoving it to the right. For example, if point is in
front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a
character whatever it may be, even if it is a digit---this gives you a
way to insert a character instead of replacing an existing character.
+@findex overwrite-mode
+@kindex INSERT
+ The command @code{overwrite-mode} is an exception to the rule that
+commands which toggle minor modes are normally not bound to keys: it is
+bound to the @key{INSERT} function key. This is because many other
+programs bind @key{INSERT} to similar functions.
+
+@findex binary-overwrite-mode
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
Options}.
Line Number mode enables continuous display in the mode line of the
-line number of point and Column Number mode enables display of the
+line number of point, and Column Number mode enables display of the
column number. @xref{Mode Line}.
Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
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.
@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
+active fields and other features.
@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.
* Face Customization:: How to edit the attributes of a face.
* Specific Customization:: Making a customization buffer for specific
options, faces, or groups.
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.
+ 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
take effect when you use the @samp{Set for Current Session} operation.
Some options have values with complex structure. For example, the
-value of @code{load-path} is a list of directories. Here is how it
-appears in the customization buffer:
+value of @code{file-coding-system-alist} is an association list. Here
+is how it appears in the customization buffer:
@smallexample
-Load Path:
-[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/site-lisp
-[INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp
-[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/leim
-[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/lisp
-[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp
-[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp/gnus
+File Coding System Alist: [Hide]
+[INS] [DEL] File regexp: \.elc\'
+ Choice: [Value Menu] Encoding/decoding pair:
+ Decoding: emacs-mule
+ Encoding: emacs-mule
+[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
+ Choice: [Value Menu] Encoding/decoding pair:
+ Decoding: raw-text
+ Encoding: raw-text-unix
+[INS] [DEL] File regexp: \.tar\'
+ Choice: [Value Menu] Encoding/decoding pair:
+ Decoding: no-conversion
+ Encoding: no-conversion
+[INS] [DEL] File regexp:
+ Choice: [Value Menu] Encoding/decoding pair:
+ Decoding: undecided
+ Encoding: nil
[INS]
- [State]: this item has been changed outside the customization buffer.
-List of directories to search for files to load....
+ [State]: this option is unchanged from its standard setting.
+Alist to decide a coding system to use for a file I/O operation. [Hide]
+The format is ((PATTERN . VAL) ...),
+where PATTERN is a regular expression matching a file name,
+@r{[@dots{}more lines of documentation@dots{}]}
@end smallexample
@noindent
-Each directory in the list appears on a separate line, and each line has
-several editable or active fields.
-
- You can edit any of the directory names. To delete a directory from
-the list, invoke @samp{[DEL]} on that line. To insert a new directory in
-the list, invoke @samp{[INS]} at the point where you want to insert it.
-
- You can also invoke @samp{[Current dir?]} to switch between including
-a specific named directory in the path, and including @code{nil} in the
-path. (@code{nil} in a search path means ``try the current
-directory.'')
+Each association in the list appears on four lines, with several
+editable or ``active'' fields. 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.
+
+To delete an association from the list, invoke the @samp{[DEL]} button
+for that item. To add an association, invoke @samp{[INS]} at the
+position where you want to add it. There is an @samp{[INS]} button
+between each pair of association, another at the beginning and another
+at the end, so you can add the new association at any position in the
+list.
@kindex TAB @r{(customization buffer)}
@kindex S-TAB @r{(customization buffer)}
previous active or editable field.
Typing @key{RET} on an editable field also moves forward, just like
-@key{TAB}. The reason for this is that people have a tendency to type
-@key{RET} when they are finished editing a field. If you have occasion
-to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q
-C-j}.
+@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;
-@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.
+@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
-Sometimes it is useful to record a comment on the value of an option
-which you have customized. Use the @samp{Add Comment} item from the
-@samp{[State]} menu to provide a field in which to edit a comment which
-will be saved and redisplayed if you re-customize the option later.
+ Sometimes it is useful to record a comment about a specific
+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 state of a group indicates whether anything in that group has been
edited, set or saved. You can select @samp{Set for Current Session},
[Reset] [Reset to Saved] [Erase Customization] [Finish]
@end smallexample
-@vindex Custom-buffer-done
+@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};
-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.
+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.
+
+@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
example of how a face looks:
@smallexample
-Custom Changed Face: (sample)
+Custom Changed Face:(sample) [Hide]
[State]: this face is unchanged from its standard setting.
Face used when the customize item has been changed.
-Attributes: [ ] Bold: [toggle] off
- [X] Italic: [toggle] on
- [ ] Underline: [toggle] off
- [ ] Inverse-Video: [toggle] on
- [ ] Foreground: black (sample)
- [ ] Background: white (sample)
- [ ] Stipple:
+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
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-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,
@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.
@node Hooks
@subsection Hooks
@cindex hook
-@cindex hook function
@cindex running a hook
@dfn{Hooks} are an important mechanism for customization of Emacs. A
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.
@group
(add-hook 'c-mode-common-hook
- (function (lambda ()
- (c-add-style "my-style" my-c-style t))))
+ '(lambda ()
+ (c-add-style "my-style" my-c-style t)))
@end group
@end example
numeric values:
@smallexample
-;; -*-mode: Lisp; fill-column: 75; comment-column: 50; -*-
+;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
@end smallexample
You can also specify the coding system for a file in this way: just
must be a coding system name that Emacs recognizes. @xref{Coding
Systems}.
+ The @code{eval} pseudo-variable, described below, can be specified in
+the first line as well.
+
+@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 accommodate
+for this, when Emacs visits a shell script, it looks for local variable
+specifications in the @emph{second} line.
+
A @dfn{local variables list} goes near the end of the file, in the
last page. (It is often best to put it on a page by itself.) The local
variables list starts with a line containing the string @samp{Local
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.
@kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse
events with keyboard events, but we recommend against it, because such
-sequences are inconvenient to type in.
+key sequences are inconvenient to use.
- As a user, you can redefine any key; but it might be 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.
+ 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 (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
(add-hook 'texinfo-mode-hook
'(lambda ()
- (define-key texinfo-mode-map
- "\C-cp"
+ (define-key texinfo-mode-map "\C-cp"
'backward-paragraph)
- (define-key texinfo-mode-map
- "\C-cn"
- 'forward-paragraph)
- ))
+ (define-key texinfo-mode-map "\C-cn"
+ 'forward-paragraph)))
@end example
@xref{Hooks}.
@node Rebinding
@subsection Changing Key Bindings Interactively
@cindex key rebinding, this session
-@cindex rebinding keys, this session
+@cindex redefining keys, this session
The way to redefine an Emacs key is to change its entry in a keymap.
You can change the global keymap, in which case the change is effective in
@example
(global-set-key "\C-xl" 'make-symbolic-link)
+@end example
+
+ To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
+string, you can use the Emacs Lisp escape sequences, @samp{\t},
+@samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds
+@kbd{C-x @key{TAB}}:
+
+@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 two examples, above, to use 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}
@end table
These names are conventional, but some systems (especially when using
-X windows) may use different names. To make certain what symbol is used
-for a given function key on your terminal, type @kbd{C-h c} followed by
-that key.
+X) may use different names. To make certain what symbol is used for a
+given function key on your terminal, type @kbd{C-h c} followed by that
+key.
A key sequence which contains function key symbols (or anything but
ASCII characters) must be a vector rather than a string. The vector
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 used with the X
-Window System. It treats the ``special'' keys as function keys named
-@code{tab}, @code{return}, @code{backspace}, @code{linefeed},
+ 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 ASCII characters @emph{if} they
have no bindings of their own. As a result, neither users nor Lisp
@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 solutions you can use. One is to specify a keyboard coding system,
+accented letters, rebinding these keys is a bit tricky. There are two
+solutions you can use. One is to specify a keyboard coding system,
using @code{set-keyboard-coding-system} (@pxref{Specify Coding}).
-Then you can bind these keys in the usual way,@footnote{Note that you
+Then you can bind these keys in the usual way@footnote{Note that you
should avoid the string syntax for binding 8-bit characters, since
-they will be interpreted as meta keys. @xref{(elisp)Strings of
-Events}.} by writing
+they will be interpreted as meta keys. @xref{Strings of
+Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this:
@example
(global-set-key [?@var{char}] 'some-function)
@end example
@noindent
-and typing the key you want to bind to insert @var{char}.
+Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
If you don't specify the keyboard coding system, that approach won't
work. Instead, you need to find out the actual code that the terminal
(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
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
;; @r{Translate @kbd{C-h} to @key{DEL}.}
(keyboard-translate ?\C-h ?\C-?)
-@need 3000
;; @r{Translate @key{DEL} to @kbd{C-h}.}
(keyboard-translate ?\C-? ?\C-h)
@end example
input processing; the keys that are looked up in keymaps contain the
characters that result from keyboard translation.
- Under X, the keyboard key named @key{DELETE} is a function key and is
-distinct from the ASCII character named @key{DEL}. @xref{Named ASCII
-Chars}. Keyboard translations affect only ASCII character input, not
-function keys; thus, the above example used under X does not affect the
-@key{DELETE} key. However, the translation above isn't necessary under
-X, because Emacs can also distinguish between the @key{BACKSPACE} key
-and @kbd{C-h}; and it normally treats @key{BACKSPACE} as @key{DEL}.
+ On a window system, the keyboard key named @key{DELETE} is a function
+key and is distinct from the ASCII character named @key{DEL}.
+@xref{Named ASCII Chars}. Keyboard translations affect only 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}.
All the Emacs commands which parse words or balance parentheses are
controlled by the @dfn{syntax table}. The syntax table says which
characters are opening delimiters, which are parts of words, which are
-string quotes, and so on. Each major mode has its own syntax table
-(though sometimes related major modes use the same one) which it
-installs in each buffer that uses that major mode. The syntax table
-installed in the current buffer is the one that all commands use, so we
-call it ``the'' syntax table. A syntax table is a Lisp object, a
-char-table, whose elements are numbers.
+string quotes, and so on. It does this by assigning each character to
+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 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.
@kindex C-h s
@findex describe-syntax
- To display a description of the contents of the current syntax table,
-type @kbd{C-h s} (@code{describe-syntax}). The description of each
-character includes both the string you would have to give to
+ To display a description of the contents of the current syntax
+table, type @kbd{C-h s} (@code{describe-syntax}). The description of
+each character includes both the string you would have to give to
@code{modify-syntax-entry} to set up that character's current syntax,
-and some English to explain that string if necessary.
+starting with the character which designates its syntax class, plus
+some English text to explain its meaning.
- For full information on the syntax table, see @ref{Syntax Tables,,
-Syntax Tables, elisp, The Emacs Lisp Reference Manual}.
+ A syntax table is actually a Lisp object, a char-table, whose
+elements are cons cells. For full information on the syntax table,
+see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
+Reference Manual}.
@node Init File
@section The Init File, @file{~/.emacs}
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
a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
@kbd{Control-Meta-A}.@refill
+@cindex international characters in @file{.emacs}
+@cindex non-ASCII characters in @file{.emacs}
+If you want to include non-ASCII characters in strings in your init
+file, you should consider putting a @w{@samp{-*-coding:
+@var{coding-system}-*-}} tag on the first line which states the coding
+system used to save your @file{.emacs}, as explained in @ref{Recognize
+Coding}. This is because the defaults for decoding non-ASCII text might
+not yet be set up by the time Emacs reads those parts of your init file
+which use such strings, possibly leading Emacs to decode those strings
+incorrectly.
+
@item Characters:
Lisp character constant syntax consists of a @samp{?} followed by
either a character or an escape sequence starting with @samp{\}.
strings and characters are not interchangeable in Lisp; some contexts
require one and some contexts require the other.
+@xref{Non-ASCII Rebinding}, for information about binding commands to
+keys which send non-ASCII characters.
+
@item True:
@code{t} stands for `true'.
@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
Here an absolute file name is used, so no searching is done.
+@item
+@cindex loading Lisp libraries automatically
+@cindex autoload Lisp libraries
+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. 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}.
@node Find Init
@subsection How Emacs Finds Your Init File
- Normally Emacs uses the environment variable @code{HOME} to find
+ 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 @code{LOGNAME} and
-@code{USER}; if neither of those exists, it uses effective user-ID.
-If that user name matches the real user-ID, then Emacs uses @code{HOME};
+It gets the 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
name in the system's data base of users.
@c LocalWords: backtab
HCoop / bpt / emacs.git / blobdiff