custom.texi 96.7 KB
Newer Older
Dave Love's avatar
Dave Love committed
@c This is part of the Emacs manual.
@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2004
Dave Love's avatar
Dave Love committed
@c  Free Software Foundation, Inc.
Dave Love's avatar
Dave Love committed
4 5 6 7 8 9 10
@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
Richard M. Stallman's avatar
Richard M. Stallman committed
11 12
Manual} for how to make more far-reaching changes.  @xref{X Resources},
for information on using X resources to customize Emacs.
Dave Love's avatar
Dave Love committed

  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
17 18 19 20
@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.
Dave Love's avatar
Dave Love committed

22 23 24 25 26
  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.

Dave Love's avatar
Dave Love committed
27 28 29
* Minor Modes::		Each minor mode is one feature you can turn on
			  independently of any others.
30 31
* Easy Customization::
                        Convenient way to browse and change user options.
Dave Love's avatar
Dave Love committed
32 33 34 35 36 37 38 39
* Variables::		Many Emacs commands examine Emacs variables
			  to decide what to do; by setting variables,
			  you can control their functioning.
* Key Bindings::	The keymaps say what command each key runs.
			  By changing them, you can "redefine keys".
* Keyboard Translations::
                        If your keyboard passes an undesired code
			   for a key, you can tell Emacs to
			   substitute another code.
Dave Love's avatar
Dave Love committed
41 42 43
* Syntax::		The syntax table controls how words and
			   expressions are parsed.
* Init File::		How to write common customizations in the
			  @file{.emacs} file.
Dave Love's avatar
Dave Love committed
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
@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.

68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
  Some minor modes are global: while enabled, they affect everything
you do in the Emacs session, in all buffers.  Other minor modes are
buffer-local; they apply only to the current buffer, so you can enable
the mode in certain buffers and not others.

  For most minor modes, the command name is also the name of a
variable which directly controls the mode.  The mode is enabled
whenever this variable's value is non-@code{nil}, and the minor-mode
command works by setting the variable.  For example, the command
@code{outline-minor-mode} works by setting the value of
@code{outline-minor-mode} as a variable; it is this variable that
directly turns Outline minor mode on and off.  To check whether a
given minor mode works this way, use @kbd{C-h v} to ask for
documentation on the variable name.

  These minor-mode variables provide a good way for Lisp programs to turn
minor modes on and off; they are also useful in a file's local variables
list.  But please think twice before setting minor modes with a local
variables list, because most minor modes are matter of user
preference---other users editing the same file might not want the same
minor modes you prefer.

  The buffer-local minor modes include Abbrev mode, Auto Fill mode,
91 92
Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents mode,
Outline minor mode, Overwrite mode, and Binary Overwrite mode.
Dave Love's avatar
Dave Love committed
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

  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.

  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.

  ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
@samp{^}, @samp{/} and @samp{~} combine with the following letter, to
119 120 121
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}.
Dave Love's avatar
Dave Love committed
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136

  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.

137 138 139 140 141 142 143 144
@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
Dave Love's avatar
Dave Love committed
145 146 147
  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.
148 149
In Binary Overwrite mode, digits after @kbd{C-q} specify an
octal character code, as usual.
Dave Love's avatar
Dave Love committed
150 151 152 153 154 155 156 157 158 159 160 161

  The following minor modes normally apply to all buffers at once.
Since each is enabled or disabled by the value of a variable, you
@emph{can} set them differently for particular buffers, by explicitly
making the corresponding variables local in those buffers.

  Icomplete mode displays an indication of available completions when
you are in the minibuffer and completion is active.  @xref{Completion

  Line Number mode enables continuous display in the mode line of the
line number of point, and Column Number mode enables display of the
Dave Love's avatar
Dave Love committed
column number.  @xref{Mode Line}.
Dave Love's avatar
Dave Love committed
164 165 166 167 168 169 170 171 172 173

  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
Dave Love's avatar
Dave Love committed
region highlighted (currently only when using X).  @xref{Mark}.
Dave Love's avatar
Dave Love committed
175 176

@node Easy Customization
177 178 179 180 181 182 183 184
@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.  Most user options are
documented in this manual.  Each user option is actually a Lisp
variable (@pxref{Variables}), so their names appear in the Variable
Index (@pxref{Variable Index}).
Dave Love's avatar
Dave Love committed
185 186 187

@findex customize
@cindex customization buffer
188 189 190 191 192 193 194 195 196 197
  You can browse interactively through the 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.

Dave Love's avatar
Dave Love committed
199 200 201 202
* Groups: Customization Groups.
                             How options are classified in a structure.
* Changing an Option::       How to edit a value and set an option.
* Saving Customizations::    Details of saving customizations.
Dave Love's avatar
Dave Love committed
204 205 206 207 208 209
* Face Customization::       How to edit the attributes of a face.
* Specific Customization::   Making a customization buffer for specific
                                options, faces, or groups.
@end menu

@node Customization Groups
@subsection Customization Groups
Dave Love's avatar
Dave Love committed
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226
@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:

/- Emacs group: ---------------------------------------------------\
      [State]: visible group members are all at standard settings.
   Customization of the One True Editor.
   See also [Manual].

227 228 229 230
Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm
   [State]: this option is unchanged from its standard setting.
How to ask for confirmation when leaving Emacs. [More]

Editing group: [Go to Group]
Dave Love's avatar
Dave Love committed
232 233
Basic text editing facilities.

External group: [Go to Group]
Dave Love's avatar
Dave Love committed
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
Interfacing to external utilities.

@var{more second-level groups}

\- Emacs group end ------------------------------------------------/

@end smallexample

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]}

@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.

265 266 267 268 269 270 271
  The @code{Emacs} group includes a few user options itself, but
mainly it contains other groups, which contain more groups, which
contain the user options.  By browsing the hierarchy of groups, you
will eventually find the feature you are interested in customizing.
Then you can use the customization buffer to set the options and faces
pertaining to that feature.  You can also go straight to a particular
group by name, using the command @kbd{M-x customize-group}.
Dave Love's avatar
Dave Love committed
272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289

@findex customize-browse
  You can view the structure of customization groups on a larger scale
with @kbd{M-x customize-browse}.  This command creates a special kind of
customization buffer which shows only the names of the groups (and
options and faces), and their structure.

  In this buffer, you can show the contents of a group by invoking
@samp{[+]}.  When the group contents are visible, this button changes to
@samp{[-]}; invoking that hides the group contents.

  Each group, option or face name in this buffer has an active field
which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}.  Invoking
that active field creates an ordinary customization buffer showing just
that group and its contents, just that option, or just that face.
This is the way to set values in it.

@node Changing an Option
@subsection Changing an Option
Dave Love's avatar
Dave Love committed
291 292 293 294 295

  Here is an example of what a user option looks like in the
customization buffer:

Kill Ring Max: [Hide] 60
Dave Love's avatar
Dave Love committed
297 298 299 300
   [State]: this option is unchanged from its standard setting.
Maximum length of kill ring before oldest elements are thrown away.
@end smallexample

  The text following @samp{[Hide]}, @samp{60} in this case, indicates
Dave Love's avatar
Dave Love committed
302 303 304 305 306 307 308 309 310 311
the current value of the option.  If you see @samp{[Show]} instead of
@samp{[Hide]}, it means that the value is hidden; the customization
buffer initially hides values that take up several lines.  Invoke
@samp{[Show]} to show the value.

  The line after the option name indicates the @dfn{customization state}
of the option: in the example above, it says you have not changed the
option yet.  The word @samp{[State]} at the beginning of this line is
active; you can get a menu of various operations by invoking it with
@kbd{Mouse-1} or @key{RET}.  These operations are essential for
customizing the user option.
Dave Love's avatar
Dave Love committed
313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330

  The line after the @samp{[State]} line displays the beginning of the
option's documentation string.  If there are more lines of
documentation, this line ends with @samp{[More]}; invoke this to show
the full documentation string.

  To enter a new value for @samp{Kill Ring Max}, move point to the value
and edit it textually.  For example, you can type @kbd{M-d}, then insert
another number.

  When you begin to alter the text, you will see the @samp{[State]} line
change to say that you have edited the value:

[State]: you have edited the value as text, but not set the option.
@end smallexample

@cindex setting option value
  Editing the value does not actually set the option.  To do
Dave Love's avatar
Dave Love committed
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359
that, you must @dfn{set} the option.  To do this, invoke the word
@samp{[State]} and choose @samp{Set for Current Session}.

  The state of the option changes visibly when you set it:

[State]: you have set this option, 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 option 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.

  Some options have a small fixed set of possible legitimate values.
These options don't let you edit the value textually.  Instead, an
active field @samp{[Value Menu]} appears before the value; invoke this
field to edit the value.  For a boolean ``on or off'' value, the active
field says @samp{[Toggle]}, and it changes to the other value.
@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
take effect when you use the @samp{Set for Current Session} operation.

  Some options have values with complex structure.  For example, the
360 361
value of @code{file-coding-system-alist} is an association list.  Here
is how it appears in the customization buffer:
Dave Love's avatar
Dave Love committed
362 363

364 365 366 367 368 369 370
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:
371 372
            Decoding: raw-text
            Encoding: raw-text-unix
373 374 375 376 377 378 379 380
[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
382 383
   [State]: this option is unchanged from its standard setting.
Alist to decide a coding system to use for a file I/O operation. [Hide]
384 385 386
The format is ((PATTERN . VAL) ...),
where PATTERN is a regular expression matching a file name,
@r{[@dots{}more lines of documentation@dots{}]}
Dave Love's avatar
Dave Love committed
387 388 389
@end smallexample

390 391 392 393 394 395 396 397 398 399 400 401
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
Dave Love's avatar
Dave Love committed
402 403 404 405 406 407 408 409 410 411 412 413

@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
414 415 416
@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}.
Dave Love's avatar
Dave Love committed
417 418

@cindex saving option value
@cindex customized options, saving
Dave Love's avatar
Dave Love committed
  Setting the option changes its value in the current Emacs session;
421 422 423
@dfn{saving} the value changes it for future sessions as well.  To
save the option, invoke @samp{[State]} and select the @samp{Save for
Future Sessions} operation.  This works by writing code so as to set
the option again, each time you start Emacs (@pxref{Saving

Dave Love's avatar
Dave Love committed
  You can also restore the option to its standard value by invoking
428 429
@samp{[State]} and selecting the @samp{Erase Customization} operation.
There are actually three reset operations:
Dave Love's avatar
Dave Love committed
430 431 432 433 434 435 436 437 438 439 440

@table @samp
@item Reset
If you have made some modifications and not yet set the option,
this restores the text in the customization buffer to match
the actual value.

@item Reset to Saved
This restores the value of the option to the last saved value,
and updates the text accordingly.

Dave Love's avatar
Dave Love committed
@item Erase Customization
Dave Love's avatar
Dave Love committed
442 443 444
This sets the option to its standard value, and updates the text
accordingly.  This also eliminates any saved value for the option,
so that you will get the standard value in future Emacs sessions.
445 446 447

@item Use Backup Value
This sets the option to a previous value that was set in the
448 449
customization buffer in this session.  If you customize an option
and then reset it, which discards the customized value,
you can get the customized value back again with this operation.
Dave Love's avatar
Dave Love committed
451 452
@end table

Dave Love's avatar
Dave Love committed
@cindex comments on customized options
454 455 456 457 458
  Sometimes it is useful to record a comment about a specific
customization.  Use the @samp{Add Comment} item from the
@samp{[State]} menu to create a field for entering the comment.  The
comment you enter will be saved, and displayed again if you again view
the same option in a customization buffer, even in another session.
Dave Love's avatar
Dave Love committed

Dave Love's avatar
Dave Love committed
460 461 462 463 464 465 466 467 468 469 470
  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:

 [Set for Current Session] [Save for Future Sessions]
Dave Love's avatar
Dave Love committed
 [Reset] [Reset to Saved] [Erase Customization]   [Finish]
Dave Love's avatar
Dave Love committed
472 473
@end smallexample

@vindex custom-buffer-done-function
Dave Love's avatar
Dave Love committed
Dave Love's avatar
Dave Love committed
Invoking @samp{[Finish]} either buries or kills this customization
477 478 479 480 481
buffer according to the setting of the option
@code{custom-buffer-done-function}; the default is to bury the buffer.
Each of the other fields performs an operation---set, save or
reset---on each of the items in the buffer that could meaningfully be
set, saved or reset.
Dave Love's avatar
Dave Love committed

@node Saving Customizations
@subsection Saving Customizations
485 486 487 488 489

@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
490 491 492 493 494 495 496
@code{custom-file} to the name of that file.  If you are using Emacs
version 21.4 or later, Emacs loads the file right after your
@file{.emacs} if you did not load it already.  In earlier versions,
you have to load the file in your @file{~/emacs}.  If you customize
@code{custom-file} through the @samp{Customize} interface, you still
need to load it in your @file{.emacs}, but there is no need to set
it.  For example:
497 498

;; @r{if not set through the @samp{Customize} interface:}
(setq custom-file "~/.emacs-custom")
501 502 503 504

;; @r{in Emacs versions before 21.4 or if set through}
;; @r{the @samp{Customize} interface.}
(load "~/.emacs-custom")
505 506
@end example

507 508
  You can also use @code{custom-file} to specify different
customization files for different Emacs versions, like this:
509 510

511 512 513 514 515 516 517 518 519 520 521
(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"))
       ;; @r{Emacs version 21.4 or later.}
       (setq custom-file "~/.custom-21.4.el")))

(load custom-file)
522 523 524 525 526 527 528 529
@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.

Dave Love's avatar
Dave Love committed
@node Face Customization
@subsection Customizing Faces
Dave Love's avatar
Dave Love committed
532 533 534 535 536 537 538 539 540 541 542
@cindex customizing faces
@cindex bold font
@cindex italic font
@cindex fonts and faces

  In addition to user options, some customization groups also include
faces.  When you show the contents of a group, both the user options and
the faces in the group appear in the customization buffer.  Here is an
example of how a face looks:

Custom Changed Face:(sample) [Hide]
Dave Love's avatar
Dave Love committed
   [State]: this face is unchanged from its standard setting.
545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560
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: *
Dave Love's avatar
Dave Love committed
561 562 563 564 565 566 567 568
@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.

569 570 571 572 573 574 575 576 577
  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.
Dave Love's avatar
Dave Love committed
578 579 580 581 582 583 584

  Setting, saving and resetting a face work like the same operations for
options (@pxref{Changing an Option}).

  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
Dave Love's avatar
Dave Love committed
586 587 588 589 590 591 592 593 594 595 596
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
Dave Love's avatar
Dave Love committed
598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615

  Instead of finding the options you want to change by moving down
through the structure of groups, you can specify the particular option,
face or group that you want to customize.

@table @kbd
@item M-x customize-option @key{RET} @var{option} @key{RET}
Set up a customization buffer with just one option, @var{option}.
@item M-x customize-face @key{RET} @var{face} @key{RET}
Set up a customization buffer with just one face, @var{face}.
@item M-x customize-group @key{RET} @var{group} @key{RET}
Set up a customization buffer with just one group, @var{group}.
@item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
Set up a customization buffer with all the options, faces and groups
that match @var{regexp}.
@item M-x customize-changed-options @key{RET} @var{version} @key{RET}
Set up a customization buffer with all the options, faces and groups
whose meaning has changed since Emacs version @var{version}.
@item M-x customize-saved
Dave Love's avatar
Dave Love committed
617 618 619 620 621 622 623 624
Set up a customization buffer containing all options and faces that you
have saved with customization buffers.
@item M-x customize-customized
Set up a customization buffer containing all options and faces that you
have customized but not saved.
@end table

@findex customize-option
  If you want to alter a particular user option with the
Dave Love's avatar
Dave Love committed
626 627 628 629 630 631 632 633
customization buffer, and you know its name, you can use the command
@kbd{M-x customize-option} and specify the option name.  This sets up
the customization buffer with just one option---the one that you asked
for.  Editing, setting and saving the value work as described above, but
only for the specified option.

@findex customize-face
  Likewise, you can modify a specific face, chosen by name, using
634 635
@kbd{M-x customize-face}.  By default it operates on the face used
on the character after point.
Dave Love's avatar
Dave Love committed
636 637 638 639

@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
Dave Love's avatar
Dave Love committed
641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663
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 and faces that you have
Dave Love's avatar
Dave Love committed
665 666 667
saved.  Use @kbd{M-x customize-customized} to look at the options and
faces that you have set but not saved.

668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692
@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 the @dfn{user
options}, the variables that are meant for users to change.  Each user
Richard M. Stallman's avatar
Richard M. Stallman committed
option that you can set with the customization buffer is, in fact, a
694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772
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; here we describe other aspects of Emacs

* 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}
@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,

C-h v fill-column @key{RET}
@end example

displays something like this:

fill-column's value is 70

*Column beyond which automatic line-wrapping should happen.
Automatically becomes buffer-local when set in any fashion.
@end smallexample

The star at the beginning of the documentation indicates that this
variable is a user option.  @kbd{C-h v} is not restricted to user
options; it allows any variable name.

@findex set-variable
  The most convenient way to set a specific user option is with @kbd{M-x
set-variable}.  This reads the variable name with the minibuffer (with
completion), and then reads a Lisp expression for the new value using
the minibuffer a second time.  For example,

M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
@end example

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}:

(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

  Setting variables, like all means of customizing Emacs except where
otherwise stated, affects only the current Emacs session.

Dave Love's avatar
Dave Love committed
773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805
@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,
Stefan Monnier's avatar
Stefan Monnier committed
@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
Dave Love's avatar
Dave Love committed
807 808 809 810
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.

811 812 813 814 815 816 817
  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.
Dave Love's avatar
Dave Love committed
818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847

  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:

(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.

(setq my-c-style
  '((c-comment-only-line-offset . 4)
@end group
    (c-cleanup-list . (scope-operator
@end group
    (c-offsets-alist . ((arglist-close . c-lineup-arglist)
			(substatement-open . 0)))))
@end group

(add-hook 'c-mode-common-hook
848 849
  '(lambda ()
     (c-add-style "my-style" my-c-style t)))
Dave Love's avatar
Dave Love committed
850 851 852 853 854 855 856 857
@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.

858 859 860 861 862
  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.
To clear them out, you can do @code{(setq @var{hook-variable} nil)}.

Dave Love's avatar
Dave Love committed
863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980
@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

@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

  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:

(setq-default fill-column 75)
@end example

@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

(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:

-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
@end example

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:

Eli Zaretskii's avatar
Eli Zaretskii committed
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
Dave Love's avatar
Dave Love committed
982 983 984 985 986
@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
987 988
Systems}.  @w{@samp{unibyte: t}} specifies unibyte loading for a
particular Lisp file.  @xref{Enabling Multibyte}.
Dave Love's avatar
Dave Love committed

990 991 992 993 994
  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
Richard M. Stallman's avatar
Richard M. Stallman committed
interpreter, so you cannot put any local variables there.  To accommodate
996 997 998
for this, when Emacs visits a shell script, it looks for local variable
specifications in the @emph{second} line.

Dave Love's avatar
Dave Love committed
999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031
  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:

;;; 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
1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047
@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:

# Local Variables:
# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
#   -Dmumble=blaah"
# End:
@end example
Dave Love's avatar
Dave Love committed

  Some ``variable names'' have special meanings in a local variables
1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
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
Dave Love's avatar
Dave Love committed
1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112

  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 option @code{enable-local-eval} controls whether Emacs
processes @code{eval} variables, as well variables with names that end
in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
and certain other variables.  The three possibilities for the option's
value are @code{t}, @code{nil}, and anything else, just as for
@code{enable-local-variables}.  The default is @code{maybe}, which is
neither @code{t} nor @code{nil}, so normally Emacs does ask for
confirmation about file settings for these variables.

1113 1114 1115 1116 1117 1118
@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.

Dave Love's avatar
Dave Love committed
1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139
@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.

* 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.
Dave Love's avatar
Dave Love committed
1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215
* 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.

   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 many 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

  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.
Dave Love's avatar
Dave Love committed

  As a user, you can redefine any key; but it is usually best to stick
1219 1220 1221 1222 1223 1224
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.
Dave Love's avatar
Dave Love committed
1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318

@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

  Some prefix keymaps are stored in variables with names:

@itemize @bullet
@vindex ctl-x-map
@code{ctl-x-map} is the variable name for the map used for characters that
follow @kbd{C-x}.
@vindex help-map
@code{help-map} is for characters that follow @kbd{C-h}.
@vindex esc-map
@code{esc-map} is for characters that follow @key{ESC}.  Thus, all Meta
characters are actually defined by this map.
@vindex ctl-x-4-map
@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
@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

@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
Dave Love's avatar
Dave Love committed
1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333
  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:

(add-hook 'texinfo-mode-hook
1334 1335 1336 1337 1338
          '(lambda ()
             (define-key texinfo-mode-map "\C-cp"
             (define-key texinfo-mode-map "\C-cn"
Dave Love's avatar
Dave Love committed
1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369
@end example


@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
@code{minibuffer-local-map} is used for ordinary input (no completion).
@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
just like @key{RET}.  This is used mainly for Mocklisp compatibility.
@code{minibuffer-local-completion-map} is for permissive completion.
@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
Dave Love's avatar
Dave Love committed
1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408