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