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