mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-25 10:47:00 +00:00
2420 lines
100 KiB
Plaintext
2420 lines
100 KiB
Plaintext
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
|
|
@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
|
|
@c 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},
|
|
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 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.
|
|
|
|
Another means of customization is the keyboard macro, which is a
|
|
sequence of keystrokes to be replayed with a single command.
|
|
@xref{Keyboard Macros}, for full instruction how to record, manage, and
|
|
replay sequences of keys.
|
|
|
|
@menu
|
|
* Minor Modes:: Each minor mode is one feature you can turn on
|
|
independently of any others.
|
|
* Easy Customization:: Convenient way to browse and change user options.
|
|
* 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".
|
|
* Syntax:: The syntax table controls how words and
|
|
expressions are parsed.
|
|
* Init File:: How to write common customizations in the
|
|
@file{.emacs} file.
|
|
@end menu
|
|
|
|
@node Minor Modes
|
|
@section Minor Modes
|
|
@cindex minor modes
|
|
@cindex mode, minor
|
|
|
|
Minor modes are optional features which you can turn on or off. For
|
|
example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
|
|
between words as you type. All the minor modes are independent of each
|
|
other and of the selected major mode. Most minor modes say in the mode
|
|
line when they are on; for example, @samp{Fill} in the mode line means
|
|
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
|
|
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
|
|
argument always turns the mode on, and an explicit zero argument or a
|
|
negative argument always turns it off.
|
|
|
|
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 (@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
|
|
mode}. @xref{Abbrevs}, for full information.
|
|
|
|
Auto Fill mode allows you to enter filled text without breaking lines
|
|
explicitly. Emacs inserts newlines as necessary to prevent lines from
|
|
becoming too long. @xref{Filling}.
|
|
|
|
Auto Save mode causes the contents of a buffer to be saved
|
|
periodically to reduce the amount of work you can lose in case of a
|
|
system crash. @xref{Auto Save}.
|
|
|
|
Enriched mode enables editing and saving of formatted text.
|
|
@xref{Formatted Text}.
|
|
|
|
Flyspell mode automatically highlights misspelled words.
|
|
@xref{Spelling}.
|
|
|
|
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.
|
|
@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}.
|
|
|
|
Outline minor mode provides the same facilities as the major mode
|
|
called Outline mode; but since it is a minor mode instead, you can
|
|
combine it with any major mode. @xref{Outline Mode}.
|
|
|
|
@cindex Overwrite mode
|
|
@cindex mode, Overwrite
|
|
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
|
|
@kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR}
|
|
as usual. In Overwrite mode, the command @kbd{C-q} inserts the next
|
|
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.
|
|
|
|
Here are some useful minor modes that 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}.
|
|
|
|
Icomplete mode displays an indication of available completions when
|
|
you are in the minibuffer and completion is active. @xref{Completion
|
|
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
|
|
column number. @xref{Mode Line}.
|
|
|
|
Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
|
|
Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
|
|
these modes are enabled by default when you use the X Window System.
|
|
|
|
In Transient Mark mode, every change in the buffer contents
|
|
``deactivates'' the mark, so that commands that operate on the region
|
|
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 Easy Customization
|
|
@section Easy Customization Interface
|
|
|
|
@cindex user option
|
|
Emacs has many @dfn{user options} which have values that you can set
|
|
in order to customize various commands. Many user options are
|
|
documented in this manual. Most user options are actually Lisp
|
|
variables (@pxref{Variables}), so their names appear in the Variable
|
|
Index (@pxref{Variable Index}). The rest are faces and their
|
|
attributes (@pxref{Faces}).
|
|
|
|
@findex customize
|
|
@cindex customization buffer
|
|
You can browse interactively through the user options and change
|
|
some of them using @kbd{M-x customize}. This command creates a
|
|
@dfn{customization buffer}, which offers commands to navigate through
|
|
a logically organized structure of the Emacs user options; you can
|
|
also use it to edit and set their values, and to save settings
|
|
permanently in your @file{~/.emacs} file (@pxref{Init File}).
|
|
|
|
The appearance of the example buffers in this section is typically
|
|
different under a window system, since faces are then used to indicate
|
|
the active fields and other features.
|
|
|
|
@menu
|
|
* Groups: Customization Groups. How options are classified in a structure.
|
|
* Changing a Variable:: 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
|
|
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
|
|
@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}.
|
|
|
|
@kbd{M-x customize} creates a customization buffer that shows the
|
|
top-level @code{Emacs} group and the second-level groups immediately
|
|
under it. It looks like this, in part:
|
|
|
|
@smallexample
|
|
/- Emacs group: ---------------------------------------------------\
|
|
[State]: visible group members are all at standard settings.
|
|
Customization of the One True Editor.
|
|
See also [Manual].
|
|
|
|
Editing group: [Go to Group]
|
|
Basic text editing facilities.
|
|
|
|
External group: [Go to Group]
|
|
Interfacing to external utilities.
|
|
|
|
@var{more second-level groups}
|
|
|
|
\- Emacs group end ------------------------------------------------/
|
|
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This says that the buffer displays the contents of the @code{Emacs}
|
|
group. The other groups are listed because they are its contents. But
|
|
they are listed differently, without indentation and dashes, because
|
|
@emph{their} contents are not included. Each group has a single-line
|
|
documentation string; the @code{Emacs} group also has a @samp{[State]}
|
|
line.
|
|
|
|
@cindex editable fields (customization buffer)
|
|
@cindex active fields (customization buffer)
|
|
Most of the text in the customization buffer is read-only, but it
|
|
typically includes some @dfn{editable fields} that you can edit. There
|
|
are also @dfn{active fields}; this means a field that does something
|
|
when you @dfn{invoke} it. To invoke an active field, either click on it
|
|
with @kbd{Mouse-1}, or move point to it and type @key{RET}.
|
|
|
|
For example, the phrase @samp{[Go to Group]} that appears in a
|
|
second-level group is an active field. Invoking the @samp{[Go to
|
|
Group]} field for a group creates a new customization buffer, which
|
|
shows that group and its contents. This field is a kind of hypertext
|
|
link to another group.
|
|
|
|
The @code{Emacs} group includes a few user options itself, but
|
|
mainly it contains other groups, which contain more groups, which
|
|
contain the user options. By browsing the hierarchy of groups, you
|
|
will eventually find the feature you are interested in customizing.
|
|
Then you can use the customization buffer to set the options
|
|
pertaining to that feature. You can also go straight to a particular
|
|
group by name, using the command @kbd{M-x customize-group}.
|
|
|
|
@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
|
|
variables and faces), and their structure.
|
|
|
|
In this buffer, you can show the contents of a group by invoking
|
|
@samp{[+]}. When the group contents are visible, this button changes to
|
|
@samp{[-]}; invoking that hides the group contents.
|
|
|
|
Each group, variable, or face name in this buffer has an active field
|
|
which says @samp{[Group]}, @samp{[Variable]} or @samp{[Face]}. Invoking
|
|
that active field creates an ordinary customization buffer showing just
|
|
that group and its contents, just that variable, or just that face.
|
|
This is the way to set values in it.
|
|
|
|
@node Changing a Variable
|
|
@subsection Changing a Variable
|
|
|
|
Here is an example of what a variable looks like in the
|
|
customization buffer:
|
|
|
|
@smallexample
|
|
Kill Ring Max: [Hide] 60
|
|
[State]: this variable 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{60} in this case, indicates
|
|
the current value of the variable. 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
|
|
@samp{[Show]} to show the value.
|
|
|
|
The line after the option name indicates the @dfn{customization state}
|
|
of the variable: in the example above, it says you have not changed the
|
|
option yet. The word @samp{[State]} at the beginning of this line is
|
|
active; you can get a menu of various operations by invoking it with
|
|
@kbd{Mouse-1} or @key{RET}. These operations are essential for
|
|
customizing the variable.
|
|
|
|
The line after the @samp{[State]} line displays the beginning of the
|
|
variable's documentation string. If there are more lines of
|
|
documentation, this line ends with @samp{[More]}; invoke this to show
|
|
the full documentation string.
|
|
|
|
To enter a new value for @samp{Kill Ring Max}, move point to the value
|
|
and edit it textually. For example, you can type @kbd{M-d}, then insert
|
|
another number.
|
|
|
|
When you begin to alter the text, you will see the @samp{[State]} line
|
|
change to say that you have edited the value:
|
|
|
|
@smallexample
|
|
[State]: you have edited the value as text, but not set the variable.
|
|
@end smallexample
|
|
|
|
@cindex setting option value
|
|
Editing the value does not actually set the variable. To do
|
|
that, you must @dfn{set} it. To do this, invoke the word
|
|
@samp{[State]} and choose @samp{Set for Current Session}.
|
|
|
|
The state of the variable changes visibly when you set it:
|
|
|
|
@smallexample
|
|
[State]: you have set this variable, but not saved it for future sessions.
|
|
@end smallexample
|
|
|
|
You don't have to worry about specifying a value that is not valid;
|
|
setting the variable checks for validity and will not really install an
|
|
unacceptable value.
|
|
|
|
@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.
|
|
(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)
|
|
|
|
Some variables have a small fixed set of possible legitimate values.
|
|
These variables don't let you edit the value textually. Instead, an
|
|
active field @samp{[Value Menu]} appears before the value; invoke this
|
|
field to edit the value. For a boolean ``on or off'' value, the active
|
|
field says @samp{[Toggle]}, and it changes to the other value.
|
|
@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
|
|
take effect when you use the @samp{Set for Current Session} operation.
|
|
|
|
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]
|
|
[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 variable 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 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)}
|
|
@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.
|
|
|
|
Typing @key{RET} on an editable field also moves forward, just like
|
|
@key{TAB}. We set it up this way because people often type @key{RET}
|
|
when they are finished editing a field. To insert a newline within an
|
|
editable field, use @kbd{C-o} or @kbd{C-q C-j}.
|
|
|
|
@cindex saving variable value
|
|
@cindex customized variables, saving
|
|
Setting the variable changes its value in the current Emacs session;
|
|
@dfn{saving} the value changes it for future sessions as well. To
|
|
save the variable, invoke @samp{[State]} and select the @samp{Save for
|
|
Future Sessions} operation. This works by writing code so as to set
|
|
the variable again, each time you start Emacs (@pxref{Saving
|
|
Customizations}).
|
|
|
|
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:
|
|
|
|
@table @samp
|
|
@item Reset
|
|
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 variable to the last saved value,
|
|
and updates the text accordingly.
|
|
|
|
@item Erase Customization
|
|
This sets the variable to its standard value, and updates the text
|
|
accordingly. This also eliminates any saved value for the option,
|
|
so that you will get the standard value in future Emacs sessions.
|
|
|
|
@item Use Backup Value
|
|
This sets the variable to a previous value that was set in the
|
|
customization buffer in this session. If you customize a variable
|
|
and then reset it, which discards the customized value,
|
|
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 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 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.
|
|
|
|
Near the top of the customization buffer there are two lines
|
|
containing several active fields:
|
|
|
|
@smallexample
|
|
[Set for Current Session] [Save for Future Sessions]
|
|
[Reset] [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 options in the buffer that could meaningfully
|
|
be set, saved or reset. They do not operate on options whose values
|
|
are hidden.
|
|
|
|
@node 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. Then you should load the
|
|
file by calling @code{load}. For example:
|
|
|
|
@example
|
|
(setq custom-file "~/.emacs-custom.el")
|
|
(load custom-file)
|
|
@end example
|
|
|
|
You can also use @code{custom-file} to specify different
|
|
customization files for different Emacs versions, like this:
|
|
|
|
@example
|
|
(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}
|
|
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
|
|
@subsection Customizing Faces
|
|
@cindex customizing faces
|
|
@cindex bold font
|
|
@cindex italic font
|
|
@cindex fonts and faces
|
|
|
|
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.
|
|
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
|
|
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.
|
|
|
|
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
|
|
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]}.
|
|
|
|
@findex modify-face
|
|
Another more basic way to set the attributes of a specific face is
|
|
with @kbd{M-x modify-face}. This command reads the name of a face, then
|
|
reads the attributes one by one. For the color and stipple attributes,
|
|
the attribute's current value is the default---type just @key{RET} if
|
|
you don't want to change that attribute. Type @samp{none} if you want
|
|
to clear out the attribute.
|
|
|
|
@node Specific Customization
|
|
@subsection Customizing Specific Items
|
|
|
|
Instead of finding the options you want to change by moving down
|
|
through the structure of groups, you can specify the particular variable,
|
|
face, or group that you want to customize.
|
|
|
|
@table @kbd
|
|
@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 variables, faces and groups
|
|
that match @var{regexp}.
|
|
@item M-x customize-changed-options @key{RET} @var{version} @key{RET}
|
|
Set up a customization buffer with all the variables, faces and groups
|
|
whose meaning has changed since Emacs version @var{version}.
|
|
@item M-x customize-saved
|
|
Set up a customization buffer containing all variables and faces that you
|
|
have saved with customization buffers.
|
|
@item M-x customize-customized
|
|
Set up a customization buffer containing all variables and faces that you
|
|
have customized but not saved.
|
|
@end table
|
|
|
|
@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.
|
|
|
|
@findex customize-face
|
|
Likewise, you can modify a specific face, chosen by name, using
|
|
@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,
|
|
using @kbd{M-x customize-group}. The immediate contents of the chosen
|
|
group, including user options, 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]}.
|
|
|
|
@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).
|
|
|
|
@findex customize-changed-options
|
|
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.
|
|
|
|
@findex customize-saved
|
|
@findex customize-customized
|
|
If you change option values and then decide the change was a
|
|
mistake, you can use two special commands to revisit your previous
|
|
changes. Use @kbd{M-x customize-saved} to look at the options that
|
|
you have saved. Use @kbd{M-x customize-customized} to look at the
|
|
options that you have set but not saved.
|
|
|
|
@node Custom Themes
|
|
@subsection Customization Themes
|
|
@cindex custom themes
|
|
|
|
@dfn{Custom themes} are collections of customized options that can be
|
|
enabled or disabled as a unit. You can use Custom themes to switch
|
|
quickly and easily between various collections of settings, and to
|
|
transfer such collections from one computer to another.
|
|
|
|
@findex customize-create-theme
|
|
To define a Custom theme, use the command
|
|
@kbd{M-x customize-create-theme}, which brings up a buffer named
|
|
@samp{*New Custom Theme*}. At the top of the buffer is an editable
|
|
field where you can specify the name of the theme. To add a
|
|
customization option to the theme, click on the @samp{INS} button to
|
|
open up a field where you can insert the name of the option. The
|
|
current value of that option is applied to the theme. After adding as
|
|
many options as you like, click on @samp{Done} to save the Custom
|
|
theme.
|
|
|
|
@vindex custom-theme-directory
|
|
Saving a Custom theme named @var{foo} writes its definition into the
|
|
file @file{@var{foo}-theme.el}, in the directory @file{~/.emacs.d/}
|
|
(you can specify the directory by setting
|
|
@code{custom-theme-directory}).
|
|
|
|
@findex load-theme
|
|
@findex enable-theme
|
|
@findex disable-theme
|
|
You can load the themes you've previously defined with the command
|
|
@code{load-theme}. It prompts for a theme name in the minibuffer,
|
|
then loads that theme if it isn't already loaded. It also
|
|
@dfn{enables} the theme, which means putting its settings into effect.
|
|
An enabled theme can be @dfn{disabled} with the command
|
|
@kbd{M-x disable-theme}; this returns the options specified in the
|
|
theme to their original values. To re-enable the theme, use the
|
|
command @kbd{M-x enable-theme}.
|
|
|
|
To enable a Custom theme named @var{foo} whenever Emacs is started up,
|
|
add the line @code{(load-theme '@var{foo})} to your @file{.emacs} file
|
|
(@pxref{Init File}).
|
|
|
|
Enabling a custom theme does not disable the themes already enabled;
|
|
instead, they are all enabled together. If two enabled Custom themes
|
|
specify different values for an option, the last theme to be enabled
|
|
takes effect.
|
|
|
|
The options that you set in the ordinary customization buffer
|
|
(@pxref{Easy Customization}) are also considered part of a Custom
|
|
theme, called @samp{user}. The @samp{user} theme is always enabled,
|
|
and always takes precedence over all other enabled Custom themes.
|
|
Additionally, the @samp{user} theme is recorded in your @file{.emacs}
|
|
file, rather than a @file{user-theme.el} file.
|
|
|
|
@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 need a value of a certain type. Often the value should
|
|
always be a string, or should always be a number. Sometimes we say that a
|
|
certain feature is turned on if a variable is ``non-@code{nil},'' meaning
|
|
that if the variable's value is @code{nil}, the feature is off, but the
|
|
feature is on for @emph{any} other value. The conventional value to use to
|
|
turn on the feature---since you have to pick one particular value when you
|
|
set the variable---is @code{t}.
|
|
|
|
Emacs uses many Lisp variables for internal record keeping, but the
|
|
most interesting variables for a non-programmer user are those that
|
|
are also @dfn{user options}, the variables that are meant for users to
|
|
change. Each user option that you can set with the customization
|
|
buffer is (if it is not a face) in fact a Lisp variable. Emacs does
|
|
not (usually) change the values of these variables; instead, you set
|
|
the values, and thereby alter and control the behavior of certain
|
|
Emacs commands. Use of the customization buffer is explained above
|
|
(@pxref{Easy Customization}); here we describe other aspects of Emacs
|
|
variables.
|
|
|
|
@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
|
|
@cindex hook
|
|
@cindex running a hook
|
|
|
|
@dfn{Hooks} are an important mechanism for customization of Emacs. A
|
|
hook is a Lisp variable which holds a list of functions, to be called on
|
|
some well-defined occasion. (This is called @dfn{running the hook}.)
|
|
The individual functions in the list are called the @dfn{hook functions}
|
|
of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
|
|
starts up, so the only hook functions in any given hook are the ones you
|
|
explicitly put there as customization.
|
|
|
|
Most major modes run one or more @dfn{mode hooks} as the last step of
|
|
initialization. This makes it easy for you to customize the behavior of
|
|
the mode, by setting up a hook function to override the local variable
|
|
assignments already made by the mode. But hooks are also used in other
|
|
contexts. For example, the hook @code{suspend-hook} runs just before
|
|
Emacs suspends itself (@pxref{Exiting}).
|
|
|
|
@cindex normal hook
|
|
Most Emacs hooks are @dfn{normal hooks}. This means that running the
|
|
hook operates by calling all the hook functions, unconditionally, with
|
|
no arguments. We have made an effort to keep most hooks normal so that
|
|
you can use them in a uniform way. Every variable in Emacs whose name
|
|
ends in @samp{-hook} is a normal hook.
|
|
|
|
@cindex abnormal hook
|
|
There are also a few @dfn{abnormal hooks}. These variables' names end
|
|
in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
|
|
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-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.
|
|
|
|
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:
|
|
|
|
@example
|
|
(add-hook 'text-mode-hook 'turn-on-auto-fill)
|
|
@end example
|
|
|
|
The next example shows how to use a hook to customize the indentation
|
|
of C code. (People often have strong personal preferences for one
|
|
format compared to another.) Here the hook function is an anonymous
|
|
lambda expression.
|
|
|
|
@example
|
|
@group
|
|
(setq my-c-style
|
|
'((c-comment-only-line-offset . 4)
|
|
@end group
|
|
@group
|
|
(c-cleanup-list . (scope-operator
|
|
empty-defun-braces
|
|
defun-close-semi))
|
|
@end group
|
|
@group
|
|
(c-offsets-alist . ((arglist-close . c-lineup-arglist)
|
|
(substatement-open . 0)))))
|
|
@end group
|
|
|
|
@group
|
|
(add-hook 'c-mode-common-hook
|
|
'(lambda ()
|
|
(c-add-style "my-style" my-c-style t)))
|
|
@end group
|
|
@end example
|
|
|
|
It is best to design your hook functions so that the order in which
|
|
they are executed does not matter. Any dependence on the order is
|
|
``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
|
|
|
|
@table @kbd
|
|
@item M-x make-local-variable @key{RET} @var{var} @key{RET}
|
|
Make variable @var{var} have a local value in the current buffer.
|
|
@item M-x kill-local-variable @key{RET} @var{var} @key{RET}
|
|
Make variable @var{var} use its global value in the current buffer.
|
|
@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
|
|
Mark variable @var{var} so that setting it will make it local to the
|
|
buffer that is current at that time.
|
|
@end table
|
|
|
|
@cindex local variables
|
|
Almost any variable can be made @dfn{local} to a specific Emacs
|
|
buffer. This means that its value in that buffer is independent of its
|
|
value in other buffers. A few variables are always local in every
|
|
buffer. Every other Emacs variable has a @dfn{global} value which is in
|
|
effect in all buffers that have not made the variable local.
|
|
|
|
@findex make-local-variable
|
|
@kbd{M-x make-local-variable} reads the name of a variable and makes it
|
|
local to the current buffer. Further changes in this buffer will not
|
|
affect others, and further changes in the global value will not affect this
|
|
buffer.
|
|
|
|
@findex make-variable-buffer-local
|
|
@cindex per-buffer variables
|
|
@kbd{M-x make-variable-buffer-local} reads the name of a variable and
|
|
changes the future behavior of the variable so that it will become local
|
|
automatically when it is set. More precisely, once a variable has been
|
|
marked in this way, the usual ways of setting the variable automatically
|
|
do @code{make-local-variable} first. We call such variables
|
|
@dfn{per-buffer} variables.
|
|
|
|
Major modes (@pxref{Major Modes}) always make variables local to the
|
|
buffer before setting the variables. This is why changing major modes
|
|
in one buffer has no effect on other buffers. Minor modes also work by
|
|
setting variables---normally, each minor mode has one controlling
|
|
variable which is non-@code{nil} when the mode is enabled (@pxref{Minor
|
|
Modes}). For most minor modes, the controlling variable is per buffer.
|
|
|
|
Emacs contains a number of variables that are always per-buffer.
|
|
These include @code{abbrev-mode}, @code{auto-fill-function},
|
|
@code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
|
|
@code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
|
|
@code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},
|
|
@code{selective-display-ellipses}, @code{selective-display},
|
|
@code{tab-width}, and @code{truncate-lines}. Some other variables are
|
|
always local in every buffer, but they are used for internal
|
|
purposes.@refill
|
|
|
|
A few variables cannot be local to a buffer because they are always
|
|
local to each display instead (@pxref{Multiple Displays}). If you try to
|
|
make one of these variables buffer-local, you'll get an error message.
|
|
|
|
@findex kill-local-variable
|
|
@kbd{M-x kill-local-variable} reads the name of a variable and makes
|
|
it cease to be local to the current buffer. The global value of the
|
|
variable henceforth is in effect in this buffer. Setting the major mode
|
|
kills all the local variables of the buffer except for a few variables
|
|
specially marked as @dfn{permanent locals}.
|
|
|
|
@findex setq-default
|
|
To set the global value of a variable, regardless of whether the
|
|
variable has a local value in the current buffer, you can use the Lisp
|
|
construct @code{setq-default}. This construct is used just like
|
|
@code{setq}, but it sets variables' global values instead of their local
|
|
values (if any). When the current buffer does have a local value, the
|
|
new global value may not be visible until you switch to another buffer.
|
|
Here is an example:
|
|
|
|
@example
|
|
(setq-default fill-column 75)
|
|
@end example
|
|
|
|
@noindent
|
|
@code{setq-default} is the only way to set the global value of a variable
|
|
that has been marked with @code{make-variable-buffer-local}.
|
|
|
|
@findex default-value
|
|
Lisp programs can use @code{default-value} to look at a variable's
|
|
default value. This function takes a symbol as argument and returns its
|
|
default value. The argument is evaluated; usually you must quote it
|
|
explicitly. For example, here's how to obtain the default value of
|
|
@code{fill-column}:
|
|
|
|
@example
|
|
(default-value 'fill-column)
|
|
@end example
|
|
|
|
@node File Variables
|
|
@subsection Local Variables in Files
|
|
@cindex local variables in files
|
|
@cindex file local variables
|
|
|
|
A file can specify local variable values for use when you edit the
|
|
file with Emacs. Visiting the file checks for local variable
|
|
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
|
|
line, or with a local variables list. Here's how to specify them in the
|
|
first line:
|
|
|
|
@example
|
|
-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
|
|
@end example
|
|
|
|
@noindent
|
|
You can specify any number of variables/value pairs in this way, each
|
|
pair with a colon and semicolon as shown above. @code{mode:
|
|
@var{modename};} specifies the major mode; this should come first in the
|
|
line. The @var{value}s are not evaluated; they are used literally.
|
|
Here is an example that specifies Lisp mode and sets two variables with
|
|
numeric values:
|
|
|
|
@smallexample
|
|
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
|
|
@end smallexample
|
|
|
|
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}. @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.
|
|
|
|
@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
|
|
Variables:}, and ends with a line containing the string @samp{End:}. In
|
|
between come the variable names and values, one set per line, as
|
|
@samp{@var{variable}:@: @var{value}}. The @var{value}s are not
|
|
evaluated; they are used literally. If a file has both a local
|
|
variables list and a @samp{-*-} line, Emacs processes @emph{everything}
|
|
in the @samp{-*-} line first, and @emph{everything} in the local
|
|
variables list afterward.
|
|
|
|
Here is an example of a local variables list:
|
|
|
|
@example
|
|
;;; Local Variables: ***
|
|
;;; mode:lisp ***
|
|
;;; comment-column:0 ***
|
|
;;; comment-start: ";;; " ***
|
|
;;; comment-end:"***" ***
|
|
;;; End: ***
|
|
@end example
|
|
|
|
As you see, each line starts with the prefix @samp{;;; } and each line
|
|
ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix
|
|
and suffix based on the first line of the list, by finding them
|
|
surrounding the magic string @samp{Local Variables:}; then it
|
|
automatically discards them from the other lines of the list.
|
|
|
|
The usual reason for using a prefix and/or suffix is to embed the
|
|
local variables list in a comment, so it won't confuse other programs
|
|
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.
|
|
|
|
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
|
|
or not is a matter of individual taste, not a matter of the contents of
|
|
particular files. If you want to use Auto Fill, set up major mode hooks
|
|
with your @file{.emacs} file to turn it on (when appropriate) for you
|
|
alone (@pxref{Init File}). Don't use a local variable list to impose
|
|
your taste on everyone.
|
|
|
|
The start of the local variables list must be no more than 3000
|
|
characters from the end of the file, and must be in the last page if the
|
|
file is divided into pages. Otherwise, Emacs will not notice it is
|
|
there. The purpose of this rule is so that a stray @samp{Local
|
|
Variables:}@: not in the last page does not confuse Emacs, and so that
|
|
visiting a long file that is all one page and has no local variables
|
|
list need not take the time to search the whole file.
|
|
|
|
Use the command @code{normal-mode} to reset the local variables and
|
|
major mode of a buffer according to the file name and contents,
|
|
including the local variables list if any. @xref{Choosing Modes}.
|
|
|
|
@findex enable-local-variables
|
|
The variable @code{enable-local-variables} controls whether to process
|
|
local variables in files, and thus gives you a chance to override them.
|
|
Its default value is @code{t}, which means do process local variables in
|
|
files. If you set the value to @code{nil}, Emacs simply ignores local
|
|
variables in files. Any other value says to query you about each file
|
|
that has local variables, showing you the local variable specifications
|
|
so you can judge.
|
|
|
|
@findex enable-local-eval
|
|
The @code{eval} ``variable,'' and certain actual variables, create a
|
|
special risk; when you visit someone else's file, local variable
|
|
specifications for these could affect your Emacs in arbitrary ways.
|
|
Therefore, the variable @code{enable-local-eval} controls whether Emacs
|
|
processes @code{eval} variables, as well variables with names that end
|
|
in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
|
|
and certain other variables. The three possibilities for the variable's
|
|
value are @code{t}, @code{nil}, and anything else, just as for
|
|
@code{enable-local-variables}. The default is @code{maybe}, which is
|
|
neither @code{t} nor @code{nil}, so normally Emacs does ask for
|
|
confirmation about file settings for these variables.
|
|
|
|
@findex safe-local-eval-forms
|
|
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.
|
|
|
|
@node Key Bindings
|
|
@section Customizing Key Bindings
|
|
@cindex key bindings
|
|
|
|
This section describes @dfn{key bindings}, which map keys to commands,
|
|
and @dfn{keymaps}, which record key bindings. It also explains how
|
|
to customize key bindings.
|
|
|
|
Recall that a command is a Lisp function whose definition provides for
|
|
interactive use. Like every Lisp function, a command has a function
|
|
name which usually consists of lower-case letters and hyphens.
|
|
|
|
@menu
|
|
* Keymaps:: Generalities. The global keymap.
|
|
* Prefix Keymaps:: Keymaps for prefix keys.
|
|
* Local Keymaps:: Major and minor modes have their own keymaps.
|
|
* Minibuffer Maps:: The minibuffer uses its own local keymaps.
|
|
* Rebinding:: How to redefine one key's meaning conveniently.
|
|
* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
|
|
* Function Keys:: Rebinding terminal function keys.
|
|
* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
|
|
* Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} characters such as Latin-1.
|
|
* Mouse Buttons:: Rebinding mouse buttons in Emacs.
|
|
* Disabling:: Disabling a command means confirmation is required
|
|
before it can be executed. This is done to protect
|
|
beginners from surprises.
|
|
@end menu
|
|
|
|
@node Keymaps
|
|
@subsection Keymaps
|
|
@cindex keymap
|
|
|
|
The bindings between key sequences and command functions are recorded
|
|
in data structures called @dfn{keymaps}. Emacs has many of these, each
|
|
used on particular occasions.
|
|
|
|
Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
|
|
of @dfn{input events} that have a meaning as a unit. Input events
|
|
include characters, function keys and mouse buttons---all the inputs
|
|
that you can send to the computer with your terminal. A key sequence
|
|
gets its meaning from its @dfn{binding}, which says what command it
|
|
runs. The function of keymaps is to record these bindings.
|
|
|
|
@cindex global keymap
|
|
The @dfn{global} keymap is the most important keymap because it is
|
|
always in effect. The global keymap defines keys for Fundamental mode;
|
|
most of these definitions are common to most or all major modes. Each
|
|
major or minor mode can have its own keymap which overrides the global
|
|
definitions of some keys.
|
|
|
|
For example, a self-inserting character such as @kbd{g} is
|
|
self-inserting because the global keymap binds it to the command
|
|
@code{self-insert-command}. The standard Emacs editing characters such
|
|
as @kbd{C-a} also get their standard meanings from the global keymap.
|
|
Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
|
|
by storing the new binding in the proper place in the global map.
|
|
@xref{Rebinding}.
|
|
|
|
Meta characters work differently; Emacs translates each Meta
|
|
character into a pair of characters starting with @key{ESC}. When you
|
|
type the character @kbd{M-a} in a key sequence, Emacs replaces it with
|
|
@kbd{@key{ESC} a}. A meta key comes in as a single input event, but
|
|
becomes two events for purposes of key bindings. The reason for this is
|
|
historical, and we might change it someday.
|
|
|
|
@cindex function key
|
|
Most modern keyboards have function keys as well as character keys.
|
|
Function keys send input events just as character keys do, and keymaps
|
|
can have bindings for them.
|
|
|
|
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
|
|
terminal type properly, it recognizes the character sequences forming
|
|
function keys wherever they occur in a key sequence (not just at the
|
|
beginning). Thus, for most purposes, you can pretend the function keys
|
|
reach Emacs directly and ignore their encoding as character sequences.
|
|
|
|
@cindex mouse
|
|
Mouse buttons also produce input events. These events come with other
|
|
data---the window and position where you pressed or released the button,
|
|
and a time stamp. But only the choice of button matters for key
|
|
bindings; the other data matters only if a command looks at it.
|
|
(Commands designed for mouse invocation usually do look at the other
|
|
data.)
|
|
|
|
A keymap records definitions for single events. Interpreting a key
|
|
sequence of multiple events involves a chain of keymaps. The first
|
|
keymap gives a definition for the first event; this definition is
|
|
another keymap, which is used to look up the second event in the
|
|
sequence, and so on.
|
|
|
|
Key sequences can mix function keys and characters. For example,
|
|
@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
|
|
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 (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
|
|
|
|
A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
|
|
which holds the definition for the event that immediately follows
|
|
that prefix.
|
|
|
|
The definition of a prefix key is usually the keymap to use for
|
|
looking up the following event. The definition can also be a Lisp
|
|
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
|
|
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.
|
|
|
|
Aside from ordinary prefix keys, there is a fictitious ``prefix key''
|
|
which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
|
|
Reference Manual}, for special information about menu bar key bindings.
|
|
Mouse button events that invoke pop-up menus are also prefix keys; see
|
|
@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
|
|
details.
|
|
|
|
Some prefix keymaps are stored in variables with names:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@vindex ctl-x-map
|
|
@code{ctl-x-map} is the variable name for the map used for characters that
|
|
follow @kbd{C-x}.
|
|
@item
|
|
@vindex help-map
|
|
@code{help-map} is for characters that follow @kbd{C-h}.
|
|
@item
|
|
@vindex esc-map
|
|
@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
|
|
characters are actually defined by this map.
|
|
@item
|
|
@vindex ctl-x-4-map
|
|
@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
|
|
@item
|
|
@vindex mode-specific-map
|
|
@code{mode-specific-map} is for characters that follow @kbd{C-c}.
|
|
@end itemize
|
|
|
|
@node Local Keymaps
|
|
@subsection Local Keymaps
|
|
|
|
@cindex local keymap
|
|
So far we have explained the ins and outs of the global map. Major
|
|
modes customize Emacs by providing their own key bindings in @dfn{local
|
|
keymaps}. For example, C mode overrides @key{TAB} to make it indent the
|
|
current line for C code. Portions of text in the buffer can specify
|
|
their own keymaps to substitute for the keymap of the buffer's major
|
|
mode.
|
|
|
|
@cindex minor mode keymap
|
|
Minor modes can also have local keymaps. Whenever a minor mode is
|
|
in effect, the definitions in its keymap override both the major
|
|
mode's local keymap and the global keymap.
|
|
|
|
@vindex c-mode-map
|
|
@vindex lisp-mode-map
|
|
The local keymaps for Lisp mode and several other major modes always
|
|
exist even when not in use. These are kept in variables named
|
|
@code{lisp-mode-map} and so on. For major modes less often used, the
|
|
local keymap is normally constructed only when the mode is used for the
|
|
first time in a session. This is to save space. If you wish to change
|
|
one of these keymaps, you must use the major mode's @dfn{mode
|
|
hook}---see below.
|
|
|
|
All minor mode keymaps are created in advance. There is no way to
|
|
defer their creation until the first time the minor mode is enabled.
|
|
|
|
A local keymap can locally redefine a key as a prefix key by defining
|
|
it as a prefix keymap. If the key is also defined globally as a prefix,
|
|
then its local and global definitions (both keymaps) effectively
|
|
combine: both of them are used to look up the event that follows the
|
|
prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
|
|
another keymap, and that keymap defines @kbd{C-z} as a command, this
|
|
provides a local meaning for @kbd{C-c C-z}. This does not affect other
|
|
sequences that start with @kbd{C-c}; if those sequences don't have their
|
|
own local bindings, their global bindings remain in effect.
|
|
|
|
Another way to think of this is that Emacs handles a multi-event key
|
|
sequence by looking in several keymaps, one by one, for a binding of the
|
|
whole key sequence. First it checks the minor mode keymaps for minor
|
|
modes that are enabled, then it checks the major mode's keymap, and then
|
|
it checks the global keymap. This is not precisely how key lookup
|
|
works, but it's good enough for understanding ordinary circumstances.
|
|
|
|
@cindex rebinding major mode keys
|
|
@findex define-key
|
|
To change the local bindings of a major mode, you must change the
|
|
mode's local keymap. Normally you must wait until the first time the
|
|
mode is used, because most major modes don't create their keymaps until
|
|
then. If you want to specify something in your @file{~/.emacs} file to
|
|
change a major mode's bindings, you must use the mode's mode hook to
|
|
delay the change until the mode is first used.
|
|
|
|
For example, the command @code{texinfo-mode} to select Texinfo mode
|
|
runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
|
|
to add local bindings (not very useful, we admit) for @kbd{C-c n} and
|
|
@kbd{C-c p} in Texinfo mode:
|
|
|
|
@example
|
|
(add-hook 'texinfo-mode-hook
|
|
'(lambda ()
|
|
(define-key texinfo-mode-map "\C-cp"
|
|
'backward-paragraph)
|
|
(define-key texinfo-mode-map "\C-cn"
|
|
'forward-paragraph)))
|
|
@end example
|
|
|
|
@xref{Hooks}.
|
|
|
|
@node Minibuffer Maps
|
|
@subsection Minibuffer Keymaps
|
|
|
|
@cindex minibuffer keymaps
|
|
@vindex minibuffer-local-map
|
|
@vindex minibuffer-local-ns-map
|
|
@vindex minibuffer-local-completion-map
|
|
@vindex minibuffer-local-must-match-map
|
|
The minibuffer has its own set of local keymaps; they contain various
|
|
completion and exit commands.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{minibuffer-local-map} is used for ordinary input (no completion).
|
|
@item
|
|
@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
|
|
just like @key{RET}. This is used mainly for Mocklisp compatibility.
|
|
@item
|
|
@code{minibuffer-local-completion-map} is for permissive completion.
|
|
@item
|
|
@code{minibuffer-local-must-match-map} is for strict completion and
|
|
for cautious completion.
|
|
@end itemize
|
|
|
|
@node Rebinding
|
|
@subsection Changing Key Bindings Interactively
|
|
@cindex key rebinding, 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
|
|
all major modes (except those that have their own overriding local
|
|
definitions for the same key). Or you can change the current buffer's
|
|
local map, which affects all buffers using the same major mode.
|
|
|
|
@findex global-set-key
|
|
@findex local-set-key
|
|
@findex global-unset-key
|
|
@findex local-unset-key
|
|
@table @kbd
|
|
@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
|
|
Define @var{key} globally to run @var{cmd}.
|
|
@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
|
|
Define @var{key} locally (in the major mode now in effect) to run
|
|
@var{cmd}.
|
|
@item M-x global-unset-key @key{RET} @var{key}
|
|
Make @var{key} undefined in the global map.
|
|
@item M-x local-unset-key @key{RET} @var{key}
|
|
Make @var{key} undefined locally (in the major mode now in effect).
|
|
@end table
|
|
|
|
For example, suppose you like to execute commands in a subshell within
|
|
an Emacs buffer, instead of suspending Emacs and executing commands in
|
|
your login shell. Normally, @kbd{C-z} is bound to the function
|
|
@code{suspend-emacs} (when not using the X Window System), but you can
|
|
change @kbd{C-z} to invoke an interactive subshell within Emacs, by
|
|
binding it to @code{shell} as follows:
|
|
|
|
@example
|
|
M-x global-set-key @key{RET} C-z shell @key{RET}
|
|
@end example
|
|
|
|
@noindent
|
|
@code{global-set-key} reads the command name after the key. After you
|
|
press the key, a message like this appears so that you can confirm that
|
|
you are binding the key you want:
|
|
|
|
@example
|
|
Set key C-z to command:
|
|
@end example
|
|
|
|
You can redefine function keys and mouse events in the same way; just
|
|
type the function key or click the mouse when it's time to specify the
|
|
key to rebind.
|
|
|
|
You can rebind a key that contains more than one event in the same
|
|
way. Emacs keeps reading the key to rebind until it is a complete key
|
|
(that is, not a prefix key). Thus, if you type @kbd{C-f} for
|
|
@var{key}, that's the end; the minibuffer is entered immediately to
|
|
read @var{cmd}. But if you type @kbd{C-x}, another character is read;
|
|
if that is @kbd{4}, another character is read, and so on. For
|
|
example,
|
|
|
|
@example
|
|
M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
|
|
@end example
|
|
|
|
@noindent
|
|
redefines @kbd{C-x 4 $} to run the (fictitious) command
|
|
@code{spell-other-window}.
|
|
|
|
The two-character keys consisting of @kbd{C-c} followed by a letter
|
|
are reserved for user customizations. Lisp programs are not supposed to
|
|
define these keys, so the bindings you make for them will be available
|
|
in all major modes and will never get in the way of anything.
|
|
|
|
You can remove the global definition of a key with
|
|
@code{global-unset-key}. This makes the key @dfn{undefined}; if you
|
|
type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
|
|
a key undefined in the current major mode keymap, which makes the global
|
|
definition (or lack of one) come back into effect in that major mode.
|
|
|
|
If you have redefined (or undefined) a key and you subsequently wish
|
|
to retract the change, undefining the key will not do the job---you need
|
|
to redefine the key with its standard definition. To find the name of
|
|
the standard definition of a key, go to a Fundamental mode buffer and
|
|
use @kbd{C-h c}. The documentation of keys in this manual also lists
|
|
their command names.
|
|
|
|
If you want to prevent yourself from invoking a command by mistake, it
|
|
is better to disable the command than to undefine the key. A disabled
|
|
command is less work to invoke when you really want to.
|
|
@xref{Disabling}.
|
|
|
|
@node Init Rebinding
|
|
@subsection Rebinding Keys in Your Init File
|
|
|
|
If you have a set of key bindings that you like to use all the time,
|
|
you can specify them in your @file{.emacs} file by using their Lisp
|
|
syntax. (@xref{Init File}.)
|
|
|
|
The simplest method for doing this works for @acronym{ASCII} characters and
|
|
Meta-modified @acronym{ASCII} characters only. This method uses a string to
|
|
represent the key sequence you want to rebind. For example, here's how
|
|
to bind @kbd{C-z} to @code{shell}:
|
|
|
|
@example
|
|
(global-set-key "\C-z" 'shell)
|
|
@end example
|
|
|
|
@noindent
|
|
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 the key sequence @kbd{C-x M-l}:
|
|
|
|
@example
|
|
(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
|
|
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 @acronym{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,
|
|
or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use
|
|
the more general method of rebinding, which uses a vector to specify the
|
|
key sequence.
|
|
|
|
The way to write a vector in Emacs Lisp is with square brackets around
|
|
the vector elements. Use spaces to separate the elements. If an
|
|
element is a symbol, simply write the symbol's name---no other
|
|
delimiters or punctuation are needed. If a vector element is a
|
|
character, write it as a Lisp character constant: @samp{?} followed by
|
|
the character as it would appear in a string.
|
|
|
|
Here are examples of using vectors to rebind @kbd{C-=} (a control
|
|
character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=}
|
|
is not), @kbd{H-a} (a Hyper character; @acronym{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 six examples above to use vectors:
|
|
|
|
@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 all of the characters in order within the square brackets that
|
|
delimit the vector.
|
|
|
|
Language and coding systems can cause problems with key bindings
|
|
for non-@acronym{ASCII} characters. @xref{Non-ASCII Rebinding}.
|
|
|
|
@node Function Keys
|
|
@subsection Rebinding Function Keys
|
|
|
|
Key sequences can contain function keys as well as ordinary
|
|
characters. Just as Lisp characters (actually integers) represent
|
|
keyboard characters, Lisp symbols represent function keys. If the
|
|
function key has a word as its label, then that word is also the name of
|
|
the corresponding Lisp symbol. Here are the conventional Lisp names for
|
|
common function keys:
|
|
|
|
@table @asis
|
|
@item @code{left}, @code{up}, @code{right}, @code{down}
|
|
Cursor arrow keys.
|
|
|
|
@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
|
|
Other cursor repositioning 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}
|
|
Miscellaneous function keys.
|
|
|
|
@item @code{f1}, @code{f2}, @dots{} @code{f35}
|
|
Numbered function keys (across the top of the keyboard).
|
|
|
|
@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
|
|
@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
|
|
@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
|
|
Keypad keys (to the right of the regular keyboard), with names or punctuation.
|
|
|
|
@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
|
|
Keypad keys with digits.
|
|
|
|
@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
|
|
Keypad PF keys.
|
|
@end table
|
|
|
|
These names are conventional, but some systems (especially when using
|
|
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
|
|
@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)
|
|
@end example
|
|
|
|
@noindent
|
|
To bind the right-arrow key to the command @code{forward-char}, you can
|
|
use this expression:
|
|
|
|
@example
|
|
(global-set-key [right] 'forward-char)
|
|
@end example
|
|
|
|
@noindent
|
|
This uses the Lisp syntax for a vector containing the symbol
|
|
@code{right}. (This binding is present in Emacs by default.)
|
|
|
|
@xref{Init Rebinding}, for more information about using vectors for
|
|
rebinding.
|
|
|
|
You can mix function keys and characters in a key sequence. This
|
|
example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
|
|
|
|
@example
|
|
(global-set-key [?\C-x next] 'forward-page)
|
|
@end example
|
|
|
|
@noindent
|
|
where @code{?\C-x} is the Lisp character constant for the character
|
|
@kbd{C-x}. The vector element @code{next} is a symbol and therefore
|
|
does not take a question mark.
|
|
|
|
You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
|
|
@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent
|
|
these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
|
|
@samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name.
|
|
Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a
|
|
word:
|
|
|
|
@example
|
|
(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 labelled @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 labelled @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. 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. 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}
|
|
(octal code 011). If you do want to distinguish, make one binding for
|
|
this @acronym{ASCII} character, and another for the ``function key'' @code{tab}.
|
|
|
|
With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
|
|
between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
|
|
because the terminal sends the same character in both cases.
|
|
|
|
@node Non-ASCII Rebinding
|
|
@subsection Non-@acronym{ASCII} Characters on the Keyboard
|
|
@cindex rebinding non-@acronym{ASCII} keys
|
|
@cindex non-@acronym{ASCII} keys, binding
|
|
|
|
If your keyboard has keys that send non-@acronym{ASCII}
|
|
characters, such as accented letters, rebinding these keys
|
|
must be done by using a vector like this@footnote{Note that
|
|
you should avoid the string syntax for binding
|
|
non-@acronym{ASCII} characters, since they will be
|
|
interpreted as meta keys. @xref{Strings of Events,,,elisp,
|
|
The Emacs Lisp Reference Manual}.}:
|
|
|
|
@example
|
|
(global-set-key [?@var{char}] 'some-function)
|
|
@end example
|
|
|
|
@noindent
|
|
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 a coding system for that file that supports the
|
|
character in question. @xref{Init Syntax}.
|
|
|
|
@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
|
|
@cindex mouse button events
|
|
@cindex rebinding mouse buttons
|
|
@cindex click events
|
|
@cindex drag events
|
|
@cindex down events
|
|
@cindex button down events
|
|
|
|
Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
|
|
mouse events in Emacs are @dfn{click} events; these happen when you
|
|
press a button and release it without moving the mouse. You can also
|
|
get @dfn{drag} events, when you move the mouse while holding the button
|
|
down. Drag events happen when you finally let go of the button.
|
|
|
|
The symbols for basic click events are @code{mouse-1} for the leftmost
|
|
button, @code{mouse-2} for the next, and so on. Here is how you can
|
|
redefine the second mouse button to split the current window:
|
|
|
|
@example
|
|
(global-set-key [mouse-2] 'split-window-vertically)
|
|
@end example
|
|
|
|
The symbols for drag events are similar, but have the prefix
|
|
@samp{drag-} before the word @samp{mouse}. For example, dragging the
|
|
first button generates a @code{drag-mouse-1} event.
|
|
|
|
You can also define bindings for events that occur when a mouse button
|
|
is pressed down. These events start with @samp{down-} instead of
|
|
@samp{drag-}. Such events are generated only if they have key bindings.
|
|
When you get a button-down event, a corresponding click or drag event
|
|
will always follow.
|
|
|
|
@cindex double clicks
|
|
@cindex triple clicks
|
|
If you wish, you can distinguish single, double, and triple clicks. A
|
|
double click means clicking a mouse button twice in approximately the
|
|
same place. The first click generates an ordinary click event. The
|
|
second click, if it comes soon enough, generates a double-click event
|
|
instead. The event type for a double-click event starts with
|
|
@samp{double-}: for example, @code{double-mouse-3}.
|
|
|
|
This means that you can give a special meaning to the second click at
|
|
the same place, but it must act on the assumption that the ordinary
|
|
single click definition has run when the first click was received.
|
|
|
|
This constrains what you can do with double clicks, but user interface
|
|
designers say that this constraint ought to be followed in any case. A
|
|
double click should do something similar to the single click, only
|
|
``more so.'' The command for the double-click event should perform the
|
|
extra work for the double click.
|
|
|
|
If a double-click event has no binding, it changes to the
|
|
corresponding single-click event. Thus, if you don't define a
|
|
particular double click specially, it executes the single-click command
|
|
twice.
|
|
|
|
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.
|
|
|
|
Emacs also records multiple presses in drag and button-down events.
|
|
For example, when you press a button twice, then move the mouse while
|
|
holding the button, Emacs gets a @samp{double-drag-} event. And at the
|
|
moment when you press it down for the second time, Emacs gets a
|
|
@samp{double-down-} event (which is ignored, like all button-down
|
|
events, if it has no binding).
|
|
|
|
@vindex double-click-time
|
|
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-},
|
|
@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-}
|
|
or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
|
|
|
|
A frame includes areas that don't show text from the buffer, such as
|
|
the mode line and the scroll bar. You can tell whether a mouse button
|
|
comes from a special area of the screen by means of dummy ``prefix
|
|
keys.'' For example, if you click the mouse in the mode line, you get
|
|
the prefix key @code{mode-line} before the ordinary mouse-button symbol.
|
|
Thus, here is how to define the command for clicking the first button in
|
|
a mode line to run @code{scroll-up}:
|
|
|
|
@example
|
|
(global-set-key [mode-line mouse-1] 'scroll-up)
|
|
@end example
|
|
|
|
Here is the complete list of these dummy prefix keys and their
|
|
meanings:
|
|
|
|
@table @code
|
|
@item mode-line
|
|
The mouse was in the mode line of a window.
|
|
@item vertical-line
|
|
The mouse was in the vertical line separating side-by-side windows. (If
|
|
you use scroll bars, they appear in place of these vertical lines.)
|
|
@item vertical-scroll-bar
|
|
The mouse was in a vertical scroll bar. (This is the only kind of
|
|
scroll bar Emacs currently supports.)
|
|
@ignore
|
|
@item horizontal-scroll-bar
|
|
The mouse was in a horizontal scroll bar. Horizontal scroll bars do
|
|
horizontal scrolling, and people don't use them often.
|
|
@end ignore
|
|
@end table
|
|
|
|
You can put more than one mouse button in a key sequence, but it isn't
|
|
usual to do so.
|
|
|
|
@node Disabling
|
|
@subsection Disabling Commands
|
|
@cindex disabled command
|
|
|
|
Disabling a command marks the command as requiring confirmation before it
|
|
can be executed. The purpose of disabling a command is to prevent
|
|
beginning users from executing it by accident and being confused.
|
|
|
|
An attempt to invoke a disabled command interactively in Emacs
|
|
displays a window containing the command's name, its documentation, and
|
|
some instructions on what to do immediately; then Emacs asks for input
|
|
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.) 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
|
|
command. Here is the Lisp program to do this:
|
|
|
|
@example
|
|
(put 'delete-region 'disabled t)
|
|
@end example
|
|
|
|
If the value of the @code{disabled} property is a string, that string
|
|
is included in the message displayed when the command is used:
|
|
|
|
@example
|
|
(put 'delete-region 'disabled
|
|
"It's better to use `kill-region' instead.\n")
|
|
@end example
|
|
|
|
@findex disable-command
|
|
@findex enable-command
|
|
You can make a command disabled either by editing the @file{.emacs}
|
|
file directly or with the command @kbd{M-x disable-command}, which edits
|
|
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
|
|
function from Lisp programs.
|
|
|
|
@node Syntax
|
|
@section The Syntax Table
|
|
@cindex syntax table
|
|
|
|
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. 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
|
|
@code{modify-syntax-entry} to set up that character's current syntax,
|
|
starting with the character which designates its syntax class, plus
|
|
some English text to explain its meaning.
|
|
|
|
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}
|
|
@cindex init file
|
|
@cindex Emacs initialization file
|
|
@cindex key rebinding, permanent
|
|
@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}).
|
|
|
|
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
|
|
named @file{default.el}, found via the standard search path for
|
|
libraries. The Emacs distribution contains no such library; your site
|
|
may create one for local customizations. If this library exists, it is
|
|
loaded whenever you start Emacs (except when you specify @samp{-q}).
|
|
But your init file, if any, is loaded first; if it sets
|
|
@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. 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}. 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{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
|
|
Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
|
|
for more information about compiling Emacs Lisp programs.
|
|
|
|
If you are going to write actual Emacs Lisp programs that go beyond
|
|
minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
|
|
@ifinfo
|
|
@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
|
|
Manual}.
|
|
@end ifinfo
|
|
|
|
@menu
|
|
* Init Syntax:: Syntax of constants in Emacs Lisp.
|
|
* Init Examples:: How to do some things with an init file.
|
|
* Terminal Init:: Each terminal type can have an init file.
|
|
* Find Init:: How Emacs finds the init file.
|
|
@end menu
|
|
|
|
@node Init Syntax
|
|
@subsection Init File Syntax
|
|
|
|
The @file{.emacs} file contains one or more Lisp function call
|
|
expressions. Each of these consists of a function name followed by
|
|
arguments, all surrounded by parentheses. For example, @code{(setq
|
|
fill-column 60)} calls the function @code{setq} to set the variable
|
|
@code{fill-column} (@pxref{Filling}) to 60.
|
|
|
|
You can set any Lisp variable with @code{setq}, but with certain
|
|
variables @code{setq} won't do what you probably want in the
|
|
@file{.emacs} file. Some variables automatically become buffer-local
|
|
when set with @code{setq}; what you want in @file{.emacs} is to set
|
|
the default value, using @code{setq-default}. Some customizable minor
|
|
mode variables do special things to enable the mode when you set them
|
|
with Customize, but ordinary @code{setq} won't do that; to enable the
|
|
mode in your @file{.emacs} file, call the minor mode command. The
|
|
following section has examples of both of these methods.
|
|
|
|
The second argument to @code{setq} is an expression for the new
|
|
value of the variable. This can be a constant, a variable, or a
|
|
function call expression. In @file{.emacs}, constants are used most
|
|
of the time. They can be:
|
|
|
|
@table @asis
|
|
@item Numbers:
|
|
Numbers are written in decimal, with an optional initial minus sign.
|
|
|
|
@item Strings:
|
|
@cindex Lisp string syntax
|
|
@cindex string syntax
|
|
Lisp string syntax is the same as C string syntax with a few extra
|
|
features. Use a double-quote character to begin and end a string constant.
|
|
|
|
In a string, you can include newlines and special characters literally.
|
|
But often it is cleaner to use backslash sequences for them: @samp{\n}
|
|
for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
|
|
@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
|
|
escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
|
|
@samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
|
|
Backslash and double-quote are the only characters for which backslash
|
|
sequences are mandatory.
|
|
|
|
@samp{\C-} can be used as a prefix for a control character, as in
|
|
@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
|
|
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-@acronym{ASCII} characters in @file{.emacs}
|
|
If you want to include non-@acronym{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-@acronym{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{\}.
|
|
Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
|
|
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-@acronym{ASCII} characters.
|
|
|
|
@item True:
|
|
@code{t} stands for `true'.
|
|
|
|
@item False:
|
|
@code{nil} stands for `false'.
|
|
|
|
@item Other Lisp objects:
|
|
Write a single-quote (@code{'}) followed by the Lisp object you want.
|
|
@end table
|
|
|
|
@node Init Examples
|
|
@subsection Init File Examples
|
|
|
|
Here are some examples of doing certain commonly desired things with
|
|
Lisp expressions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Make @key{TAB} in C mode just insert a tab if point is in the middle of a
|
|
line.
|
|
|
|
@example
|
|
(setq c-tab-always-indent nil)
|
|
@end example
|
|
|
|
Here we have a variable whose value is normally @code{t} for `true'
|
|
and the alternative is @code{nil} for `false'.
|
|
|
|
@item
|
|
Make searches case sensitive by default (in all buffers that do not
|
|
override this).
|
|
|
|
@example
|
|
(setq-default case-fold-search nil)
|
|
@end example
|
|
|
|
This sets the default value, which is effective in all buffers that do
|
|
not have local values for the variable. Setting @code{case-fold-search}
|
|
with @code{setq} affects only the current buffer's local value, which
|
|
is not what you probably want to do in an init file.
|
|
|
|
@item
|
|
@vindex user-mail-address
|
|
Specify your own email address, if Emacs can't figure it out correctly.
|
|
|
|
@example
|
|
(setq user-mail-address "coon@@yoyodyne.com")
|
|
@end example
|
|
|
|
Various Emacs packages that need your own email address use the value of
|
|
@code{user-mail-address}.
|
|
|
|
@item
|
|
Make Text mode the default mode for new buffers.
|
|
|
|
@example
|
|
(setq default-major-mode 'text-mode)
|
|
@end example
|
|
|
|
Note that @code{text-mode} is used because it is the command for
|
|
entering Text mode. The single-quote before it makes the symbol a
|
|
constant; otherwise, @code{text-mode} would be treated as a variable
|
|
name.
|
|
|
|
@need 1500
|
|
@item
|
|
Set up defaults for the Latin-1 character set
|
|
which supports most of the languages of Western Europe.
|
|
|
|
@example
|
|
(set-language-environment "Latin-1")
|
|
@end example
|
|
|
|
@need 1500
|
|
@item
|
|
Turn off Line Number mode, a global minor mode.
|
|
|
|
@example
|
|
(line-number-mode 0)
|
|
@end example
|
|
|
|
@need 1500
|
|
@item
|
|
Turn on Auto Fill mode automatically in Text mode and related modes.
|
|
|
|
@example
|
|
(add-hook 'text-mode-hook
|
|
'(lambda () (auto-fill-mode 1)))
|
|
@end example
|
|
|
|
This shows how to add a hook function to a normal hook variable
|
|
(@pxref{Hooks}). The function we supply is a list starting with
|
|
@code{lambda}, with a single-quote in front of it to make it a list
|
|
constant rather than an expression.
|
|
|
|
It's beyond the scope of this manual to explain Lisp functions, but for
|
|
this example it is enough to know that the effect is to execute
|
|
@code{(auto-fill-mode 1)} when Text mode is entered. You can replace
|
|
that with any other expression that you like, or with several
|
|
expressions in a row.
|
|
|
|
Emacs comes with a function named @code{turn-on-auto-fill} whose
|
|
definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
|
|
way to write the above example is as follows:
|
|
|
|
@example
|
|
(add-hook 'text-mode-hook 'turn-on-auto-fill)
|
|
@end example
|
|
|
|
@item
|
|
Load the installed Lisp library named @file{foo} (actually a file
|
|
@file{foo.elc} or @file{foo.el} in a standard Emacs directory).
|
|
|
|
@example
|
|
(load "foo")
|
|
@end example
|
|
|
|
When the argument to @code{load} is a relative file name, not starting
|
|
with @samp{/} or @samp{~}, @code{load} searches the directories in
|
|
@code{load-path} (@pxref{Lisp Libraries}).
|
|
|
|
@item
|
|
Load the compiled Lisp file @file{foo.elc} from your home directory.
|
|
|
|
@example
|
|
(load "~/foo.elc")
|
|
@end example
|
|
|
|
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}
|
|
(@pxref{Init Rebinding}).
|
|
|
|
@example
|
|
(global-set-key "\C-xl" 'make-symbolic-link)
|
|
@end example
|
|
|
|
or
|
|
|
|
@example
|
|
(define-key global-map "\C-xl" 'make-symbolic-link)
|
|
@end example
|
|
|
|
Note once again the single-quote used to refer to the symbol
|
|
@code{make-symbolic-link} instead of its value as a variable.
|
|
|
|
@item
|
|
Do the same thing for Lisp mode only.
|
|
|
|
@example
|
|
(define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
|
|
@end example
|
|
|
|
@item
|
|
Redefine all keys which now run @code{next-line} in Fundamental mode
|
|
so that they run @code{forward-line} instead.
|
|
|
|
@findex substitute-key-definition
|
|
@example
|
|
(substitute-key-definition 'next-line 'forward-line
|
|
global-map)
|
|
@end example
|
|
|
|
@item
|
|
Make @kbd{C-x C-v} undefined.
|
|
|
|
@example
|
|
(global-unset-key "\C-x\C-v")
|
|
@end example
|
|
|
|
One reason to undefine a key is so that you can make it a prefix.
|
|
Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
|
|
prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
|
|
definition.
|
|
|
|
@item
|
|
Make @samp{$} have the syntax of punctuation in Text mode.
|
|
Note the use of a character constant for @samp{$}.
|
|
|
|
@example
|
|
(modify-syntax-entry ?\$ "." text-mode-syntax-table)
|
|
@end example
|
|
|
|
@item
|
|
Enable the use of the command @code{narrow-to-region} without confirmation.
|
|
|
|
@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
|
|
@subsection Terminal-specific Initialization
|
|
|
|
Each terminal type can have a Lisp library to be loaded into Emacs when
|
|
it is run on that type of terminal. For a terminal type named
|
|
@var{termtype}, the library is called @file{term/@var{termtype}} and it is
|
|
found by searching the directories @code{load-path} as usual and trying the
|
|
suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
|
|
subdirectory @file{term} of the directory where most Emacs libraries are
|
|
kept.@refill
|
|
|
|
The usual purpose of the terminal-specific library is to map the
|
|
escape sequences used by the terminal's function keys onto more
|
|
meaningful names, using @code{function-key-map}. See the file
|
|
@file{term/lk201.el} for an example of how this is done. Many function
|
|
keys are mapped automatically according to the information in the
|
|
Termcap data base; the terminal-specific library needs to map only the
|
|
function keys that Termcap does not specify.
|
|
|
|
When the terminal type contains a hyphen, only the part of the name
|
|
before the first hyphen is significant in choosing the library name.
|
|
Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
|
|
the library @file{term/aaa}. The code in the library can use
|
|
@code{(getenv "TERM")} to find the full terminal type name.@refill
|
|
|
|
@vindex term-file-prefix
|
|
The library's name is constructed by concatenating the value of the
|
|
variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
|
|
file can prevent the loading of the terminal-specific library by setting
|
|
@code{term-file-prefix} to @code{nil}.
|
|
|
|
@vindex term-setup-hook
|
|
Emacs runs the hook @code{term-setup-hook} at the end of
|
|
initialization, after both your @file{.emacs} file and any
|
|
terminal-specific library have been read in. Add hook functions to this
|
|
hook if you wish to override part of any of the terminal-specific
|
|
libraries and to define initializations for terminals that do not have a
|
|
library. @xref{Hooks}.
|
|
|
|
@node Find Init
|
|
@subsection How Emacs Finds Your Init File
|
|
|
|
Normally Emacs uses the environment variable @env{HOME} to find
|
|
@file{.emacs}; that's what @samp{~} means in a file name. If @file{.emacs}
|
|
is not found directly inside @file{~/}, Emacs looks for it in
|
|
@file{~/.emacs.d/}.
|
|
|
|
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
|
|
@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
|
|
|
|
@ignore
|
|
arch-tag: c68abddb-4410-4fb5-925f-63394e971d93
|
|
@end ignore
|