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