1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2004
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. @xref{X Resources},
12 for information on using X resources to customize Emacs.
14 Customization that you do within Emacs normally affects only the
15 particular Emacs session that you do it in---it does not persist
16 between sessions unless you save the customization in a file such as
17 @file{.emacs} or @file{.Xdefaults} that will affect future sessions.
18 @xref{Init File}. In the customization buffer, when you save
19 customizations for future sessions, this actually works by editing
20 @file{.emacs} for you.
22 Another means of customization is the keyboard macro, which is a
23 sequence of keystrokes to be replayed with a single command.
24 @xref{Keyboard Macros}, for full instruction how to record, manage, and
25 replay sequences of keys.
28 * Minor Modes:: Each minor mode is one feature you can turn on
29 independently of any others.
30 * Easy Customization::
31 Convenient way to browse and change user options.
32 * Variables:: Many Emacs commands examine Emacs variables
33 to decide what to do; by setting variables,
34 you can control their functioning.
35 * Key Bindings:: The keymaps say what command each key runs.
36 By changing them, you can "redefine keys".
37 * Keyboard Translations::
38 If your keyboard passes an undesired code
39 for a key, you can tell Emacs to
40 substitute another code.
41 * Syntax:: The syntax table controls how words and
42 expressions are parsed.
43 * Init File:: How to write common customizations in the
52 Minor modes are optional features which you can turn on or off. For
53 example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
54 between words as you type. All the minor modes are independent of each
55 other and of the selected major mode. Most minor modes say in the mode
56 line when they are on; for example, @samp{Fill} in the mode line means
57 that Auto Fill mode is on.
59 Append @code{-mode} to the name of a minor mode to get the name of a
60 command function that turns the mode on or off. Thus, the command to
61 enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These
62 commands are usually invoked with @kbd{M-x}, but you can bind keys to them
63 if you wish. With no argument, the function turns the mode on if it was
64 off and off if it was on. This is known as @dfn{toggling}. A positive
65 argument always turns the mode on, and an explicit zero argument or a
66 negative argument always turns it off.
68 Some minor modes are global: while enabled, they affect everything
69 you do in the Emacs session, in all buffers. Other minor modes are
70 buffer-local; they apply only to the current buffer, so you can enable
71 the mode in certain buffers and not others.
73 For most minor modes, the command name is also the name of a
74 variable which directly controls the mode. The mode is enabled
75 whenever this variable's value is non-@code{nil}, and the minor-mode
76 command works by setting the variable. For example, the command
77 @code{outline-minor-mode} works by setting the value of
78 @code{outline-minor-mode} as a variable; it is this variable that
79 directly turns Outline minor mode on and off. To check whether a
80 given minor mode works this way, use @kbd{C-h v} to ask for
81 documentation on the variable name.
83 These minor-mode variables provide a good way for Lisp programs to turn
84 minor modes on and off; they are also useful in a file's local variables
85 list. But please think twice before setting minor modes with a local
86 variables list, because most minor modes are a matter of user
87 preference---other users editing the same file might not want the same
88 minor modes you prefer.
90 The buffer-local minor modes include Abbrev mode, Auto Fill mode,
91 Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents mode,
92 Outline minor mode, Overwrite mode, and Binary Overwrite mode.
94 Abbrev mode allows you to define abbreviations that automatically expand
95 as you type them. For example, @samp{amd} might expand to @samp{abbrev
96 mode}. @xref{Abbrevs}, for full information.
98 Auto Fill mode allows you to enter filled text without breaking lines
99 explicitly. Emacs inserts newlines as necessary to prevent lines from
100 becoming too long. @xref{Filling}.
102 Auto Save mode causes the contents of a buffer to be saved
103 periodically to reduce the amount of work you can lose in case of a
104 system crash. @xref{Auto Save}.
106 Enriched mode enables editing and saving of formatted text.
107 @xref{Formatted Text}.
109 Flyspell mode automatically highlights misspelled words.
112 Font-Lock mode automatically highlights certain textual units found in
113 programs, such as comments, strings, and function names being defined.
114 This requires a window system that can display multiple fonts.
117 ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"},
118 @samp{^}, @samp{/} and @samp{~} combine with the following letter, to
119 produce an accented letter in the ISO Latin-1 character set. The
120 newer and more general feature of input methods more or less
121 supersedes ISO Accents mode. @xref{Single-Byte Character Support}.
123 Outline minor mode provides the same facilities as the major mode
124 called Outline mode; but since it is a minor mode instead, you can
125 combine it with any major mode. @xref{Outline Mode}.
127 @cindex Overwrite mode
128 @cindex mode, Overwrite
129 Overwrite mode causes ordinary printing characters to replace existing
130 text instead of shoving it to the right. For example, if point is in
131 front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a
132 @kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR}
133 as usual. In Overwrite mode, the command @kbd{C-q} inserts the next
134 character whatever it may be, even if it is a digit---this gives you a
135 way to insert a character instead of replacing an existing character.
137 @findex overwrite-mode
139 The command @code{overwrite-mode} is an exception to the rule that
140 commands which toggle minor modes are normally not bound to keys: it is
141 bound to the @key{INSERT} function key. This is because many other
142 programs bind @key{INSERT} to similar functions.
144 @findex binary-overwrite-mode
145 Binary Overwrite mode is a variant of Overwrite mode for editing
146 binary files; it treats newlines and tabs like other characters, so that
147 they overwrite other characters and can be overwritten by them.
148 In Binary Overwrite mode, digits after @kbd{C-q} specify an
149 octal character code, as usual.
151 The following minor modes normally apply to all buffers at once.
152 Since each is enabled or disabled by the value of a variable, you
153 @emph{can} set them differently for particular buffers, by explicitly
154 making the corresponding variables local in those buffers.
157 Icomplete mode displays an indication of available completions when
158 you are in the minibuffer and completion is active. @xref{Completion
161 Line Number mode enables continuous display in the mode line of the
162 line number of point, and Column Number mode enables display of the
163 column number. @xref{Mode Line}.
165 Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
166 Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of
167 these modes are enabled by default when you use the X Window System.
169 In Transient Mark mode, every change in the buffer contents
170 ``deactivates'' the mark, so that commands that operate on the region
171 will get an error. This means you must either set the mark, or
172 explicitly ``reactivate'' it, before each command that uses the region.
173 The advantage of Transient Mark mode is that Emacs can display the
174 region highlighted (currently only when using X). @xref{Mark}.
176 @node Easy Customization
177 @section Easy Customization Interface
180 Emacs has many @dfn{user options} which have values that you can set
181 in order to customize various commands. Many user options are
182 documented in this manual. Most user options are actually Lisp
183 variables (@pxref{Variables}), so their names appear in the Variable
184 Index (@pxref{Variable Index}). The rest are faces and their
185 attributes (@pxref{Faces}).
188 @cindex customization buffer
189 You can browse interactively through the the user options and change
190 some of them using @kbd{M-x customize}. This command creates a
191 @dfn{customization buffer}, which offers commands to navigate through
192 a logically organized structure of the Emacs user options; you can
193 also use it to edit and set their values, and to save settings
194 permanently in your @file{~/.emacs} file (@pxref{Init File}).
196 The appearance of the example buffers in this section is typically
197 different under a window system, since faces are then used to indicate
198 the active fields and other features.
201 * Groups: Customization Groups. How options are classified in a structure.
202 * Changing a Variable:: How to edit a value and set an option.
203 * Saving Customizations:: Details of saving customizations.
204 * Face Customization:: How to edit the attributes of a face.
205 * Specific Customization:: Making a customization buffer for specific
206 variables, faces, or groups.
209 @node Customization Groups
210 @subsection Customization Groups
211 @cindex customization groups
213 For customization purposes, user options are organized into
214 @dfn{groups} to help you find them. Groups are collected into bigger
215 groups, all the way up to a master group called @code{Emacs}.
217 @kbd{M-x customize} creates a customization buffer that shows the
218 top-level @code{Emacs} group and the second-level groups immediately
219 under it. It looks like this, in part:
222 /- Emacs group: ---------------------------------------------------\
223 [State]: visible group members are all at standard settings.
224 Customization of the One True Editor.
227 Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm
228 [State]: this option is unchanged from its standard setting.
229 How to ask for confirmation when leaving Emacs. [More]
231 Editing group: [Go to Group]
232 Basic text editing facilities.
234 External group: [Go to Group]
235 Interfacing to external utilities.
237 @var{more second-level groups}
239 \- Emacs group end ------------------------------------------------/
244 This says that the buffer displays the contents of the @code{Emacs}
245 group. The other groups are listed because they are its contents. But
246 they are listed differently, without indentation and dashes, because
247 @emph{their} contents are not included. Each group has a single-line
248 documentation string; the @code{Emacs} group also has a @samp{[State]}
251 @cindex editable fields (customization buffer)
252 @cindex active fields (customization buffer)
253 Most of the text in the customization buffer is read-only, but it
254 typically includes some @dfn{editable fields} that you can edit. There
255 are also @dfn{active fields}; this means a field that does something
256 when you @dfn{invoke} it. To invoke an active field, either click on it
257 with @kbd{Mouse-1}, or move point to it and type @key{RET}.
259 For example, the phrase @samp{[Go to Group]} that appears in a
260 second-level group is an active field. Invoking the @samp{[Go to
261 Group]} field for a group creates a new customization buffer, which
262 shows that group and its contents. This field is a kind of hypertext
263 link to another group.
265 The @code{Emacs} group includes a few user options itself, but
266 mainly it contains other groups, which contain more groups, which
267 contain the user options. By browsing the hierarchy of groups, you
268 will eventually find the feature you are interested in customizing.
269 Then you can use the customization buffer to set the options
270 pertaining to that feature. You can also go straight to a particular
271 group by name, using the command @kbd{M-x customize-group}.
273 @findex customize-browse
274 You can view the structure of customization groups on a larger scale
275 with @kbd{M-x customize-browse}. This command creates a special kind of
276 customization buffer which shows only the names of the groups (and
277 variables and faces), and their structure.
279 In this buffer, you can show the contents of a group by invoking
280 @samp{[+]}. When the group contents are visible, this button changes to
281 @samp{[-]}; invoking that hides the group contents.
283 Each group, variable, or face name in this buffer has an active field
284 which says @samp{[Group]}, @samp{[Variable]} or @samp{[Face]}. Invoking
285 that active field creates an ordinary customization buffer showing just
286 that group and its contents, just that variable, or just that face.
287 This is the way to set values in it.
289 @node Changing a Variable
290 @subsection Changing a Variable
292 Here is an example of what a variable looks like in the
293 customization buffer:
296 Kill Ring Max: [Hide] 60
297 [State]: this variable is unchanged from its standard setting.
298 Maximum length of kill ring before oldest elements are thrown away.
301 The text following @samp{[Hide]}, @samp{60} in this case, indicates
302 the current value of the variable. If you see @samp{[Show]} instead of
303 @samp{[Hide]}, it means that the value is hidden; the customization
304 buffer initially hides values that take up several lines. Invoke
305 @samp{[Show]} to show the value.
307 The line after the option name indicates the @dfn{customization state}
308 of the variable: in the example above, it says you have not changed the
309 option yet. The word @samp{[State]} at the beginning of this line is
310 active; you can get a menu of various operations by invoking it with
311 @kbd{Mouse-1} or @key{RET}. These operations are essential for
312 customizing the variable.
314 The line after the @samp{[State]} line displays the beginning of the
315 variable's documentation string. If there are more lines of
316 documentation, this line ends with @samp{[More]}; invoke this to show
317 the full documentation string.
319 To enter a new value for @samp{Kill Ring Max}, move point to the value
320 and edit it textually. For example, you can type @kbd{M-d}, then insert
323 When you begin to alter the text, you will see the @samp{[State]} line
324 change to say that you have edited the value:
327 [State]: you have edited the value as text, but not set the variable.
330 @cindex setting option value
331 Editing the value does not actually set the variable. To do
332 that, you must @dfn{set} it. To do this, invoke the word
333 @samp{[State]} and choose @samp{Set for Current Session}.
335 The state of the variable changes visibly when you set it:
338 [State]: you have set this variable, but not saved it for future sessions.
341 You don't have to worry about specifying a value that is not valid;
342 setting the variable checks for validity and will not really install an
345 @kindex M-TAB @r{(customization buffer)}
346 @findex widget-complete
347 While editing a value or field that is a file name, directory name,
348 command name, or anything else for which completion is defined, you can
349 type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
351 Some variables have a small fixed set of possible legitimate values.
352 These variables don't let you edit the value textually. Instead, an
353 active field @samp{[Value Menu]} appears before the value; invoke this
354 field to edit the value. For a boolean ``on or off'' value, the active
355 field says @samp{[Toggle]}, and it changes to the other value.
356 @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
357 take effect when you use the @samp{Set for Current Session} operation.
359 Some variables have values with complex structure. For example, the
360 value of @code{file-coding-system-alist} is an association list. Here
361 is how it appears in the customization buffer:
364 File Coding System Alist: [Hide]
365 [INS] [DEL] File regexp: \.elc\'
366 Choice: [Value Menu] Encoding/decoding pair:
369 [INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\'
370 Choice: [Value Menu] Encoding/decoding pair:
372 Encoding: raw-text-unix
373 [INS] [DEL] File regexp: \.tar\'
374 Choice: [Value Menu] Encoding/decoding pair:
375 Decoding: no-conversion
376 Encoding: no-conversion
377 [INS] [DEL] File regexp:
378 Choice: [Value Menu] Encoding/decoding pair:
382 [State]: this variable is unchanged from its standard setting.
383 Alist to decide a coding system to use for a file I/O operation. [Hide]
384 The format is ((PATTERN . VAL) ...),
385 where PATTERN is a regular expression matching a file name,
386 @r{[@dots{}more lines of documentation@dots{}]}
390 Each association in the list appears on four lines, with several
391 editable or ``active'' fields. You can edit the regexps and coding
392 systems using ordinary editing commands. You can also invoke
393 @samp{[Value Menu]} to switch to a kind of value---for instance, to
394 specify a function instead of a pair of coding systems.
396 To delete an association from the list, invoke the @samp{[DEL]} button
397 for that item. To add an association, invoke @samp{[INS]} at the
398 position where you want to add it. There is an @samp{[INS]} button
399 between each pair of association, another at the beginning and another
400 at the end, so you can add the new association at any position in the
403 @kindex TAB @r{(customization buffer)}
404 @kindex S-TAB @r{(customization buffer)}
405 @findex widget-forward
406 @findex widget-backward
407 Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for
408 moving through the customization buffer. @key{TAB}
409 (@code{widget-forward}) moves forward to the next active or editable
410 field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the
411 previous active or editable field.
413 Typing @key{RET} on an editable field also moves forward, just like
414 @key{TAB}. We set it up this way because people often type @key{RET}
415 when they are finished editing a field. To insert a newline within an
416 editable field, use @kbd{C-o} or @kbd{C-q C-j}.
418 @cindex saving variable value
419 @cindex customized variables, saving
420 Setting the variable changes its value in the current Emacs session;
421 @dfn{saving} the value changes it for future sessions as well. To
422 save the variable, invoke @samp{[State]} and select the @samp{Save for
423 Future Sessions} operation. This works by writing code so as to set
424 the variable again, each time you start Emacs (@pxref{Saving
427 You can also restore the variable to its standard value by invoking
428 @samp{[State]} and selecting the @samp{Erase Customization} operation.
429 There are actually three reset operations:
433 If you have made some modifications and not yet set the variable,
434 this restores the text in the customization buffer to match
438 This restores the value of the variable to the last saved value,
439 and updates the text accordingly.
441 @item Erase Customization
442 This sets the variable to its standard value, and updates the text
443 accordingly. This also eliminates any saved value for the option,
444 so that you will get the standard value in future Emacs sessions.
446 @item Use Backup Value
447 This sets the variable to a previous value that was set in the
448 customization buffer in this session. If you customize a variable
449 and then reset it, which discards the customized value,
450 you can get the customized value back again with this operation.
453 @cindex comments on customized options
454 Sometimes it is useful to record a comment about a specific
455 customization. Use the @samp{Add Comment} item from the
456 @samp{[State]} menu to create a field for entering the comment. The
457 comment you enter will be saved, and displayed again if you again view
458 the same variable in a customization buffer, even in another session.
460 The state of a group indicates whether anything in that group has been
461 edited, set or saved. You can select @samp{Set for Current Session},
462 @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
463 operation for the group; these operations on the group apply to all
464 options in the group and its subgroups.
466 Near the top of the customization buffer there are two lines
467 containing several active fields:
470 [Set for Current Session] [Save for Future Sessions]
471 [Reset] [Reset to Saved] [Erase Customization] [Finish]
474 @vindex custom-buffer-done-function
476 Invoking @samp{[Finish]} either buries or kills this customization
477 buffer according to the setting of the option
478 @code{custom-buffer-done-function}; the default is to bury the buffer.
479 Each of the other fields performs an operation---set, save or
480 reset---on each of the options in the buffer that could meaningfully
481 be set, saved or reset. They do not operate on options whose values
484 @node Saving Customizations
485 @subsection Saving Customizations
488 The customization buffer normally saves customizations in
489 @file{~/.emacs}. If you wish, you can save customizations in another
490 file instead. To make this work, your @file{~/.emacs} should set
491 @code{custom-file} to the name of that file. Then you should load the
492 file by calling @code{load}. For example:
495 (setq custom-file "~/.emacs-custom.el")
499 You can also use @code{custom-file} to specify different
500 customization files for different Emacs versions, like this:
503 (cond ((< emacs-major-version 21)
504 ;; @r{Emacs 20 customization.}
505 (setq custom-file "~/.custom-20.el"))
506 ((and (= emacs-major-version 21) (< emacs-minor-version 4))
507 ;; @r{Emacs 21 customization, before version 21.4.}
508 (setq custom-file "~/.custom-21.el"))
510 ;; @r{Emacs version 21.4 or later.}
511 (setq custom-file "~/.custom-21.4.el")))
516 If Emacs was invoked with the @option{-q} or @option{--no-init-file}
517 options (@pxref{Initial Options}), it will not let you save your
518 customizations in your @file{~/.emacs} init file. This is because
519 saving customizations from such a session would wipe out all the other
520 customizations you might have on your init file.
522 @node Face Customization
523 @subsection Customizing Faces
524 @cindex customizing faces
527 @cindex fonts and faces
529 In addition to variables, some customization groups also include
530 faces. When you show the contents of a group, both the variables and
531 the faces in the group appear in the customization buffer. Here is an
532 example of how a face looks:
535 Custom Changed Face:(sample) [Hide]
536 [State]: this face is unchanged from its standard setting.
537 Face used when the customize item has been changed.
538 Parent groups: => Custom Magic Faces
539 Attributes: [ ] Font Family: *
546 [ ] Strike-through: *
547 [ ] Box around text: *
549 [X] Foreground: white (sample)
550 [X] Background: blue (sample)
555 Each face attribute has its own line. The @samp{[@var{x}]} field
556 before the attribute name indicates whether the attribute is
557 @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
558 attribute by invoking that field. When the attribute is enabled, you
559 can change the attribute value in the usual ways.
561 For the colors, you can specify a color name (use @kbd{M-x
562 list-colors-display}) for a list of them) or a hexadecimal color
563 specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
564 (@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
565 green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a
566 black-and-white display, the colors you can use for the background are
567 @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and
568 @samp{gray3}. Emacs supports these shades of gray by using background
569 stipple patterns instead of a color.
571 Setting, saving and resetting a face work like the same operations for
572 variables (@pxref{Changing a Variable}).
574 A face can specify different appearances for different types of
575 display. For example, a face can make text red on a color display, but
576 use a bold font on a monochrome display. To specify multiple
577 appearances for a face, select @samp{Show all display specs} in the menu you
578 get from invoking @samp{[State]}.
581 Another more basic way to set the attributes of a specific face is
582 with @kbd{M-x modify-face}. This command reads the name of a face, then
583 reads the attributes one by one. For the color and stipple attributes,
584 the attribute's current value is the default---type just @key{RET} if
585 you don't want to change that attribute. Type @samp{none} if you want
586 to clear out the attribute.
588 @node Specific Customization
589 @subsection Customizing Specific Items
591 Instead of finding the options you want to change by moving down
592 through the structure of groups, you can specify the particular variable,
593 face, or group that you want to customize.
596 @item M-x customize-variable @key{RET} @var{variable} @key{RET}
597 Set up a customization buffer with just one variable, @var{variable}.
598 @item M-x customize-face @key{RET} @var{face} @key{RET}
599 Set up a customization buffer with just one face, @var{face}.
600 @item M-x customize-group @key{RET} @var{group} @key{RET}
601 Set up a customization buffer with just one group, @var{group}.
602 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
603 Set up a customization buffer with all the variables, faces and groups
604 that match @var{regexp}.
605 @item M-x customize-changed-options @key{RET} @var{version} @key{RET}
606 Set up a customization buffer with all the variables, faces and groups
607 whose meaning has changed since Emacs version @var{version}.
608 @item M-x customize-saved
609 Set up a customization buffer containing all variables and faces that you
610 have saved with customization buffers.
611 @item M-x customize-customized
612 Set up a customization buffer containing all variables and faces that you
613 have customized but not saved.
616 @findex customize-variable
617 If you want to alter a particular variable with the customization
618 buffer, and you know its name, you can use the command @kbd{M-x
619 customize-variable} and specify the variable name. This sets up the
620 customization buffer with just one variable---the one that you asked
621 for. Editing, setting and saving the value work as described above,
622 but only for the specified variable.
624 @findex customize-face
625 Likewise, you can modify a specific face, chosen by name, using
626 @kbd{M-x customize-face}. By default it operates on the face used
627 on the character after point.
629 @findex customize-group
630 You can also set up the customization buffer with a specific group,
631 using @kbd{M-x customize-group}. The immediate contents of the chosen
632 group, including user options, faces, and other groups, all appear
633 as well. However, these subgroups' own contents start out hidden. You
634 can show their contents in the usual way, by invoking @samp{[Show]}.
636 @findex customize-apropos
637 To control more precisely what to customize, you can use @kbd{M-x
638 customize-apropos}. You specify a regular expression as argument; then
639 all options, faces and groups whose names match this regular expression
640 are set up in the customization buffer. If you specify an empty regular
641 expression, this includes @emph{all} groups, options and faces in the
642 customization buffer (but that takes a long time).
644 @findex customize-changed-options
645 When you upgrade to a new Emacs version, you might want to customize
646 new options and options whose meanings or default values have changed.
647 To do this, use @kbd{M-x customize-changed-options} and specify a
648 previous Emacs version number using the minibuffer. It creates a
649 customization buffer which shows all the options (and groups) whose
650 definitions have been changed since the specified version.
652 @findex customize-saved
653 @findex customize-customized
654 If you change option values and then decide the change was a
655 mistake, you can use two special commands to revisit your previous
656 changes. Use @kbd{M-x customize-saved} to look at the options that
657 you have saved. Use @kbd{M-x customize-customized} to look at the
658 options that you have set but not saved.
666 A @dfn{variable} is a Lisp symbol which has a value. The symbol's
667 name is also called the name of the variable. A variable name can
668 contain any characters that can appear in a file, but conventionally
669 variable names consist of words separated by hyphens. A variable can
670 have a documentation string which describes what kind of value it should
671 have and how the value will be used.
673 Lisp allows any variable to have any kind of value, but most variables
674 that Emacs uses need a value of a certain type. Often the value should
675 always be a string, or should always be a number. Sometimes we say that a
676 certain feature is turned on if a variable is ``non-@code{nil},'' meaning
677 that if the variable's value is @code{nil}, the feature is off, but the
678 feature is on for @emph{any} other value. The conventional value to use to
679 turn on the feature---since you have to pick one particular value when you
680 set the variable---is @code{t}.
682 Emacs uses many Lisp variables for internal record keeping, but the
683 most interesting variables for a non-programmer user are those that
684 are also @dfn{user options}, the variables that are meant for users to
685 change. Each user option that you can set with the customization
686 buffer is (if it is not a face) in fact a Lisp variable. Emacs does
687 not (usually) change the values of these variables; instead, you set
688 the values, and thereby alter and control the behavior of certain
689 Emacs commands. Use of the customization buffer is explained above
690 (@pxref{Easy Customization}); here we describe other aspects of Emacs
694 * Examining:: Examining or setting one variable's value.
695 * Hooks:: Hook variables let you specify programs for parts
696 of Emacs to run on particular occasions.
697 * Locals:: Per-buffer values of variables.
698 * File Variables:: How files can specify variable values.
702 @subsection Examining and Setting Variables
703 @cindex setting variables
706 @item C-h v @var{var} @key{RET}
707 Display the value and documentation of variable @var{var}
708 (@code{describe-variable}).
709 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
710 Change the value of variable @var{var} to @var{value}.
713 To examine the value of a single variable, use @kbd{C-h v}
714 (@code{describe-variable}), which reads a variable name using the
715 minibuffer, with completion. It displays both the value and the
716 documentation of the variable. For example,
719 C-h v fill-column @key{RET}
723 displays something like this:
726 fill-column's value is 70
729 *Column beyond which automatic line-wrapping should happen.
730 Automatically becomes buffer-local when set in any fashion.
734 The star at the beginning of the documentation indicates that this
735 variable is a user option. @kbd{C-h v} is not restricted to user
736 options; it allows any variable name.
739 The most convenient way to set a specific user option variable is
740 with @kbd{M-x set-variable}. This reads the variable name with the
741 minibuffer (with completion), and then reads a Lisp expression for the
742 new value using the minibuffer a second time. For example,
745 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
749 sets @code{fill-column} to 75.
751 @kbd{M-x set-variable} is limited to user option variables, but you can
752 set any variable with a Lisp expression, using the function @code{setq}.
753 Here is a @code{setq} expression to set @code{fill-column}:
756 (setq fill-column 75)
759 To execute an expression like this one, go to the @samp{*scratch*}
760 buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
763 Setting variables, like all means of customizing Emacs except where
764 otherwise stated, affects only the current Emacs session. The only
765 way to alter the variable in future sessions is to put something in
766 the @file{~/.emacs} file to set it those sessions (@pxref{Init File}).
771 @cindex running a hook
773 @dfn{Hooks} are an important mechanism for customization of Emacs. A
774 hook is a Lisp variable which holds a list of functions, to be called on
775 some well-defined occasion. (This is called @dfn{running the hook}.)
776 The individual functions in the list are called the @dfn{hook functions}
777 of the hook. With rare exceptions, hooks in Emacs are empty when Emacs
778 starts up, so the only hook functions in any given hook are the ones you
779 explicitly put there as customization.
781 Most major modes run one or more @dfn{mode hooks} as the last step of
782 initialization. This makes it easy for you to customize the behavior of
783 the mode, by setting up a hook function to override the local variable
784 assignments already made by the mode. But hooks are also used in other
785 contexts. For example, the hook @code{suspend-hook} runs just before
786 Emacs suspends itself (@pxref{Exiting}).
789 Most Emacs hooks are @dfn{normal hooks}. This means that running the
790 hook operates by calling all the hook functions, unconditionally, with
791 no arguments. We have made an effort to keep most hooks normal so that
792 you can use them in a uniform way. Every variable in Emacs whose name
793 ends in @samp{-hook} is a normal hook.
795 @cindex abnormal hook
796 There are also a few @dfn{abnormal hooks}. These variables' names end
797 in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What
798 makes these hooks abnormal is that there is something peculiar about the
799 way its functions are called---perhaps they are given arguments, or
800 perhaps the values they return are used in some way. For example,
801 @code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
802 as soon as one hook function returns a non-@code{nil} value, the rest
803 are not called at all. The documentation of each abnormal hook variable
804 explains in detail what is peculiar about it.
806 You can set a hook variable with @code{setq} like any other Lisp
807 variable, but the recommended way to add a hook function to a hook
808 (either normal or abnormal) is by calling @code{add-hook}. You can
809 specify any valid Lisp function as the hook function, provided it can
810 handle the proper number of arguments (zero arguments, in the case of
811 a normal hook). Of course, not every Lisp function is @emph{useful}
812 in any particular hook.
814 For example, here's how to set up a hook to turn on Auto Fill mode
815 when entering Text mode and other modes based on Text mode:
818 (add-hook 'text-mode-hook 'turn-on-auto-fill)
821 The next example shows how to use a hook to customize the indentation
822 of C code. (People often have strong personal preferences for one
823 format compared to another.) Here the hook function is an anonymous
829 '((c-comment-only-line-offset . 4)
832 (c-cleanup-list . (scope-operator
837 (c-offsets-alist . ((arglist-close . c-lineup-arglist)
838 (substatement-open . 0)))))
842 (add-hook 'c-mode-common-hook
844 (c-add-style "my-style" my-c-style t)))
848 It is best to design your hook functions so that the order in which
849 they are executed does not matter. Any dependence on the order is
850 ``asking for trouble.'' However, the order is predictable: the most
851 recently added hook functions are executed first.
853 If you play with adding various different versions of a hook
854 function by calling @code{add-hook} over and over, remember that all
855 the versions you added will remain in the hook variable together.
856 To clear them out, you can do @code{(setq @var{hook-variable} nil)}.
859 @subsection Local Variables
862 @item M-x make-local-variable @key{RET} @var{var} @key{RET}
863 Make variable @var{var} have a local value in the current buffer.
864 @item M-x kill-local-variable @key{RET} @var{var} @key{RET}
865 Make variable @var{var} use its global value in the current buffer.
866 @item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
867 Mark variable @var{var} so that setting it will make it local to the
868 buffer that is current at that time.
871 @cindex local variables
872 Almost any variable can be made @dfn{local} to a specific Emacs
873 buffer. This means that its value in that buffer is independent of its
874 value in other buffers. A few variables are always local in every
875 buffer. Every other Emacs variable has a @dfn{global} value which is in
876 effect in all buffers that have not made the variable local.
878 @findex make-local-variable
879 @kbd{M-x make-local-variable} reads the name of a variable and makes it
880 local to the current buffer. Further changes in this buffer will not
881 affect others, and further changes in the global value will not affect this
884 @findex make-variable-buffer-local
885 @cindex per-buffer variables
886 @kbd{M-x make-variable-buffer-local} reads the name of a variable and
887 changes the future behavior of the variable so that it will become local
888 automatically when it is set. More precisely, once a variable has been
889 marked in this way, the usual ways of setting the variable automatically
890 do @code{make-local-variable} first. We call such variables
891 @dfn{per-buffer} variables.
893 Major modes (@pxref{Major Modes}) always make variables local to the
894 buffer before setting the variables. This is why changing major modes
895 in one buffer has no effect on other buffers. Minor modes also work by
896 setting variables---normally, each minor mode has one controlling
897 variable which is non-@code{nil} when the mode is enabled (@pxref{Minor
898 Modes}). For most minor modes, the controlling variable is per buffer.
900 Emacs contains a number of variables that are always per-buffer.
901 These include @code{abbrev-mode}, @code{auto-fill-function},
902 @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
903 @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
904 @code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},
905 @code{selective-display-ellipses}, @code{selective-display},
906 @code{tab-width}, and @code{truncate-lines}. Some other variables are
907 always local in every buffer, but they are used for internal
910 A few variables cannot be local to a buffer because they are always
911 local to each display instead (@pxref{Multiple Displays}). If you try to
912 make one of these variables buffer-local, you'll get an error message.
914 @findex kill-local-variable
915 @kbd{M-x kill-local-variable} reads the name of a variable and makes
916 it cease to be local to the current buffer. The global value of the
917 variable henceforth is in effect in this buffer. Setting the major mode
918 kills all the local variables of the buffer except for a few variables
919 specially marked as @dfn{permanent locals}.
922 To set the global value of a variable, regardless of whether the
923 variable has a local value in the current buffer, you can use the Lisp
924 construct @code{setq-default}. This construct is used just like
925 @code{setq}, but it sets variables' global values instead of their local
926 values (if any). When the current buffer does have a local value, the
927 new global value may not be visible until you switch to another buffer.
931 (setq-default fill-column 75)
935 @code{setq-default} is the only way to set the global value of a variable
936 that has been marked with @code{make-variable-buffer-local}.
938 @findex default-value
939 Lisp programs can use @code{default-value} to look at a variable's
940 default value. This function takes a symbol as argument and returns its
941 default value. The argument is evaluated; usually you must quote it
942 explicitly. For example, here's how to obtain the default value of
946 (default-value 'fill-column)
950 @subsection Local Variables in Files
951 @cindex local variables in files
952 @cindex file local variables
954 A file can specify local variable values for use when you edit the
955 file with Emacs. Visiting the file checks for local variable
956 specifications; it automatically makes these variables local to the
957 buffer, and sets them to the values specified in the file.
959 There are two ways to specify local variable values: in the first
960 line, or with a local variables list. Here's how to specify them in the
964 -*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
968 You can specify any number of variables/value pairs in this way, each
969 pair with a colon and semicolon as shown above. @code{mode:
970 @var{modename};} specifies the major mode; this should come first in the
971 line. The @var{value}s are not evaluated; they are used literally.
972 Here is an example that specifies Lisp mode and sets two variables with
976 ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
979 You can also specify the coding system for a file in this way: just
980 specify a value for the ``variable'' named @code{coding}. The ``value''
981 must be a coding system name that Emacs recognizes. @xref{Coding
982 Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a
983 particular Lisp file. @xref{Enabling Multibyte}.
985 The @code{eval} pseudo-variable, described below, can be specified in
986 the first line as well.
988 @cindex shell scripts, and local file variables
989 In shell scripts, the first line is used to identify the script
990 interpreter, so you cannot put any local variables there. To accommodate
991 for this, when Emacs visits a shell script, it looks for local variable
992 specifications in the @emph{second} line.
994 A @dfn{local variables list} goes near the end of the file, in the
995 last page. (It is often best to put it on a page by itself.) The local
996 variables list starts with a line containing the string @samp{Local
997 Variables:}, and ends with a line containing the string @samp{End:}. In
998 between come the variable names and values, one set per line, as
999 @samp{@var{variable}:@: @var{value}}. The @var{value}s are not
1000 evaluated; they are used literally. If a file has both a local
1001 variables list and a @samp{-*-} line, Emacs processes @emph{everything}
1002 in the @samp{-*-} line first, and @emph{everything} in the local
1003 variables list afterward.
1005 Here is an example of a local variables list:
1008 ;;; Local Variables: ***
1010 ;;; comment-column:0 ***
1011 ;;; comment-start: ";;; " ***
1012 ;;; comment-end:"***" ***
1016 As you see, each line starts with the prefix @samp{;;; } and each line
1017 ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix
1018 and suffix based on the first line of the list, by finding them
1019 surrounding the magic string @samp{Local Variables:}; then it
1020 automatically discards them from the other lines of the list.
1022 The usual reason for using a prefix and/or suffix is to embed the
1023 local variables list in a comment, so it won't confuse other programs
1024 that the file is intended as input for. The example above is for a
1025 language where comment lines start with @samp{;;; } and end with
1026 @samp{***}; the local values for @code{comment-start} and
1027 @code{comment-end} customize the rest of Emacs for this unusual
1028 syntax. Don't use a prefix (or a suffix) if you don't need one.
1030 If you write a multi-line string value, you should put the prefix
1031 and suffix on each line, even lines that start or end within the
1032 string. They will be stripped off for processing the list. If you
1033 want to split a long string across multiple lines of the file, you can
1034 use backslash-newline, which is ignored in Lisp string constants.
1035 Here's an example of doing this:
1039 # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
1044 Some ``variable names'' have special meanings in a local variables
1045 list. Specifying the ``variable'' @code{mode} really sets the major
1046 mode, while any value specified for the ``variable'' @code{eval} is
1047 simply evaluated as an expression (its value is ignored). A value for
1048 @code{coding} specifies the coding system for character code
1049 conversion of this file, and a value of @code{t} for @code{unibyte}
1050 says to visit the file in a unibyte buffer. These four ``variables''
1051 are not really variables; setting them in any other context has no
1054 @emph{If @code{mode} is used to set a major mode, it should be the
1055 first ``variable'' in the list.} Otherwise, the entries that precede
1056 it will usually be ignored, since most modes kill all local variables
1057 as part of their initialization.
1059 You can use the @code{mode} ``variable'' to set minor modes as well
1060 as the major modes; in fact, you can use it more than once, first to
1061 set the major mode and then to set minor modes which are specific to
1062 particular buffers. But most minor modes should not be specified in
1063 the file at all, regardless of how, because they represent user
1066 For example, you may be tempted to try to turn on Auto Fill mode with
1067 a local variable list. That is a mistake. The choice of Auto Fill mode
1068 or not is a matter of individual taste, not a matter of the contents of
1069 particular files. If you want to use Auto Fill, set up major mode hooks
1070 with your @file{.emacs} file to turn it on (when appropriate) for you
1071 alone (@pxref{Init File}). Don't use a local variable list to impose
1072 your taste on everyone.
1074 The start of the local variables list must be no more than 3000
1075 characters from the end of the file, and must be in the last page if the
1076 file is divided into pages. Otherwise, Emacs will not notice it is
1077 there. The purpose of this rule is so that a stray @samp{Local
1078 Variables:}@: not in the last page does not confuse Emacs, and so that
1079 visiting a long file that is all one page and has no local variables
1080 list need not take the time to search the whole file.
1082 Use the command @code{normal-mode} to reset the local variables and
1083 major mode of a buffer according to the file name and contents,
1084 including the local variables list if any. @xref{Choosing Modes}.
1086 @findex enable-local-variables
1087 The variable @code{enable-local-variables} controls whether to process
1088 local variables in files, and thus gives you a chance to override them.
1089 Its default value is @code{t}, which means do process local variables in
1090 files. If you set the value to @code{nil}, Emacs simply ignores local
1091 variables in files. Any other value says to query you about each file
1092 that has local variables, showing you the local variable specifications
1095 @findex enable-local-eval
1096 The @code{eval} ``variable,'' and certain actual variables, create a
1097 special risk; when you visit someone else's file, local variable
1098 specifications for these could affect your Emacs in arbitrary ways.
1099 Therefore, the variable @code{enable-local-eval} controls whether Emacs
1100 processes @code{eval} variables, as well variables with names that end
1101 in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
1102 and certain other variables. The three possibilities for the variable's
1103 value are @code{t}, @code{nil}, and anything else, just as for
1104 @code{enable-local-variables}. The default is @code{maybe}, which is
1105 neither @code{t} nor @code{nil}, so normally Emacs does ask for
1106 confirmation about file settings for these variables.
1108 @findex safe-local-eval-forms
1109 The @code{safe-local-eval-forms} is a customizable list of eval
1110 forms which are safe to eval, so Emacs should not ask for
1111 confirmation to evaluate these forms, even if
1112 @code{enable-local-variables} says to ask for confirmation in general.
1115 @section Customizing Key Bindings
1116 @cindex key bindings
1118 This section describes @dfn{key bindings}, which map keys to commands,
1119 and @dfn{keymaps}, which record key bindings. It also explains how
1120 to customize key bindings.
1122 Recall that a command is a Lisp function whose definition provides for
1123 interactive use. Like every Lisp function, a command has a function
1124 name which usually consists of lower-case letters and hyphens.
1127 * Keymaps:: Generalities. The global keymap.
1128 * Prefix Keymaps:: Keymaps for prefix keys.
1129 * Local Keymaps:: Major and minor modes have their own keymaps.
1130 * Minibuffer Maps:: The minibuffer uses its own local keymaps.
1131 * Rebinding:: How to redefine one key's meaning conveniently.
1132 * Init Rebinding:: Rebinding keys with your init file, @file{.emacs}.
1133 * Function Keys:: Rebinding terminal function keys.
1134 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
1135 * Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} characters such as Latin-1.
1136 * Mouse Buttons:: Rebinding mouse buttons in Emacs.
1137 * Disabling:: Disabling a command means confirmation is required
1138 before it can be executed. This is done to protect
1139 beginners from surprises.
1146 The bindings between key sequences and command functions are recorded
1147 in data structures called @dfn{keymaps}. Emacs has many of these, each
1148 used on particular occasions.
1150 Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
1151 of @dfn{input events} that have a meaning as a unit. Input events
1152 include characters, function keys and mouse buttons---all the inputs
1153 that you can send to the computer with your terminal. A key sequence
1154 gets its meaning from its @dfn{binding}, which says what command it
1155 runs. The function of keymaps is to record these bindings.
1157 @cindex global keymap
1158 The @dfn{global} keymap is the most important keymap because it is
1159 always in effect. The global keymap defines keys for Fundamental mode;
1160 most of these definitions are common to most or all major modes. Each
1161 major or minor mode can have its own keymap which overrides the global
1162 definitions of some keys.
1164 For example, a self-inserting character such as @kbd{g} is
1165 self-inserting because the global keymap binds it to the command
1166 @code{self-insert-command}. The standard Emacs editing characters such
1167 as @kbd{C-a} also get their standard meanings from the global keymap.
1168 Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
1169 by storing the new binding in the proper place in the global map.
1172 Meta characters work differently; Emacs translates each Meta
1173 character into a pair of characters starting with @key{ESC}. When you
1174 type the character @kbd{M-a} in a key sequence, Emacs replaces it with
1175 @kbd{@key{ESC} a}. A meta key comes in as a single input event, but
1176 becomes two events for purposes of key bindings. The reason for this is
1177 historical, and we might change it someday.
1179 @cindex function key
1180 Most modern keyboards have function keys as well as character keys.
1181 Function keys send input events just as character keys do, and keymaps
1182 can have bindings for them.
1184 On text terminals, typing a function key actually sends the computer a
1185 sequence of characters; the precise details of the sequence depends on
1186 which function key and on the model of terminal you are using. (Often
1187 the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
1188 terminal type properly, it recognizes the character sequences forming
1189 function keys wherever they occur in a key sequence (not just at the
1190 beginning). Thus, for most purposes, you can pretend the function keys
1191 reach Emacs directly and ignore their encoding as character sequences.
1194 Mouse buttons also produce input events. These events come with other
1195 data---the window and position where you pressed or released the button,
1196 and a time stamp. But only the choice of button matters for key
1197 bindings; the other data matters only if a command looks at it.
1198 (Commands designed for mouse invocation usually do look at the other
1201 A keymap records definitions for single events. Interpreting a key
1202 sequence of multiple events involves a chain of keymaps. The first
1203 keymap gives a definition for the first event; this definition is
1204 another keymap, which is used to look up the second event in the
1205 sequence, and so on.
1207 Key sequences can mix function keys and characters. For example,
1208 @kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix
1209 key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse
1210 events with keyboard events, but we recommend against it, because such
1211 key sequences are inconvenient to use.
1213 As a user, you can redefine any key; but it is usually best to stick
1214 to key sequences that consist of @kbd{C-c} followed by a letter (upper
1215 or lower case). These keys are ``reserved for users,'' so they won't
1216 conflict with any properly designed Emacs extension. The function
1217 keys @key{F5} through @key{F9} are also reserved for users. If you
1218 redefine some other key, your definition may be overridden by certain
1219 extensions or major modes which redefine the same key.
1221 @node Prefix Keymaps
1222 @subsection Prefix Keymaps
1224 A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
1225 which holds the definition for the event that immediately follows
1228 The definition of a prefix key is usually the keymap to use for
1229 looking up the following event. The definition can also be a Lisp
1230 symbol whose function definition is the following keymap; the effect is
1231 the same, but it provides a command name for the prefix key that can be
1232 used as a description of what the prefix key is for. Thus, the binding
1233 of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
1234 definition is the keymap for @kbd{C-x} commands. The definitions of
1235 @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in
1236 the global map, so these prefix keys are always available.
1238 Aside from ordinary prefix keys, there is a fictitious ``prefix key''
1239 which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
1240 Reference Manual}, for special information about menu bar key bindings.
1241 Mouse button events that invoke pop-up menus are also prefix keys; see
1242 @ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
1245 Some prefix keymaps are stored in variables with names:
1250 @code{ctl-x-map} is the variable name for the map used for characters that
1254 @code{help-map} is for characters that follow @kbd{C-h}.
1257 @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
1258 characters are actually defined by this map.
1261 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1263 @vindex mode-specific-map
1264 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1268 @subsection Local Keymaps
1270 @cindex local keymap
1271 So far we have explained the ins and outs of the global map. Major
1272 modes customize Emacs by providing their own key bindings in @dfn{local
1273 keymaps}. For example, C mode overrides @key{TAB} to make it indent the
1274 current line for C code. Portions of text in the buffer can specify
1275 their own keymaps to substitute for the keymap of the buffer's major
1278 @cindex minor mode keymap
1279 Minor modes can also have local keymaps. Whenever a minor mode is
1280 in effect, the definitions in its keymap override both the major
1281 mode's local keymap and the global keymap.
1284 @vindex lisp-mode-map
1285 The local keymaps for Lisp mode and several other major modes always
1286 exist even when not in use. These are kept in variables named
1287 @code{lisp-mode-map} and so on. For major modes less often used, the
1288 local keymap is normally constructed only when the mode is used for the
1289 first time in a session. This is to save space. If you wish to change
1290 one of these keymaps, you must use the major mode's @dfn{mode
1293 All minor mode keymaps are created in advance. There is no way to
1294 defer their creation until the first time the minor mode is enabled.
1296 A local keymap can locally redefine a key as a prefix key by defining
1297 it as a prefix keymap. If the key is also defined globally as a prefix,
1298 then its local and global definitions (both keymaps) effectively
1299 combine: both of them are used to look up the event that follows the
1300 prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as
1301 another keymap, and that keymap defines @kbd{C-z} as a command, this
1302 provides a local meaning for @kbd{C-c C-z}. This does not affect other
1303 sequences that start with @kbd{C-c}; if those sequences don't have their
1304 own local bindings, their global bindings remain in effect.
1306 Another way to think of this is that Emacs handles a multi-event key
1307 sequence by looking in several keymaps, one by one, for a binding of the
1308 whole key sequence. First it checks the minor mode keymaps for minor
1309 modes that are enabled, then it checks the major mode's keymap, and then
1310 it checks the global keymap. This is not precisely how key lookup
1311 works, but it's good enough for understanding ordinary circumstances.
1313 @cindex rebinding major mode keys
1315 To change the local bindings of a major mode, you must change the
1316 mode's local keymap. Normally you must wait until the first time the
1317 mode is used, because most major modes don't create their keymaps until
1318 then. If you want to specify something in your @file{~/.emacs} file to
1319 change a major mode's bindings, you must use the mode's mode hook to
1320 delay the change until the mode is first used.
1322 For example, the command @code{texinfo-mode} to select Texinfo mode
1323 runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook
1324 to add local bindings (not very useful, we admit) for @kbd{C-c n} and
1325 @kbd{C-c p} in Texinfo mode:
1328 (add-hook 'texinfo-mode-hook
1330 (define-key texinfo-mode-map "\C-cp"
1331 'backward-paragraph)
1332 (define-key texinfo-mode-map "\C-cn"
1333 'forward-paragraph)))
1338 @node Minibuffer Maps
1339 @subsection Minibuffer Keymaps
1341 @cindex minibuffer keymaps
1342 @vindex minibuffer-local-map
1343 @vindex minibuffer-local-ns-map
1344 @vindex minibuffer-local-completion-map
1345 @vindex minibuffer-local-must-match-map
1346 The minibuffer has its own set of local keymaps; they contain various
1347 completion and exit commands.
1351 @code{minibuffer-local-map} is used for ordinary input (no completion).
1353 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1354 just like @key{RET}. This is used mainly for Mocklisp compatibility.
1356 @code{minibuffer-local-completion-map} is for permissive completion.
1358 @code{minibuffer-local-must-match-map} is for strict completion and
1359 for cautious completion.
1363 @subsection Changing Key Bindings Interactively
1364 @cindex key rebinding, this session
1365 @cindex redefining keys, this session
1367 The way to redefine an Emacs key is to change its entry in a keymap.
1368 You can change the global keymap, in which case the change is effective in
1369 all major modes (except those that have their own overriding local
1370 definitions for the same key). Or you can change the current buffer's
1371 local map, which affects all buffers using the same major mode.
1373 @findex global-set-key
1374 @findex local-set-key
1375 @findex global-unset-key
1376 @findex local-unset-key
1378 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1379 Define @var{key} globally to run @var{cmd}.
1380 @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1381 Define @var{key} locally (in the major mode now in effect) to run
1383 @item M-x global-unset-key @key{RET} @var{key}
1384 Make @var{key} undefined in the global map.
1385 @item M-x local-unset-key @key{RET} @var{key}
1386 Make @var{key} undefined locally (in the major mode now in effect).
1389 For example, suppose you like to execute commands in a subshell within
1390 an Emacs buffer, instead of suspending Emacs and executing commands in
1391 your login shell. Normally, @kbd{C-z} is bound to the function
1392 @code{suspend-emacs} (when not using the X Window System), but you can
1393 change @kbd{C-z} to invoke an interactive subshell within Emacs, by
1394 binding it to @code{shell} as follows:
1397 M-x global-set-key @key{RET} C-z shell @key{RET}
1401 @code{global-set-key} reads the command name after the key. After you
1402 press the key, a message like this appears so that you can confirm that
1403 you are binding the key you want:
1406 Set key C-z to command:
1409 You can redefine function keys and mouse events in the same way; just
1410 type the function key or click the mouse when it's time to specify the
1413 You can rebind a key that contains more than one event in the same
1414 way. Emacs keeps reading the key to rebind until it is a complete key
1415 (that is, not a prefix key). Thus, if you type @kbd{C-f} for
1416 @var{key}, that's the end; the minibuffer is entered immediately to
1417 read @var{cmd}. But if you type @kbd{C-x}, another character is read;
1418 if that is @kbd{4}, another character is read, and so on. For
1422 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1426 redefines @kbd{C-x 4 $} to run the (fictitious) command
1427 @code{spell-other-window}.
1429 The two-character keys consisting of @kbd{C-c} followed by a letter
1430 are reserved for user customizations. Lisp programs are not supposed to
1431 define these keys, so the bindings you make for them will be available
1432 in all major modes and will never get in the way of anything.
1434 You can remove the global definition of a key with
1435 @code{global-unset-key}. This makes the key @dfn{undefined}; if you
1436 type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
1437 a key undefined in the current major mode keymap, which makes the global
1438 definition (or lack of one) come back into effect in that major mode.
1440 If you have redefined (or undefined) a key and you subsequently wish
1441 to retract the change, undefining the key will not do the job---you need
1442 to redefine the key with its standard definition. To find the name of
1443 the standard definition of a key, go to a Fundamental mode buffer and
1444 use @kbd{C-h c}. The documentation of keys in this manual also lists
1445 their command names.
1447 If you want to prevent yourself from invoking a command by mistake, it
1448 is better to disable the command than to undefine the key. A disabled
1449 command is less work to invoke when you really want to.
1452 @node Init Rebinding
1453 @subsection Rebinding Keys in Your Init File
1455 If you have a set of key bindings that you like to use all the time,
1456 you can specify them in your @file{.emacs} file by using their Lisp
1457 syntax. (@xref{Init File}.)
1459 The simplest method for doing this works for @acronym{ASCII} characters and
1460 Meta-modified @acronym{ASCII} characters only. This method uses a string to
1461 represent the key sequence you want to rebind. For example, here's how
1462 to bind @kbd{C-z} to @code{shell}:
1465 (global-set-key "\C-z" 'shell)
1469 This example uses a string constant containing one character,
1470 @kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The
1471 single-quote before the command name, @code{shell}, marks it as a
1472 constant symbol rather than a variable. If you omit the quote, Emacs
1473 would try to evaluate @code{shell} immediately as a variable. This
1474 probably causes an error; it certainly isn't what you want.
1476 Here is another example that binds the key sequence @kbd{C-x M-l}:
1479 (global-set-key "\C-x\M-l" 'make-symbolic-link)
1482 To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
1483 string, you can use the Emacs Lisp escape sequences, @samp{\t},
1484 @samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds
1485 @kbd{C-x @key{TAB}}:
1488 (global-set-key "\C-x\t" 'indent-rigidly)
1491 These examples show how to write some other special @acronym{ASCII} characters
1492 in strings for key bindings:
1495 (global-set-key "\r" 'newline) ;; @key{RET}
1496 (global-set-key "\d" 'delete-backward-char) ;; @key{DEL}
1497 (global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC}
1500 When the key sequence includes function keys or mouse button events,
1501 or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use
1502 the more general method of rebinding, which uses a vector to specify the
1505 The way to write a vector in Emacs Lisp is with square brackets around
1506 the vector elements. Use spaces to separate the elements. If an
1507 element is a symbol, simply write the symbol's name---no other
1508 delimiters or punctuation are needed. If a vector element is a
1509 character, write it as a Lisp character constant: @samp{?} followed by
1510 the character as it would appear in a string.
1512 Here are examples of using vectors to rebind @kbd{C-=} (a control
1513 character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=}
1514 is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at
1515 all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
1516 keyboard-modified mouse button):
1519 (global-set-key [?\C-=] 'make-symbolic-link)
1520 (global-set-key [?\M-\C-=] 'make-symbolic-link)
1521 (global-set-key [?\H-a] 'make-symbolic-link)
1522 (global-set-key [f7] 'make-symbolic-link)
1523 (global-set-key [C-mouse-1] 'make-symbolic-link)
1526 You can use a vector for the simple cases too. Here's how to
1527 rewrite the first six examples above to use vectors:
1530 (global-set-key [?\C-z] 'shell)
1531 (global-set-key [?\C-x ?l] 'make-symbolic-link)
1532 (global-set-key [?\C-x ?\t] 'indent-rigidly)
1533 (global-set-key [?\r] 'newline)
1534 (global-set-key [?\d] 'delete-backward-char)
1535 (global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
1539 As you see, you represent a multi-character key sequence with a vector
1540 by listing all of the characters in order within the square brackets that
1543 Language and coding systems can cause problems with key bindings
1544 for non-@acronym{ASCII} characters. @xref{Non-ASCII Rebinding}.
1547 @subsection Rebinding Function Keys
1549 Key sequences can contain function keys as well as ordinary
1550 characters. Just as Lisp characters (actually integers) represent
1551 keyboard characters, Lisp symbols represent function keys. If the
1552 function key has a word as its label, then that word is also the name of
1553 the corresponding Lisp symbol. Here are the conventional Lisp names for
1554 common function keys:
1557 @item @code{left}, @code{up}, @code{right}, @code{down}
1560 @item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
1561 Other cursor repositioning keys.
1563 @item @code{select}, @code{print}, @code{execute}, @code{backtab}
1564 @itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
1565 @itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}
1566 Miscellaneous function keys.
1568 @item @code{f1}, @code{f2}, @dots{} @code{f35}
1569 Numbered function keys (across the top of the keyboard).
1571 @item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
1572 @itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
1573 @itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
1574 Keypad keys (to the right of the regular keyboard), with names or punctuation.
1576 @item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
1577 Keypad keys with digits.
1579 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1583 These names are conventional, but some systems (especially when using
1584 X) may use different names. To make certain what symbol is used for a
1585 given function key on your terminal, type @kbd{C-h c} followed by that
1588 A key sequence which contains function key symbols (or anything but
1589 @acronym{ASCII} characters) must be a vector rather than a string.
1590 Thus, to bind function key @samp{f1} to the command @code{rmail},
1591 write the following:
1594 (global-set-key [f1] 'rmail)
1598 To bind the right-arrow key to the command @code{forward-char}, you can
1599 use this expression:
1602 (global-set-key [right] 'forward-char)
1606 This uses the Lisp syntax for a vector containing the symbol
1607 @code{right}. (This binding is present in Emacs by default.)
1609 @xref{Init Rebinding}, for more information about using vectors for
1612 You can mix function keys and characters in a key sequence. This
1613 example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}.
1616 (global-set-key [?\C-x next] 'forward-page)
1620 where @code{?\C-x} is the Lisp character constant for the character
1621 @kbd{C-x}. The vector element @code{next} is a symbol and therefore
1622 does not take a question mark.
1624 You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
1625 @key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent
1626 these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-},
1627 @samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name.
1628 Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a
1632 (global-set-key [H-M-right] 'forward-word)
1635 @node Named ASCII Chars
1636 @subsection Named @acronym{ASCII} Control Characters
1638 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL}
1639 started out as names for certain @acronym{ASCII} control characters,
1640 used so often that they have special keys of their own. For instance,
1641 @key{TAB} was another name for @kbd{C-i}. Later, users found it
1642 convenient to distinguish in Emacs between these keys and the ``same''
1643 control characters typed with the @key{CTRL} key. Therefore, on most
1644 modern terminals, they are no longer the same, and @key{TAB} is
1645 distinguishable from @kbd{C-i}.
1647 Emacs can distinguish these two kinds of input if the keyboard does.
1648 It treats the ``special'' keys as function keys named @code{tab},
1649 @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
1650 @code{delete}. These function keys translate automatically into the
1651 corresponding @acronym{ASCII} characters @emph{if} they have no
1652 bindings of their own. As a result, neither users nor Lisp programs
1653 need to pay attention to the distinction unless they care to.
1655 If you do not want to distinguish between (for example) @key{TAB} and
1656 @kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
1657 (octal code 011). If you do want to distinguish, make one binding for
1658 this @acronym{ASCII} character, and another for the ``function key'' @code{tab}.
1660 With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
1661 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
1662 because the terminal sends the same character in both cases.
1664 @node Non-ASCII Rebinding
1665 @subsection Non-@acronym{ASCII} Characters on the Keyboard
1666 @cindex rebinding non-@acronym{ASCII} keys
1667 @cindex non-@acronym{ASCII} keys, binding
1669 If your keyboard has keys that send non-@acronym{ASCII}
1670 characters, such as accented letters, rebinding these keys
1671 must be done by using a vector like this@footnote{Note that
1672 you should avoid the string syntax for binding
1673 non-@acronym{ASCII} characters, since they will be
1674 interpreted as meta keys. @xref{Strings of Events,,,elisp,
1675 The Emacs Lisp Reference Manual}.}:
1678 (global-set-key [?@var{char}] 'some-function)
1682 Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
1684 Since this puts a non-@acronym{ASCII} character in the @file{.emacs},
1685 you should specify a coding system for that file that supports the
1686 character in question. @xref{Init Syntax}.
1688 @strong{Warning:} if you change the keyboard encoding, or change
1689 between multibyte and unibyte mode, or anything that would alter which
1690 code @kbd{C-q} would insert for that character, you'll need to edit
1691 the Lisp expression accordingly, to use the character code generated
1692 by @kbd{C-q} in the new mode.
1695 @subsection Rebinding Mouse Buttons
1696 @cindex mouse button events
1697 @cindex rebinding mouse buttons
1698 @cindex click events
1701 @cindex button down events
1703 Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
1704 mouse events in Emacs are @dfn{click} events; these happen when you
1705 press a button and release it without moving the mouse. You can also
1706 get @dfn{drag} events, when you move the mouse while holding the button
1707 down. Drag events happen when you finally let go of the button.
1709 The symbols for basic click events are @code{mouse-1} for the leftmost
1710 button, @code{mouse-2} for the next, and so on. Here is how you can
1711 redefine the second mouse button to split the current window:
1714 (global-set-key [mouse-2] 'split-window-vertically)
1717 The symbols for drag events are similar, but have the prefix
1718 @samp{drag-} before the word @samp{mouse}. For example, dragging the
1719 first button generates a @code{drag-mouse-1} event.
1721 You can also define bindings for events that occur when a mouse button
1722 is pressed down. These events start with @samp{down-} instead of
1723 @samp{drag-}. Such events are generated only if they have key bindings.
1724 When you get a button-down event, a corresponding click or drag event
1727 @cindex double clicks
1728 @cindex triple clicks
1729 If you wish, you can distinguish single, double, and triple clicks. A
1730 double click means clicking a mouse button twice in approximately the
1731 same place. The first click generates an ordinary click event. The
1732 second click, if it comes soon enough, generates a double-click event
1733 instead. The event type for a double-click event starts with
1734 @samp{double-}: for example, @code{double-mouse-3}.
1736 This means that you can give a special meaning to the second click at
1737 the same place, but it must act on the assumption that the ordinary
1738 single click definition has run when the first click was received.
1740 This constrains what you can do with double clicks, but user interface
1741 designers say that this constraint ought to be followed in any case. A
1742 double click should do something similar to the single click, only
1743 ``more so.'' The command for the double-click event should perform the
1744 extra work for the double click.
1746 If a double-click event has no binding, it changes to the
1747 corresponding single-click event. Thus, if you don't define a
1748 particular double click specially, it executes the single-click command
1751 Emacs also supports triple-click events whose names start with
1752 @samp{triple-}. Emacs does not distinguish quadruple clicks as event
1753 types; clicks beyond the third generate additional triple-click events.
1754 However, the full number of clicks is recorded in the event list, so you
1755 can distinguish if you really want to. We don't recommend distinct
1756 meanings for more than three clicks, but sometimes it is useful for
1757 subsequent clicks to cycle through the same set of three meanings, so
1758 that four clicks are equivalent to one click, five are equivalent to
1759 two, and six are equivalent to three.
1761 Emacs also records multiple presses in drag and button-down events.
1762 For example, when you press a button twice, then move the mouse while
1763 holding the button, Emacs gets a @samp{double-drag-} event. And at the
1764 moment when you press it down for the second time, Emacs gets a
1765 @samp{double-down-} event (which is ignored, like all button-down
1766 events, if it has no binding).
1768 @vindex double-click-time
1769 The variable @code{double-click-time} specifies how much time can
1770 elapse between clicks and still allow them to be grouped as a multiple
1771 click. Its value is in units of milliseconds. If the value is
1772 @code{nil}, double clicks are not detected at all. If the value is
1773 @code{t}, then there is no time limit. The default is 500.
1775 @vindex double-click-fuzz
1776 The variable @code{double-click-fuzz} specifies how much the mouse
1777 can move between clicks still allow them to be grouped as a multiple
1778 click. Its value is in units of pixels on windowed displays and in
1779 units of 1/8 of a character cell on text-mode terminals; the default is
1782 The symbols for mouse events also indicate the status of the modifier
1783 keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
1784 @samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-}
1785 or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
1787 A frame includes areas that don't show text from the buffer, such as
1788 the mode line and the scroll bar. You can tell whether a mouse button
1789 comes from a special area of the screen by means of dummy ``prefix
1790 keys.'' For example, if you click the mouse in the mode line, you get
1791 the prefix key @code{mode-line} before the ordinary mouse-button symbol.
1792 Thus, here is how to define the command for clicking the first button in
1793 a mode line to run @code{scroll-up}:
1796 (global-set-key [mode-line mouse-1] 'scroll-up)
1799 Here is the complete list of these dummy prefix keys and their
1804 The mouse was in the mode line of a window.
1806 The mouse was in the vertical line separating side-by-side windows. (If
1807 you use scroll bars, they appear in place of these vertical lines.)
1808 @item vertical-scroll-bar
1809 The mouse was in a vertical scroll bar. (This is the only kind of
1810 scroll bar Emacs currently supports.)
1812 @item horizontal-scroll-bar
1813 The mouse was in a horizontal scroll bar. Horizontal scroll bars do
1814 horizontal scrolling, and people don't use them often.
1818 You can put more than one mouse button in a key sequence, but it isn't
1822 @subsection Disabling Commands
1823 @cindex disabled command
1825 Disabling a command marks the command as requiring confirmation before it
1826 can be executed. The purpose of disabling a command is to prevent
1827 beginning users from executing it by accident and being confused.
1829 An attempt to invoke a disabled command interactively in Emacs
1830 displays a window containing the command's name, its documentation, and
1831 some instructions on what to do immediately; then Emacs asks for input
1832 saying whether to execute the command as requested, enable it and
1833 execute it, or cancel. If you decide to enable the command, you are
1834 asked whether to do this permanently or just for the current session.
1835 (Enabling permanently works by automatically editing your @file{.emacs}
1836 file.) You can also type @kbd{!} to enable @emph{all} commands,
1837 for the current session only.
1839 The direct mechanism for disabling a command is to put a
1840 non-@code{nil} @code{disabled} property on the Lisp symbol for the
1841 command. Here is the Lisp program to do this:
1844 (put 'delete-region 'disabled t)
1847 If the value of the @code{disabled} property is a string, that string
1848 is included in the message displayed when the command is used:
1851 (put 'delete-region 'disabled
1852 "It's better to use `kill-region' instead.\n")
1855 @findex disable-command
1856 @findex enable-command
1857 You can make a command disabled either by editing the @file{.emacs}
1858 file directly or with the command @kbd{M-x disable-command}, which edits
1859 the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command}
1860 edits @file{.emacs} to enable a command permanently. @xref{Init File}.
1862 If Emacs was invoked with the @option{-q} or @option{--no-init-file}
1863 options (@pxref{Initial Options}), it will not edit your
1864 @file{~/.emacs} init file. This is because editing the init file from
1865 such a session might overwrite the lines you might have on your init
1866 file which enable and disable commands.
1868 Whether a command is disabled is independent of what key is used to
1869 invoke it; disabling also applies if the command is invoked using
1870 @kbd{M-x}. Disabling a command has no effect on calling it as a
1871 function from Lisp programs.
1873 @node Keyboard Translations
1874 @section Keyboard Translations
1876 Some keyboards do not make it convenient to send all the special
1877 characters that Emacs uses. The most common problem case is the
1878 @key{DEL} character. Some keyboards provide no convenient way to type
1879 this very important character---usually because they were designed to
1880 expect the character @kbd{C-h} to be used for deletion. On these
1881 keyboards, if you press the key normally used for deletion, Emacs handles
1882 the @kbd{C-h} as a prefix character and offers you a list of help
1883 options, which is not what you want.
1885 @cindex keyboard translations
1886 @findex keyboard-translate
1887 You can work around this problem within Emacs by setting up keyboard
1888 translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into
1889 @kbd{C-h}, as follows:
1892 ;; @r{Translate @kbd{C-h} to @key{DEL}.}
1893 (keyboard-translate ?\C-h ?\C-?)
1895 ;; @r{Translate @key{DEL} to @kbd{C-h}.}
1896 (keyboard-translate ?\C-? ?\C-h)
1899 Keyboard translations are not the same as key bindings in keymaps
1900 (@pxref{Keymaps}). Emacs contains numerous keymaps that apply in
1901 different situations, but there is only one set of keyboard
1902 translations, and it applies to every character that Emacs reads from
1903 the terminal. Keyboard translations take place at the lowest level of
1904 input processing; the keys that are looked up in keymaps contain the
1905 characters that result from keyboard translation.
1907 On a window system, the keyboard key named @key{DELETE} is a function
1908 key and is distinct from the @acronym{ASCII} character named @key{DEL}.
1909 @xref{Named ASCII Chars}. Keyboard translations affect only @acronym{ASCII}
1910 character input, not function keys; thus, the above example used on a
1911 window system does not affect the @key{DELETE} key. However, the
1912 translation above isn't necessary on window systems, because Emacs can
1913 also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
1914 normally treats @key{BACKSPACE} as @key{DEL}.
1916 For full information about how to use keyboard translations, see
1917 @ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.
1920 @section The Syntax Table
1921 @cindex syntax table
1923 All the Emacs commands which parse words or balance parentheses are
1924 controlled by the @dfn{syntax table}. The syntax table says which
1925 characters are opening delimiters, which are parts of words, which are
1926 string quotes, and so on. It does this by assigning each character to
1927 one of fifteen-odd @dfn{syntax classes}. In some cases it specifies
1928 some additional information also.
1930 Each major mode has its own syntax table (though related major modes
1931 sometimes share one syntax table) which it installs in each buffer
1932 that uses the mode. The syntax table installed in the current buffer
1933 is the one that all commands use, so we call it ``the'' syntax table.
1936 @findex describe-syntax
1937 To display a description of the contents of the current syntax
1938 table, type @kbd{C-h s} (@code{describe-syntax}). The description of
1939 each character includes both the string you would have to give to
1940 @code{modify-syntax-entry} to set up that character's current syntax,
1941 starting with the character which designates its syntax class, plus
1942 some English text to explain its meaning.
1944 A syntax table is actually a Lisp object, a char-table, whose
1945 elements are cons cells. For full information on the syntax table,
1946 see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp
1950 @section The Init File, @file{~/.emacs}
1952 @cindex Emacs initialization file
1953 @cindex key rebinding, permanent
1954 @cindex rebinding keys, permanently
1955 @cindex startup (init file)
1957 When Emacs is started, it normally loads a Lisp program from the
1958 file @file{.emacs} or @file{.emacs.el} in your home directory. (You
1959 can also put it in a subdirectory @file{~/.emacs.d} and Emacs will
1960 still find it.) We call this file your @dfn{init file} because it
1961 specifies how to initialize Emacs for you. You can use the command
1962 line switch @samp{-q} to prevent loading your init file, and @samp{-u}
1963 (or @samp{--user}) to specify a different user's init file
1964 (@pxref{Initial Options}).
1966 @cindex @file{default.el}, the default init file
1967 There can also be a @dfn{default init file}, which is the library
1968 named @file{default.el}, found via the standard search path for
1969 libraries. The Emacs distribution contains no such library; your site
1970 may create one for local customizations. If this library exists, it is
1971 loaded whenever you start Emacs (except when you specify @samp{-q}).
1972 But your init file, if any, is loaded first; if it sets
1973 @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
1976 @cindex site init file
1977 @cindex @file{site-start.el}, the site startup file
1978 Your site may also have a @dfn{site startup file}; this is named
1979 @file{site-start.el}, if it exists. Like @file{default.el}, Emacs
1980 finds this file via the standard search path for Lisp libraries.
1981 Emacs loads this library before it loads your init file. To inhibit
1982 loading of this library, use the option @samp{--no-site-file}.
1983 @xref{Initial Options}.
1985 You can place @file{default.el} and @file{site-start.el} in any of
1986 the directories which Emacs searches for Lisp libraries. The variable
1987 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories.
1988 Many sites put these files in the @file{site-lisp} subdirectory of the
1989 Emacs installation directory, typically
1990 @file{/usr/local/share/emacs/site-lisp}.
1992 If you have a large amount of code in your @file{.emacs} file, you
1993 should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte
1994 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual},
1995 for more information about compiling Emacs Lisp programs.
1997 If you are going to write actual Emacs Lisp programs that go beyond
1998 minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
2000 @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
2005 * Init Syntax:: Syntax of constants in Emacs Lisp.
2006 * Init Examples:: How to do some things with an init file.
2007 * Terminal Init:: Each terminal type can have an init file.
2008 * Find Init:: How Emacs finds the init file.
2012 @subsection Init File Syntax
2014 The @file{.emacs} file contains one or more Lisp function call
2015 expressions. Each of these consists of a function name followed by
2016 arguments, all surrounded by parentheses. For example, @code{(setq
2017 fill-column 60)} calls the function @code{setq} to set the variable
2018 @code{fill-column} (@pxref{Filling}) to 60.
2020 You can set any Lisp variable with @code{setq}, but with certain
2021 variables @code{setq} won't do what you probably want in the
2022 @file{.emacs} file. Some variables automatically become buffer-local
2023 when set with @code{setq}; what you want in @file{.emacs} is to set
2024 the default value, using @code{setq-default}. Some customizable minor
2025 mode variables do special things to enable the mode when you set them
2026 with Customize, but ordinary @code{setq} won't do that; to enable the
2027 mode in your @file{.emacs} file, call the minor mode command. The
2028 following section has examples of both of these methods.
2030 The second argument to @code{setq} is an expression for the new
2031 value of the variable. This can be a constant, a variable, or a
2032 function call expression. In @file{.emacs}, constants are used most
2033 of the time. They can be:
2037 Numbers are written in decimal, with an optional initial minus sign.
2040 @cindex Lisp string syntax
2041 @cindex string syntax
2042 Lisp string syntax is the same as C string syntax with a few extra
2043 features. Use a double-quote character to begin and end a string constant.
2045 In a string, you can include newlines and special characters literally.
2046 But often it is cleaner to use backslash sequences for them: @samp{\n}
2047 for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
2048 @samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
2049 escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
2050 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
2051 Backslash and double-quote are the only characters for which backslash
2052 sequences are mandatory.
2054 @samp{\C-} can be used as a prefix for a control character, as in
2055 @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
2056 a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
2057 @kbd{Control-Meta-A}.@refill
2059 @cindex international characters in @file{.emacs}
2060 @cindex non-@acronym{ASCII} characters in @file{.emacs}
2061 If you want to include non-@acronym{ASCII} characters in strings in your init
2062 file, you should consider putting a @w{@samp{-*-coding:
2063 @var{coding-system}-*-}} tag on the first line which states the coding
2064 system used to save your @file{.emacs}, as explained in @ref{Recognize
2065 Coding}. This is because the defaults for decoding non-@acronym{ASCII} text might
2066 not yet be set up by the time Emacs reads those parts of your init file
2067 which use such strings, possibly leading Emacs to decode those strings
2071 Lisp character constant syntax consists of a @samp{?} followed by
2072 either a character or an escape sequence starting with @samp{\}.
2073 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
2074 strings and characters are not interchangeable in Lisp; some contexts
2075 require one and some contexts require the other.
2077 @xref{Non-ASCII Rebinding}, for information about binding commands to
2078 keys which send non-@acronym{ASCII} characters.
2081 @code{t} stands for `true'.
2084 @code{nil} stands for `false'.
2086 @item Other Lisp objects:
2087 Write a single-quote (@code{'}) followed by the Lisp object you want.
2091 @subsection Init File Examples
2093 Here are some examples of doing certain commonly desired things with
2098 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
2102 (setq c-tab-always-indent nil)
2105 Here we have a variable whose value is normally @code{t} for `true'
2106 and the alternative is @code{nil} for `false'.
2109 Make searches case sensitive by default (in all buffers that do not
2113 (setq-default case-fold-search nil)
2116 This sets the default value, which is effective in all buffers that do
2117 not have local values for the variable. Setting @code{case-fold-search}
2118 with @code{setq} affects only the current buffer's local value, which
2119 is not what you probably want to do in an init file.
2122 @vindex user-mail-address
2123 Specify your own email address, if Emacs can't figure it out correctly.
2126 (setq user-mail-address "coon@@yoyodyne.com")
2129 Various Emacs packages that need your own email address use the value of
2130 @code{user-mail-address}.
2133 Make Text mode the default mode for new buffers.
2136 (setq default-major-mode 'text-mode)
2139 Note that @code{text-mode} is used because it is the command for
2140 entering Text mode. The single-quote before it makes the symbol a
2141 constant; otherwise, @code{text-mode} would be treated as a variable
2146 Set up defaults for the Latin-1 character set
2147 which supports most of the languages of Western Europe.
2150 (set-language-environment "Latin-1")
2155 Turn off Line Number mode, a global minor mode.
2158 (line-number-mode 0)
2163 Turn on Auto Fill mode automatically in Text mode and related modes.
2166 (add-hook 'text-mode-hook
2167 '(lambda () (auto-fill-mode 1)))
2170 This shows how to add a hook function to a normal hook variable
2171 (@pxref{Hooks}). The function we supply is a list starting with
2172 @code{lambda}, with a single-quote in front of it to make it a list
2173 constant rather than an expression.
2175 It's beyond the scope of this manual to explain Lisp functions, but for
2176 this example it is enough to know that the effect is to execute
2177 @code{(auto-fill-mode 1)} when Text mode is entered. You can replace
2178 that with any other expression that you like, or with several
2179 expressions in a row.
2181 Emacs comes with a function named @code{turn-on-auto-fill} whose
2182 definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler
2183 way to write the above example is as follows:
2186 (add-hook 'text-mode-hook 'turn-on-auto-fill)
2190 Load the installed Lisp library named @file{foo} (actually a file
2191 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
2197 When the argument to @code{load} is a relative file name, not starting
2198 with @samp{/} or @samp{~}, @code{load} searches the directories in
2199 @code{load-path} (@pxref{Lisp Libraries}).
2202 Load the compiled Lisp file @file{foo.elc} from your home directory.
2208 Here an absolute file name is used, so no searching is done.
2211 @cindex loading Lisp libraries automatically
2212 @cindex autoload Lisp libraries
2213 Tell Emacs to find the definition for the function @code{myfunction}
2214 by loading a Lisp library named @file{mypackage} (i.e.@: a file
2215 @file{mypackage.elc} or @file{mypackage.el}):
2218 (autoload 'myfunction "mypackage" "Do what I say." t)
2222 Here the string @code{"Do what I say."} is the function's
2223 documentation string. You specify it in the @code{autoload}
2224 definition so it will be available for help commands even when the
2225 package is not loaded. The last argument, @code{t}, indicates that
2226 this function is interactive; that is, it can be invoked interactively
2227 by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
2228 If the function is not interactive, omit the @code{t} or use
2232 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
2233 (@xref{Init Rebinding}.)
2236 (global-set-key "\C-xl" 'make-symbolic-link)
2242 (define-key global-map "\C-xl" 'make-symbolic-link)
2245 Note once again the single-quote used to refer to the symbol
2246 @code{make-symbolic-link} instead of its value as a variable.
2249 Do the same thing for Lisp mode only.
2252 (define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
2256 Redefine all keys which now run @code{next-line} in Fundamental mode
2257 so that they run @code{forward-line} instead.
2259 @findex substitute-key-definition
2261 (substitute-key-definition 'next-line 'forward-line
2266 Make @kbd{C-x C-v} undefined.
2269 (global-unset-key "\C-x\C-v")
2272 One reason to undefine a key is so that you can make it a prefix.
2273 Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
2274 prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
2278 Make @samp{$} have the syntax of punctuation in Text mode.
2279 Note the use of a character constant for @samp{$}.
2282 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
2286 Enable the use of the command @code{narrow-to-region} without confirmation.
2289 (put 'narrow-to-region 'disabled nil)
2294 @subsection Terminal-specific Initialization
2296 Each terminal type can have a Lisp library to be loaded into Emacs when
2297 it is run on that type of terminal. For a terminal type named
2298 @var{termtype}, the library is called @file{term/@var{termtype}} and it is
2299 found by searching the directories @code{load-path} as usual and trying the
2300 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
2301 subdirectory @file{term} of the directory where most Emacs libraries are
2304 The usual purpose of the terminal-specific library is to map the
2305 escape sequences used by the terminal's function keys onto more
2306 meaningful names, using @code{function-key-map}. See the file
2307 @file{term/lk201.el} for an example of how this is done. Many function
2308 keys are mapped automatically according to the information in the
2309 Termcap data base; the terminal-specific library needs to map only the
2310 function keys that Termcap does not specify.
2312 When the terminal type contains a hyphen, only the part of the name
2313 before the first hyphen is significant in choosing the library name.
2314 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
2315 the library @file{term/aaa}. The code in the library can use
2316 @code{(getenv "TERM")} to find the full terminal type name.@refill
2318 @vindex term-file-prefix
2319 The library's name is constructed by concatenating the value of the
2320 variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
2321 file can prevent the loading of the terminal-specific library by setting
2322 @code{term-file-prefix} to @code{nil}.
2324 @vindex term-setup-hook
2325 Emacs runs the hook @code{term-setup-hook} at the end of
2326 initialization, after both your @file{.emacs} file and any
2327 terminal-specific library have been read in. Add hook functions to this
2328 hook if you wish to override part of any of the terminal-specific
2329 libraries and to define initializations for terminals that do not have a
2330 library. @xref{Hooks}.
2333 @subsection How Emacs Finds Your Init File
2335 Normally Emacs uses the environment variable @env{HOME} to find
2336 @file{.emacs}; that's what @samp{~} means in a file name. If @file{.emacs}
2337 is not found directly inside @file{~/}, Emacs looks for it in
2340 However, if you run Emacs from a shell started by @code{su}, Emacs
2341 tries to find your own @file{.emacs}, not that of the user you are
2342 currently pretending to be. The idea is that you should get your own
2343 editor customizations even if you are running as the super user.
2345 More precisely, Emacs first determines which user's init file to use.
2346 It gets the user name from the environment variables @env{LOGNAME} and
2347 @env{USER}; if neither of those exists, it uses effective user-ID.
2348 If that user name matches the real user-ID, then Emacs uses @env{HOME};
2349 otherwise, it looks up the home directory corresponding to that user
2350 name in the system's data base of users.
2351 @c LocalWords: backtab
2354 arch-tag: c68abddb-4410-4fb5-925f-63394e971d93