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