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