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