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