1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software
5 @c See file emacs.texi for copying conditions.
10 This chapter describes some simple methods to customize the behavior
13 Apart from the methods described here, see @ref{X Resources} for
14 information about using X resources to customize Emacs, and see
15 @ref{Keyboard Macros} for information about recording and replaying
16 keyboard macros. Making more far-reaching and open-ended changes
17 involves writing Emacs Lisp code; see
19 @cite{The Emacs Lisp Reference Manual}.
22 @ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp
27 * Easy Customization:: Convenient way to browse and change settings.
28 * Variables:: Many Emacs commands examine Emacs variables
29 to decide what to do; by setting variables,
30 you can control their functioning.
31 * Key Bindings:: The keymaps say what command each key runs.
32 By changing them, you can redefine keys.
33 * Init File:: How to write common customizations in the
37 @node Easy Customization
38 @section Easy Customization Interface
42 @cindex customizable variable
43 Emacs has many @dfn{settings} which you can change. Most settings
44 are @dfn{customizable variables} (@pxref{Variables}), which are also
45 called @dfn{user options}. There is a huge number of customizable
46 variables, controlling numerous aspects of Emacs behavior; the
47 variables documented in this manual are listed in @ref{Variable
48 Index}. A separate class of settings are the @dfn{faces}, which
49 determine the fonts, colors, and other attributes of text
53 @cindex customization buffer
54 To browse and alter settings (both variables and faces), type
55 @kbd{M-x customize}. This creates a @dfn{customization buffer}, which
56 lets you navigate through a logically organized list of settings, edit
57 and set their values, and save them permanently.
60 * Customization Groups:: How settings are classified.
61 * Browsing Custom:: Browsing and searching for settings.
62 * Changing a Variable:: How to edit an option's value and set the option.
63 * Saving Customizations:: Saving customizations for future Emacs sessions.
64 * Face Customization:: How to edit the attributes of a face.
65 * Specific Customization:: Customizing specific settings or groups.
66 * Custom Themes:: Collections of customization settings.
67 * Creating Custom Themes:: How to create a new custom theme.
70 @node Customization Groups
71 @subsection Customization Groups
72 @cindex customization groups
74 Customization settings are organized into @dfn{customization
75 groups}. These groups are collected into bigger groups, all the way
76 up to a master group called @code{Emacs}.
78 @kbd{M-x customize} creates a customization buffer that shows the
79 top-level @code{Emacs} group. It looks like this, in part:
81 @c we want the buffer example to all be on one page, but unfortunately
82 @c that's quite a bit of text, so force all space to the bottom.
86 For help using this buffer, see [Easy Customization] in the [Emacs manual].
88 ________________________________________ [ Search ]
90 Operate on all settings in this buffer:
91 [ Revert... ] [ Apply ] [ Apply and Save ]
94 Emacs group: Customization of the One True Editor.
95 [State]: visible group members are all at standard values.
98 [Editing] Basic text editing facilities.
99 [Convenience] Convenience features for faster editing.
101 @var{...more second-level groups...}
106 The main part of this buffer shows the @samp{Emacs} customization
107 group, which contains several other groups (@samp{Editing},
108 @samp{Convenience}, etc.). The contents of those groups are not
109 listed here, only one line of documentation each.
111 The @dfn{state} of the group indicates whether setting in that group
112 has been edited, set, or saved. @xref{Changing a Variable}.
114 @cindex editable fields (customization buffer)
115 @cindex buttons (customization buffer)
116 @cindex links (customization buffer)
117 Most of the customization buffer is read-only, but it includes some
118 @dfn{editable fields} that you can edit. For example, at the top of
119 the customization buffer is an editable field for searching for
120 settings (@pxref{Browsing Custom}). There are also @dfn{buttons} and
121 @dfn{links}, which you can activate by either clicking with the mouse,
122 or moving point there and typing @kbd{@key{RET}}. For example, the group
123 names like @samp{[Editing]} are links; activating one of these links
124 brings up the customization buffer for that group.
126 @kindex TAB @r{(customization buffer)}
127 @kindex S-TAB @r{(customization buffer)}
128 @findex widget-forward
129 @findex widget-backward
130 In the customization buffer, you can type @kbd{@key{TAB}}
131 (@code{widget-forward}) to move forward to the next button or editable
132 field. @kbd{S-@key{TAB}} (@code{widget-backward}) moves back to the
133 previous button or editable field.
135 @node Browsing Custom
136 @subsection Browsing and Searching for Settings
137 @findex customize-browse
139 From the top-level customization buffer created by @kbd{M-x
140 customize}, you can follow the links to the subgroups of the
141 @samp{Emacs} customization group. These subgroups may contain
142 settings for you to customize; they may also contain further subgroups,
143 dealing with yet more specialized subsystems of Emacs. As you
144 navigate the hierarchy of customization groups, you should find some
145 settings that you want to customize.
147 If you are interested in customizing a particular setting or
148 customization group, you can go straight there with the commands
149 @kbd{M-x customize-option}, @kbd{M-x customize-face}, or @w{@kbd{M-x
150 customize-group}}. @xref{Specific Customization}.
152 @vindex custom-search-field
153 If you don't know exactly what groups or settings you want to
154 customize, you can search for them using the editable search field at
155 the top of each customization buffer. Here, you can type in a search
156 term---either one or more words separated by spaces, or a regular
157 expression (@pxref{Regexps}). Then type @kbd{@key{RET}} in the field,
158 or activate the @samp{Search} button next to it, to switch to a
159 customization buffer containing groups and settings that match those
160 terms. Note, however, that this feature only finds groups and
161 settings that are loaded in the current Emacs session.
163 If you don't want customization buffers to show the search field,
164 change the variable @code{custom-search-field} to @code{nil}.
166 The command @kbd{M-x customize-apropos} is similar to using the
167 search field, except that it reads the search term(s) using the
168 minibuffer. @xref{Specific Customization}.
170 @kbd{M-x customize-browse} is another way to browse the available
171 settings. This command creates a special customization buffer, which
172 shows only the names of groups and settings, in a structured layout.
173 You can show the contents of a group, in the same buffer, by invoking
174 the @samp{[+]} button next to the group name. When the group contents
175 are shown, the button changes to @samp{[-]}; invoking that hides the
176 group contents again. Each group or setting in this buffer has a link
177 which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
178 this link creates an ordinary customization buffer showing just that
179 group, option, or face; this is the way to change settings that you
180 find with @kbd{M-x customize-browse}.
182 @node Changing a Variable
183 @subsection Changing a Variable
185 Here is an example of what a variable, or user option, looks like in
186 the customization buffer:
189 [Hide] Kill Ring Max: 60
191 Maximum length of kill ring before oldest elements are thrown away.
194 The first line shows that the variable is named
195 @code{kill-ring-max}, formatted as @samp{Kill Ring Max} for easier
196 viewing. Its value is @samp{60}. The button labeled @samp{[Hide]},
197 if activated, hides the variable's value and state; this is useful to
198 avoid cluttering up the customization buffer with very long values
199 (for this reason, variables that have very long values may start out
200 hidden). If you use the @samp{[Hide]} button, it changes to
201 @samp{[Show Value]}, which you can activate to reveal the value and
202 state. On a graphical display, the @samp{[Hide]} and @samp{[Show
203 Value]} buttons are replaced with graphical triangles pointing
204 downwards and rightwards respectively.
206 The line after the variable name indicates the @dfn{customization
207 state} of the variable: in this example, @samp{STANDARD} means you
208 have not changed the variable, so its value is the default one. The
209 @samp{[State]} button gives a menu of operations for customizing the
212 Below the customization state is the documentation for the variable.
213 This is the same documentation that would be shown by the @kbd{C-h v}
214 command (@pxref{Examining}). If the documentation is more than one
215 line long, only one line may be shown. If so, that line ends with a
216 @samp{[More]} button; activate this to see the full documentation.
218 @cindex user options, changing
219 @cindex customizing variables
220 @cindex variables, changing
221 To enter a new value for @samp{Kill Ring Max}, just move point to
222 the value and edit it. For example, type @kbd{M-d} to delete the
223 @samp{60} and type in another number. As you begin to alter the text,
224 the @samp{[State]} line will change:
227 [State]: EDITED, shown value does not take effect until you
232 Editing the value does not make it take effect right away. To do
233 that, you must @dfn{set} the variable by activating the @samp{[State]}
234 button and choosing @samp{Set for Current Session}. Then the
235 variable's state becomes:
238 [State]: SET for current session only.
242 You don't have to worry about specifying a value that is not valid;
243 the @samp{Set for Current Session} operation checks for validity and
244 will not install an unacceptable value.
246 @kindex M-TAB @r{(customization buffer)}
247 @kindex C-M-i @r{(customization buffer)}
248 @findex widget-complete
249 While editing certain kinds of values, such as file names, directory
250 names, and Emacs command names, you can perform completion with
251 @kbd{C-M-i} (@code{widget-complete}), or the equivalent keys
252 @kbd{M-@key{TAB}} or @kbd{@key{ESC} @key{TAB}}. This behaves much
253 like minibuffer completion (@pxref{Completion}).
255 Typing @kbd{@key{RET}} on an editable value field moves point
256 forward to the next field or button, like @kbd{@key{TAB}}. You can
257 thus type @kbd{@key{RET}} when you are finished editing a field, to
258 move on to the next button or field. To insert a newline within an
259 editable field, use @kbd{C-o} or @kbd{C-q C-j}.
261 For some variables, there is only a fixed set of legitimate values,
262 and you are not allowed to edit the value directly. Instead, a
263 @samp{[Value Menu]} button appears before the value; activating this
264 button presents a choice of values. For a boolean ``on or off''
265 value, the button says @samp{[Toggle]}, and flips the value. After
266 using the @samp{[Value Menu]} or @samp{[Toggle]} button, you must
267 again set the variable to make the chosen value take effect.
269 Some variables have values with complex structure. For example, the
270 value of @code{minibuffer-frame-alist} is an association list. Here
271 is how it appears in the customization buffer:
274 [Hide] Minibuffer Frame Alist:
275 [INS] [DEL] Parameter: width
277 [INS] [DEL] Parameter: height
281 Alist of parameters for the initial minibuffer frame. [Hide]
282 @r{[@dots{}more lines of documentation@dots{}]}
286 In this case, each association in the list consists of two items, one
287 labeled @samp{Parameter} and one labeled @samp{Value}; both are
288 editable fields. You can delete an association from the list with the
289 @samp{[DEL]} button next to it. To add an association, use the
290 @samp{[INS]} button at the position where you want to insert it; the
291 very last @samp{[INS]} button inserts at the end of the list.
293 @cindex saving a setting
294 @cindex settings, how to save
295 When you set a variable, the new value takes effect only in the
296 current Emacs session. To @dfn{save} the value for future sessions,
297 use the @samp{[State]} button and select the @samp{Save for Future
298 Sessions} operation. @xref{Saving Customizations}.
300 You can also restore the variable to its standard value by using the
301 @samp{[State]} button and selecting the @samp{Erase Customization}
302 operation. There are actually four reset operations:
306 If you have modified but not yet set the variable, this restores the
307 text in the customization buffer to match the actual value.
309 @item Revert This Session's Customizations
310 This restores the value of the variable to the last saved value, if
311 there was one. Otherwise it restores the standard value. It updates
312 the text accordingly.
314 @item Erase Customization
315 This sets the variable to its standard value. Any saved value that
316 you have is also eliminated.
318 @item Set to Backup Value
319 This sets the variable to a previous value that was set in the
320 customization buffer in this session. If you customize a variable
321 and then reset it, which discards the customized value,
322 you can get the discarded value back again with this operation.
325 @cindex comments on customized settings
326 Sometimes it is useful to record a comment about a specific
327 customization. Use the @samp{Add Comment} item from the
328 @samp{[State]} menu to create a field for entering the comment.
330 Near the top of the customization buffer are two lines of buttons:
333 Operate on all settings in this buffer:
334 [Revert...] [Apply] [Apply and Save]
338 The @samp{[Revert...]} button drops a menu with the first 3 reset
339 operations described above. The @samp{[Apply]} button applies the
340 settings for the current session. The @samp{[Apply and Save]} button
341 applies the settings and saves them for future sessions; this button
342 does not appear if Emacs was started with the @option{-q} or
343 @option{-Q} option (@pxref{Initial Options}).
345 @kindex C-c C-c @r{(customization buffer)}
346 @kindex C-x C-c @r{(customization buffer)}
349 The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent to using
350 the @samp{[Set for Current Session]} button. The command @kbd{C-x
351 C-s} (@code{Custom-save}) is like using the @samp{[Save for Future
354 @vindex custom-buffer-done-kill
355 The @samp{[Exit]} button switches out of the customization buffer,
356 and buries the buffer at the bottom of the buffer list. To make it
357 kill the customization buffer instead, change the variable
358 @code{custom-buffer-done-kill} to @code{t}.
360 @node Saving Customizations
361 @subsection Saving Customizations
363 In the customization buffer, you can @dfn{save} a customization
364 setting by choosing the @samp{Save for Future Sessions} choice from
365 its @samp{[State]} button. The @kbd{C-x C-s} (@code{Custom-save})
366 command, or the @samp{[Apply and Save]} button at the top of the
367 customization buffer, saves all applicable settings in the buffer.
369 Saving works by writing code to a file, usually your initialization
370 file (@pxref{Init File}). Future Emacs sessions automatically read
371 this file at startup, which sets up the customizations again.
374 You can choose to save customizations somewhere other than your
375 initialization file. To make this work, you must add a couple of
376 lines of code to your initialization file, to set the variable
377 @code{custom-file} to the name of the desired file, and to load that
381 (setq custom-file "~/.emacs-custom.el")
385 You can even specify different customization files for different
386 Emacs versions, like this:
389 (cond ((< emacs-major-version 22)
390 ;; @r{Emacs 21 customization.}
391 (setq custom-file "~/.custom-21.el"))
392 ((and (= emacs-major-version 22)
393 (< emacs-minor-version 3))
394 ;; @r{Emacs 22 customization, before version 22.3.}
395 (setq custom-file "~/.custom-22.el"))
397 ;; @r{Emacs version 22.3 or later.}
398 (setq custom-file "~/.emacs-custom.el")))
403 If Emacs was invoked with the @option{-q} or @option{--no-init-file}
404 options (@pxref{Initial Options}), it will not let you save your
405 customizations in your initialization file. This is because saving
406 customizations from such a session would wipe out all the other
407 customizations you might have on your initialization file.
409 @cindex unsaved customizations, reminder to save
410 @findex custom-prompt-customize-unsaved-options
411 Please note that any customizations you have not chosen to save for
412 future sessions will be lost when you terminate Emacs. If you'd like
413 to be prompted about unsaved customizations at termination time, add
414 the following to your initialization file:
417 (add-hook 'kill-emacs-query-functions
418 'custom-prompt-customize-unsaved-options)
421 @node Face Customization
422 @subsection Customizing Faces
423 @cindex customizing faces
424 @cindex faces, customizing
425 @cindex fonts and faces
427 You can customize faces (@pxref{Faces}), which determine how Emacs
428 displays different types of text. Customization groups can contain
429 both variables and faces.
431 For example, in programming language modes, source code comments are
432 shown with @code{font-lock-comment-face} (@pxref{Font Lock}). In a
433 customization buffer, that face appears like this, after you click on
434 the @samp{[Show All Attributes]} link:
437 [Hide] Font Lock Comment Face:[sample]
439 Font Lock mode face used to highlight comments.
448 [ ] Strike-through: --
449 [ ] Box around text: --
450 [ ] Inverse-video: --
451 [X] Foreground: Firebrick [Choose] (sample)
455 [Hide Unused Attributes]
459 The first three lines show the name, @samp{[State]} button, and
460 documentation for the face. Below that is a list of @dfn{face
461 attributes}. In front of each attribute is a checkbox. A filled
462 checkbox, @samp{[X]}, means that the face specifies a value for this
463 attribute; an empty checkbox, @samp{[ ]}, means that the face does not
464 specify any special value for the attribute. You can activate a
465 checkbox to specify or unspecify its attribute.
467 A face does not have to specify every single attribute; in fact,
468 most faces only specify a few attributes. In the above example,
469 @code{font-lock-comment-face} only specifies the foreground color.
470 Any unspecified attribute is taken from the special face named
471 @code{default}, whose attributes are all specified. The
472 @code{default} face is the face used to display any text that does not
473 have an explicitly-assigned face; furthermore, its background color
474 attribute serves as the background color of the frame.
476 The @samp{[Hide Unused Attributes]} button, at the end of the
477 attribute list, hides the unspecified attributes of the face. When
478 attributes are being hidden, the button changes to @samp{[Show All
479 Attributes]}, which reveals the entire attribute list. The
480 customization buffer may start out with unspecified attributes hidden,
481 to avoid cluttering the interface.
483 When an attribute is specified, you can change its value in the
486 Foreground and background colors can be specified using either color
487 names or RGB triplets (@pxref{Colors}). You can also use the
488 @samp{[Choose]} button to switch to a list of color names; select a
489 color with @kbd{@key{RET}} in that buffer to put the color name in the
492 Setting, saving and resetting a face work like the same operations for
493 variables (@pxref{Changing a Variable}).
495 A face can specify different appearances for different types of
496 displays. For example, a face can make text red on a color display,
497 but use a bold font on a monochrome display. To specify multiple
498 appearances for a face, select @samp{For All Kinds of Displays} in the
499 menu you get from invoking @samp{[State]}.
501 @node Specific Customization
502 @subsection Customizing Specific Items
505 @item M-x customize-option @key{RET} @var{option} @key{RET}
506 @itemx M-x customize-variable @key{RET} @var{option} @key{RET}
507 Set up a customization buffer for just one user option, @var{option}.
509 @item M-x customize-face @key{RET} @var{face} @key{RET}
510 Set up a customization buffer for just one face, @var{face}.
512 @item M-x customize-group @key{RET} @var{group} @key{RET}
513 Set up a customization buffer for just one group, @var{group}.
515 @item M-x customize-apropos @key{RET} @var{regexp} @key{RET}
516 Set up a customization buffer for all the settings and groups that
519 @item M-x customize-changed @key{RET} @var{version} @key{RET}
520 Set up a customization buffer with all the settings and groups
521 whose meaning has changed since Emacs version @var{version}.
523 @item M-x customize-changed-options @key{RET} @var{version} @key{RET}
524 Set up a customization buffer with all the options whose meaning or
525 default values have changed since Emacs version @var{version}.
527 @item M-x customize-saved
528 Set up a customization buffer containing all settings that you
529 have saved with customization buffers.
531 @item M-x customize-unsaved
532 Set up a customization buffer containing all settings that you have
536 @findex customize-option
537 If you want to customize a particular user option, type @kbd{M-x
538 customize-option}. This reads the variable name, and sets up the
539 customization buffer with just that one user option. When entering
540 the variable name into the minibuffer, completion is available, but
541 only for the names of variables that have been loaded into Emacs.
543 @findex customize-face
544 @findex customize-group
545 Likewise, you can customize a specific face using @kbd{M-x
546 customize-face}. You can set up a customization buffer for a specific
547 customization group using @kbd{M-x customize-group}.
549 @findex customize-apropos
550 @kbd{M-x customize-apropos} prompts for a search term---either one
551 or more words separated by spaces, or a regular expression---and sets
552 up a customization buffer for all @emph{loaded} settings and groups
553 with matching names. This is like using the search field at the top
554 of the customization buffer (@pxref{Customization Groups}).
556 @findex customize-changed
557 When you upgrade to a new Emacs version, you might want to consider
558 customizing new settings, and settings whose meanings or default
559 values have changed. To do this, use @kbd{M-x customize-changed} and
560 specify a previous Emacs version number using the minibuffer. It
561 creates a customization buffer which shows all the settings and groups
562 whose definitions have been changed since the specified version,
563 loading them if necessary.
565 @findex customize-saved
566 @findex customize-unsaved
567 If you change settings and then decide the change was a mistake, you
568 can use two commands to revisit your changes. Use @kbd{M-x
569 customize-saved} to customize settings that you have saved. Use
570 @kbd{M-x customize-unsaved} to customize settings that you have set
574 @subsection Custom Themes
575 @cindex custom themes
577 @dfn{Custom themes} are collections of settings that can be enabled
578 or disabled as a unit. You can use Custom themes to switch easily
579 between various collections of settings, and to transfer such
580 collections from one computer to another.
582 A Custom theme is stored as an Emacs Lisp source file. If the name of
583 the Custom theme is @var{name}, the theme file is named
584 @file{@var{name}-theme.el}. @xref{Creating Custom Themes}, for the
585 format of a theme file and how to make one.
587 @findex customize-themes
588 @vindex custom-theme-directory
590 Type @kbd{M-x customize-themes} to switch to a buffer named
591 @file{*Custom Themes*}, which lists the Custom themes that Emacs knows
592 about. By default, Emacs looks for theme files in two locations: the
593 directory specified by the variable @code{custom-theme-directory}
594 (which defaults to @file{~/.emacs.d/}), and a directory named
595 @file{etc/themes} in your Emacs installation (see the variable
596 @code{data-directory}). The latter contains several Custom themes
597 distributed with Emacs that customize Emacs's faces to fit
598 various color schemes. (Note, however, that Custom themes need not be
599 restricted to this purpose; they can be used to customize variables
602 @vindex custom-theme-load-path
603 If you want Emacs to look for Custom themes in some other directory,
604 add the directory to the list variable
605 @code{custom-theme-load-path}. Its default value is
606 @code{(custom-theme-directory t)}; here, the symbol
607 @code{custom-theme-directory} has the special meaning of the value of
608 the variable @code{custom-theme-directory}, while @code{t} stands for
609 the built-in theme directory @file{etc/themes}. The themes listed in
610 the @file{*Custom Themes*} buffer are those found in the directories
611 specified by @code{custom-theme-load-path}.
613 @kindex C-x C-s @r{(Custom Themes buffer)}
614 In the @file{*Custom Themes*} buffer, you can activate the checkbox
615 next to a Custom theme to enable or disable the theme for the current
616 Emacs session. When a Custom theme is enabled, all of its settings
617 (variables and faces) take effect in the Emacs session. To apply the
618 choice of theme(s) to future Emacs sessions, type @kbd{C-x C-s}
619 (@code{custom-theme-save}) or use the @samp{[Save Theme Settings]}
622 @vindex custom-safe-themes
623 When you first enable a Custom theme, Emacs displays the contents of
624 the theme file and asks if you really want to load it. Because
625 loading a Custom theme can execute arbitrary Lisp code, you should
626 only say yes if you know that the theme is safe; in that case, Emacs
627 offers to remember in the future that the theme is safe (this is done
628 by saving the theme file's SHA-256 hash to the variable
629 @code{custom-safe-themes}; if you want to treat all themes as safe,
630 change its value to @code{t}). Themes that come with Emacs (in the
631 @file{etc/themes} directory) are exempt from this check, and are
632 always considered safe.
634 @vindex custom-enabled-themes
635 Setting or saving Custom themes actually works by customizing the
636 variable @code{custom-enabled-themes}. The value of this variable is
637 a list of Custom theme names (as Lisp symbols, e.g., @code{tango}).
638 Instead of using the @file{*Custom Themes*} buffer to set
639 @code{custom-enabled-themes}, you can customize the variable using the
640 usual customization interface, e.g., with @kbd{M-x customize-option}.
641 Note that Custom themes are not allowed to set
642 @code{custom-enabled-themes} themselves.
644 Any customizations that you make through the customization buffer
645 take precedence over theme settings. This lets you easily override
646 individual theme settings that you disagree with. If settings from
647 two different themes overlap, the theme occurring earlier in
648 @code{custom-enabled-themes} takes precedence. In the customization
649 buffer, if a setting has been changed from its default by a Custom
650 theme, its @samp{State} display shows @samp{THEMED} instead of
655 @findex disable-theme
656 You can enable a specific Custom theme in the current Emacs session
657 by typing @kbd{M-x load-theme}. This prompts for a theme name, loads
658 the theme from the theme file, and enables it. If a theme file
659 has been loaded before, you can enable the theme without loading its
660 file by typing @kbd{M-x enable-theme}. To disable a Custom theme,
661 type @kbd{M-x disable-theme}.
663 @findex describe-theme
664 To see a description of a Custom theme, type @kbd{?} on its line in
665 the @file{*Custom Themes*} buffer; or type @kbd{M-x describe-theme}
666 anywhere in Emacs and enter the theme name.
668 @node Creating Custom Themes
669 @subsection Creating Custom Themes
670 @cindex custom themes, creating
672 @findex customize-create-theme
673 You can define a Custom theme using an interface similar to the
674 customization buffer, by typing @kbd{M-x customize-create-theme}.
675 This switches to a buffer named @file{*Custom Theme*}. It also offers
676 to insert some common Emacs faces into the theme (a convenience, since
677 Custom themes are often used to customize faces). If you answer no,
678 the theme will initially contain no settings.
680 Near the top of the @file{*Custom Theme*} buffer, there are editable fields
681 where you can enter the theme's name and description. The name can be
682 anything except @samp{user}. The description is the one that will be
683 shown when you invoke @kbd{M-x describe-theme} for the theme. Its
684 first line should be a brief one-sentence summary; in the buffer made
685 by @kbd{M-x customize-themes}, this sentence is displayed next to the
688 To add a new setting to the theme, use the @samp{[Insert Additional
689 Face]} or @samp{[Insert Additional Variable]} buttons. Each button
690 reads a face or variable name using the minibuffer, with completion,
691 and inserts a customization entry for the face or variable. You can
692 edit the variable values or face attributes in the same way as in a
693 normal customization buffer. To remove a face or variable from the
694 theme, uncheck the checkbox next to its name.
696 @vindex custom-theme-directory@r{, saving theme files}
697 After specifying the Custom theme's faces and variables, type
698 @kbd{C-x C-s} (@code{custom-theme-write}) or use the buffer's
699 @samp{[Save Theme]} button. This saves the theme file, named
700 @file{@var{name}-theme.el} where @var{name} is the theme name, in the
701 directory named by @code{custom-theme-directory}.
703 From the @file{*Custom Theme*} buffer, you can view and edit an
704 existing Custom theme by activating the @samp{[Visit Theme]} button
705 and specifying the theme name. You can also add the settings of
706 another theme into the buffer, using the @samp{[Merge Theme]} button.
707 You can import your non-theme settings into a Custom theme by using
708 the @samp{[Merge Theme]} button and specifying the special theme named
711 A theme file is simply an Emacs Lisp source file, and loading the
712 Custom theme works by loading the Lisp file. Therefore, you can edit
713 a theme file directly instead of using the @file{*Custom Theme*}
714 buffer. @xref{Custom Themes,,, elisp, The Emacs Lisp Reference
715 Manual}, for details.
721 A @dfn{variable} is a Lisp symbol which has a value. The symbol's
722 name is also called the @dfn{variable name}. A variable name can
723 contain any characters that can appear in a file, but most variable
724 names consist of ordinary words separated by hyphens.
726 The name of the variable serves as a compact description of its
727 role. Most variables also have a @dfn{documentation string}, which
728 describes what the variable's purpose is, what kind of value it should
729 have, and how the value will be used. You can view this documentation
730 using the help command @kbd{C-h v} (@code{describe-variable}).
733 Emacs uses many Lisp variables for internal record keeping, but the
734 most interesting variables for a non-programmer user are those meant
735 for users to change---these are called @dfn{customizable variables} or
736 @dfn{user options} (@pxref{Easy Customization}). In the following
737 sections, we will describe other aspects of Emacs variables, such as
738 how to set them outside Customize.
740 Emacs Lisp allows any variable (with a few exceptions) to have any
741 kind of value. However, many variables are meaningful only if
742 assigned values of a certain type. For example, only numbers are
743 meaningful values for @code{kill-ring-max}, which specifies the
744 maximum length of the kill ring (@pxref{Earlier Kills}); if you give
745 @code{kill-ring-max} a string value, commands such as @kbd{C-y}
746 (@code{yank}) will signal an error. On the other hand, some variables
747 don't care about type; for instance, if a variable has one effect for
748 @code{nil} values and another effect for non-@code{nil} values,
749 then any value that is not the symbol @code{nil} induces the second
750 effect, regardless of its type (by convention, we usually use the
751 value @code{t}---a symbol which stands for ``true''---to specify a
752 non-@code{nil} value). If you set a variable using the customization
753 buffer, you need not worry about giving it an invalid type: the
754 customization buffer usually only allows you to enter meaningful
755 values. When in doubt, use @kbd{C-h v} (@code{describe-variable}) to
756 check the variable's documentation string to see kind of value it
757 expects (@pxref{Examining}).
760 * Examining:: Examining or setting one variable's value.
761 * Hooks:: Hook variables let you specify programs for parts
762 of Emacs to run on particular occasions.
763 * Locals:: Per-buffer values of variables.
764 * File Variables:: How files can specify variable values.
765 * Directory Variables:: How variable values can be specified by directory.
769 @subsection Examining and Setting Variables
770 @cindex setting variables
773 @item C-h v @var{var} @key{RET}
774 Display the value and documentation of variable @var{var}
775 (@code{describe-variable}).
777 @item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
778 Change the value of variable @var{var} to @var{value}.
781 To examine the value of a variable, use @kbd{C-h v}
782 (@code{describe-variable}). This reads a variable name using the
783 minibuffer, with completion, and displays both the value and the
784 documentation of the variable. For example,
787 C-h v fill-column @key{RET}
791 displays something like this:
794 fill-column is a variable defined in ‘C source code’.
797 Automatically becomes buffer-local when set.
798 This variable is safe as a file local variable if its value
799 satisfies the predicate ‘integerp’.
802 Column beyond which automatic line-wrapping should happen.
803 Interactively, you can set the buffer local value using C-x f.
805 You can customize this variable.
809 The line that says @samp{You can customize the variable} indicates that
810 this variable is a user option. @kbd{C-h v} is not restricted to user
811 options; it allows non-customizable variables too.
814 The most convenient way to set a specific customizable variable is
815 with @kbd{M-x set-variable}. This reads the variable name with the
816 minibuffer (with completion), and then reads a Lisp expression for the
817 new value using the minibuffer a second time (you can insert the old
818 value into the minibuffer for editing via @kbd{M-n}). For example,
821 M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
825 sets @code{fill-column} to 75.
827 @kbd{M-x set-variable} is limited to customizable variables, but you
828 can set any variable with a Lisp expression like this:
831 (setq fill-column 75)
835 To execute such an expression, type @kbd{M-:} (@code{eval-expression})
836 and enter the expression in the minibuffer (@pxref{Lisp Eval}).
837 Alternatively, go to the @file{*scratch*} buffer, type in the
838 expression, and then type @kbd{C-j} (@pxref{Lisp Interaction}).
840 Setting variables, like all means of customizing Emacs except where
841 otherwise stated, affects only the current Emacs session. The only
842 way to alter the variable in future sessions is to put something in
843 your initialization file (@pxref{Init File}).
848 @cindex running a hook
850 @dfn{Hooks} are an important mechanism for customizing Emacs. A
851 hook is a Lisp variable which holds a list of functions, to be called
852 on some well-defined occasion. (This is called @dfn{running the
853 hook}.) The individual functions in the list are called the @dfn{hook
854 functions} of the hook. For example, the hook @code{kill-emacs-hook}
855 runs just before exiting Emacs (@pxref{Exiting}).
858 Most hooks are @dfn{normal hooks}. This means that when Emacs runs
859 the hook, it calls each hook function in turn, with no arguments. We
860 have made an effort to keep most hooks normal, so that you can use
861 them in a uniform way. Every variable whose name ends in @samp{-hook}
864 @cindex abnormal hook
865 A few hooks are @dfn{abnormal hooks}. Their names end in
866 @samp{-functions}, instead of @samp{-hook} (some old code may also use
867 the deprecated suffix @samp{-hooks}). What
868 makes these hooks abnormal is the way its functions are
869 called---perhaps they are given arguments, or perhaps the values they
870 return are used in some way. For example,
871 @code{find-file-not-found-functions} is abnormal because as soon as
872 one hook function returns a non-@code{nil} value, the rest are not
873 called at all (@pxref{Visiting}). The documentation of each abnormal
874 hook variable explains how its functions are used.
877 You can set a hook variable with @code{setq} like any other Lisp
878 variable, but the recommended way to add a function to a hook (either
879 normal or abnormal) is to use @code{add-hook}, as shown by the
880 following examples. @xref{Hooks,,, elisp, The Emacs Lisp Reference
881 Manual}, for details.
883 Most major modes run one or more @dfn{mode hooks} as the last step
884 of initialization. Mode hooks are a convenient way to customize the
885 behavior of individual modes; they are always normal. For example,
886 here's how to set up a hook to turn on Auto Fill mode in Text mode and
887 other modes based on Text mode:
890 (add-hook 'text-mode-hook 'auto-fill-mode)
894 This works by calling @code{auto-fill-mode}, which enables the minor
895 mode when no argument is supplied (@pxref{Minor Modes}). Next,
896 suppose you don't want Auto Fill mode turned on in @LaTeX{} mode,
897 which is one of the modes based on Text mode. You can do this with
898 the following additional line:
901 (add-hook 'latex-mode-hook (lambda () (auto-fill-mode -1)))
905 Here we have used the special macro @code{lambda} to construct an
906 anonymous function (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp
907 Reference Manual}), which calls @code{auto-fill-mode} with an argument
908 of @code{-1} to disable the minor mode. Because @LaTeX{} mode runs
909 @code{latex-mode-hook} after running @code{text-mode-hook}, the result
910 leaves Auto Fill mode disabled.
912 Here is a more complex example, showing how to use a hook to
913 customize the indentation of C code:
918 '((c-comment-only-line-offset . 4)
921 (c-cleanup-list . (scope-operator
927 (add-hook 'c-mode-common-hook
928 (lambda () (c-add-style "my-style" my-c-style t)))
933 @cindex modes for editing programs
934 Major mode hooks also apply to other major modes @dfn{derived} from
935 the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp
936 Reference Manual}). For instance, HTML mode is derived from Text mode
937 (@pxref{HTML Mode}); when HTML mode is enabled, it runs
938 @code{text-mode-hook} before running @code{html-mode-hook}. This
939 provides a convenient way to use a single hook to affect several
940 related modes. In particular, if you want to apply a hook function to
941 any programming language mode, add it to @code{prog-mode-hook}; Prog
942 mode is a major mode that does little else than to let other major
943 modes inherit from it, exactly for this purpose.
945 It is best to design your hook functions so that the order in which
946 they are executed does not matter. Any dependence on the order is
947 asking for trouble. However, the order is predictable: the hook
948 functions are executed in the order they appear in the hook.
951 If you play with adding various different versions of a hook
952 function by calling @code{add-hook} over and over, remember that all
953 the versions you added will remain in the hook variable together. You
954 can clear out individual functions by calling @code{remove-hook}, or
955 do @code{(setq @var{hook-variable} nil)} to remove everything.
957 @cindex buffer-local hooks
958 If the hook variable is buffer-local, the buffer-local variable will
959 be used instead of the global variable. However, if the buffer-local
960 variable contains the element @code{t}, the global hook variable will
964 @subsection Local Variables
967 @item M-x make-local-variable @key{RET} @var{var} @key{RET}
968 Make variable @var{var} have a local value in the current buffer.
970 @item M-x kill-local-variable @key{RET} @var{var} @key{RET}
971 Make variable @var{var} use its global value in the current buffer.
973 @item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
974 Mark variable @var{var} so that setting it will make it local to the
975 buffer that is current at that time.
978 @cindex local variables
979 Almost any variable can be made @dfn{local} to a specific Emacs
980 buffer. This means that its value in that buffer is independent of its
981 value in other buffers. A few variables are always local in every
982 buffer. Every other Emacs variable has a @dfn{global} value which is in
983 effect in all buffers that have not made the variable local.
985 @findex make-local-variable
986 @kbd{M-x make-local-variable} reads the name of a variable and makes
987 it local to the current buffer. Changing its value subsequently in
988 this buffer will not affect others, and changes in its global value
989 will not affect this buffer.
991 @findex make-variable-buffer-local
992 @cindex per-buffer variables
993 @kbd{M-x make-variable-buffer-local} marks a variable so it will
994 become local automatically whenever it is set. More precisely, once a
995 variable has been marked in this way, the usual ways of setting the
996 variable automatically do @code{make-local-variable} first. We call
997 such variables @dfn{per-buffer} variables. Many variables in Emacs
998 are normally per-buffer; the variable's document string tells you when
999 this is so. A per-buffer variable's global value is normally never
1000 effective in any buffer, but it still has a meaning: it is the initial
1001 value of the variable for each new buffer.
1003 Major modes (@pxref{Major Modes}) always make variables local to the
1004 buffer before setting the variables. This is why changing major modes
1005 in one buffer has no effect on other buffers. Minor modes also work
1006 by setting variables---normally, each minor mode has one controlling
1007 variable which is non-@code{nil} when the mode is enabled
1008 (@pxref{Minor Modes}). For many minor modes, the controlling variable
1009 is per buffer, and thus always buffer-local. Otherwise, you can make
1010 it local in a specific buffer like any other variable.
1012 A few variables cannot be local to a buffer because they are always
1013 local to each display instead (@pxref{Multiple Displays}). If you try to
1014 make one of these variables buffer-local, you'll get an error message.
1016 @findex kill-local-variable
1017 @kbd{M-x kill-local-variable} makes a specified variable cease to be
1018 local to the current buffer. The global value of the variable
1019 henceforth is in effect in this buffer. Setting the major mode kills
1020 all the local variables of the buffer except for a few variables
1021 specially marked as @dfn{permanent locals}.
1023 @findex setq-default
1024 To set the global value of a variable, regardless of whether the
1025 variable has a local value in the current buffer, you can use the Lisp
1026 construct @code{setq-default}. This construct is used just like
1027 @code{setq}, but it sets variables' global values instead of their local
1028 values (if any). When the current buffer does have a local value, the
1029 new global value may not be visible until you switch to another buffer.
1033 (setq-default fill-column 75)
1037 @code{setq-default} is the only way to set the global value of a variable
1038 that has been marked with @code{make-variable-buffer-local}.
1040 @findex default-value
1041 Lisp programs can use @code{default-value} to look at a variable's
1042 default value. This function takes a symbol as argument and returns its
1043 default value. The argument is evaluated; usually you must quote it
1044 explicitly. For example, here's how to obtain the default value of
1048 (default-value 'fill-column)
1051 @node File Variables
1052 @subsection Local Variables in Files
1053 @cindex local variables in files
1054 @cindex file local variables
1056 A file can specify local variable values to use when editing the
1057 file with Emacs. Visiting the file or setting a major mode checks for
1058 local variable specifications; it automatically makes these variables
1059 local to the buffer, and sets them to the values specified in the
1063 * Specifying File Variables:: Specifying file local variables.
1064 * Safe File Variables:: Making sure file local variables are safe.
1067 @node Specifying File Variables
1068 @subsubsection Specifying File Variables
1070 There are two ways to specify file local variable values: in the first
1071 line, or with a local variables list. Here's how to specify them in the
1075 -*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
1079 You can specify any number of variable/value pairs in this way, each
1080 pair with a colon and semicolon. The special variable/value pair
1081 @code{mode: @var{modename};}, if present, specifies a major mode. The
1082 @var{value}s are used literally, and not evaluated.
1084 @findex add-file-local-variable-prop-line
1085 @findex delete-file-local-variable-prop-line
1086 @findex copy-dir-locals-to-file-locals-prop-line
1087 You can use @kbd{M-x add-file-local-variable-prop-line} instead of
1088 adding entries by hand. This command prompts for a variable and
1089 value, and adds them to the first line in the appropriate way.
1090 @kbd{M-x delete-file-local-variable-prop-line} prompts for a variable,
1091 and deletes its entry from the line. The command @kbd{M-x
1092 copy-dir-locals-to-file-locals-prop-line} copies the current
1093 directory-local variables to the first line (@pxref{Directory
1096 Here is an example first line that specifies Lisp mode and sets two
1097 variables with numeric values:
1100 ;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
1104 Aside from @code{mode}, other keywords that have special meanings as
1105 file variables are @code{coding}, @code{unibyte}, and @code{eval}.
1106 These are described below.
1108 @cindex shell scripts, and local file variables
1109 @cindex man pages, and local file variables
1110 In shell scripts, the first line is used to identify the script
1111 interpreter, so you cannot put any local variables there. To
1112 accommodate this, Emacs looks for local variable specifications in the
1113 @emph{second} line if the first line specifies an interpreter. The
1114 same is true for man pages which start with the magic string
1115 @samp{'\"} to specify a list of troff preprocessors (not all do,
1118 Apart from using a @samp{-*-} line, you can define file local
1119 variables using a @dfn{local variables list} near the end of the file.
1120 The start of the local variables list should be no more than 3000
1121 characters from the end of the file, and must be on the last page if
1122 the file is divided into pages.
1124 If a file has both a local variables list and a @samp{-*-} line,
1125 Emacs processes @emph{everything} in the @samp{-*-} line first, and
1126 @emph{everything} in the local variables list afterward. The exception
1127 to this is a major mode specification. Emacs applies this first,
1128 wherever it appears, since most major modes kill all local variables as
1129 part of their initialization.
1131 A local variables list starts with a line containing the string
1132 @samp{Local Variables:}, and ends with a line containing the string
1133 @samp{End:}. In between come the variable names and values, one set
1134 per line, like this:
1137 /* Local Variables: */
1139 /* comment-column: 0 */
1144 In this example, each line starts with the prefix @samp{/*} and ends
1145 with the suffix @samp{*/}. Emacs recognizes the prefix and suffix by
1146 finding them surrounding the magic string @samp{Local Variables:}, on
1147 the first line of the list; it then automatically discards them from
1148 the other lines of the list. The usual reason for using a prefix
1149 and/or suffix is to embed the local variables list in a comment, so it
1150 won't confuse other programs that the file is intended for. The
1151 example above is for the C programming language, where comments start
1152 with @samp{/*} and end with @samp{*/}.
1154 If some unrelated text might look to Emacs as a local variables list,
1155 you can countermand that by inserting a form-feed character (a page
1156 delimiter, @pxref{Pages}) after that text. Emacs only looks for
1157 file-local variables in the last page of a file, after the last page
1160 @findex add-file-local-variable
1161 @findex delete-file-local-variable
1162 @findex copy-dir-locals-to-file-locals
1163 Instead of typing in the local variables list directly, you can use
1164 the command @kbd{M-x add-file-local-variable}. This prompts for a
1165 variable and value, and adds them to the list, adding the @samp{Local
1166 Variables:} string and start and end markers as necessary. The
1167 command @kbd{M-x delete-file-local-variable} deletes a variable from
1168 the list. @kbd{M-x copy-dir-locals-to-file-locals} copies
1169 directory-local variables to the list (@pxref{Directory Variables}).
1171 As with the @samp{-*-} line, the variables in a local variables list
1172 are used literally, and are not evaluated first. If you want to split
1173 a long string value across multiple lines of the file, you can use
1174 backslash-newline, which is ignored in Lisp string constants; you
1175 should put the prefix and suffix on each line, even lines that start
1176 or end within the string, as they will be stripped off when processing
1177 the list. Here is an example:
1181 # compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
1186 Some names have special meanings in a local variables
1191 @code{mode} enables the specified major mode.
1194 @code{eval} evaluates the specified Lisp expression (the value
1195 returned by that expression is ignored).
1198 @code{coding} specifies the coding system for character code
1199 conversion of this file. @xref{Coding Systems}.
1202 @code{unibyte} says to load or compile a file of Emacs Lisp in unibyte
1203 mode, if the value is @code{t}. @xref{Disabling Multibyte, ,
1204 Disabling Multibyte Characters, elisp, GNU Emacs Lisp Reference
1210 These four keywords are not really variables; setting them in any
1211 other context has no special meaning.
1213 Do not use the @code{mode} keyword for minor modes. To enable or
1214 disable a minor mode in a local variables list, use the @code{eval}
1215 keyword with a Lisp expression that runs the mode command
1216 (@pxref{Minor Modes}). For example, the following local variables
1217 list enables Eldoc mode (@pxref{Lisp Doc}) by calling
1218 @code{eldoc-mode} with no argument (calling it with an argument of 1
1219 would do the same), and disables Font Lock mode (@pxref{Font Lock}) by
1220 calling @code{font-lock-mode} with an argument of @minus{}1.
1224 ;; eval: (eldoc-mode)
1225 ;; eval: (font-lock-mode -1)
1230 Note, however, that it is often a mistake to specify minor modes this
1231 way. Minor modes represent individual user preferences, and it may be
1232 inappropriate to impose your preferences on another user who might
1233 edit the file. If you wish to automatically enable or disable a minor
1234 mode in a situation-dependent way, it is often better to do it in a
1235 major mode hook (@pxref{Hooks}).
1237 Use the command @kbd{M-x normal-mode} to reset the local variables
1238 and major mode of a buffer according to the file name and contents,
1239 including the local variables list if any. @xref{Choosing Modes}.
1241 @node Safe File Variables
1242 @subsubsection Safety of File Variables
1244 File-local variables can be dangerous; when you visit someone else's
1245 file, there's no telling what its local variables list could do to
1246 your Emacs. Improper values of the @code{eval} ``variable'', and
1247 other variables such as @code{load-path}, could execute Lisp code you
1248 didn't intend to run.
1250 Therefore, whenever Emacs encounters file local variable values that
1251 are not known to be safe, it displays the file's entire local
1252 variables list, and asks you for confirmation before setting them.
1253 You can type @kbd{y} or @key{SPC} to put the local variables list into
1254 effect, or @kbd{n} to ignore it. When Emacs is run in batch mode
1255 (@pxref{Initial Options}), it can't really ask you, so it assumes the
1258 Emacs normally recognizes certain variable/value pairs as safe.
1259 For instance, it is safe to give @code{comment-column} or
1260 @code{fill-column} any integer value. If a file specifies only
1261 known-safe variable/value pairs, Emacs does not ask for confirmation
1262 before setting them. Otherwise, you can tell Emacs to record all the
1263 variable/value pairs in this file as safe, by typing @kbd{!} at the
1264 confirmation prompt. When Emacs encounters these variable/value pairs
1265 subsequently, in the same file or others, it will assume they are
1268 @vindex safe-local-variable-values
1269 @cindex risky variable
1270 Some variables, such as @code{load-path}, are considered
1271 particularly @dfn{risky}: there is seldom any reason to specify them
1272 as local variables, and changing them can be dangerous. If a file
1273 contains only risky local variables, Emacs neither offers nor accepts
1274 @kbd{!} as input at the confirmation prompt. If some of the local
1275 variables in a file are risky, and some are only potentially unsafe, you
1276 can enter @kbd{!} at the prompt. It applies all the variables, but only
1277 marks the non-risky ones as safe for the future. If you really want to
1278 record safe values for risky variables, do it directly by customizing
1279 @samp{safe-local-variable-values} (@pxref{Easy Customization}).
1281 @vindex enable-local-variables
1282 The variable @code{enable-local-variables} allows you to change the
1283 way Emacs processes local variables. Its default value is @code{t},
1284 which specifies the behavior described above. If it is @code{nil},
1285 Emacs simply ignores all file local variables. @code{:safe} means use
1286 only the safe values and ignore the rest. Any other value says to
1287 query you about each file that has local variables, without trying to
1288 determine whether the values are known to be safe.
1290 @vindex enable-local-eval
1291 @vindex safe-local-eval-forms
1292 The variable @code{enable-local-eval} controls whether Emacs
1293 processes @code{eval} variables. The three possibilities for the
1294 variable's value are @code{t}, @code{nil}, and anything else, just as
1295 for @code{enable-local-variables}. The default is @code{maybe}, which
1296 is neither @code{t} nor @code{nil}, so normally Emacs does ask for
1297 confirmation about processing @code{eval} variables.
1299 As an exception, Emacs never asks for confirmation to evaluate any
1300 @code{eval} form if that form occurs within the variable
1301 @code{safe-local-eval-forms}.
1303 @node Directory Variables
1304 @subsection Per-Directory Local Variables
1305 @cindex local variables, for all files in a directory
1306 @cindex directory-local variables
1307 @cindex per-directory local variables
1309 Sometimes, you may wish to define the same set of local variables to
1310 all the files in a certain directory and its subdirectories, such as
1311 the directory tree of a large software project. This can be
1312 accomplished with @dfn{directory-local variables}.
1314 @cindex @file{.dir-locals.el} file
1315 The usual way to define directory-local variables is to put a file
1316 named @file{.dir-locals.el}@footnote{ On MS-DOS, the name of this file
1317 should be @file{_dir-locals.el}, due to limitations of the DOS
1318 filesystems. If the filesystem is limited to 8+3 file names, the name
1319 of the file will be truncated by the OS to @file{_dir-loc.el}.
1320 }@footnote{ You can also use @file{.dir-locals-2.el}, which
1321 is loaded in addition. This is useful when @file{.dir-locals.el} is
1322 under version control in a shared repository and can't be used for
1323 personal customizations. } in a
1324 directory. Whenever Emacs visits any file in that directory or any of
1325 its subdirectories, it will apply the directory-local variables
1326 specified in @file{.dir-locals.el}, as though they had been defined as
1327 file-local variables for that file (@pxref{File Variables}). Emacs
1328 searches for @file{.dir-locals.el} starting in the directory of the
1329 visited file, and moving up the directory tree. To avoid slowdown,
1330 this search is skipped for remote files. If needed, the search can be
1331 extended for remote files by setting the variable
1332 @code{enable-remote-dir-locals} to @code{t}.
1334 The @file{.dir-locals.el} file should hold a specially-constructed
1335 list, which maps major mode names (symbols) to alists
1336 (@pxref{Association Lists,,, elisp, The Emacs Lisp Reference Manual}).
1337 Each alist entry consists of a variable name and the directory-local
1338 value to assign to that variable, when the specified major mode is
1339 enabled. Instead of a mode name, you can specify @samp{nil}, which
1340 means that the alist applies to any mode; or you can specify a
1341 subdirectory (a string), in which case the alist applies to all
1342 files in that subdirectory.
1344 Here's an example of a @file{.dir-locals.el} file:
1347 ((nil . ((indent-tabs-mode . t)
1348 (fill-column . 80)))
1349 (c-mode . ((c-file-style . "BSD")
1352 . ((nil . ((change-log-default-name
1353 . "ChangeLog.local"))))))
1357 This sets @samp{indent-tabs-mode} and @code{fill-column} for any file
1358 in the directory tree, and the indentation style for any C source
1359 file. The special @code{subdirs} element is not a variable, but a
1360 special keyword which indicates that the C mode settings are only to
1361 be applied in the current directory, not in any subdirectories.
1362 Finally, it specifies a different @file{ChangeLog} file name for any
1363 file in the @file{src/imported} subdirectory.
1365 You can specify the variables @code{mode}, @code{eval}, and
1366 @code{unibyte} in your @file{.dir-locals.el}, and they have the same
1367 meanings as they would have in file local variables. @code{coding}
1368 cannot be specified as a directory local variable. @xref{File
1371 @findex add-dir-local-variable
1372 @findex delete-dir-local-variable
1373 @findex copy-file-locals-to-dir-locals
1374 Instead of editing the @file{.dir-locals.el} file by hand, you can
1375 use the command @kbd{M-x add-dir-local-variable}. This prompts for a
1376 mode or subdirectory, and for variable and value, and adds the
1377 entry defining the directory-local variable. @kbd{M-x
1378 delete-dir-local-variable} deletes an entry. @kbd{M-x
1379 copy-file-locals-to-dir-locals} copies the file-local variables in the
1380 current file into @file{.dir-locals.el}.
1382 @findex dir-locals-set-class-variables
1383 @findex dir-locals-set-directory-class
1384 Another method of specifying directory-local variables is to define
1385 a group of variables/value pairs in a @dfn{directory class}, using the
1386 @code{dir-locals-set-class-variables} function; then, tell Emacs which
1387 directories correspond to the class by using the
1388 @code{dir-locals-set-directory-class} function. These function calls
1389 normally go in your initialization file (@pxref{Init File}). This
1390 method is useful when you can't put @file{.dir-locals.el} in a
1391 directory for some reason. For example, you could apply settings to
1392 an unwritable directory this way:
1395 (dir-locals-set-class-variables 'unwritable-directory
1396 '((nil . ((some-useful-setting . value)))))
1398 (dir-locals-set-directory-class
1399 "/usr/include/" 'unwritable-directory)
1402 If a variable has both a directory-local and file-local value
1403 specified, the file-local value takes effect. Unsafe directory-local
1404 variables are handled in the same way as unsafe file-local variables
1405 (@pxref{Safe File Variables}).
1407 Directory-local variables also take effect in certain buffers that
1408 do not visit a file directly but perform work within a directory, such
1409 as Dired buffers (@pxref{Dired}).
1412 @section Customizing Key Bindings
1413 @cindex key bindings
1415 This section describes @dfn{key bindings}, which map keys to
1416 commands, and @dfn{keymaps}, which record key bindings. It also
1417 explains how to customize key bindings, which is done by editing your
1418 init file (@pxref{Init Rebinding}).
1421 * Keymaps:: Generalities. The global keymap.
1422 * Prefix Keymaps:: Keymaps for prefix keys.
1423 * Local Keymaps:: Major and minor modes have their own keymaps.
1424 * Minibuffer Maps:: The minibuffer uses its own local keymaps.
1425 * Rebinding:: How to redefine one key's meaning conveniently.
1426 * Init Rebinding:: Rebinding keys with your initialization file.
1427 * Modifier Keys:: Using modifier keys.
1428 * Function Keys:: Rebinding terminal function keys.
1429 * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on.
1430 * Mouse Buttons:: Rebinding mouse buttons in Emacs.
1431 * Disabling:: Disabling a command means confirmation is required
1432 before it can be executed. This is done to protect
1433 beginners from surprises.
1440 As described in @ref{Commands}, each Emacs command is a Lisp
1441 function whose definition provides for interactive use. Like every
1442 Lisp function, a command has a function name, which usually consists
1443 of lower-case letters and hyphens.
1445 A @dfn{key sequence} (@dfn{key}, for short) is a sequence of
1446 @dfn{input events} that have a meaning as a unit. Input events
1447 include characters, function keys, and mouse buttons---all the inputs
1448 that you can send to the computer. A key sequence gets its meaning
1449 from its @dfn{binding}, which says what command it runs.
1451 The bindings between key sequences and command functions are
1452 recorded in data structures called @dfn{keymaps}. Emacs has many of
1453 these, each used on particular occasions.
1455 @cindex global keymap
1456 The @dfn{global} keymap is the most important keymap because it is
1457 always in effect. The global keymap defines keys for Fundamental mode
1458 (@pxref{Major Modes}); most of these definitions are common to most or
1459 all major modes. Each major or minor mode can have its own keymap
1460 which overrides the global definitions of some keys.
1462 For example, a self-inserting character such as @kbd{g} is
1463 self-inserting because the global keymap binds it to the command
1464 @code{self-insert-command}. The standard Emacs editing characters
1465 such as @kbd{C-a} also get their standard meanings from the global
1466 keymap. Commands to rebind keys, such as @kbd{M-x global-set-key},
1467 work by storing the new binding in the proper place in the global map
1468 (@pxref{Rebinding}).
1470 @cindex function key
1471 Most modern keyboards have function keys as well as character keys.
1472 Function keys send input events just as character keys do, and keymaps
1473 can have bindings for them. Key sequences can mix function keys and
1474 characters. For example, if your keyboard has a @key{Home} function
1475 key, Emacs can recognize key sequences like @kbd{C-x @key{Home}}. You
1476 can even mix mouse events with keyboard events, such as
1477 @kbd{S-down-mouse-1}.
1479 On text terminals, typing a function key actually sends the computer
1480 a sequence of characters; the precise details of the sequence depend
1481 on the function key and on the terminal type. (Often the sequence
1482 starts with @kbd{@key{ESC} [}.) If Emacs understands your terminal
1483 type properly, it automatically handles such sequences as single input
1486 @node Prefix Keymaps
1487 @subsection Prefix Keymaps
1489 Internally, Emacs records only single events in each keymap.
1490 Interpreting a key sequence of multiple events involves a chain of
1491 keymaps: the first keymap gives a definition for the first event,
1492 which is another keymap, which is used to look up the second event in
1493 the sequence, and so on. Thus, a prefix key such as @kbd{C-x} or
1494 @key{ESC} has its own keymap, which holds the definition for the event
1495 that immediately follows that prefix.
1497 The definition of a prefix key is usually the keymap to use for
1498 looking up the following event. The definition can also be a Lisp
1499 symbol whose function definition is the following keymap; the effect is
1500 the same, but it provides a command name for the prefix key that can be
1501 used as a description of what the prefix key is for. Thus, the binding
1502 of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function
1503 definition is the keymap for @kbd{C-x} commands. The definitions of
1504 @kbd{C-c}, @kbd{C-x}, @kbd{C-h}, and @key{ESC} as prefix keys appear in
1505 the global map, so these prefix keys are always available.
1507 Aside from ordinary prefix keys, there is a fictitious ``prefix key''
1508 which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp
1509 Reference Manual}, for special information about menu bar key bindings.
1510 Mouse button events that invoke pop-up menus are also prefix keys; see
1511 @ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more
1514 Some prefix keymaps are stored in variables with names:
1519 @code{ctl-x-map} is the variable name for the map used for characters that
1523 @code{help-map} is for characters that follow @kbd{C-h}.
1526 @code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta
1527 characters are actually defined by this map.
1530 @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
1532 @vindex mode-specific-map
1533 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
1537 @subsection Local Keymaps
1539 @cindex local keymap
1540 @cindex minor mode keymap
1541 So far, we have explained the ins and outs of the global map. Major
1542 modes customize Emacs by providing their own key bindings in
1543 @dfn{local keymaps}. For example, C mode overrides @key{TAB} to make
1544 it indent the current line for C code. Minor modes can also have
1545 local keymaps; whenever a minor mode is in effect, the definitions in
1546 its keymap override both the major mode's local keymap and the global
1547 keymap. In addition, portions of text in the buffer can specify their
1548 own keymaps, which override all other keymaps.
1550 A local keymap can redefine a key as a prefix key by defining it as
1551 a prefix keymap. If the key is also defined globally as a prefix, its
1552 local and global definitions (both keymaps) effectively combine: both
1553 definitions are used to look up the event that follows the prefix key.
1554 For example, if a local keymap defines @kbd{C-c} as a prefix keymap,
1555 and that keymap defines @kbd{C-z} as a command, this provides a local
1556 meaning for @kbd{C-c C-z}. This does not affect other sequences that
1557 start with @kbd{C-c}; if those sequences don't have their own local
1558 bindings, their global bindings remain in effect.
1560 Another way to think of this is that Emacs handles a multi-event key
1561 sequence by looking in several keymaps, one by one, for a binding of the
1562 whole key sequence. First it checks the minor mode keymaps for minor
1563 modes that are enabled, then it checks the major mode's keymap, and then
1564 it checks the global keymap. This is not precisely how key lookup
1565 works, but it's good enough for understanding the results in ordinary
1568 @node Minibuffer Maps
1569 @subsection Minibuffer Keymaps
1571 @cindex minibuffer keymaps
1572 @vindex minibuffer-local-map
1573 @vindex minibuffer-local-ns-map
1574 @vindex minibuffer-local-completion-map
1575 @vindex minibuffer-local-must-match-map
1576 @vindex minibuffer-local-filename-completion-map
1577 @vindex minibuffer-local-filename-must-match-map
1578 The minibuffer has its own set of local keymaps; they contain various
1579 completion and exit commands.
1583 @code{minibuffer-local-map} is used for ordinary input (no completion).
1585 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
1586 just like @key{RET}.
1588 @code{minibuffer-local-completion-map} is for permissive completion.
1590 @code{minibuffer-local-must-match-map} is for strict completion and
1591 for cautious completion.
1593 @code{minibuffer-local-filename-completion-map} and
1594 @code{minibuffer-local-filename-must-match-map} are like the two
1595 previous ones, but they are specifically for file name completion.
1596 They do not bind @key{SPC}.
1600 @subsection Changing Key Bindings Interactively
1601 @cindex key rebinding, this session
1602 @cindex redefining keys, this session
1603 @cindex binding keys
1605 The way to redefine an Emacs key is to change its entry in a keymap.
1606 You can change the global keymap, in which case the change is
1607 effective in all major modes (except those that have their own
1608 overriding local bindings for the same key). Or you can change a
1609 local keymap, which affects all buffers using the same major mode.
1611 In this section, we describe how to rebind keys for the present
1612 Emacs session. @xref{Init Rebinding}, for a description of how to
1613 make key rebindings affect future Emacs sessions.
1615 @findex global-set-key
1616 @findex local-set-key
1617 @findex global-unset-key
1618 @findex local-unset-key
1620 @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1621 Define @var{key} globally to run @var{cmd}.
1622 @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
1623 Define @var{key} locally (in the major mode now in effect) to run
1625 @item M-x global-unset-key @key{RET} @var{key}
1626 Make @var{key} undefined in the global map.
1627 @item M-x local-unset-key @key{RET} @var{key}
1628 Make @var{key} undefined locally (in the major mode now in effect).
1631 For example, the following binds @kbd{C-z} to the @code{shell}
1632 command (@pxref{Interactive Shell}), replacing the normal global
1633 definition of @kbd{C-z}:
1636 M-x global-set-key @key{RET} C-z shell @key{RET}
1640 The @code{global-set-key} command reads the command name after the
1641 key. After you press the key, a message like this appears so that you
1642 can confirm that you are binding the key you want:
1645 Set key C-z to command:
1648 You can redefine function keys and mouse events in the same way; just
1649 type the function key or click the mouse when it's time to specify the
1652 You can rebind a key that contains more than one event in the same
1653 way. Emacs keeps reading the key to rebind until it is a complete key
1654 (that is, not a prefix key). Thus, if you type @kbd{C-f} for
1655 @var{key}, that's the end; it enters the minibuffer immediately to
1656 read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it
1657 reads another character; if that is @kbd{4}, another prefix character,
1658 it reads one more character, and so on. For example,
1661 M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
1665 redefines @kbd{C-x 4 $} to run the (fictitious) command
1666 @code{spell-other-window}.
1668 You can remove the global definition of a key with
1669 @code{global-unset-key}. This makes the key @dfn{undefined}; if you
1670 type it, Emacs will just beep. Similarly, @code{local-unset-key} makes
1671 a key undefined in the current major mode keymap, which makes the global
1672 definition (or lack of one) come back into effect in that major mode.
1674 If you have redefined (or undefined) a key and you subsequently wish
1675 to retract the change, undefining the key will not do the job---you need
1676 to redefine the key with its standard definition. To find the name of
1677 the standard definition of a key, go to a Fundamental mode buffer in a
1678 fresh Emacs and use @kbd{C-h c}. The documentation of keys in this
1679 manual also lists their command names.
1681 If you want to prevent yourself from invoking a command by mistake, it
1682 is better to disable the command than to undefine the key. A disabled
1683 command is less work to invoke when you really want to.
1686 @node Init Rebinding
1687 @subsection Rebinding Keys in Your Init File
1688 @cindex rebinding major mode keys
1689 @cindex key rebinding, permanent
1690 @cindex rebinding keys, permanently
1691 @c This node is referenced in the tutorial. When renaming or deleting
1692 @c it, the tutorial needs to be adjusted. (TUTORIAL.de)
1694 If you have a set of key bindings that you like to use all the time,
1695 you can specify them in your initialization file by writing Lisp code.
1696 @xref{Init File}, for a description of the initialization file.
1699 There are several ways to write a key binding using Lisp. The
1700 simplest is to use the @code{kbd} function, which converts a textual
1701 representation of a key sequence---similar to how we have written key
1702 sequences in this manual---into a form that can be passed as an
1703 argument to @code{global-set-key}. For example, here's how to bind
1704 @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
1707 (global-set-key (kbd "C-z") 'shell)
1711 The single-quote before the command name, @code{shell}, marks it as a
1712 constant symbol rather than a variable. If you omit the quote, Emacs
1713 would try to evaluate @code{shell} as a variable. This probably
1714 causes an error; it certainly isn't what you want.
1716 Here are some additional examples, including binding function keys
1720 (global-set-key (kbd "C-c y") 'clipboard-yank)
1721 (global-set-key (kbd "C-M-q") 'query-replace)
1722 (global-set-key (kbd "<f5>") 'flyspell-mode)
1723 (global-set-key (kbd "C-<f5>") 'display-line-numbers-mode)
1724 (global-set-key (kbd "C-<right>") 'forward-sentence)
1725 (global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
1728 Instead of using @code{kbd}, you can use a Lisp string or vector to
1729 specify the key sequence. Using a string is simpler, but only works
1730 for @acronym{ASCII} characters and Meta-modified @acronym{ASCII}
1731 characters. For example, here's how to bind @kbd{C-x M-l} to
1732 @code{make-symbolic-link} (@pxref{Copying and Naming}):
1735 (global-set-key "\C-x\M-l" 'make-symbolic-link)
1738 To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the string,
1739 use the Emacs Lisp escape sequences @samp{\t}, @samp{\r}, @samp{\e},
1740 and @samp{\d} respectively. Here is an example which binds @kbd{C-x
1741 @key{TAB}} to @code{indent-rigidly} (@pxref{Indentation}):
1744 (global-set-key "\C-x\t" 'indent-rigidly)
1747 When the key sequence includes function keys or mouse button events,
1748 or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a},
1749 you can use a vector to specify the key sequence. Each element in the
1750 vector stands for an input event; the elements are separated by spaces
1751 and surrounded by a pair of square brackets. If a vector element is a
1752 character, write it as a Lisp character constant: @samp{?} followed by
1753 the character as it would appear in a string. Function keys are
1754 represented by symbols (@pxref{Function Keys}); simply write the
1755 symbol's name, with no other delimiters or punctuation. Here are some
1759 (global-set-key [?\C-=] 'make-symbolic-link)
1760 (global-set-key [?\M-\C-=] 'make-symbolic-link)
1761 (global-set-key [?\H-a] 'make-symbolic-link)
1762 (global-set-key [f7] 'make-symbolic-link)
1763 (global-set-key [C-mouse-1] 'make-symbolic-link)
1767 You can use a vector for the simple cases too:
1770 (global-set-key [?\C-z ?\M-l] 'make-symbolic-link)
1773 Language and coding systems may cause problems with key bindings for
1774 non-@acronym{ASCII} characters. @xref{Init Non-ASCII}.
1776 As described in @ref{Local Keymaps}, major modes and minor modes can
1777 define local keymaps. These keymaps are constructed when the mode is
1778 used for the first time in a session. If you wish to change one of
1779 these keymaps, you must use the @dfn{mode hook} (@pxref{Hooks}).
1782 For example, Texinfo mode runs the hook @code{texinfo-mode-hook}.
1783 Here's how you can use the hook to add local bindings for @kbd{C-c n}
1784 and @kbd{C-c p} in Texinfo mode:
1787 (add-hook 'texinfo-mode-hook
1789 (define-key texinfo-mode-map "\C-cp"
1790 'backward-paragraph)
1791 (define-key texinfo-mode-map "\C-cn"
1792 'forward-paragraph)))
1796 @subsection Modifier Keys
1797 @cindex modifier keys, and key rebinding
1799 The default key bindings in Emacs are set up so that modified
1800 alphabetical characters are case-insensitive. In other words,
1801 @kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the
1802 same thing as @kbd{M-a}. This concerns only alphabetical characters,
1803 and does not apply to shifted versions of other keys; for
1804 instance, @kbd{C-@@} is not the same as @kbd{C-2}.
1806 A @key{Control}-modified alphabetical character is always considered
1807 case-insensitive: Emacs always treats @kbd{C-A} as @kbd{C-a},
1808 @kbd{C-B} as @kbd{C-b}, and so forth. The reason for this is
1811 For all other modifiers, you can make the modified alphabetical
1812 characters case-sensitive when you customize Emacs. For instance, you
1813 could make @kbd{M-a} and @kbd{M-A} run different commands.
1815 Although only the @key{Control} and @key{META} modifier keys are
1816 commonly used, Emacs supports three other modifier keys. These are
1817 called @key{Super}, @key{Hyper}, and @key{Alt}. Few terminals provide
1818 ways to use these modifiers; the key labeled @key{Alt} on most
1819 keyboards usually issues the @key{META} modifier, not @key{Alt}. The
1820 standard key bindings in Emacs do not include any characters with
1821 these modifiers. However, you can customize Emacs to assign meanings
1822 to them. The modifier bits are labeled as @samp{s-}, @samp{H-} and
1823 @samp{A-} respectively.
1825 Even if your keyboard lacks these additional modifier keys, you can
1826 enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the Hyper flag to
1827 the next character, @kbd{C-x @@ s} adds the Super flag, and
1828 @kbd{C-x @@ a} adds the Alt flag. For instance, @kbd{C-x @@ h
1829 C-a} is a way to enter @kbd{Hyper-Control-a}. (Unfortunately, there
1830 is no way to add two modifiers by using @kbd{C-x @@} twice for the
1831 same character, because the first one goes to work on the @kbd{C-x}.)
1834 @subsection Rebinding Function Keys
1836 Key sequences can contain function keys as well as ordinary
1837 characters. Just as Lisp characters (actually integers) represent
1838 keyboard characters, Lisp symbols represent function keys. If the
1839 function key has a word as its label, then that word is also the name of
1840 the corresponding Lisp symbol. Here are the conventional Lisp names for
1841 common function keys:
1844 @item @code{LEFT}, @code{UP}, @code{RIGHT}, @code{DOWN}
1847 @item @code{Begin}, @code{End}, @code{Home}, @code{next}, @code{prior}
1848 Other cursor repositioning keys.
1850 @item @code{select}, @code{print}, @code{execute}, @code{backtab}
1851 @itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
1852 @itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}
1853 Miscellaneous function keys.
1855 @item @code{f1}, @code{f2}, @dots{} @code{f35}
1856 Numbered function keys (across the top of the keyboard).
1858 @item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
1859 @itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
1860 @itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
1861 Keypad keys (to the right of the regular keyboard), with names or punctuation.
1863 @item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
1864 Keypad keys with digits.
1866 @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
1870 These names are conventional, but some systems (especially when using
1871 X) may use different names. To make certain what symbol is used for a
1872 given function key on your terminal, type @kbd{C-h c} followed by that
1875 @xref{Init Rebinding}, for examples of binding function keys.
1878 Many keyboards have a numeric keypad on the right-hand side.
1879 The numeric keys in the keypad double up as cursor motion keys,
1880 toggled by a key labeled @samp{Num Lock}. By default, Emacs
1881 translates these keys to the corresponding keys on the main keyboard.
1882 For example, when @samp{Num Lock} is on, the key labeled @samp{8} on
1883 the numeric keypad produces @code{kp-8}, which is translated to
1884 @kbd{8}; when @samp{Num Lock} is off, the same key produces
1885 @code{kp-up}, which is translated to @key{UP}. If you rebind a key
1886 such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too.
1887 However, if you rebind a @samp{kp-} key directly, that won't affect
1888 its non-keypad equivalent. Note that the modified keys are not
1889 translated: for instance, if you hold down the @key{META} key while
1890 pressing the @samp{8} key on the numeric keypad, that generates
1893 Emacs provides a convenient method for binding the numeric keypad
1894 keys, using the variables @code{keypad-setup},
1895 @code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and
1896 @code{keypad-numlock-shifted-setup}. These can be found in the
1897 @samp{keyboard} customization group (@pxref{Easy Customization}). You
1898 can rebind the keys to perform other tasks, such as issuing numeric
1901 @node Named ASCII Chars
1902 @subsection Named @acronym{ASCII} Control Characters
1904 @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC}, and @key{DEL}
1905 started out as names for certain @acronym{ASCII} control characters,
1906 used so often that they have special keys of their own. For instance,
1907 @key{TAB} was another name for @kbd{C-i}. Later, users found it
1908 convenient to distinguish in Emacs between these keys and the corresponding
1909 control characters typed with the @key{Ctrl} key. Therefore, on most
1910 modern terminals, they are no longer the same: @key{TAB} is different
1913 Emacs can distinguish these two kinds of input if the keyboard does.
1914 It treats the special keys as function keys named @code{tab},
1915 @code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
1916 @code{delete}. These function keys translate automatically into the
1917 corresponding @acronym{ASCII} characters @emph{if} they have no
1918 bindings of their own. As a result, neither users nor Lisp programs
1919 need to pay attention to the distinction unless they care to.
1921 If you do not want to distinguish between (for example) @key{TAB} and
1922 @kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
1923 (octal code 011). If you do want to distinguish, make one binding for
1924 this @acronym{ASCII} character, and another for the function key @code{tab}.
1926 With an ordinary @acronym{ASCII} terminal, there is no way to distinguish
1927 between @key{TAB} and @kbd{C-i} (and likewise for other such pairs),
1928 because the terminal sends the same character in both cases.
1931 @subsection Rebinding Mouse Buttons
1932 @cindex mouse button events
1933 @cindex rebinding mouse buttons
1934 @cindex click events
1937 @cindex button-down events
1939 Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary
1940 mouse events in Emacs are @dfn{click} events; these happen when you
1941 press a button and release it without moving the mouse. You can also
1942 get @dfn{drag} events, when you move the mouse while holding the button
1943 down. Drag events happen when you finally let go of the button.
1945 The symbols for basic click events are @code{mouse-1} for the leftmost
1946 button, @code{mouse-2} for the next, and so on. Here is how you can
1947 redefine the second mouse button to split the current window:
1950 (global-set-key [mouse-2] 'split-window-below)
1953 The symbols for drag events are similar, but have the prefix
1954 @samp{drag-} before the word @samp{mouse}. For example, dragging the
1955 first button generates a @code{drag-mouse-1} event.
1957 You can also define bindings for events that occur when a mouse button
1958 is pressed down. These events start with @samp{down-} instead of
1959 @samp{drag-}. Such events are generated only if they have key bindings.
1960 When you get a button-down event, a corresponding click or drag event
1963 @cindex double clicks
1964 @cindex triple clicks
1965 If you wish, you can distinguish single, double, and triple clicks. A
1966 double click means clicking a mouse button twice in approximately the
1967 same place. The first click generates an ordinary click event. The
1968 second click, if it comes soon enough, generates a double-click event
1969 instead. The event type for a double-click event starts with
1970 @samp{double-}: for example, @code{double-mouse-3}.
1972 This means that you can give a special meaning to the second click at
1973 the same place, but it must act on the assumption that the ordinary
1974 single click definition has run when the first click was received.
1976 This constrains what you can do with double clicks, but user interface
1977 designers say that this constraint ought to be followed in any case. A
1978 double click should do something similar to the single click, only
1979 more so. The command for the double-click event should perform the
1980 extra work for the double click.
1982 If a double-click event has no binding, it changes to the
1983 corresponding single-click event. Thus, if you don't define a
1984 particular double click specially, it executes the single-click command
1987 Emacs also supports triple-click events whose names start with
1988 @samp{triple-}. Emacs does not distinguish quadruple clicks as event
1989 types; clicks beyond the third generate additional triple-click events.
1990 However, the full number of clicks is recorded in the event list, so
1991 if you know Emacs Lisp you can distinguish if you really want to
1992 (@pxref{Click Events,,, elisp, The Emacs Lisp Reference Manual}).
1993 We don't recommend distinct meanings for more than three clicks, but
1994 sometimes it is useful for subsequent clicks to cycle through the same
1995 set of three meanings, so that four clicks are equivalent to one
1996 click, five are equivalent to two, and six are equivalent to three.
1998 Emacs also records multiple presses in drag and button-down events.
1999 For example, when you press a button twice, then move the mouse while
2000 holding the button, Emacs gets a @samp{double-drag-} event. And at the
2001 moment when you press it down for the second time, Emacs gets a
2002 @samp{double-down-} event (which is ignored, like all button-down
2003 events, if it has no binding).
2005 @vindex double-click-time
2006 The variable @code{double-click-time} specifies how much time can
2007 elapse between clicks and still allow them to be grouped as a multiple
2008 click. Its value is in units of milliseconds. If the value is
2009 @code{nil}, double clicks are not detected at all. If the value is
2010 @code{t}, then there is no time limit. The default is 500.
2012 @vindex double-click-fuzz
2013 The variable @code{double-click-fuzz} specifies how much the mouse
2014 can move between clicks and still allow them to be grouped as a multiple
2015 click. Its value is in units of pixels on windowed displays and in
2016 units of 1/8 of a character cell on text-mode terminals; the default is
2019 The symbols for mouse events also indicate the status of the modifier
2020 keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
2021 @samp{s-}, @samp{A-}, and @samp{S-}. These always precede @samp{double-}
2022 or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.
2024 A frame includes areas that don't show text from the buffer, such as
2025 the mode line and the scroll bar. You can tell whether a mouse button
2026 comes from a special area of the screen by means of dummy prefix
2027 keys. For example, if you click the mouse in the mode line, you get
2028 the prefix key @code{mode-line} before the ordinary mouse-button symbol.
2029 Thus, here is how to define the command for clicking the first button in
2030 a mode line to run @code{scroll-up-command}:
2033 (global-set-key [mode-line mouse-1] 'scroll-up-command)
2036 Here is the complete list of these dummy prefix keys and their
2041 The mouse was in the mode line of a window.
2043 The mouse was in the vertical line separating side-by-side windows. (If
2044 you use scroll bars, they appear in place of these vertical lines.)
2045 @item vertical-scroll-bar
2046 The mouse was in a vertical scroll bar. (This is the only kind of
2047 scroll bar Emacs currently supports.)
2049 The mouse was in the menu bar.
2051 The mouse was in a header line.
2053 @item horizontal-scroll-bar
2054 The mouse was in a horizontal scroll bar. Horizontal scroll bars do
2055 horizontal scrolling, and people don't use them often.
2059 You can put more than one mouse button in a key sequence, but it isn't
2063 @subsection Disabling Commands
2064 @cindex disabled command
2066 Disabling a command means that invoking it interactively asks for
2067 confirmation from the user. The purpose of disabling a command is to
2068 prevent users from executing it by accident; we do this for commands
2069 that might be confusing to the uninitiated.
2071 Attempting to invoke a disabled command interactively in Emacs
2072 displays a window containing the command's name, its documentation,
2073 and some instructions on what to do immediately; then Emacs asks for
2074 input saying whether to execute the command as requested, enable it
2075 and execute it, or cancel. If you decide to enable the command, you
2076 must then answer another question---whether to do this permanently, or
2077 just for the current session. (Enabling permanently works by
2078 automatically editing your initialization file.) You can also type
2079 @kbd{!} to enable @emph{all} commands, for the current session only.
2081 The direct mechanism for disabling a command is to put a
2082 non-@code{nil} @code{disabled} property on the Lisp symbol for the
2083 command. Here is the Lisp program to do this:
2086 (put 'delete-region 'disabled t)
2089 If the value of the @code{disabled} property is a string, that string
2090 is included in the message displayed when the command is used:
2093 (put 'delete-region 'disabled
2094 "It's better to use `kill-region' instead.\n")
2097 @findex disable-command
2098 @findex enable-command
2099 You can make a command disabled either by editing the initialization
2100 file directly, or with the command @kbd{M-x disable-command}, which
2101 edits the initialization file for you. Likewise, @kbd{M-x
2102 enable-command} edits the initialization file to enable a command
2103 permanently. @xref{Init File}.
2105 If Emacs was invoked with the @option{-q} or @option{--no-init-file}
2106 options (@pxref{Initial Options}), it will not edit your
2107 initialization file. Doing so could lose information because Emacs
2108 has not read your initialization file.
2110 Whether a command is disabled is independent of what key is used to
2111 invoke it; disabling also applies if the command is invoked using
2112 @kbd{M-x}. However, disabling a command has no effect on calling it
2113 as a function from Lisp programs.
2116 @section The Emacs Initialization File
2119 @cindex ~/.emacs file
2120 @cindex Emacs initialization file
2121 @cindex startup (init file)
2123 When Emacs is started, it normally tries to load a Lisp program from
2124 an @dfn{initialization file}, or @dfn{init file} for short. This
2125 file, if it exists, specifies how to initialize Emacs for you. Emacs
2126 looks for your init file using the filenames @file{~/.emacs},
2127 @file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to
2128 use any one of these three names (@pxref{Find Init}). Here, @file{~/}
2129 stands for your home directory.
2131 You can use the command line switch @samp{-q} to prevent loading
2132 your init file, and @samp{-u} (or @samp{--user}) to specify a
2133 different user's init file (@pxref{Initial Options}).
2135 @cindex @file{default.el}, the default init file
2136 There can also be a @dfn{default init file}, which is the library
2137 named @file{default.el}, found via the standard search path for
2138 libraries. The Emacs distribution contains no such library; your site
2139 may create one for local customizations. If this library exists, it is
2140 loaded whenever you start Emacs (except when you specify @samp{-q}).
2141 But your init file, if any, is loaded first; if it sets
2142 @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
2145 @cindex site init file
2146 @cindex @file{site-start.el}, the site startup file
2147 Your site may also have a @dfn{site startup file}; this is named
2148 @file{site-start.el}, if it exists. Like @file{default.el}, Emacs
2149 finds this file via the standard search path for Lisp libraries.
2150 Emacs loads this library before it loads your init file. To inhibit
2151 loading of this library, use the option @samp{--no-site-file}.
2152 @xref{Initial Options}. We recommend against using
2153 @file{site-start.el} for changes that some users may not like. It is
2154 better to put them in @file{default.el}, so that users can more easily
2157 @cindex site-lisp directories
2158 You can place @file{default.el} and @file{site-start.el} in any of
2159 the directories which Emacs searches for Lisp libraries. The variable
2160 @code{load-path} (@pxref{Lisp Libraries}) specifies these directories.
2161 Many sites put these files in a subdirectory named @file{site-lisp} in
2162 the Emacs installation directory, such as
2163 @file{/usr/local/share/emacs/site-lisp}.
2165 Byte-compiling your init file is not recommended (@pxref{Byte
2166 Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference
2167 Manual}). It generally does not speed up startup very much, and often
2168 leads to problems when you forget to recompile the file. A better
2169 solution is to use the Emacs server to reduce the number of times you
2170 have to start Emacs (@pxref{Emacs Server}). If your init file defines
2171 many functions, consider moving them to a separate (byte-compiled)
2172 file that you load in your init file.
2174 If you are going to write actual Emacs Lisp programs that go beyond
2175 minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
2177 @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
2182 * Init Syntax:: Syntax of constants in Emacs Lisp.
2183 * Init Examples:: How to do some things with an init file.
2184 * Terminal Init:: Each terminal type can have an init file.
2185 * Find Init:: How Emacs finds the init file.
2186 * Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file.
2190 @subsection Init File Syntax
2192 The init file contains one or more Lisp expressions. Each of these
2193 consists of a function name followed by arguments, all surrounded by
2194 parentheses. For example, @code{(setq fill-column 60)} calls the
2195 function @code{setq} to set the variable @code{fill-column}
2196 (@pxref{Filling}) to 60.
2198 You can set any Lisp variable with @code{setq}, but with certain
2199 variables @code{setq} won't do what you probably want in the
2200 @file{.emacs} file. Some variables automatically become buffer-local
2201 when set with @code{setq}; what you want in @file{.emacs} is to set
2202 the default value, using @code{setq-default}. Some customizable minor
2203 mode variables do special things to enable the mode when you set them
2204 with Customize, but ordinary @code{setq} won't do that; to enable the
2205 mode in your @file{.emacs} file, call the minor mode command. The
2206 following section has examples of both of these methods.
2208 The second argument to @code{setq} is an expression for the new
2209 value of the variable. This can be a constant, a variable, or a
2210 function call expression. In @file{.emacs}, constants are used most
2211 of the time. They can be:
2215 Numbers are written in decimal, with an optional initial minus sign.
2218 @cindex Lisp string syntax
2219 @cindex string syntax
2220 Lisp string syntax is the same as C string syntax with a few extra
2221 features. Use a double-quote character to begin and end a string constant.
2223 In a string, you can include newlines and special characters literally.
2224 But often it is cleaner to use backslash sequences for them: @samp{\n}
2225 for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
2226 @samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
2227 escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
2228 @samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
2229 Backslash and double-quote are the only characters for which backslash
2230 sequences are mandatory.
2232 @samp{\C-} can be used as a prefix for a control character, as in
2233 @samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
2234 a Meta character, as in @samp{\M-a} for @kbd{@key{META}-A} or
2235 @samp{\M-\C-a} for @kbd{@key{Ctrl}-@key{META}-A}.
2237 @xref{Init Non-ASCII}, for information about including
2238 non-@acronym{ASCII} in your init file.
2241 @cindex Lisp character syntax
2242 @cindex character syntax
2243 Lisp character constant syntax consists of a @samp{?} followed by
2244 either a character or an escape sequence starting with @samp{\}.
2245 Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that
2246 strings and characters are not interchangeable in Lisp; some contexts
2247 require one and some contexts require the other.
2249 @xref{Init Non-ASCII}, for information about binding commands to
2250 keys which send non-@acronym{ASCII} characters.
2253 @code{t} stands for ``true''.
2256 @code{nil} stands for ``false''.
2258 @item Other Lisp objects:
2259 @cindex Lisp object syntax
2260 Write a single-quote (@code{'}) followed by the Lisp object you want.
2264 @subsection Init File Examples
2266 Here are some examples of doing certain commonly desired things with
2271 Add a directory to the variable @code{load-path}. You can then put
2272 Lisp libraries that are not included with Emacs in this directory, and
2273 load them with @kbd{M-x load-library}. @xref{Lisp Libraries}.
2276 (add-to-list 'load-path "/path/to/lisp/libraries")
2280 Make @key{TAB} in C mode just insert a tab if point is in the middle of a
2284 (setq c-tab-always-indent nil)
2287 Here we have a variable whose value is normally @code{t} for ``true''
2288 and the alternative is @code{nil} for ``false''.
2291 Make searches case sensitive by default (in all buffers that do not
2295 (setq-default case-fold-search nil)
2298 This sets the default value, which is effective in all buffers that do
2299 not have local values for the variable (@pxref{Locals}). Setting
2300 @code{case-fold-search} with @code{setq} affects only the current
2301 buffer's local value, which is probably not what you want to do in an
2305 @vindex user-mail-address@r{, in init file}
2306 Specify your own email address, if Emacs can't figure it out correctly.
2309 (setq user-mail-address "cheney@@torture.gov")
2312 Various Emacs packages, such as Message mode, consult
2313 @code{user-mail-address} when they need to know your email address.
2314 @xref{Mail Headers}.
2317 Make Text mode the default mode for new buffers.
2320 (setq-default major-mode 'text-mode)
2323 Note that @code{text-mode} is used because it is the command for
2324 entering Text mode. The single-quote before it makes the symbol a
2325 constant; otherwise, @code{text-mode} would be treated as a variable
2330 Set up defaults for the Latin-1 character set,
2331 which supports most of the languages of Western Europe.
2334 (set-language-environment "Latin-1")
2339 Turn off Line Number mode, a global minor mode.
2342 (line-number-mode 0)
2347 Turn on Auto Fill mode automatically in Text mode and related modes
2351 (add-hook 'text-mode-hook 'auto-fill-mode)
2355 Load the installed Lisp library named @file{foo} (actually a file
2356 @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
2362 When the argument to @code{load} is a relative file name, not starting
2363 with @samp{/} or @samp{~}, @code{load} searches the directories in
2364 @code{load-path} (@pxref{Lisp Libraries}).
2367 Load the compiled Lisp file @file{foo.elc} from your home directory.
2373 Here a full file name is used, so no searching is done.
2376 @cindex loading Lisp libraries automatically
2377 @cindex autoload Lisp libraries
2378 Tell Emacs to find the definition for the function @code{myfunction}
2379 by loading a Lisp library named @file{mypackage} (i.e., a file
2380 @file{mypackage.elc} or @file{mypackage.el}):
2383 (autoload 'myfunction "mypackage" "Do what I say." t)
2387 Here the string @code{"Do what I say."} is the function's
2388 documentation string. You specify it in the @code{autoload}
2389 definition so it will be available for help commands even when the
2390 package is not loaded. The last argument, @code{t}, indicates that
2391 this function is interactive; that is, it can be invoked interactively
2392 by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key.
2393 If the function is not interactive, omit the @code{t} or use
2397 Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
2398 (@pxref{Init Rebinding}).
2401 (global-set-key "\C-xl" 'make-symbolic-link)
2407 (define-key global-map "\C-xl" 'make-symbolic-link)
2410 Note once again the single-quote used to refer to the symbol
2411 @code{make-symbolic-link} instead of its value as a variable.
2414 Do the same thing for Lisp mode only.
2417 (define-key lisp-mode-map "\C-xl" 'make-symbolic-link)
2421 Redefine all keys which now run @code{next-line} in Fundamental mode
2422 so that they run @code{forward-line} instead.
2424 @findex substitute-key-definition
2426 (substitute-key-definition 'next-line 'forward-line
2431 Make @kbd{C-x C-v} undefined.
2434 (global-unset-key "\C-x\C-v")
2437 One reason to undefine a key is so that you can make it a prefix.
2438 Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
2439 prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
2443 Make @samp{$} have the syntax of punctuation in Text mode.
2444 Note the use of a character constant for @samp{$}.
2447 (modify-syntax-entry ?\$ "." text-mode-syntax-table)
2451 Enable the use of the command @code{narrow-to-region} without confirmation.
2454 (put 'narrow-to-region 'disabled nil)
2458 Adjusting the configuration to various platforms and Emacs versions.
2460 Users typically want Emacs to behave the same on all systems, so the
2461 same init file is right for all platforms. However, sometimes it
2462 happens that a function you use for customizing Emacs is not available
2463 on some platforms or in older Emacs versions. To deal with that
2464 situation, put the customization inside a conditional that tests whether
2465 the function or facility is available, like this:
2468 (if (fboundp 'blink-cursor-mode)
2469 (blink-cursor-mode 0))
2471 (if (boundp 'coding-category-utf-8)
2472 (set-coding-priority '(coding-category-utf-8)))
2476 You can also simply disregard the errors that occur if the
2477 function is not defined.
2480 (ignore-errors (set-face-background 'region "grey75"))
2483 A @code{setq} on a variable which does not exist is generally
2484 harmless, so those do not need a conditional.
2488 @subsection Terminal-specific Initialization
2490 @vindex term-file-aliases
2491 Each terminal type can have a Lisp library to be loaded into Emacs when
2492 it is run on that type of terminal. For a terminal type named
2493 @var{termtype}, the library is called @file{term/@var{termtype}}.
2494 (If there is an entry of the form @code{(@var{termtype} . @var{alias})}
2495 in the @code{term-file-aliases} association list, Emacs uses
2496 @var{alias} in place of @var{termtype}.) The library is
2497 found by searching the directories @code{load-path} as usual and trying the
2498 suffixes @samp{.elc} and @samp{.el}. Normally it appears in the
2499 subdirectory @file{term} of the directory where most Emacs libraries are
2502 The usual purpose of the terminal-specific library is to map the
2503 escape sequences used by the terminal's function keys onto more
2504 meaningful names, using @code{input-decode-map} (or
2505 @code{function-key-map} before it). See the file
2506 @file{term/lk201.el} for an example of how this is done. Many function
2507 keys are mapped automatically according to the information in the
2508 Termcap data base; the terminal-specific library needs to map only the
2509 function keys that Termcap does not specify.
2511 When the terminal type contains a hyphen, only the part of the name
2512 before the first hyphen is significant in choosing the library name.
2513 Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
2514 the library @file{term/aaa}. The code in the library can use
2515 @code{(getenv "TERM")} to find the full terminal type name.
2517 @vindex term-file-prefix
2518 The library's name is constructed by concatenating the value of the
2519 variable @code{term-file-prefix} and the terminal type. Your @file{.emacs}
2520 file can prevent the loading of the terminal-specific library by setting
2521 @code{term-file-prefix} to @code{nil}.
2523 @vindex tty-setup-hook
2524 Emacs runs the hook @code{tty-setup-hook} at the end of
2525 initialization, after both your @file{.emacs} file and any
2526 terminal-specific library have been read in. Add hook functions to this
2527 hook if you wish to override part of any of the terminal-specific
2528 libraries and to define initializations for terminals that do not have a
2529 library. @xref{Hooks}.
2532 @subsection How Emacs Finds Your Init File
2534 Normally Emacs uses the environment variable @env{HOME}
2535 (@pxref{General Variables, HOME}) to find @file{.emacs}; that's what
2536 @samp{~} means in a file name. If @file{.emacs} is not found inside
2537 @file{~/} (nor @file{.emacs.el}), Emacs looks for
2538 @file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be
2541 However, if you run Emacs from a shell started by @code{su}, Emacs
2542 tries to find your own @file{.emacs}, not that of the user you are
2543 currently pretending to be. The idea is that you should get your own
2544 editor customizations even if you are running as the super user.
2546 More precisely, Emacs first determines which user's init file to use.
2547 It gets your user name from the environment variables @env{LOGNAME} and
2548 @env{USER}; if neither of those exists, it uses effective user-ID@.
2549 If that user name matches the real user-ID, then Emacs uses @env{HOME};
2550 otherwise, it looks up the home directory corresponding to that user
2551 name in the system's data base of users.
2552 @c LocalWords: backtab
2554 @node Init Non-ASCII
2555 @subsection Non-@acronym{ASCII} Characters in Init Files
2556 @cindex international characters in @file{.emacs}
2557 @cindex non-@acronym{ASCII} characters in @file{.emacs}
2558 @cindex non-@acronym{ASCII} keys, binding
2559 @cindex rebinding non-@acronym{ASCII} keys
2561 Language and coding systems may cause problems if your init file
2562 contains non-@acronym{ASCII} characters, such as accented letters, in
2563 strings or key bindings.
2565 If you want to use non-@acronym{ASCII} characters in your init file,
2566 you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on
2567 the first line of the init file, and specify a coding system that
2568 supports the character(s) in question. @xref{Recognize Coding}. This
2569 is because the defaults for decoding non-@acronym{ASCII} text might
2570 not yet be set up by the time Emacs reads those parts of your init
2571 file which use such strings, possibly leading Emacs to decode those
2572 strings incorrectly. You should then avoid adding Emacs Lisp code
2573 that modifies the coding system in other ways, such as calls to
2574 @code{set-language-environment}.
2576 To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init
2577 Rebinding}). The string syntax cannot be used, since the
2578 non-@acronym{ASCII} characters will be interpreted as meta keys. For
2582 (global-set-key [?@var{char}] 'some-function)
2586 Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}.