1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Customization, Quitting, Amusements, Top
9 This chapter talks about various topics relevant to adapting the
10 behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference
11 Manual} for how to make more far-reaching changes.
13 All kinds of customization affect only the particular Emacs session
14 that you do them in. They are completely lost when you kill the Emacs
15 session, and have no effect on other Emacs sessions you may run at the
16 same time or later. The only way an Emacs session can affect anything
17 outside of it is by writing a file; in particular, the only way to make
18 a customization ``permanent'' is to put something in your @file{.emacs}
19 file or other appropriate file to do the customization in each session.
23 * Minor Modes:: Each minor mode is one feature you can turn on
24 independently of any others.
25 * Variables:: Many Emacs commands examine Emacs variables
26 to decide what to do; by setting variables,
27 you can control their functioning.
28 * Keyboard Macros:: A keyboard macro records a sequence of
29 keystrokes to be replayed with a single
31 * Key Bindings:: The keymaps say what command each key runs.
32 By changing them, you can "redefine keys".
33 * Keyboard Translations::
34 If your keyboard passes an undesired code
35 for a key, you can tell Emacs to
36 substitute another code.
37 * Syntax:: The syntax table controls how words and
38 expressions are parsed.
39 * Init File:: How to write common customizations in the
48 Minor modes are optional features which you can turn on or off. For
49 example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
50 between words as you type. All the minor modes are independent of each
51 other and of the selected major mode. Most minor modes say in the mode
52 line when they are on; for example, @samp{Fill} in the mode line means
53 that Auto Fill mode is on.
55 Append @code{-mode} to the name of a minor mode to get the name of a
56 command function that turns the mode on or off. Thus, the command to
57 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
58 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
59 if you wish. With no argument, the function turns the mode on if it was
60 off and off if it was on. This is known as @dfn{toggling}. A positive
61 argument always turns the mode on, and an explicit zero argument or a
62 negative argument always turns it off.
64 Enabling or disabling some minor modes applies only to the current
65 buffer; each buffer is independent of the other buffers. Therefore, you
66 can enable the mode in particular buffers and disable it in others. The
67 per-buffer minor modes include Abbrev mode, Auto Fill mode, Auto Save
68 mode, Font-Lock mode, ISO Accents mode, Outline minor
69 mode, Overwrite mode, and Binary Overwrite mode.
71 Abbrev mode allows you to define abbreviations that automatically expand
72 as you type them. For example, @samp{amd} might expand to @samp{abbrev
73 mode}. @xref{Abbrevs}, for full information.
75 Auto Fill mode allows you to enter filled text without breaking lines
76 explicitly. Emacs inserts newlines as necessary to prevent lines from
77 becoming too long. @xref{Filling}.
79 Auto Save mode causes the contents of a buffer to be saved
80 periodically to reduce the amount of work you can lose in case of a
81 system crash. @xref{Auto Save}.
83 Enriched mode enables editing and saving of formatted text.
84 @xref{Formatted Text}.
86 Flyspell mode automatically highlights misspelled words.
89 Font-Lock mode automatically highlights certain textual units found in
90 programs, such as comments, strings, and function names being defined.
91 This requires a window system that can display multiple fonts.
94 ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
95 @samp{^}, @samp{/} and @samp{~} combine with the following letter, to
96 produce an accented letter in the ISO Latin-1 character set.
97 @xref{Single-Byte Character Support}.
99 Outline minor mode provides the same facilities as the major mode
100 called Outline mode; but since it is a minor mode instead, you can
101 combine it with any major mode. @xref{Outline Mode}.
103 @cindex Overwrite mode
104 @cindex mode, Overwrite
105 @findex overwrite-mode
106 @findex binary-overwrite-mode
107 Overwrite mode causes ordinary printing characters to replace existing
108 text instead of shoving it to the right. For example, if point is in
109 front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a
110 @kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR}
111 as usual. In Overwrite mode, the command @kbd{C-q} inserts the next
112 character whatever it may be, even if it is a digit---this gives you a
113 way to insert a character instead of replacing an existing character.
115 Binary Overwrite mode is a variant of Overwrite mode for editing
116 binary files; it treats newlines and tabs like other characters, so that
117 they overwrite other characters and can be overwritten by them.
119 The following minor modes normally apply to all buffers at once.
120 Since each is enabled or disabled by the value of a variable, you
121 @emph{can} set them differently for particular buffers, by explicitly
122 making the corresponding variables local in those buffers.
125 Icomplete mode displays an indication of available completions when
126 you are in the minibuffer and completion is active. @xref{Completion
129 Line Number mode enables continuous display in the mode line of the
130 line number of point, and Column Number mode enables display of the
131 column number. @xref{Mode Line}.
133 Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
134 Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
135 these modes are enabled by default when you use the X Window System.
137 In Transient Mark mode, every change in the buffer contents
138 ``deactivates'' the mark, so that commands that operate on the region
139 will get an error. This means you must either set the mark, or
140 explicitly ``reactivate'' it, before each command that uses the region.
141 The advantage of Transient Mark mode is that Emacs can display the
142 region highlighted (currently only when using X). @xref{Mark}.
144 For most minor modes, the command name is also the name of a variable
145 which directly controls the mode. The mode is enabled whenever this
146 variable's value is non-@code{nil}, and the minor-mode command works by
147 setting the variable. For example, the command
148 @code{outline-minor-mode} works by setting the value of
149 @code{outline-minor-mode} as a variable; it is this variable that
150 directly turns Outline minor mode on and off. To check whether a given
151 minor mode works this way, use @kbd{C-h v} to ask for documentation on
154 These minor-mode variables provide a good way for Lisp programs to turn
155 minor modes on and off; they are also useful in a file's local variables
156 list. But please think twice before setting minor modes with a local
157 variables list, because most minor modes are matter of user
158 preference---other users editing the same file might not want the same
159 minor modes you prefer.
167 A @dfn{variable} is a Lisp symbol which has a value. The symbol's
168 name is also called the name of the variable. A variable name can
169 contain any characters that can appear in a file, but conventionally
170 variable names consist of words separated by hyphens. A variable can
171 have a documentation string which describes what kind of value it should
172 have and how the value will be used.
174 Lisp allows any variable to have any kind of value, but most variables
175 that Emacs uses require a value of a certain type. Often the value should
176 always be a string, or should always be a number. Sometimes we say that a
177 certain feature is turned on if a variable is ``non-@code{nil},'' meaning
178 that if the variable's value is @code{nil}, the feature is off, but the
179 feature is on for @emph{any} other value. The conventional value to use to
180 turn on the feature---since you have to pick one particular value when you
181 set the variable---is @code{t}.
183 Emacs uses many Lisp variables for internal record keeping, as any
184 Lisp program must, but the most interesting variables for you are the
185 ones that exist for the sake of customization. Emacs does not (usually)
186 change the values of these variables; instead, you set the values, and
187 thereby alter and control the behavior of certain Emacs commands. These
188 variables are called @dfn{user options}. Most user options are
189 documented in this manual, and appear in the Variable Index
190 (@pxref{Variable Index}).
192 One example of a variable which is a user option is @code{fill-column}, which
193 specifies the position of the right margin (as a number of characters from
194 the left margin) to be used by the fill commands (@pxref{Filling}).
197 * Examining:: Examining or setting one variable's value.
198 * Easy Customization::
199 Convenient and easy customization of variables.
200 * Hooks:: Hook variables let you specify programs for parts
201 of Emacs to run on particular occasions.
202 * Locals:: Per-buffer values of variables.
203 * File Variables:: How files can specify variable values.
207 @subsection Examining and Setting Variables
208 @cindex setting variables
211 @item C-h v @var{var} @key{RET}
212 Display the value and documentation of variable @var{var}
213 (@code{describe-variable}).
214 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
215 Change the value of variable @var{var} to @var{value}.
218 To examine the value of a single variable, use @kbd{C-h v}
219 (@code{describe-variable}), which reads a variable name using the
220 minibuffer, with completion. It displays both the value and the
221 documentation of the variable. For example,
224 C-h v fill-column @key{RET}
228 displays something like this:
231 fill-column's value is 75
234 *Column beyond which automatic line-wrapping should happen.
235 Automatically becomes buffer-local when set in any fashion.
239 The star at the beginning of the documentation indicates that this
240 variable is a user option. @kbd{C-h v} is not restricted to user
241 options; it allows any variable name.
244 The most convenient way to set a specific user option is with @kbd{M-x
245 set-variable}. This reads the variable name with the minibuffer (with
246 completion), and then reads a Lisp expression for the new value using
247 the minibuffer a second time. For example,
250 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
254 sets @code{fill-column} to 75.
256 @kbd{M-x set-variable} is limited to user option variables, but you can
257 set any variable with a Lisp expression, using the function @code{setq}.
258 Here is a @code{setq} expression to set @code{fill-column}:
261 (setq fill-column 75)
264 To execute an expression like this one, go to the @samp{*scratch*}
265 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
268 Setting variables, like all means of customizing Emacs except where
269 otherwise stated, affects only the current Emacs session.
271 @node Easy Customization
272 @subsection Easy Customization Interface
275 @cindex customization buffer
276 A convenient way to find the user option variables that you want to
277 change, and then change them, is with @kbd{M-x customize}. This command
278 creates a @dfn{customization buffer} with which you can browse through
279 the Emacs user options in a logically organized structure, then edit and
280 set their values. You can also use the customization buffer to save
281 settings permanently. (Not all Emacs user options are included in this
282 structure as of yet, but we are adding the rest.)
284 The appearance of the example buffers in the following is typically
285 different under a window system where faces can be used to indicate the
286 active fields and other features.
289 * Groups: Customization Groups.
290 How options are classified in a structure.
291 * Changing an Option:: How to edit a value and set an option.
292 * Face Customization:: How to edit the attributes of a face.
293 * Specific Customization:: Making a customization buffer for specific
294 options, faces, or groups.
297 @node Customization Groups
298 @subsubsection Customization Groups
299 @cindex customization groups
301 For customization purposes, user options are organized into
302 @dfn{groups} to help you find them. Groups are collected into bigger
303 groups, all the way up to a master group called @code{Emacs}.
305 @kbd{M-x customize} creates a customization buffer that shows the
306 top-level @code{Emacs} group and the second-level groups immediately
307 under it. It looks like this, in part:
310 /- Emacs group: ---------------------------------------------------\
311 [State]: visible group members are all at standard settings.
312 Customization of the One True Editor.
315 Editing group: [Go to Group]
316 Basic text editing facilities.
318 External group: [Go to Group]
319 Interfacing to external utilities.
321 @var{more second-level groups}
323 \- Emacs group end ------------------------------------------------/
328 This says that the buffer displays the contents of the @code{Emacs}
329 group. The other groups are listed because they are its contents. But
330 they are listed differently, without indentation and dashes, because
331 @emph{their} contents are not included. Each group has a single-line
332 documentation string; the @code{Emacs} group also has a @samp{[State]}
335 @cindex editable fields (customization buffer)
336 @cindex active fields (customization buffer)
337 Most of the text in the customization buffer is read-only, but it
338 typically includes some @dfn{editable fields} that you can edit. There
339 are also @dfn{active fields}; this means a field that does something
340 when you @dfn{invoke} it. To invoke an active field, either click on it
341 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
343 For example, the phrase @samp{[Go to Group]} that appears in a
344 second-level group is an active field. Invoking the @samp{[Go to
345 Group]} field for a group creates a new customization buffer, which
346 shows that group and its contents. This field is a kind of hypertext
347 link to another group.
349 The @code{Emacs} group does not include any user options itself, but
350 other groups do. By examining various groups, you will eventually find
351 the options and faces that belong to the feature you are interested in
352 customizing. Then you can use the customization buffer to set them.
354 @findex customize-browse
355 You can view the structure of customization groups on a larger scale
356 with @kbd{M-x customize-browse}. This command creates a special kind of
357 customization buffer which shows only the names of the groups (and
358 options and faces), and their structure.
360 In this buffer, you can show the contents of a group by invoking
361 @samp{[+]}. When the group contents are visible, this button changes to
362 @samp{[-]}; invoking that hides the group contents.
364 Each group, option or face name in this buffer has an active field
365 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
366 that active field creates an ordinary customization buffer showing just
367 that group and its contents, just that option, or just that face.
368 This is the way to set values in it.
370 @node Changing an Option
371 @subsubsection Changing an Option
373 Here is an example of what a user option looks like in the
374 customization buffer:
377 Kill Ring Max: [Hide] 30
378 [State]: this option is unchanged from its standard setting.
379 Maximum length of kill ring before oldest elements are thrown away.
382 The text following @samp{[Hide]}, @samp{30} in this case, indicates
383 the current value of the option. If you see @samp{[Show]} instead of
384 @samp{[Hide]}, it means that the value is hidden; the customization
385 buffer initially hides values that take up several lines. Invoke
386 @samp{[Show]} to show the value.
388 The line after the option name indicates the @dfn{customization state}
389 of the option: in the example above, it says you have not changed the
390 option yet. The word @samp{[State]} at the beginning of this line is
391 active; you can get a menu of various operations by invoking it with
392 @kbd{Mouse-1} or @key{RET}. These operations are essential for
393 customizing the variable.
395 The line after the @samp{[State]} line displays the beginning of the
396 option's documentation string. If there are more lines of
397 documentation, this line ends with @samp{[More]}; invoke this to show
398 the full documentation string.
400 To enter a new value for @samp{Kill Ring Max}, move point to the value
401 and edit it textually. For example, you can type @kbd{M-d}, then insert
404 When you begin to alter the text, you will see the @samp{[State]} line
405 change to say that you have edited the value:
408 [State]: you have edited the value as text, but not set the option.
411 @cindex setting option value
412 Editing the value does not actually set the option variable. To do
413 that, you must @dfn{set} the option. To do this, invoke the word
414 @samp{[State]} and choose @samp{Set for Current Session}.
416 The state of the option changes visibly when you set it:
419 [State]: you have set this option, but not saved it for future sessions.
422 You don't have to worry about specifying a value that is not valid;
423 setting the option checks for validity and will not really install an
426 @kindex M-TAB @r{(customization buffer)}
427 @findex widget-complete
428 While editing a value or field that is a file name, directory name,
429 command name, or anything else for which completion is defined, you can
430 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
432 Some options have a small fixed set of possible legitimate values.
433 These options don't let you edit the value textually. Instead, an
434 active field @samp{[Value Menu]} appears before the value; invoke this
435 field to edit the value. For a boolean ``on or off'' value, the active
436 field says @samp{[Toggle]}, and it changes to the other value.
437 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
438 take effect when you use the @samp{Set for Current Session} operation.
440 Some options have values with complex structure. For example, the
441 value of @code{file-coding-system-alist} is an association list. Here
442 is how it appears in the customization buffer:
445 File Coding System Alist: [Hide]
446 [INS] [DEL] File regexp: \.elc\'
447 Choice: [Value Menu] Encoding/decoding pair:
450 [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
451 Choice: [Value Menu] Encoding/decoding pair:
452 Decoding: no-conversion
453 Encoding: no-conversion
454 [INS] [DEL] File regexp: \.tar\'
455 Choice: [Value Menu] Encoding/decoding pair:
456 Decoding: no-conversion
457 Encoding: no-conversion
458 [INS] [DEL] File regexp:
459 Choice: [Value Menu] Encoding/decoding pair:
463 [State]: this option is unchanged from its standard setting.
464 Alist to decide a coding system to use for a file I/O operation. [Hide]
465 The format is ((PATTERN . VAL) ...),
466 where PATTERN is a regular expression matching a file name,
467 @r{[@dots{}more lines of documentation@dots{}]}
471 Each association in the list appears on four lines, with several
472 editable or ``active'' fields. You can edit the regexps and coding
473 systems using ordinary editing commands. You can also invoke
474 @samp{[Value Menu]} to switch to a kind of value---for instance, to
475 specify a function instead of a pair of coding systems.
477 To delete an association from the list, invoke the @samp{[DEL]} button
478 for that item. To add an association, invoke @samp{[INS]} at the
479 position where you want to add it. There is an @samp{[INS]} button
480 between each pair of association, another at the beginning and another
481 at the end, so you can add the new association at any position in the
484 @kindex TAB @r{(customization buffer)}
485 @kindex S-TAB @r{(customization buffer)}
486 @findex widget-forward
487 @findex widget-backward
488 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
489 moving through the customization buffer. @key{TAB}
490 (@code{widget-forward}) moves forward to the next active or editable
491 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
492 previous active or editable field.
494 Typing @key{RET} on an editable field also moves forward, just like
495 @key{TAB}. We set it up this way because people often type @key{RET}
496 when they are finished editing a field. To insert a newline within an
497 editable field, use @kbd{C-o} or @kbd{C-q C-j}.
499 @cindex saving option value
500 Setting the option changes its value in the current Emacs session;
501 @dfn{saving} the value changes it for future sessions as well. This
502 works by writing code into your @file{~/.emacs} file so as to set the
503 option variable again each time you start Emacs. To save the option,
504 invoke @samp{[State]} and select the @samp{Save for Future Sessions}
507 You can also restore the option to its standard value by invoking
508 @samp{[State]} and selecting the @samp{Erase Customization}
509 operation. There are actually three reset operations:
513 If you have made some modifications and not yet set the option,
514 this restores the text in the customization buffer to match
518 This restores the value of the option to the last saved value,
519 and updates the text accordingly.
521 @item Erase Customization
522 This sets the option to its standard value, and updates the text
523 accordingly. This also eliminates any saved value for the option,
524 so that you will get the standard value in future Emacs sessions.
527 @cindex comments on customized options
528 Sometimes it is useful to record a comment about a specific
529 customization. Use the @samp{Add Comment} item from the
530 @samp{[State]} menu to create a field for entering the comment. The
531 comment you enter will be saved, and displayed again if you again view
532 the same option in a customization buffer, even in another session.
534 The state of a group indicates whether anything in that group has been
535 edited, set or saved. You can select @samp{Set for Current Session},
536 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
537 operation for the group; these operations on the group apply to all
538 options in the group and its subgroups.
540 Near the top of the customization buffer there are two lines
541 containing several active fields:
544 [Set for Current Session] [Save for Future Sessions]
545 [Reset] [Reset to Saved] [Erase Customization] [Finish]
548 @vindex custom-buffer-done-function
550 Invoking @samp{[Finish]} either buries or kills this customization
551 buffer according to the setting of the option
552 @code{custom-buffer-done-function}; the default is to bury the buffer.
553 Each of the other fields performs an operation---set, save or
554 reset---on each of the items in the buffer that could meaningfully be
557 @node Face Customization
558 @subsubsection Customizing Faces
559 @cindex customizing faces
562 @cindex fonts and faces
564 In addition to user options, some customization groups also include
565 faces. When you show the contents of a group, both the user options and
566 the faces in the group appear in the customization buffer. Here is an
567 example of how a face looks:
570 Custom Changed Face: (sample) [Hide]
571 [State]: this face is unchanged from its standard setting.
572 Parent groups: [Custom Magic Faces]
573 Attributes: [ ] Font family: [Value Menu] *
574 [ ] Width: [Value Menu] *
575 [ ] Height: [Value Menu] *
576 [ ] Weight: [Value Menu] *
577 [ ] Slant: [Value Menu] *
578 [ ] Underline: [Value Menu] *
579 [ ] Overline: [Value Menu] *
580 [ ] Strike-through: [Value Menu] *
581 [ ] Box around text: [Value Menu] Off
582 [ ] Inverse-video: [Value Menu] *
583 [X] Foreground: [Value Menu] Color: white (sample)
584 [X] Background: [Value Menu] Color: blue (sample)
585 [ ] Stipple: [Value Menu] *
588 Each face attribute has its own line. The @samp{[@var{x}]} field
589 before the attribute name indicates whether the attribute is
590 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
591 attribute by invoking that field. When the attribute is enabled, you
592 can change the attribute value in the usual ways.
594 On a black-and-white display, the colors you can use for the
595 background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1},
596 and @samp{gray3}. Emacs supports these shades of gray by using
597 background stipple patterns instead of a color.
599 Setting, saving and resetting a face work like the same operations for
600 options (@pxref{Changing an Option}).
602 A face can specify different appearances for different types of
603 display. For example, a face can make text red on a color display, but
604 use a bold font on a monochrome display. To specify multiple
605 appearances for a face, select @samp{Show Display Types} in the menu you
606 get from invoking @samp{[State]}.
609 Another more basic way to set the attributes of a specific face is
610 with @kbd{M-x modify-face}. This command reads the name of a face, then
611 reads the attributes one by one. For the color and stipple attributes,
612 the attribute's current value is the default---type just @key{RET} if
613 you don't want to change that attribute. Type @samp{none} if you want
614 to clear out the attribute.
616 @node Specific Customization
617 @subsubsection Customizing Specific Items
619 Instead of finding the options you want to change by moving down
620 through the structure of groups, you can specify the particular option,
621 face or group that you want to customize.
624 @item M-x customize-option @key{RET} @var{option} @key{RET}
625 Set up a customization buffer with just one option, @var{option}.
626 @item M-x customize-face @key{RET} @var{face} @key{RET}
627 Set up a customization buffer with just one face, @var{face}.
628 @item M-x customize-group @key{RET} @var{group} @key{RET}
629 Set up a customization buffer with just one group, @var{group}.
630 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
631 Set up a customization buffer with all the options, faces and groups
632 that match @var{regexp}.
633 @item M-x customize-changed-options @key{RET} @var{version} @key{RET}
634 Set up a customization buffer with all the options, faces and groups
635 whose meaning has changed since Emacs version @var{version}.
636 @item M-x customize-saved
637 Set up a customization buffer containing all options and faces that you
638 have saved with customization buffers.
639 @item M-x customize-customized
640 Set up a customization buffer containing all options and faces that you
641 have customized but not saved.
644 @findex customize-option
645 If you want to alter a particular user option variable with the
646 customization buffer, and you know its name, you can use the command
647 @kbd{M-x customize-option} and specify the option name. This sets up
648 the customization buffer with just one option---the one that you asked
649 for. Editing, setting and saving the value work as described above, but
650 only for the specified option.
652 @findex customize-face
653 Likewise, you can modify a specific face, chosen by name, using
654 @kbd{M-x customize-face}.
656 @findex customize-group
657 You can also set up the customization buffer with a specific group,
658 using @kbd{M-x customize-group}. The immediate contents of the chosen
659 group, including option variables, faces, and other groups, all appear
660 as well. However, these subgroups' own contents start out hidden. You
661 can show their contents in the usual way, by invoking @samp{[Show]}.
663 @findex customize-apropos
664 To control more precisely what to customize, you can use @kbd{M-x
665 customize-apropos}. You specify a regular expression as argument; then
666 all options, faces and groups whose names match this regular expression
667 are set up in the customization buffer. If you specify an empty regular
668 expression, this includes @emph{all} groups, options and faces in the
669 customization buffer (but that takes a long time).
671 @findex customize-changed-options
672 When you upgrade to a new Emacs version, you might want to customize
673 new options and options whose meanings or default values have changed.
674 To do this, use @kbd{M-x customize-changed-options} and specify a
675 previous Emacs version number using the minibuffer. It creates a
676 customization buffer which shows all the options (and groups) whose
677 definitions have been changed since the specified version.
679 @findex customize-saved
680 @findex customize-customized
681 If you change option values and then decide the change was a mistake,
682 you can use two special commands to revisit your previous changes. Use
683 @kbd{customize-saved} to look at the options and faces that you have
684 saved. Use @kbd{M-x customize-customized} to look at the options and
685 faces that you have set but not saved.
690 @cindex running a hook
692 @dfn{Hooks} are an important mechanism for customization of Emacs. A
693 hook is a Lisp variable which holds a list of functions, to be called on
694 some well-defined occasion. (This is called @dfn{running the hook}.)
695 The individual functions in the list are called the @dfn{hook functions}
696 of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
697 starts up, so the only hook functions in any given hook are the ones you
698 explicitly put there as customization.
700 Most major modes run one or more @dfn{mode hooks} as the last step of
701 initialization. This makes it easy for you to customize the behavior of
702 the mode, by setting up a hook function to override the local variable
703 assignments already made by the mode. But hooks are also used in other
704 contexts. For example, the hook @code{suspend-hook} runs just before
705 Emacs suspends itself (@pxref{Exiting}).
708 Most Emacs hooks are @dfn{normal hooks}. This means that running the
709 hook operates by calling all the hook functions, unconditionally, with
710 no arguments. We have made an effort to keep most hooks normal so that
711 you can use them in a uniform way. Every variable in Emacs whose name
712 ends in @samp{-hook} is a normal hook.
714 @cindex abnormal hook
715 There are also a few @dfn{abnormal hooks}. These variables' names end
716 in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
717 makes these hooks abnormal is that there is something peculiar about the
718 way its functions are called---perhaps they are given arguments, or
719 perhaps the values they return are used in some way. For example,
720 @code{find-file-not-found-hooks} (@pxref{Visiting}) is abnormal because
721 as soon as one hook function returns a non-@code{nil} value, the rest
722 are not called at all. The documentation of each abnormal hook variable
723 explains in detail what is peculiar about it.
725 The recommended way to add a hook function to a hook (either normal or
726 abnormal) is by calling @code{add-hook}. You can use any valid Lisp
727 function as the hook function, provided it can handle the proper number
728 of arguments (zero arguments, in the case of a normal hook). Of course,
729 not every Lisp function is @emph{useful} in any particular hook.
731 For example, here's how to set up a hook to turn on Auto Fill mode
732 when entering Text mode and other modes based on Text mode:
735 (add-hook 'text-mode-hook 'turn-on-auto-fill)
738 The next example shows how to use a hook to customize the indentation
739 of C code. (People often have strong personal preferences for one
740 format compared to another.) Here the hook function is an anonymous
746 '((c-comment-only-line-offset . 4)
749 (c-cleanup-list . (scope-operator
754 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
755 (substatement-open . 0)))))
759 (add-hook 'c-mode-common-hook
761 (c-add-style "my-style" my-c-style t)))
765 It is best to design your hook functions so that the order in which
766 they are executed does not matter. Any dependence on the order is
767 ``asking for trouble.'' However, the order is predictable: the most
768 recently added hook functions are executed first.
771 @subsection Local Variables
774 @item M-x make-local-variable @key{RET} @var{var} @key{RET}
775 Make variable @var{var} have a local value in the current buffer.
776 @item M-x kill-local-variable @key{RET} @var{var} @key{RET}
777 Make variable @var{var} use its global value in the current buffer.
778 @item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
779 Mark variable @var{var} so that setting it will make it local to the
780 buffer that is current at that time.
783 @cindex local variables
784 Almost any variable can be made @dfn{local} to a specific Emacs
785 buffer. This means that its value in that buffer is independent of its
786 value in other buffers. A few variables are always local in every
787 buffer. Every other Emacs variable has a @dfn{global} value which is in
788 effect in all buffers that have not made the variable local.
790 @findex make-local-variable
791 @kbd{M-x make-local-variable} reads the name of a variable and makes it
792 local to the current buffer. Further changes in this buffer will not
793 affect others, and further changes in the global value will not affect this
796 @findex make-variable-buffer-local
797 @cindex per-buffer variables
798 @kbd{M-x make-variable-buffer-local} reads the name of a variable and
799 changes the future behavior of the variable so that it will become local
800 automatically when it is set. More precisely, once a variable has been
801 marked in this way, the usual ways of setting the variable automatically
802 do @code{make-local-variable} first. We call such variables
803 @dfn{per-buffer} variables.
805 Major modes (@pxref{Major Modes}) always make variables local to the
806 buffer before setting the variables. This is why changing major modes
807 in one buffer has no effect on other buffers. Minor modes also work by
808 setting variables---normally, each minor mode has one controlling
809 variable which is non-@code{nil} when the mode is enabled (@pxref{Minor
810 Modes}). For most minor modes, the controlling variable is per buffer.
812 Emacs contains a number of variables that are always per-buffer.
813 These include @code{abbrev-mode}, @code{auto-fill-function},
814 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
815 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
816 @code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},
817 @code{selective-display-ellipses}, @code{selective-display},
818 @code{tab-width}, and @code{truncate-lines}. Some other variables are
819 always local in every buffer, but they are used for internal
822 A few variables cannot be local to a buffer because they are always
823 local to each display instead (@pxref{Multiple Displays}). If you try to
824 make one of these variables buffer-local, you'll get an error message.
826 @findex kill-local-variable
827 @kbd{M-x kill-local-variable} reads the name of a variable and makes
828 it cease to be local to the current buffer. The global value of the
829 variable henceforth is in effect in this buffer. Setting the major mode
830 kills all the local variables of the buffer except for a few variables
831 specially marked as @dfn{permanent locals}.
834 To set the global value of a variable, regardless of whether the
835 variable has a local value in the current buffer, you can use the Lisp
836 construct @code{setq-default}. This construct is used just like
837 @code{setq}, but it sets variables' global values instead of their local
838 values (if any). When the current buffer does have a local value, the
839 new global value may not be visible until you switch to another buffer.
843 (setq-default fill-column 75)
847 @code{setq-default} is the only way to set the global value of a variable
848 that has been marked with @code{make-variable-buffer-local}.
850 @findex default-value
851 Lisp programs can use @code{default-value} to look at a variable's
852 default value. This function takes a symbol as argument and returns its
853 default value. The argument is evaluated; usually you must quote it
854 explicitly. For example, here's how to obtain the default value of
858 (default-value 'fill-column)
862 @subsection Local Variables in Files
863 @cindex local variables in files
864 @cindex file local variables
866 A file can specify local variable values for use when you edit the
867 file with Emacs. Visiting the file checks for local variable
868 specifications; it automatically makes these variables local to the
869 buffer, and sets them to the values specified in the file.
871 There are two ways to specify local variable values: in the first
872 line, or with a local variables list. Here's how to specify them in the
876 -*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
880 You can specify any number of variables/value pairs in this way, each
881 pair with a colon and semicolon as shown above. @code{mode:
882 @var{modename};} specifies the major mode; this should come first in the
883 line. The @var{value}s are not evaluated; they are used literally.
884 Here is an example that specifies Lisp mode and sets two variables with
888 ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
891 You can also specify the coding system for a file in this way: just
892 specify a value for the ``variable'' named @code{coding}. The ``value''
893 must be a coding system name that Emacs recognizes. @xref{Coding
896 The @code{eval} pseudo-variable, described below, can be specified in
897 the first line as well.
899 @cindex shell scripts, and local file variables
900 In shell scripts, the first line is used to identify the script
901 interpreter, so you cannot put any local variables there. To accomodate
902 for this, when Emacs visits a shell script, it looks for local variable
903 specifications in the @emph{second} line.
905 A @dfn{local variables list} goes near the end of the file, in the
906 last page. (It is often best to put it on a page by itself.) The local
907 variables list starts with a line containing the string @samp{Local
908 Variables:}, and ends with a line containing the string @samp{End:}. In
909 between come the variable names and values, one set per line, as
910 @samp{@var{variable}:@: @var{value}}. The @var{value}s are not
911 evaluated; they are used literally. If a file has both a local
912 variables list and a @samp{-*-} line, Emacs processes @emph{everything}
913 in the @samp{-*-} line first, and @emph{everything} in the local
914 variables list afterward.
916 Here is an example of a local variables list:
919 ;;; Local Variables: ***
921 ;;; comment-column:0 ***
922 ;;; comment-start: ";;; " ***
923 ;;; comment-end:"***" ***
927 As you see, each line starts with the prefix @samp{;;; } and each line
928 ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix
929 and suffix based on the first line of the list, by finding them
930 surrounding the magic string @samp{Local Variables:}; then it
931 automatically discards them from the other lines of the list.
933 The usual reason for using a prefix and/or suffix is to embed the
934 local variables list in a comment, so it won't confuse other programs
935 that the file is intended as input for. The example above is for a
936 language where comment lines start with @samp{;;; } and end with
937 @samp{***}; the local values for @code{comment-start} and
938 @code{comment-end} customize the rest of Emacs for this unusual syntax.
939 Don't use a prefix (or a suffix) if you don't need one.
941 Two ``variable names'' have special meanings in a local variables
942 list: a value for the variable @code{mode} really sets the major mode,
943 and a value for the variable @code{eval} is simply evaluated as an
944 expression and the value is ignored. @code{mode} and @code{eval} are
945 not real variables; setting variables named @code{mode} and @code{eval}
946 in any other context has no special meaning. If @code{mode} is used to
947 set a major mode, it should be the first ``variable'' in the list.
949 You can use the @code{mode} ``variable'' to set minor modes as well as
950 major modes; in fact, you can use it more than once, first to set the
951 major mode and then to set minor modes which are specific to particular
952 buffers. But most minor modes should not be specified in the file in
953 any fashion, because they represent user preferences.
955 For example, you may be tempted to try to turn on Auto Fill mode with
956 a local variable list. That is a mistake. The choice of Auto Fill mode
957 or not is a matter of individual taste, not a matter of the contents of
958 particular files. If you want to use Auto Fill, set up major mode hooks
959 with your @file{.emacs} file to turn it on (when appropriate) for you
960 alone (@pxref{Init File}). Don't use a local variable list to impose
961 your taste on everyone.
963 The start of the local variables list must be no more than 3000
964 characters from the end of the file, and must be in the last page if the
965 file is divided into pages. Otherwise, Emacs will not notice it is
966 there. The purpose of this rule is so that a stray @samp{Local
967 Variables:}@: not in the last page does not confuse Emacs, and so that
968 visiting a long file that is all one page and has no local variables
969 list need not take the time to search the whole file.
971 Use the command @code{normal-mode} to reset the local variables and
972 major mode of a buffer according to the file name and contents,
973 including the local variables list if any. @xref{Choosing Modes}.
975 @findex enable-local-variables
976 The variable @code{enable-local-variables} controls whether to process
977 local variables in files, and thus gives you a chance to override them.
978 Its default value is @code{t}, which means do process local variables in
979 files. If you set the value to @code{nil}, Emacs simply ignores local
980 variables in files. Any other value says to query you about each file
981 that has local variables, showing you the local variable specifications
984 @findex enable-local-eval
985 The @code{eval} ``variable,'' and certain actual variables, create a
986 special risk; when you visit someone else's file, local variable
987 specifications for these could affect your Emacs in arbitrary ways.
988 Therefore, the option @code{enable-local-eval} controls whether Emacs
989 processes @code{eval} variables, as well variables with names that end
990 in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
991 and certain other variables. The three possibilities for the option's
992 value are @code{t}, @code{nil}, and anything else, just as for
993 @code{enable-local-variables}. The default is @code{maybe}, which is
994 neither @code{t} nor @code{nil}, so normally Emacs does ask for
995 confirmation about file settings for these variables.
997 @node Keyboard Macros
998 @section Keyboard Macros
1000 @cindex defining keyboard macros
1001 @cindex keyboard macro
1002 A @dfn{keyboard macro} is a command defined by the user to stand for
1003 another sequence of keys. For example, if you discover that you are
1004 about to type @kbd{C-n C-d} forty times, you can speed your work by
1005 defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
1006 repeat count of forty.
1011 Start defining a keyboard macro (@code{start-kbd-macro}).
1013 End the definition of a keyboard macro (@code{end-kbd-macro}).
1015 Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
1017 Re-execute last keyboard macro, then add more keys to its definition.
1019 When this point is reached during macro execution, ask for confirmation
1020 (@code{kbd-macro-query}).
1021 @item M-x name-last-kbd-macro
1022 Give a command name (for the duration of the session) to the most
1023 recently defined keyboard macro.
1024 @item M-x insert-kbd-macro
1025 Insert in the buffer a keyboard macro's definition, as Lisp code.
1027 Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
1028 @item M-x apply-macro-to-region-lines
1029 Run the last keyboard macro on each complete line in the region.
1032 Keyboard macros differ from ordinary Emacs commands in that they are
1033 written in the Emacs command language rather than in Lisp. This makes it
1034 easier for the novice to write them, and makes them more convenient as
1035 temporary hacks. However, the Emacs command language is not powerful
1036 enough as a programming language to be useful for writing anything
1037 intelligent or general. For such things, Lisp must be used.
1039 You define a keyboard macro while executing the commands which are the
1040 definition. Put differently, as you define a keyboard macro, the
1041 definition is being executed for the first time. This way, you can see
1042 what the effects of your commands are, so that you don't have to figure
1043 them out in your head. When you are finished, the keyboard macro is
1044 defined and also has been, in effect, executed once. You can then do the
1045 whole thing over again by invoking the macro.
1048 * Basic Kbd Macro:: Defining and running keyboard macros.
1049 * Save Kbd Macro:: Giving keyboard macros names; saving them in files.
1050 * Kbd Macro Query:: Making keyboard macros do different things each time.
1053 @node Basic Kbd Macro
1054 @subsection Basic Use
1059 @findex start-kbd-macro
1060 @findex end-kbd-macro
1061 @findex call-last-kbd-macro
1062 To start defining a keyboard macro, type the @kbd{C-x (} command
1063 (@code{start-kbd-macro}). From then on, your keys continue to be
1064 executed, but also become part of the definition of the macro. @samp{Def}
1065 appears in the mode line to remind you of what is going on. When you are
1066 finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
1067 definition (without becoming part of it!). For example,
1074 defines a macro to move forward a word and then insert @samp{foo}.
1076 The macro thus defined can be invoked again with the @kbd{C-x e}
1077 command (@code{call-last-kbd-macro}), which may be given a repeat count
1078 as a numeric argument to execute the macro many times. @kbd{C-x )} can
1079 also be given a repeat count as an argument, in which case it repeats
1080 the macro that many times right after defining it, but defining the
1081 macro counts as the first repetition (since it is executed as you define
1082 it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro
1083 immediately 3 additional times. An argument of zero to @kbd{C-x e} or
1084 @kbd{C-x )} means repeat the macro indefinitely (until it gets an error
1085 or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}).
1087 If you wish to repeat an operation at regularly spaced places in the
1088 text, define a macro and include as part of the macro the commands to move
1089 to the next place you want to use it. For example, if you want to change
1090 each line, you should position point at the start of a line, and define a
1091 macro to change that line and leave point at the start of the next line.
1092 Then repeating the macro will operate on successive lines.
1094 After you have terminated the definition of a keyboard macro, you can add
1095 to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
1096 to plain @kbd{C-x (} followed by retyping the whole definition so far. As
1097 a consequence it re-executes the macro as previously defined.
1099 You can use function keys in a keyboard macro, just like keyboard
1100 keys. You can even use mouse events, but be careful about that: when
1101 the macro replays the mouse event, it uses the original mouse position
1102 of that event, the position that the mouse had while you were defining
1103 the macro. The effect of this may be hard to predict. (Using the
1104 current mouse position would be even less predictable.)
1106 One thing that doesn't always work well in a keyboard macro is the
1107 command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command
1108 exits a recursive edit that started within the macro, it works as you'd
1109 expect. But if it exits a recursive edit that started before you
1110 invoked the keyboard macro, it also necessarily exits the keyboard macro
1111 as part of the process.
1113 @findex edit-kbd-macro
1115 You can edit a keyboard macro already defined by typing @kbd{C-x C-k}
1116 (@code{edit-kbd-macro}). Follow that with the keyboard input that you
1117 would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or
1118 some other key sequence. This formats the macro definition in a buffer
1119 and enters a specialized major mode for editing it. Type @kbd{C-h m}
1120 once in that buffer to display details of how to edit the macro. When
1121 you are finished editing, type @kbd{C-c C-c}.
1123 @findex apply-macro-to-region-lines
1124 The command @kbd{M-x apply-macro-to-region-lines} repeats the last
1125 defined keyboard macro on each complete line within the current region.
1126 It does this line by line, by moving point to the beginning of the line
1127 and then executing the macro.
1129 @node Save Kbd Macro
1130 @subsection Naming and Saving Keyboard Macros
1132 @cindex saving keyboard macros
1133 @findex name-last-kbd-macro
1134 If you wish to save a keyboard macro for longer than until you define the
1135 next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
1136 This reads a name as an argument using the minibuffer and defines that name
1137 to execute the macro. The macro name is a Lisp symbol, and defining it in
1138 this way makes it a valid command name for calling with @kbd{M-x} or for
1139 binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
1140 specify a name that has a prior definition other than another keyboard
1141 macro, an error message is printed and nothing is changed.
1143 @findex insert-kbd-macro
1144 Once a macro has a command name, you can save its definition in a file.
1145 Then it can be used in another editing session. First, visit the file
1146 you want to save the definition in. Then use this command:
1149 M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
1153 This inserts some Lisp code that, when executed later, will define the
1154 same macro with the same definition it has now. (You need not
1155 understand Lisp code to do this, because @code{insert-kbd-macro} writes
1156 the Lisp code for you.) Then save the file. You can load the file
1157 later with @code{load-file} (@pxref{Lisp Libraries}). If the file you
1158 save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
1159 macro will be defined each time you run Emacs.
1161 If you give @code{insert-kbd-macro} a numeric argument, it makes
1162 additional Lisp code to record the keys (if any) that you have bound to the
1163 keyboard macro, so that the macro will be reassigned the same keys when you
1166 @node Kbd Macro Query
1167 @subsection Executing Macros with Variations
1170 @findex kbd-macro-query
1171 Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
1172 similar to that of @code{query-replace}, where the macro asks you each
1173 time around whether to make a change. While defining the macro,
1174 type @kbd{C-x q} at the point where you want the query to occur. During
1175 macro definition, the @kbd{C-x q} does nothing, but when you run the
1176 macro later, @kbd{C-x q} asks you interactively whether to continue.
1178 The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
1179 @key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
1180 The answers are the same as in @code{query-replace}, though not all of
1181 the @code{query-replace} options are meaningful.
1183 These responses include @key{SPC} to continue, and @key{DEL} to skip
1184 the remainder of this repetition of the macro and start right away with
1185 the next repetition. @key{RET} means to skip the remainder of this
1186 repetition and cancel further repetitions. @kbd{C-l} redraws the screen
1187 and asks you again for a character to say what to do.
1189 @kbd{C-r} enters a recursive editing level, in which you can perform
1190 editing which is not part of the macro. When you exit the recursive
1191 edit using @kbd{C-M-c}, you are asked again how to continue with the
1192 keyboard macro. If you type a @key{SPC} at this time, the rest of the
1193 macro definition is executed. It is up to you to leave point and the
1194 text in a state such that the rest of the macro will do what you
1197 @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument,
1198 performs a completely different function. It enters a recursive edit
1199 reading input from the keyboard, both when you type it during the
1200 definition of the macro, and when it is executed from the macro. During
1201 definition, the editing you do inside the recursive edit does not become
1202 part of the macro. During macro execution, the recursive edit gives you
1203 a chance to do some particularized editing on each repetition.
1204 @xref{Recursive Edit}.
1206 Another way to vary the behavior of a keyboard macro is to use a
1207 register as a counter, incrementing it on each repetition of the macro.
1211 @section Customizing Key Bindings
1212 @cindex key bindings
1214 This section describes @dfn{key bindings}, which map keys to commands,
1215 and @dfn{keymaps}, which record key bindings. It also explains how
1216 to customize key bindings.
1218 Recall that a command is a Lisp function whose definition provides for
1219 interactive use. Like every Lisp function, a command has a function
1220 name which usually consists of lower-case letters and hyphens.
1223 * Keymaps:: Generalities. The global keymap.
1224 * Prefix Keymaps:: Keymaps for prefix keys.
1225 * Local Keymaps:: Major and minor modes have their own keymaps.
1226 * Minibuffer Maps:: The minibuffer uses its own local keymaps.
1227 * Rebinding:: How to redefine one key's meaning conveniently.
1228 * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
1229 * Function Keys:: Rebinding terminal function keys.
1230 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
1231 * Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1.
1232 * Mouse Buttons:: Rebinding mouse buttons in Emacs.
1233 * Disabling:: Disabling a command means confirmation is required
1234 before it can be executed. This is done to protect
1235 beginners from surprises.
1242 The bindings between key sequences and command functions are recorded
1243 in data structures called @dfn{keymaps}. Emacs has many of these, each
1244 used on particular occasions.
1246 Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
1247 of @dfn{input events} that have a meaning as a unit. Input events
1248 include characters, function keys and mouse buttons---all the inputs
1249 that you can send to the computer with your terminal. A key sequence
1250 gets its meaning from its @dfn{binding}, which says what command it
1251 runs. The function of keymaps is to record these bindings.
1253 @cindex global keymap
1254 The @dfn{global} keymap is the most important keymap because it is
1255 always in effect. The global keymap defines keys for Fundamental mode;
1256 most of these definitions are common to most or all major modes. Each
1257 major or minor mode can have its own keymap which overrides the global
1258 definitions of some keys.
1260 For example, a self-inserting character such as @kbd{g} is
1261 self-inserting because the global keymap binds it to the command
1262 @code{self-insert-command}. The standard Emacs editing characters such
1263 as @kbd{C-a} also get their standard meanings from the global keymap.
1264 Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
1265 by storing the new binding in the proper place in the global map.
1268 Meta characters work differently; Emacs translates each Meta
1269 character into a pair of characters starting with @key{ESC}. When you
1270 type the character @kbd{M-a} in a key sequence, Emacs replaces it with
1271 @kbd{@key{ESC} a}. A meta key comes in as a single input event, but
1272 becomes two events for purposes of key bindings. The reason for this is
1273 historical, and we might change it someday.
1275 @cindex function key
1276 Most modern keyboards have function keys as well as character keys.
1277 Function keys send input events just as character keys do, and keymaps
1278 can have bindings for them.
1280 On many terminals, typing a function key actually sends the computer a
1281 sequence of characters; the precise details of the sequence depends on
1282 which function key and on the model of terminal you are using. (Often
1283 the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
1284 terminal type properly, it recognizes the character sequences forming
1285 function keys wherever they occur in a key sequence (not just at the
1286 beginning). Thus, for most purposes, you can pretend the function keys
1287 reach Emacs directly and ignore their encoding as character sequences.
1290 Mouse buttons also produce input events. These events come with other
1291 data---the window and position where you pressed or released the button,
1292 and a time stamp. But only the choice of button matters for key
1293 bindings; the other data matters only if a command looks at it.
1294 (Commands designed for mouse invocation usually do look at the other
1297 A keymap records definitions for single events. Interpreting a key
1298 sequence of multiple events involves a chain of keymaps. The first
1299 keymap gives a definition for the first event; this definition is
1300 another keymap, which is used to look up the second event in the
1301 sequence, and so on.
1303 Key sequences can mix function keys and characters. For example,
1304 @kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
1305 key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse
1306 events with keyboard events, but we recommend against it, because such
1307 sequences are inconvenient to type in.
1309 As a user, you can redefine any key; but it might be best to stick to
1310 key sequences that consist of @kbd{C-c} followed by a letter. These
1311 keys are ``reserved for users,'' so they won't conflict with any
1312 properly designed Emacs extension. The function keys @key{F5} through
1313 @key{F9} are also reserved for users. If you redefine some other key,
1314 your definition may be overridden by certain extensions or major modes
1315 which redefine the same key.
1317 @node Prefix Keymaps
1318 @subsection Prefix Keymaps
1320 A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
1321 which holds the definition for the event that immediately follows
1324 The definition of a prefix key is usually the keymap to use for
1325 looking up the following event. The definition can also be a Lisp
1326 symbol whose function definition is the following keymap; the effect is
1327 the same, but it provides a command name for the prefix key that can be
1328 used as a description of what the prefix key is for. Thus, the binding
1329 of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
1330 definition is the keymap for @kbd{C-x} commands. The definitions of
1331 @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
1332 the global map, so these prefix keys are always available.
1334 Aside from ordinary prefix keys, there is a fictitious ``prefix key''
1335 which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
1336 Reference Manual}, for special information about menu bar key bindings.
1337 Mouse button events that invoke pop-up menus are also prefix keys; see
1338 @ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
1341 Some prefix keymaps are stored in variables with names:
1346 @code{ctl-x-map} is the variable name for the map used for characters that
1350 @code{help-map} is for characters that follow @kbd{C-h}.
1353 @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
1354 characters are actually defined by this map.
1357 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1359 @vindex mode-specific-map
1360 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1364 @subsection Local Keymaps
1366 @cindex local keymap
1367 So far we have explained the ins and outs of the global map. Major
1368 modes customize Emacs by providing their own key bindings in @dfn{local
1369 keymaps}. For example, C mode overrides @key{TAB} to make it indent the
1370 current line for C code. Portions of text in the buffer can specify
1371 their own keymaps to substitute for the keymap of the buffer's major
1374 @cindex minor mode keymap
1375 Minor modes can also have local keymaps. Whenever a minor mode is
1376 in effect, the definitions in its keymap override both the major
1377 mode's local keymap and the global keymap.
1380 @vindex lisp-mode-map
1381 The local keymaps for Lisp mode and several other major modes always
1382 exist even when not in use. These are kept in variables named
1383 @code{lisp-mode-map} and so on. For major modes less often used, the
1384 local keymap is normally constructed only when the mode is used for the
1385 first time in a session. This is to save space. If you wish to change
1386 one of these keymaps, you must use the major mode's @dfn{mode
1389 All minor mode keymaps are created in advance. There is no way to
1390 defer their creation until the first time the minor mode is enabled.
1392 A local keymap can locally redefine a key as a prefix key by defining
1393 it as a prefix keymap. If the key is also defined globally as a prefix,
1394 then its local and global definitions (both keymaps) effectively
1395 combine: both of them are used to look up the event that follows the
1396 prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
1397 another keymap, and that keymap defines @kbd{C-z} as a command, this
1398 provides a local meaning for @kbd{C-c C-z}. This does not affect other
1399 sequences that start with @kbd{C-c}; if those sequences don't have their
1400 own local bindings, their global bindings remain in effect.
1402 Another way to think of this is that Emacs handles a multi-event key
1403 sequence by looking in several keymaps, one by one, for a binding of the
1404 whole key sequence. First it checks the minor mode keymaps for minor
1405 modes that are enabled, then it checks the major mode's keymap, and then
1406 it checks the global keymap. This is not precisely how key lookup
1407 works, but it's good enough for understanding ordinary circumstances.
1409 @cindex rebinding major mode keys
1411 To change the local bindings of a major mode, you must change the
1412 mode's local keymap. Normally you must wait until the first time the
1413 mode is used, because most major modes don't create their keymaps until
1414 then. If you want to specify something in your @file{~/.emacs} file to
1415 change a major mode's bindings, you must use the mode's mode hook to
1416 delay the change until the mode is first used.
1418 For example, the command @code{texinfo-mode} to select Texinfo mode
1419 runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
1420 to add local bindings (not very useful, we admit) for @kbd{C-c n} and
1421 @kbd{C-c p} in Texinfo mode:
1424 (add-hook 'texinfo-mode-hook
1426 (define-key texinfo-mode-map "\C-cp"
1427 'backward-paragraph)
1428 (define-key texinfo-mode-map "\C-cn"
1429 'forward-paragraph)))
1434 @node Minibuffer Maps
1435 @subsection Minibuffer Keymaps
1437 @cindex minibuffer keymaps
1438 @vindex minibuffer-local-map
1439 @vindex minibuffer-local-ns-map
1440 @vindex minibuffer-local-completion-map
1441 @vindex minibuffer-local-must-match-map
1442 The minibuffer has its own set of local keymaps; they contain various
1443 completion and exit commands.
1447 @code{minibuffer-local-map} is used for ordinary input (no completion).
1449 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1450 just like @key{RET}. This is used mainly for Mocklisp compatibility.
1452 @code{minibuffer-local-completion-map} is for permissive completion.
1454 @code{minibuffer-local-must-match-map} is for strict completion and
1455 for cautious completion.
1459 @subsection Changing Key Bindings Interactively
1460 @cindex key rebinding, this session
1461 @cindex redefining keys, this session
1463 The way to redefine an Emacs key is to change its entry in a keymap.
1464 You can change the global keymap, in which case the change is effective in
1465 all major modes (except those that have their own overriding local
1466 definitions for the same key). Or you can change the current buffer's
1467 local map, which affects all buffers using the same major mode.
1469 @findex global-set-key
1470 @findex local-set-key
1471 @findex global-unset-key
1472 @findex local-unset-key
1474 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1475 Define @var{key} globally to run @var{cmd}.
1476 @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1477 Define @var{key} locally (in the major mode now in effect) to run
1479 @item M-x global-unset-key @key{RET} @var{key}
1480 Make @var{key} undefined in the global map.
1481 @item M-x local-unset-key @key{RET} @var{key}
1482 Make @var{key} undefined locally (in the major mode now in effect).
1485 For example, suppose you like to execute commands in a subshell within
1486 an Emacs buffer, instead of suspending Emacs and executing commands in
1487 your login shell. Normally, @kbd{C-z} is bound to the function
1488 @code{suspend-emacs} (when not using the X Window System), but you can
1489 change @kbd{C-z} to invoke an interactive subshell within Emacs, by
1490 binding it to @code{shell} as follows:
1493 M-x global-set-key @key{RET} C-z shell @key{RET}
1497 @code{global-set-key} reads the command name after the key. After you
1498 press the key, a message like this appears so that you can confirm that
1499 you are binding the key you want:
1502 Set key C-z to command:
1505 You can redefine function keys and mouse events in the same way; just
1506 type the function key or click the mouse when it's time to specify the
1509 You can rebind a key that contains more than one event in the same
1510 way. Emacs keeps reading the key to rebind until it is a complete key
1511 (that is, not a prefix key). Thus, if you type @kbd{C-f} for
1512 @var{key}, that's the end; the minibuffer is entered immediately to
1513 read @var{cmd}. But if you type @kbd{C-x}, another character is read;
1514 if that is @kbd{4}, another character is read, and so on. For
1518 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1522 redefines @kbd{C-x 4 $} to run the (fictitious) command
1523 @code{spell-other-window}.
1525 The two-character keys consisting of @kbd{C-c} followed by a letter
1526 are reserved for user customizations. Lisp programs are not supposed to
1527 define these keys, so the bindings you make for them will be available
1528 in all major modes and will never get in the way of anything.
1530 You can remove the global definition of a key with
1531 @code{global-unset-key}. This makes the key @dfn{undefined}; if you
1532 type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
1533 a key undefined in the current major mode keymap, which makes the global
1534 definition (or lack of one) come back into effect in that major mode.
1536 If you have redefined (or undefined) a key and you subsequently wish
1537 to retract the change, undefining the key will not do the job---you need
1538 to redefine the key with its standard definition. To find the name of
1539 the standard definition of a key, go to a Fundamental mode buffer and
1540 use @kbd{C-h c}. The documentation of keys in this manual also lists
1541 their command names.
1543 If you want to prevent yourself from invoking a command by mistake, it
1544 is better to disable the command than to undefine the key. A disabled
1545 command is less work to invoke when you really want to.
1548 @node Init Rebinding
1549 @subsection Rebinding Keys in Your Init File
1551 If you have a set of key bindings that you like to use all the time,
1552 you can specify them in your @file{.emacs} file by using their Lisp
1553 syntax. (@xref{Init File}.)
1555 The simplest method for doing this works for ASCII characters and
1556 Meta-modified ASCII characters only. This method uses a string to
1557 represent the key sequence you want to rebind. For example, here's how
1558 to bind @kbd{C-z} to @code{shell}:
1561 (global-set-key "\C-z" 'shell)
1565 This example uses a string constant containing one character, @kbd{C-z}.
1566 The single-quote before the command name, @code{shell}, marks it as a
1567 constant symbol rather than a variable. If you omit the quote, Emacs
1568 would try to evaluate @code{shell} immediately as a variable. This
1569 probably causes an error; it certainly isn't what you want.
1571 Here is another example that binds a key sequence two characters long:
1574 (global-set-key "\C-xl" 'make-symbolic-link)
1577 When the key sequence includes function keys or mouse button events,
1578 or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use
1579 the more general method of rebinding, which uses a vector to specify the
1582 The way to write a vector in Emacs Lisp is with square brackets around
1583 the vector elements. Use spaces to separate the elements. If an
1584 element is a symbol, simply write the symbol's name---no other
1585 delimiters or punctuation are needed. If a vector element is a
1586 character, write it as a Lisp character constant: @samp{?} followed by
1587 the character as it would appear in a string.
1589 Here are examples of using vectors to rebind @kbd{C-=} (a control
1590 character outside of ASCII), @kbd{H-a} (a Hyper character; ASCII doesn't
1591 have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
1592 keyboard-modified mouse button):
1595 (global-set-key [?\C-=] 'make-symbolic-link)
1596 (global-set-key [?\H-a] 'make-symbolic-link)
1597 (global-set-key [f7] 'make-symbolic-link)
1598 (global-set-key [C-mouse-1] 'make-symbolic-link)
1601 You can use a vector for the simple cases too. Here's how to rewrite
1602 the first two examples, above, to use vectors:
1605 (global-set-key [?\C-z] 'shell)
1607 (global-set-key [?\C-x ?l] 'make-symbolic-link)
1611 @subsection Rebinding Function Keys
1613 Key sequences can contain function keys as well as ordinary
1614 characters. Just as Lisp characters (actually integers) represent
1615 keyboard characters, Lisp symbols represent function keys. If the
1616 function key has a word as its label, then that word is also the name of
1617 the corresponding Lisp symbol. Here are the conventional Lisp names for
1618 common function keys:
1621 @item @code{left}, @code{up}, @code{right}, @code{down}
1624 @item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
1625 Other cursor repositioning keys.
1627 @item @code{select}, @code{print}, @code{execute}, @code{backtab}
1628 @itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
1629 @itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar},
1630 Miscellaneous function keys.
1632 @item @code{f1}, @code{f2}, @dots{} @code{f35}
1633 Numbered function keys (across the top of the keyboard).
1635 @item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
1636 @itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
1637 @itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
1638 Keypad keys (to the right of the regular keyboard), with names or punctuation.
1640 @item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
1641 Keypad keys with digits.
1643 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1647 These names are conventional, but some systems (especially when using
1648 X) may use different names. To make certain what symbol is used for a
1649 given function key on your terminal, type @kbd{C-h c} followed by that
1652 A key sequence which contains function key symbols (or anything but
1653 ASCII characters) must be a vector rather than a string. The vector
1654 syntax uses spaces between the elements, and square brackets around the
1655 whole vector. Thus, to bind function key @samp{f1} to the command
1656 @code{rmail}, write the following:
1659 (global-set-key [f1] 'rmail)
1663 To bind the right-arrow key to the command @code{forward-char}, you can
1664 use this expression:
1667 (global-set-key [right] 'forward-char)
1671 This uses the Lisp syntax for a vector containing the symbol
1672 @code{right}. (This binding is present in Emacs by default.)
1674 @xref{Init Rebinding}, for more information about using vectors for
1677 You can mix function keys and characters in a key sequence. This
1678 example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
1681 (global-set-key [?\C-x next] 'forward-page)
1685 where @code{?\C-x} is the Lisp character constant for the character
1686 @kbd{C-x}. The vector element @code{next} is a symbol and therefore
1687 does not take a question mark.
1689 You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
1690 @key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent
1691 these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
1692 @samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name.
1693 Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a
1697 (global-set-key [H-M-right] 'forward-word)
1700 @node Named ASCII Chars
1701 @subsection Named ASCII Control Characters
1703 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
1704 started out as names for certain ASCII control characters, used so often
1705 that they have special keys of their own. Later, users found it
1706 convenient to distinguish in Emacs between these keys and the ``same''
1707 control characters typed with the @key{CTRL} key.
1709 Emacs distinguishes these two kinds of input, when the keyboard
1710 reports these keys to Emacs. It treats the ``special'' keys as function
1711 keys named @code{tab}, @code{return}, @code{backspace}, @code{linefeed},
1712 @code{escape}, and @code{delete}. These function keys translate
1713 automatically into the corresponding ASCII characters @emph{if} they
1714 have no bindings of their own. As a result, neither users nor Lisp
1715 programs need to pay attention to the distinction unless they care to.
1717 If you do not want to distinguish between (for example) @key{TAB} and
1718 @kbd{C-i}, make just one binding, for the ASCII character @key{TAB}
1719 (octal code 011). If you do want to distinguish, make one binding for
1720 this ASCII character, and another for the ``function key'' @code{tab}.
1722 With an ordinary ASCII terminal, there is no way to distinguish
1723 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
1724 because the terminal sends the same character in both cases.
1726 @node Non-ASCII Rebinding
1727 @subsection Non-ASCII Characters on the Keyboard
1729 If your keyboard has keys that send non-ASCII characters, such as
1730 accented letters, rebinding these keys is a bit tricky. There are two
1731 solutions you can use. One is to specify a keyboard coding system,
1732 using @code{set-keyboard-coding-system} (@pxref{Specify Coding}).
1733 Then you can bind these keys in the usual way@footnote{Note that you
1734 should avoid the string syntax for binding 8-bit characters, since
1735 they will be interpreted as meta keys. @xref{Strings of
1736 Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this:
1739 (global-set-key [?@var{char}] 'some-function)
1743 Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
1745 If you don't specify the keyboard coding system, that approach won't
1746 work. Instead, you need to find out the actual code that the terminal
1747 sends. The easiest way to do this in Emacs is to create an empty buffer
1748 with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x
1749 toggle-enable-multibyte-characters @key{RET}}, then type the key to
1750 insert the character into this buffer.
1752 Move point before the character, then type @kbd{C-x =}. This
1753 displays a message in the minibuffer, showing the character code in
1754 three ways, octal, decimal and hexadecimal, all within a set of
1755 parentheses. Use the second of the three numbers, the decimal one,
1756 inside the vector to bind:
1759 (global-set-key [@var{decimal-code}] 'some-function)
1762 If you bind 8-bit characters like this in your init file, you my find it
1763 convenient to specify that it is unibyte. @xref{Enabling Multibyte}.
1766 @subsection Rebinding Mouse Buttons
1767 @cindex mouse button events
1768 @cindex rebinding mouse buttons
1769 @cindex click events
1772 @cindex button down events
1774 Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
1775 mouse events in Emacs are @dfn{click} events; these happen when you
1776 press a button and release it without moving the mouse. You can also
1777 get @dfn{drag} events, when you move the mouse while holding the button
1778 down. Drag events happen when you finally let go of the button.
1780 The symbols for basic click events are @code{mouse-1} for the leftmost
1781 button, @code{mouse-2} for the next, and so on. Here is how you can
1782 redefine the second mouse button to split the current window:
1785 (global-set-key [mouse-2] 'split-window-vertically)
1788 The symbols for drag events are similar, but have the prefix
1789 @samp{drag-} before the word @samp{mouse}. For example, dragging the
1790 first button generates a @code{drag-mouse-1} event.
1792 You can also define bindings for events that occur when a mouse button
1793 is pressed down. These events start with @samp{down-} instead of
1794 @samp{drag-}. Such events are generated only if they have key bindings.
1795 When you get a button-down event, a corresponding click or drag event
1798 @cindex double clicks
1799 @cindex triple clicks
1800 If you wish, you can distinguish single, double, and triple clicks. A
1801 double click means clicking a mouse button twice in approximately the
1802 same place. The first click generates an ordinary click event. The
1803 second click, if it comes soon enough, generates a double-click event
1804 instead. The event type for a double-click event starts with
1805 @samp{double-}: for example, @code{double-mouse-3}.
1807 This means that you can give a special meaning to the second click at
1808 the same place, but it must act on the assumption that the ordinary
1809 single click definition has run when the first click was received.
1811 This constrains what you can do with double clicks, but user interface
1812 designers say that this constraint ought to be followed in any case. A
1813 double click should do something similar to the single click, only
1814 ``more so.'' The command for the double-click event should perform the
1815 extra work for the double click.
1817 If a double-click event has no binding, it changes to the
1818 corresponding single-click event. Thus, if you don't define a
1819 particular double click specially, it executes the single-click command
1822 Emacs also supports triple-click events whose names start with
1823 @samp{triple-}. Emacs does not distinguish quadruple clicks as event
1824 types; clicks beyond the third generate additional triple-click events.
1825 However, the full number of clicks is recorded in the event list, so you
1826 can distinguish if you really want to. We don't recommend distinct
1827 meanings for more than three clicks, but sometimes it is useful for
1828 subsequent clicks to cycle through the same set of three meanings, so
1829 that four clicks are equivalent to one click, five are equivalent to
1830 two, and six are equivalent to three.
1832 Emacs also records multiple presses in drag and button-down events.
1833 For example, when you press a button twice, then move the mouse while
1834 holding the button, Emacs gets a @samp{double-drag-} event. And at the
1835 moment when you press it down for the second time, Emacs gets a
1836 @samp{double-down-} event (which is ignored, like all button-down
1837 events, if it has no binding).
1839 @vindex double-click-time
1840 The variable @code{double-click-time} specifies how long may elapse
1841 between clicks that are recognized as a pair. Its value is measured
1842 in milliseconds. If the value is @code{nil}, double clicks are not
1843 detected at all. If the value is @code{t}, then there is no time
1846 The symbols for mouse events also indicate the status of the modifier
1847 keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
1848 @samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-}
1849 or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
1851 A frame includes areas that don't show text from the buffer, such as
1852 the mode line and the scroll bar. You can tell whether a mouse button
1853 comes from a special area of the screen by means of dummy ``prefix
1854 keys.'' For example, if you click the mouse in the mode line, you get
1855 the prefix key @code{mode-line} before the ordinary mouse-button symbol.
1856 Thus, here is how to define the command for clicking the first button in
1857 a mode line to run @code{scroll-up}:
1860 (global-set-key [mode-line mouse-1] 'scroll-up)
1863 Here is the complete list of these dummy prefix keys and their
1868 The mouse was in the mode line of a window.
1870 The mouse was in the vertical line separating side-by-side windows. (If
1871 you use scroll bars, they appear in place of these vertical lines.)
1872 @item vertical-scroll-bar
1873 The mouse was in a vertical scroll bar. (This is the only kind of
1874 scroll bar Emacs currently supports.)
1876 @item horizontal-scroll-bar
1877 The mouse was in a horizontal scroll bar. Horizontal scroll bars do
1878 horizontal scrolling, and people don't use them often.
1882 You can put more than one mouse button in a key sequence, but it isn't
1886 @subsection Disabling Commands
1887 @cindex disabled command
1889 Disabling a command marks the command as requiring confirmation before it
1890 can be executed. The purpose of disabling a command is to prevent
1891 beginning users from executing it by accident and being confused.
1893 An attempt to invoke a disabled command interactively in Emacs
1894 displays a window containing the command's name, its documentation, and
1895 some instructions on what to do immediately; then Emacs asks for input
1896 saying whether to execute the command as requested, enable it and
1897 execute it, or cancel. If you decide to enable the command, you are
1898 asked whether to do this permanently or just for the current session.
1899 Enabling permanently works by automatically editing your @file{.emacs}
1902 The direct mechanism for disabling a command is to put a
1903 non-@code{nil} @code{disabled} property on the Lisp symbol for the
1904 command. Here is the Lisp program to do this:
1907 (put 'delete-region 'disabled t)
1910 If the value of the @code{disabled} property is a string, that string
1911 is included in the message printed when the command is used:
1914 (put 'delete-region 'disabled
1915 "It's better to use `kill-region' instead.\n")
1918 @findex disable-command
1919 @findex enable-command
1920 You can make a command disabled either by editing the @file{.emacs}
1921 file directly or with the command @kbd{M-x disable-command}, which edits
1922 the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
1923 edits @file{.emacs} to enable a command permanently. @xref{Init File}.
1925 Whether a command is disabled is independent of what key is used to
1926 invoke it; disabling also applies if the command is invoked using
1927 @kbd{M-x}. Disabling a command has no effect on calling it as a
1928 function from Lisp programs.
1930 @node Keyboard Translations
1931 @section Keyboard Translations
1933 Some keyboards do not make it convenient to send all the special
1934 characters that Emacs uses. The most common problem case is the
1935 @key{DEL} character. Some keyboards provide no convenient way to type
1936 this very important character---usually because they were designed to
1937 expect the character @kbd{C-h} to be used for deletion. On these
1938 keyboards, if you press the key normally used for deletion, Emacs handles
1939 the @kbd{C-h} as a prefix character and offers you a list of help
1940 options, which is not what you want.
1942 @cindex keyboard translations
1943 @findex keyboard-translate
1944 You can work around this problem within Emacs by setting up keyboard
1945 translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into
1946 @kbd{C-h}, as follows:
1949 ;; @r{Translate @kbd{C-h} to @key{DEL}.}
1950 (keyboard-translate ?\C-h ?\C-?)
1952 ;; @r{Translate @key{DEL} to @kbd{C-h}.}
1953 (keyboard-translate ?\C-? ?\C-h)
1956 Keyboard translations are not the same as key bindings in keymaps
1957 (@pxref{Keymaps}). Emacs contains numerous keymaps that apply in
1958 different situations, but there is only one set of keyboard
1959 translations, and it applies to every character that Emacs reads from
1960 the terminal. Keyboard translations take place at the lowest level of
1961 input processing; the keys that are looked up in keymaps contain the
1962 characters that result from keyboard translation.
1964 On a window system, the keyboard key named @key{DELETE} is a function
1965 key and is distinct from the ASCII character named @key{DEL}.
1966 @xref{Named ASCII Chars}. Keyboard translations affect only ASCII
1967 character input, not function keys; thus, the above example used on a
1968 window system does not affect the @key{DELETE} key. However, the
1969 translation above isn't necessary on window systems, because Emacs can
1970 also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
1971 normally treats @key{BACKSPACE} as @key{DEL}.
1973 For full information about how to use keyboard translations, see
1974 @ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.
1977 @section The Syntax Table
1978 @cindex syntax table
1980 All the Emacs commands which parse words or balance parentheses are
1981 controlled by the @dfn{syntax table}. The syntax table says which
1982 characters are opening delimiters, which are parts of words, which are
1983 string quotes, and so on. It does this by assigning each character to
1984 one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
1985 some additional information also.
1987 Each major mode has its own syntax table (though sometimes related
1988 major modes share one syntax table) which it installs in each buffer
1989 that uses the mode. The syntax table installed in the current buffer
1990 is the one that all commands use, so we call it ``the'' syntax table.
1993 @findex describe-syntax
1994 To display a description of the contents of the current syntax
1995 table, type @kbd{C-h s} (@code{describe-syntax}). The description of
1996 each character includes both the string you would have to give to
1997 @code{modify-syntax-entry} to set up that character's current syntax,
1998 starting with the character which designates its syntax class, plus
1999 some English text to explain its meaning.
2001 A syntax table is actually a Lisp object, a char-table, whose
2002 elements are cons cells. For full information on the syntax table,
2003 see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
2007 @section The Init File, @file{~/.emacs}
2009 @cindex Emacs initialization file
2010 @cindex key rebinding, permanent
2011 @cindex rebinding keys, permanently
2012 @cindex startup (init file)
2014 When Emacs is started, it normally loads a Lisp program from the file
2015 @file{.emacs} or @file{.emacs.el} in your home directory. We call this
2016 file your @dfn{init file} because it specifies how to initialize Emacs
2017 for you. You can use the command line switch @samp{-q} to prevent
2018 loading your init file, and @samp{-u} (or @samp{--user}) to specify a
2019 different user's init file (@pxref{Entering Emacs}).
2021 There can also be a @dfn{default init file}, which is the library
2022 named @file{default.el}, found via the standard search path for
2023 libraries. The Emacs distribution contains no such library; your site
2024 may create one for local customizations. If this library exists, it is
2025 loaded whenever you start Emacs (except when you specify @samp{-q}).
2026 But your init file, if any, is loaded first; if it sets
2027 @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
2030 Your site may also have a @dfn{site startup file}; this is named
2031 @file{site-start.el}, if it exists. Emacs loads this library before it
2032 loads your init file. To inhibit loading of this library, use the
2033 option @samp{-no-site-file}. @xref{Initial Options}.
2035 If you have a large amount of code in your @file{.emacs} file, you
2036 should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
2037 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
2038 for more information about compiling Emacs Lisp programs.
2040 If you are going to write actual Emacs Lisp programs that go beyond
2041 minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
2043 @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
2048 * Init Syntax:: Syntax of constants in Emacs Lisp.
2049 * Init Examples:: How to do some things with an init file.
2050 * Terminal Init:: Each terminal type can have an init file.
2051 * Find Init:: How Emacs finds the init file.
2055 @subsection Init File Syntax
2057 The @file{.emacs} file contains one or more Lisp function call
2058 expressions. Each of these consists of a function name followed by
2059 arguments, all surrounded by parentheses. For example, @code{(setq
2060 fill-column 60)} calls the function @code{setq} to set the variable
2061 @code{fill-column} (@pxref{Filling}) to 60.
2063 The second argument to @code{setq} is an expression for the new value of
2064 the variable. This can be a constant, a variable, or a function call
2065 expression. In @file{.emacs}, constants are used most of the time. They can be:
2069 Numbers are written in decimal, with an optional initial minus sign.
2072 @cindex Lisp string syntax
2073 @cindex string syntax
2074 Lisp string syntax is the same as C string syntax with a few extra
2075 features. Use a double-quote character to begin and end a string constant.
2077 In a string, you can include newlines and special characters literally.
2078 But often it is cleaner to use backslash sequences for them: @samp{\n}
2079 for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
2080 @samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
2081 escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
2082 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
2083 Backslash and double-quote are the only characters for which backslash
2084 sequences are mandatory.
2086 @samp{\C-} can be used as a prefix for a control character, as in
2087 @samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for
2088 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
2089 @kbd{Control-Meta-A}.@refill
2091 @cindex international characters in @file{.emacs}
2092 @cindex non-ASCII characters in @file{.emacs}
2093 If you want to include non-ASCII characters in strings in your init
2094 file, you should consider putting a @samp{-*- coding: -*-} tag on the
2095 first line which states the coding system used to save your
2096 @file{.emacs}, as explained in @ref{Recognize Coding}. This is
2097 because the defaults for decoding non-ASCII text might not yet be set
2098 up by the time Emacs reads those parts of your init file which use
2099 such strings, and Emacs might decode those strings incorrectly.
2102 Lisp character constant syntax consists of a @samp{?} followed by
2103 either a character or an escape sequence starting with @samp{\}.
2104 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
2105 strings and characters are not interchangeable in Lisp; some contexts
2106 require one and some contexts require the other.
2109 @code{t} stands for `true'.
2112 @code{nil} stands for `false'.
2114 @item Other Lisp objects:
2115 Write a single-quote (') followed by the Lisp object you want.
2119 @subsection Init File Examples
2121 Here are some examples of doing certain commonly desired things with
2126 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
2130 (setq c-tab-always-indent nil)
2133 Here we have a variable whose value is normally @code{t} for `true'
2134 and the alternative is @code{nil} for `false'.
2137 Make searches case sensitive by default (in all buffers that do not
2141 (setq-default case-fold-search nil)
2144 This sets the default value, which is effective in all buffers that do
2145 not have local values for the variable. Setting @code{case-fold-search}
2146 with @code{setq} affects only the current buffer's local value, which
2147 is not what you probably want to do in an init file.
2150 @vindex user-mail-address
2151 Specify your own email address, if Emacs can't figure it out correctly.
2154 (setq user-mail-address "coon@@yoyodyne.com")
2157 Various Emacs packages that need your own email address use the value of
2158 @code{user-mail-address}.
2161 Make Text mode the default mode for new buffers.
2164 (setq default-major-mode 'text-mode)
2167 Note that @code{text-mode} is used because it is the command for
2168 entering Text mode. The single-quote before it makes the symbol a
2169 constant; otherwise, @code{text-mode} would be treated as a variable
2174 Set up defaults for the Latin-1 character set
2175 which supports most of the languages of Western Europe.
2178 (set-language-environment "Latin-1")
2183 Turn on Auto Fill mode automatically in Text mode and related modes.
2186 (add-hook 'text-mode-hook
2187 '(lambda () (auto-fill-mode 1)))
2190 This shows how to add a hook function to a normal hook variable
2191 (@pxref{Hooks}). The function we supply is a list starting with
2192 @code{lambda}, with a single-quote in front of it to make it a list
2193 constant rather than an expression.
2195 It's beyond the scope of this manual to explain Lisp functions, but for
2196 this example it is enough to know that the effect is to execute
2197 @code{(auto-fill-mode 1)} when Text mode is entered. You can replace
2198 that with any other expression that you like, or with several
2199 expressions in a row.
2201 Emacs comes with a function named @code{turn-on-auto-fill} whose
2202 definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
2203 way to write the above example is as follows:
2206 (add-hook 'text-mode-hook 'turn-on-auto-fill)
2210 Load the installed Lisp library named @file{foo} (actually a file
2211 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
2217 When the argument to @code{load} is a relative file name, not starting
2218 with @samp{/} or @samp{~}, @code{load} searches the directories in
2219 @code{load-path} (@pxref{Lisp Libraries}).
2222 Load the compiled Lisp file @file{foo.elc} from your home directory.
2228 Here an absolute file name is used, so no searching is done.
2231 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
2234 (global-set-key "\C-xl" 'make-symbolic-link)
2240 (define-key global-map "\C-xl" 'make-symbolic-link)
2243 Note once again the single-quote used to refer to the symbol
2244 @code{make-symbolic-link} instead of its value as a variable.
2247 Do the same thing for Lisp mode only.
2250 (define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
2254 Redefine all keys which now run @code{next-line} in Fundamental mode
2255 so that they run @code{forward-line} instead.
2257 @findex substitute-key-definition
2259 (substitute-key-definition 'next-line 'forward-line
2264 Make @kbd{C-x C-v} undefined.
2267 (global-unset-key "\C-x\C-v")
2270 One reason to undefine a key is so that you can make it a prefix.
2271 Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
2272 prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
2276 Make @samp{$} have the syntax of punctuation in Text mode.
2277 Note the use of a character constant for @samp{$}.
2280 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
2284 Enable the use of the command @code{narrow-to-region} without confirmation.
2287 (put 'narrow-to-region 'disabled nil)
2292 @subsection Terminal-specific Initialization
2294 Each terminal type can have a Lisp library to be loaded into Emacs when
2295 it is run on that type of terminal. For a terminal type named
2296 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
2297 found by searching the directories @code{load-path} as usual and trying the
2298 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
2299 subdirectory @file{term} of the directory where most Emacs libraries are
2302 The usual purpose of the terminal-specific library is to map the
2303 escape sequences used by the terminal's function keys onto more
2304 meaningful names, using @code{function-key-map}. See the file
2305 @file{term/lk201.el} for an example of how this is done. Many function
2306 keys are mapped automatically according to the information in the
2307 Termcap data base; the terminal-specific library needs to map only the
2308 function keys that Termcap does not specify.
2310 When the terminal type contains a hyphen, only the part of the name
2311 before the first hyphen is significant in choosing the library name.
2312 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
2313 the library @file{term/aaa}. The code in the library can use
2314 @code{(getenv "TERM")} to find the full terminal type name.@refill
2316 @vindex term-file-prefix
2317 The library's name is constructed by concatenating the value of the
2318 variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
2319 file can prevent the loading of the terminal-specific library by setting
2320 @code{term-file-prefix} to @code{nil}.
2322 @vindex term-setup-hook
2323 Emacs runs the hook @code{term-setup-hook} at the end of
2324 initialization, after both your @file{.emacs} file and any
2325 terminal-specific library have been read in. Add hook functions to this
2326 hook if you wish to override part of any of the terminal-specific
2327 libraries and to define initializations for terminals that do not have a
2328 library. @xref{Hooks}.
2331 @subsection How Emacs Finds Your Init File
2333 Normally Emacs uses the environment variable @env{HOME} to find
2334 @file{.emacs}; that's what @samp{~} means in a file name. But if you
2335 have done @code{su}, Emacs tries to find your own @file{.emacs}, not
2336 that of the user you are currently pretending to be. The idea is
2337 that you should get your own editor customizations even if you are
2338 running as the super user.
2340 More precisely, Emacs first determines which user's init file to use.
2341 It gets the user name from the environment variables @env{LOGNAME} and
2342 @env{USER}; if neither of those exists, it uses effective user-ID.
2343 If that user name matches the real user-ID, then Emacs uses @env{HOME};
2344 otherwise, it looks up the home directory corresponding to that user
2345 name in the system's data base of users.
2346 @c LocalWords: backtab