Mercurial > emacs
changeset 84230:c6c2d1e7f3e4
Move here from ../../man
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:44:54 +0000 |
| parents | bb21f14d6ad2 |
| children | 0a6eccff1e0d |
| files | doc/emacs/custom.texi |
| diffstat | 1 files changed, 2515 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/emacs/custom.texi Thu Sep 06 04:44:54 2007 +0000 @@ -0,0 +1,2515 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Customization, Quitting, Amusements, Top +@chapter Customization +@cindex customization + + This chapter talks about various topics relevant to adapting the +behavior of Emacs in ways we have anticipated. +@iftex +See @cite{The Emacs Lisp Reference Manual} +@end iftex +@ifnottex +@xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp +Reference Manual}, +@end ifnottex +for how to make more far-reaching and open-ended changes. @xref{X +Resources}, for information on using X resources to customize Emacs. + + Customization that you do within Emacs normally affects only the +particular Emacs session that you do it in---it does not persist +between sessions unless you save the customization in a file such as +your init file (@file{.emacs}) that will affect future sessions. +(@xref{Init File}.) When you tell the customization buffer to save +customizations for future sessions, this actually works by editing +@file{.emacs} for you. + + Another means of customization is the keyboard macro, which is a +sequence of keystrokes to be replayed with a single command. +@xref{Keyboard Macros}, for full instruction how to record, manage, and +replay sequences of keys. + +@menu +* Minor Modes:: Each minor mode is one feature you can turn on + independently of any others. +* Easy Customization:: Convenient way to browse and change settings. +* Variables:: Many Emacs commands examine Emacs variables + to decide what to do; by setting variables, + you can control their functioning. +* Key Bindings:: The keymaps say what command each key runs. + By changing them, you can "redefine keys". +* Syntax:: The syntax table controls how words and + expressions are parsed. +* Init File:: How to write common customizations in the + @file{.emacs} file. +@end menu + +@node Minor Modes +@section Minor Modes +@cindex minor modes +@cindex mode, minor + + Minor modes are optional features which you can turn on or off. For +example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines +between words as you type. All the minor modes are independent of each +other and of the selected major mode. Most minor modes say in the mode +line when they are enabled; for example, @samp{Fill} in the mode line means +that Auto Fill mode is enabled. + + You should append @code{-mode} to the name of a minor mode to +produce the name of the command that turns the mode on or off. Thus, +the command to enable or disable Auto Fill mode is called +@code{auto-fill-mode}. These commands are usually invoked with +@kbd{M-x}, but you can bind keys to them if you wish. + + With no argument, the minor mode function turns the mode on if it +was off, and off if it was on. This is known as @dfn{toggling}. A +positive argument always turns the mode on, and an explicit zero +argument or a negative argument always turns it off. + + Some minor modes are global: while enabled, they affect everything +you do in the Emacs session, in all buffers. Other minor modes are +buffer-local; they apply only to the current buffer, so you can enable +the mode in certain buffers and not others. + + For most minor modes, the command name is also the name of a +variable. The variable's value is non-@code{nil} if the mode is +enabled and @code{nil} if it is disabled. Some minor-mode commands +work by just setting the variable. For example, the command +@code{abbrev-mode} works by setting the value of @code{abbrev-mode} as +a variable; it is this variable that directly turns Abbrev mode on and +off. You can directly set the variable's value instead of calling the +mode function. For other minor modes, you need to either set the +variable through the Customize interface or call the mode function to +correctly enable or disable the mode. To check which of these two +possibilities applies to a given minor mode, use @kbd{C-h v} to ask +for documentation on the variable name. + + For minor mode commands that work by just setting the minor mode +variable, that variable provides a good way for Lisp programs to turn +minor modes on and off; it is also useful in a file's local variables +list (@pxref{File Variables}). But please think twice before setting +minor modes with a local variables list, because most minor modes are +a matter of user preference---other users editing the same file might +not want the same minor modes you prefer. + + The most useful buffer-local minor modes include Abbrev mode, Auto +Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, Outline minor +mode, Overwrite mode, and Binary Overwrite mode. + + Abbrev mode allows you to define abbreviations that automatically expand +as you type them. For example, @samp{amd} might expand to @samp{abbrev +mode}. @xref{Abbrevs}, for full information. + + Auto Fill mode allows you to enter filled text without breaking lines +explicitly. Emacs inserts newlines as necessary to prevent lines from +becoming too long. @xref{Filling}. + + Auto Save mode saves the buffer contents periodically to reduce the +amount of work you can lose in case of a crash. @xref{Auto Save}. + + Enriched mode enables editing and saving of formatted text. +@xref{Formatted Text}. + + Flyspell mode automatically highlights misspelled words. +@xref{Spelling}. + + Font-Lock mode automatically highlights certain textual units found +in programs, such as comments, strings, and function names being +defined. This requires a display that can show multiple fonts or +colors. @xref{Faces}. + +@ignore + ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"}, +@samp{^}, @samp{/} and @samp{~} combine with the following letter, to +produce an accented letter in the ISO Latin-1 character set. The +newer and more general feature of input methods more or less +supersedes ISO Accents mode. @xref{Unibyte Mode}. +@end ignore + + Outline minor mode provides the same facilities as the major mode +called Outline mode; but since it is a minor mode instead, you can +combine it with any major mode. @xref{Outline Mode}. + +@cindex Overwrite mode +@cindex mode, Overwrite + Overwrite mode causes ordinary printing characters to replace existing +text instead of shoving it to the right. For example, if point is in +front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a +@kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR} +as usual. In Overwrite mode, the command @kbd{C-q} inserts the next +character whatever it may be, even if it is a digit---this gives you a +way to insert a character instead of replacing an existing character. + +@findex overwrite-mode +@kindex INSERT + The command @code{overwrite-mode} is an exception to the rule that +commands which toggle minor modes are normally not bound to keys: it is +bound to the @key{INSERT} function key. This is because many other +programs bind @key{INSERT} to similar functions. + +@findex binary-overwrite-mode + Binary Overwrite mode is a variant of Overwrite mode for editing +binary files; it treats newlines and tabs like other characters, so that +they overwrite other characters and can be overwritten by them. +In Binary Overwrite mode, digits after @kbd{C-q} specify an +octal character code, as usual. + + Here are some useful minor modes that normally apply to all buffers +at once. Since Line Number mode and Transient Mark mode can be +enabled or disabled just by setting the value of the minor mode +variable, you @emph{can} set them differently for particular buffers, +by explicitly making the corresponding variable local in those +buffers. @xref{Locals}. + + Icomplete mode displays an indication of available completions when +you are in the minibuffer and completion is active. @xref{Completion +Options}. + + Line Number mode enables continuous display in the mode line of the +line number of point, and Column Number mode enables display of the +column number. @xref{Mode Line}. + + Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}). +Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of +these modes are enabled by default when you use the X Window System. + + In Transient Mark mode, every change in the buffer contents +``deactivates'' the mark, so that commands that operate on the region +will get an error. This means you must either set the mark, or +explicitly ``reactivate'' it, before each command that uses the region. +The advantage of Transient Mark mode is that Emacs can display the +region highlighted. @xref{Mark}. + +@node Easy Customization +@section Easy Customization Interface + +@cindex settings + Emacs has many @dfn{settings} which have values that you can specify +in order to customize various commands. Many are documented in this +manual. Most settings are @dfn{user options}---that is to say, Lisp +variables (@pxref{Variables})---so their names appear in the Variable +Index (@pxref{Variable Index}). The other settings are faces and +their attributes (@pxref{Faces}). + +@findex customize +@cindex customization buffer + You can browse interactively through settings and change them using +@kbd{M-x customize}. This command creates a @dfn{customization +buffer}, which offers commands to navigate through a logically +organized structure of the Emacs settings; you can also use it to edit +and set their values, and to save settings permanently in your +@file{~/.emacs} file (@pxref{Init File}). + + The appearance of the example buffers in this section is typically +different under a graphical display, since faces are then used to indicate +buttons, links and editable fields. + +@menu +* Groups: Customization Groups. How settings are classified in a structure. +* Browsing: Browsing Custom. Browsing and searching for settings. +* Changing a Variable:: How to edit an option's value and set the option. +* Saving Customizations:: Specifying the file for saving customizations. +* Face Customization:: How to edit the attributes of a face. +* Specific Customization:: Making a customization buffer for specific + variables, faces, or groups. +* Custom Themes:: How to define collections of customized options + that can be loaded and unloaded together. +@end menu + +@node Customization Groups +@subsection Customization Groups +@cindex customization groups + + For customization purposes, settings are organized into @dfn{groups} +to help you find them. Groups are collected into bigger groups, all +the way up to a master group called @code{Emacs}. + + @kbd{M-x customize} creates a customization buffer that shows the +top-level @code{Emacs} group and the second-level groups immediately +under it. It looks like this, in part: + +@c we want the buffer example to all be on one page, but unfortunately +@c that's quite a bit of text, so force all space to the bottom. +@page +@smallexample +@group +/- Emacs group: ---------------------------------------------------\ + [State]: visible group members are all at standard values. + Customization of the One True Editor. + See also [Manual]. + +Editing group: [Go to Group] +Basic text editing facilities. + +External group: [Go to Group] +Interfacing to external utilities. + +@var{more second-level groups} + +\- Emacs group end ------------------------------------------------/ +@end group +@end smallexample + +@noindent +This says that the buffer displays the contents of the @code{Emacs} +group. The other groups are listed because they are its contents. But +they are listed differently, without indentation and dashes, because +@emph{their} contents are not included. Each group has a single-line +documentation string; the @code{Emacs} group also has a @samp{[State]} +line. + +@cindex editable fields (customization buffer) +@cindex buttons (customization buffer) +@cindex links (customization buffer) + Most of the text in the customization buffer is read-only, but it +typically includes some @dfn{editable fields} that you can edit. +There are also @dfn{buttons} and @dfn{links}, which do something when +you @dfn{invoke} them. To invoke a button or a link, either click on +it with @kbd{Mouse-1}, or move point to it and type @key{RET}. + + For example, the phrase @samp{[State]} that appears in +a second-level group is a button. It operates on the same +customization buffer. The phrase @samp{[Go to Group]} is a kind +of hypertext link to another group. Invoking it creates a new +customization buffer, which shows that group and its contents. + + The @code{Emacs} group includes a few settings, but mainly it +contains other groups, which contain more groups, which contain the +settings. By browsing the hierarchy of groups, you will eventually +find the feature you are interested in customizing. Then you can use +the customization buffer to set that feature's settings. You can also +go straight to a particular group by name, using the command @kbd{M-x +customize-group}. + +@node Browsing Custom +@subsection Browsing and Searching for Options and Faces +@findex customize-browse + + @kbd{M-x customize-browse} is another way to browse the available +settings. This command creates a special customization buffer which +shows only the names of groups and settings, and puts them in a +structure. + + In this buffer, you can show the contents of a group by invoking the +@samp{[+]} button. When the group contents are visible, this button +changes to @samp{[-]}; invoking that hides the group contents again. + + Each group or setting in this buffer has a link which says +@samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking this link +creates an ordinary customization buffer showing just that group and +its contents, just that user option, or just that face. This is the +way to change settings that you find with @kbd{M-x customize-browse}. + + If you can guess part of the name of the settings you are interested +in, @kbd{M-x customize-apropos} is another way to search for settings. +However, unlike @code{customize} and @code{customize-browse}, +@code{customize-apropos} can only find groups and settings that are +loaded in the current Emacs session. @xref{Specific Customization,, +Customizing Specific Items}. + +@node Changing a Variable +@subsection Changing a Variable + + Here is an example of what a variable (a user option) looks like in +the customization buffer: + +@smallexample +Kill Ring Max: [Hide Value] 60 + [State]: STANDARD. +Maximum length of kill ring before oldest elements are thrown away. +@end smallexample + + The text following @samp{[Hide Value]}, @samp{60} in this case, indicates +the current value of the variable. If you see @samp{[Show Value]} instead of +@samp{[Hide Value]}, it means that the value is hidden; the customization +buffer initially hides values that take up several lines. Invoke +@samp{[Show Value]} to show the value. + + The line after the variable name indicates the @dfn{customization +state} of the variable: in the example above, it says you have not +changed the option yet. The @samp{[State]} button at the beginning of +this line gives you a menu of various operations for customizing the +variable. + + The line after the @samp{[State]} line displays the beginning of the +variable's documentation string. If there are more lines of +documentation, this line ends with a @samp{[More]} button; invoke that +to show the full documentation string. + + To enter a new value for @samp{Kill Ring Max}, move point to the +value and edit it textually. For example, you can type @kbd{M-d}, +then insert another number. As you begin to alter the text, you will +see the @samp{[State]} line change to say that you have edited the +value: + +@smallexample +[State]: EDITED, shown value does not take effect until you set or @r{@dots{}} + save it. +@end smallexample + +@cindex user options, how to set +@cindex variables, how to set +@cindex settings, how to set + Editing the value does not actually set the variable. To do that, +you must @dfn{set} the variable. To do this, invoke the +@samp{[State]} button and choose @samp{Set for Current Session}. + + The state of the variable changes visibly when you set it: + +@smallexample +[State]: SET for current session only. +@end smallexample + + You don't have to worry about specifying a value that is not valid; +the @samp{Set for Current Session} operation checks for validity and +will not install an unacceptable value. + +@kindex M-TAB @r{(customization buffer)} +@findex widget-complete + While editing a field that is a file name, directory name, +command name, or anything else for which completion is defined, you +can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. +(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) + + Some variables have a small fixed set of possible legitimate values. +These variables don't let you edit the value textually. Instead, a +@samp{[Value Menu]} button appears before the value; invoke this +button to change the value. For a boolean ``on or off'' value, the +button says @samp{[Toggle]}, and it changes to the other value. +@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the +changes take real effect when you use the @samp{Set for Current +Session} operation. + + Some variables have values with complex structure. For example, the +value of @code{file-coding-system-alist} is an association list. Here +is how it appears in the customization buffer: + +@smallexample +File Coding System Alist: [Hide Value] +[INS] [DEL] File regexp: \.elc\' + Choice: [Value Menu] Encoding/decoding pair: + Decoding: emacs-mule + Encoding: emacs-mule +[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' + Choice: [Value Menu] Encoding/decoding pair: + Decoding: raw-text + Encoding: raw-text-unix +[INS] [DEL] File regexp: \.tar\' + Choice: [Value Menu] Encoding/decoding pair: + Decoding: no-conversion + Encoding: no-conversion +[INS] [DEL] File regexp: + Choice: [Value Menu] Encoding/decoding pair: + Decoding: undecided + Encoding: nil +[INS] + [State]: STANDARD. +Alist to decide a coding system to use for a file I/O @r{@dots{}} + operation. [Hide Rest] +The format is ((PATTERN . VAL) ...), +where PATTERN is a regular expression matching a file name, +@r{[@dots{}more lines of documentation@dots{}]} +@end smallexample + +@noindent +Each association in the list appears on four lines, with several +editable fields and/or buttons. You can edit the regexps and coding +systems using ordinary editing commands. You can also invoke +@samp{[Value Menu]} to switch to a different kind of value---for +instance, to specify a function instead of a pair of coding systems. + +To delete an association from the list, invoke the @samp{[DEL]} button +for that item. To add an association, invoke @samp{[INS]} at the +position where you want to add it. There is an @samp{[INS]} button +between each pair of associations, another at the beginning and another +at the end, so you can add a new association at any position in the +list. + +@kindex TAB @r{(customization buffer)} +@kindex S-TAB @r{(customization buffer)} +@findex widget-forward +@findex widget-backward + Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful +for moving through the customization buffer. @key{TAB} +(@code{widget-forward}) moves forward to the next button or editable +field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to +the previous button or editable field. + + Typing @key{RET} on an editable field also moves forward, just like +@key{TAB}. We set it up this way because people often type @key{RET} +when they are finished editing a field. To insert a newline within an +editable field, use @kbd{C-o} or @kbd{C-q C-j}. + +@cindex saving a setting +@cindex settings, how to save + Setting the variable changes its value in the current Emacs session; +@dfn{saving} the value changes it for future sessions as well. To +save the variable, invoke @samp{[State]} and select the @samp{Save for +Future Sessions} operation. This works by writing code so as to set +the variable again, each time you start Emacs (@pxref{Saving +Customizations}). + + You can also restore the variable to its standard value by invoking +@samp{[State]} and selecting the @samp{Erase Customization} operation. +There are actually four reset operations: + +@table @samp +@item Undo Edits +If you have made some modifications and not yet set the variable, +this restores the text in the customization buffer to match +the actual value. + +@item Reset to Saved +This restores the value of the variable to the last saved value, +and updates the text accordingly. + +@item Erase Customization +This sets the variable to its standard value, and updates the text +accordingly. This also eliminates any saved value for the variable, +so that you will get the standard value in future Emacs sessions. + +@item Set to Backup Value +This sets the variable to a previous value that was set in the +customization buffer in this session. If you customize a variable +and then reset it, which discards the customized value, +you can get the discarded value back again with this operation. +@end table + +@cindex comments on customized settings + Sometimes it is useful to record a comment about a specific +customization. Use the @samp{Add Comment} item from the +@samp{[State]} menu to create a field for entering the comment. The +comment you enter will be saved, and displayed again if you again view +the same variable in a customization buffer, even in another session. + + The state of a group indicates whether anything in that group has been +edited, set or saved. + + Near the top of the customization buffer there are two lines of buttons: + +@smallexample + [Set for Current Session] [Save for Future Sessions] + [Undo Edits] [Reset to Saved] [Erase Customization] [Finish] +@end smallexample + +@vindex custom-buffer-done-function +@noindent +Invoking @samp{[Finish]} either buries or kills this customization +buffer according to the setting of the option +@code{custom-buffer-done-kill}; the default is to bury the buffer. +Each of the other buttons performs an operation---set, save or +reset---on each of the settings in the buffer that could meaningfully +be set, saved or reset. They do not operate on settings whose values +are hidden, nor on subgroups which are hidden or not visible in the buffer. + +@node Saving Customizations +@subsection Saving Customizations + + Saving customizations from the customization buffer works by writing +code that future sessions will read, code to set up those +customizations again. + +@vindex custom-file + Normally this saves customizations in your init file, +@file{~/.emacs}. If you wish, you can save customizations in another +file instead. To make this work, your @file{~/.emacs} should set +@code{custom-file} to the name of that file. Then you should load the +file by calling @code{load}. For example: + +@example +(setq custom-file "~/.emacs-custom.el") +(load custom-file) +@end example + + You can use @code{custom-file} to specify different customization +files for different Emacs versions, like this: + +@example +(cond ((< emacs-major-version 21) + ;; @r{Emacs 20 customization.} + (setq custom-file "~/.custom-20.el")) + ((and (= emacs-major-version 21) (< emacs-minor-version 4)) + ;; @r{Emacs 21 customization, before version 21.4.} + (setq custom-file "~/.custom-21.el")) + ((< emacs-major-version 22) + ;; @r{Emacs version 21.4 or later.} + (setq custom-file "~/.custom-21.4.el")) + (t + ;; @r{Emacs version 22.1 or later.} + (setq custom-file "~/.custom-22.el"))) + +(load custom-file) +@end example + + If Emacs was invoked with the @option{-q} or @option{--no-init-file} +options (@pxref{Initial Options}), it will not let you save your +customizations in your @file{~/.emacs} init file. This is because +saving customizations from such a session would wipe out all the other +customizations you might have on your init file. + +@node Face Customization +@subsection Customizing Faces +@cindex customizing faces +@cindex bold font +@cindex italic font +@cindex fonts and faces + + In addition to variables, some customization groups also include +faces. When you show the contents of a group, both the variables and +the faces in the group appear in the customization buffer. Here is an +example of how a face looks: + +@smallexample +Custom Changed Face:(sample) [Hide Face] + [State]: STANDARD. +Face used when the customize item has been changed. +Parent groups: [Custom Magic Faces] +Attributes: [ ] Font Family: * + [ ] Width: * + [ ] Height: * + [ ] Weight: * + [ ] Slant: * + [ ] Underline: * + [ ] Overline: * + [ ] Strike-through: * + [ ] Box around text: * + [ ] Inverse-video: * + [X] Foreground: white (sample) + [X] Background: blue (sample) + [ ] Stipple: * + [ ] Inherit: * +@end smallexample + + Each face attribute has its own line. The @samp{[@var{x}]} button +before the attribute name indicates whether the attribute is +@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} +means that it's disabled. You can enable or disable the attribute by +clicking that button. When the attribute is enabled, you can change +the attribute value in the usual ways. + + For the colors, you can specify a color name (use @kbd{M-x +list-colors-display} for a list of them) or a hexadecimal color +specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. +(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is +green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a +black-and-white display, the colors you can use for the background are +@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and +@samp{gray3}. Emacs supports these shades of gray by using background +stipple patterns instead of a color. + + Setting, saving and resetting a face work like the same operations for +variables (@pxref{Changing a Variable}). + + A face can specify different appearances for different types of +display. For example, a face can make text red on a color display, but +use a bold font on a monochrome display. To specify multiple +appearances for a face, select @samp{For All Kinds of Displays} in the +menu you get from invoking @samp{[State]}. + +@findex modify-face + Another more basic way to set the attributes of a specific face is +with @kbd{M-x modify-face}. This command reads the name of a face, then +reads the attributes one by one. For the color and stipple attributes, +the attribute's current value is the default---type just @key{RET} if +you don't want to change that attribute. Type @samp{none} if you want +to clear out the attribute. + +@node Specific Customization +@subsection Customizing Specific Items + + Instead of finding the setting you want to change by navigating the +structure of groups, here are other ways to specify the settings that +you want to customize. + +@table @kbd +@item M-x customize-option @key{RET} @var{option} @key{RET} +Set up a customization buffer with just one user option variable, +@var{option}. +@item M-x customize-face @key{RET} @var{face} @key{RET} +Set up a customization buffer with just one face, @var{face}. +@item M-x customize-group @key{RET} @var{group} @key{RET} +Set up a customization buffer with just one group, @var{group}. +@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} +Set up a customization buffer with all the settings and groups that +match @var{regexp}. +@item M-x customize-changed @key{RET} @var{version} @key{RET} +Set up a customization buffer with all the settings and groups +whose meaning has changed since Emacs version @var{version}. +@item M-x customize-saved +Set up a customization buffer containing all settings that you +have saved with customization buffers. +@item M-x customize-unsaved +Set up a customization buffer containing all settings that you have +set but not saved. +@end table + +@findex customize-option + If you want to alter a particular user option with the customization +buffer, and you know its name, you can use the command @kbd{M-x +customize-option} and specify the user option (variable) name. This +sets up the customization buffer with just one user option---the one +that you asked for. Editing, setting and saving the value work as +described above, but only for the specified user option. Minibuffer +completion is handy if you only know part of the name. However, this +command can only see options that have been loaded in the current +Emacs session. + +@findex customize-face + Likewise, you can modify a specific face, chosen by name, using +@kbd{M-x customize-face}. By default it operates on the face used +on the character after point. + +@findex customize-group + You can also set up the customization buffer with a specific group, +using @kbd{M-x customize-group}. The immediate contents of the chosen +group, including settings (user options and faces), and other groups, +all appear as well (even if not already loaded). However, the +subgroups' own contents are not included. + +@findex customize-apropos + For a more general way of controlling what to customize, you can use +@kbd{M-x customize-apropos}. You specify a regular expression as +argument; then all @emph{loaded} settings and groups whose names match +this regular expression are set up in the customization buffer. If +you specify an empty regular expression, this includes @emph{all} +loaded groups and settings---which takes a long time to set up. + +@findex customize-changed + When you upgrade to a new Emacs version, you might want to consider +customizing new settings, and settings whose meanings or default +values have changed. To do this, use @kbd{M-x customize-changed} and +specify a previous Emacs version number using the minibuffer. It +creates a customization buffer which shows all the settings and groups +whose definitions have been changed since the specified version, +loading them if necessary. + +@findex customize-saved +@findex customize-unsaved + If you change settings and then decide the change was a mistake, you +can use two special commands to revisit your previous changes. Use +@kbd{M-x customize-saved} to look at the settings that you have saved. +Use @kbd{M-x customize-unsaved} to look at the settings that you +have set but not saved. + +@node Custom Themes +@subsection Customization Themes +@cindex custom themes + + @dfn{Custom themes} are collections of settings that can be enabled +or disabled as a unit. You can use Custom themes to switch quickly +and easily between various collections of settings, and to transfer +such collections from one computer to another. + +@findex customize-create-theme + To define a Custom theme, use @kbd{M-x customize-create-theme}, +which brings up a buffer named @samp{*New Custom Theme*}. At the top +of the buffer is an editable field where you can specify the name of +the theme. Click on the button labelled @samp{Insert Variable} to add +a variable to the theme, and click on @samp{Insert Face} to add a +face. You can edit these values in the @samp{*New Custom Theme*} +buffer like in an ordinary Customize buffer. To remove an option from +the theme, click on its @samp{State} button and select @samp{Delete}. + +@vindex custom-theme-directory + After adding the desired options, click on @samp{Save Theme} to save +the Custom theme. This writes the theme definition to a file +@file{@var{foo}-theme.el} (where @var{foo} is the theme name you +supplied), in the directory @file{~/.emacs.d/}. You can specify the +directory by setting @code{custom-theme-directory}. + + You can view and edit the settings of a previously-defined theme by +clicking on @samp{Visit Theme} and specifying the theme name. You can +also import the variables and faces that you have set using Customize +by visiting the ``special'' theme named @samp{user}. This theme, which +records all the options that you set in the ordinary customization +buffer, is always enabled, and always takes precedence over all other +enabled Custom themes. Additionally, the @samp{user} theme is +recorded with code in your @file{.emacs} file, rather than a +@file{user-theme.el} file. + +@vindex custom-enabled-themes + Once you have defined a Custom theme, you can use it by customizing +the variable @code{custom-enabled-themes}. This is a list of Custom +themes that are @dfn{enabled}, or put into effect. If you set +@code{custom-enabled-themes} using the Customize interface, the theme +definitions are automatically loaded from the theme files, if they +aren't already. If you save the value of @code{custom-enabled-themes} +for future Emacs sessions, those Custom themes will be enabled +whenever Emacs is started up. + + If two enabled themes specify different values for an option, the +theme occurring earlier in @code{custom-enabled-themes} takes effect. + +@findex load-theme +@findex enable-theme +@findex disable-theme + You can temporarily enable a Custom theme with @kbd{M-x +enable-theme}. This prompts for a theme name in the minibuffer, loads +the theme from the theme file if necessary, and enables the theme. +You can @dfn{disable} any enabled theme with the command @kbd{M-x +disable-theme}; this returns the options specified in the theme to +their original values. To re-enable the theme, type @kbd{M-x +enable-theme} again. If a theme file is changed during your Emacs +session, you can reload it by typing @kbd{M-x load-theme}. (This also +enables the theme.) + +@node Variables +@section Variables +@cindex variable +@cindex option, user +@cindex user option + + A @dfn{variable} is a Lisp symbol which has a value. The symbol's +name is also called the name of the variable. A variable name can +contain any characters that can appear in a file, but conventionally +variable names consist of words separated by hyphens. A variable can +have a documentation string which describes what kind of value it should +have and how the value will be used. + + Emacs Lisp allows any variable (with a few exceptions) to have any +kind of value, but most variables that Emacs uses expect a value of a +certain type. Often the value should always be a string, or should +always be a number. Sometimes we say that a certain feature is turned +on if a variable is ``non-@code{nil},'' meaning that if the variable's +value is @code{nil}, the feature is off, but the feature is on for +@emph{any} other value. The conventional value to use to turn on the +feature---since you have to pick one particular value when you set the +variable---is @code{t}. + + Emacs uses many Lisp variables for internal record keeping, but the +most interesting variables for a non-programmer user are those meant +for users to change---these are called @dfn{user options}. + + Each user option that you can set with the customization buffer is +in fact a Lisp variable. Emacs does not (usually) change the values +of these variables on its own; instead, you set the values in order to +control the behavior of certain Emacs commands. Use of the +customization buffer is explained above (@pxref{Easy Customization}); +here we describe other aspects of Emacs variables. + +@menu +* Examining:: Examining or setting one variable's value. +* Hooks:: Hook variables let you specify programs for parts + of Emacs to run on particular occasions. +* Locals:: Per-buffer values of variables. +* File Variables:: How files can specify variable values. +@end menu + +@node Examining +@subsection Examining and Setting Variables +@cindex setting variables + +@table @kbd +@item C-h v @var{var} @key{RET} +Display the value and documentation of variable @var{var} +(@code{describe-variable}). +@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} +Change the value of variable @var{var} to @var{value}. +@end table + + To examine the value of a single variable, use @kbd{C-h v} +(@code{describe-variable}), which reads a variable name using the +minibuffer, with completion. It displays both the value and the +documentation of the variable. For example, + +@example +C-h v fill-column @key{RET} +@end example + +@noindent +displays something like this: + +@smallexample +fill-column is a variable defined in `C source code'. +fill-column's value is 70 +Local in buffer custom.texi; global value is 70 +Automatically becomes buffer-local when set in any fashion. + +This variable is safe to use as a file local variable only if its value +satisfies the predicate `integerp'. + +Documentation: +*Column beyond which automatic line-wrapping should happen. +Interactively, you can set the buffer local value using C-x f. + +You can customize this variable. +@end smallexample + +@noindent +The line that says you can customize the variable indicates that this +variable is a user option. (The star also indicates this, but it is +an obsolete indicator that may eventually disappear.) @kbd{C-h v} is +not restricted to user options; it allows any variable name. + +@findex set-variable +The most convenient way to set a specific user option variable is with +@kbd{M-x set-variable}. This reads the variable name with the +minibuffer (with completion), and then reads a Lisp expression for the +new value using the minibuffer a second time (you can insert the old +value into the minibuffer for editing via @kbd{M-n}). For example, + +@example +M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} +@end example + +@noindent +sets @code{fill-column} to 75. + + @kbd{M-x set-variable} is limited to user option variables, but you can +set any variable with a Lisp expression, using the function @code{setq}. +Here is a @code{setq} expression to set @code{fill-column}: + +@example +(setq fill-column 75) +@end example + + To execute an expression like this one, go to the @samp{*scratch*} +buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp +Interaction}. + + Setting variables, like all means of customizing Emacs except where +otherwise stated, affects only the current Emacs session. The only +way to alter the variable in future sessions is to put something in +the @file{~/.emacs} file to set it those sessions (@pxref{Init File}). + +@node Hooks +@subsection Hooks +@cindex hook +@cindex running a hook + + @dfn{Hooks} are an important mechanism for customization of Emacs. A +hook is a Lisp variable which holds a list of functions, to be called on +some well-defined occasion. (This is called @dfn{running the hook}.) +The individual functions in the list are called the @dfn{hook functions} +of the hook. With rare exceptions, hooks in Emacs are empty when Emacs +starts up, so the only hook functions in any given hook are the ones you +explicitly put there as customization. + + Most major modes run one or more @dfn{mode hooks} as the last step of +initialization. This makes it easy for you to customize the behavior of +the mode, by setting up a hook function to override the local variable +assignments already made by the mode. But hooks are also used in other +contexts. For example, the hook @code{suspend-hook} runs just before +Emacs suspends itself (@pxref{Exiting}). + +@cindex normal hook + Most Emacs hooks are @dfn{normal hooks}. This means that running the +hook operates by calling all the hook functions, unconditionally, with +no arguments. We have made an effort to keep most hooks normal so that +you can use them in a uniform way. Every variable in Emacs whose name +ends in @samp{-hook} is a normal hook. + +@cindex abnormal hook + There are also a few @dfn{abnormal hooks}. These variables' names end +in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What +makes these hooks abnormal is that there is something peculiar about the +way its functions are called---perhaps they are given arguments, or +perhaps the values they return are used in some way. For example, +@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because +as soon as one hook function returns a non-@code{nil} value, the rest +are not called at all. The documentation of each abnormal hook variable +explains in detail what is peculiar about it. + +@findex add-hook + You can set a hook variable with @code{setq} like any other Lisp +variable, but the recommended way to add a hook function to a hook +(either normal or abnormal) is by calling @code{add-hook}. +@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}. + + For example, here's how to set up a hook to turn on Auto Fill mode +when entering Text mode and other modes based on Text mode: + +@example +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end example + + The next example shows how to use a hook to customize the indentation +of C code. (People often have strong personal preferences for one +format compared to another.) Here the hook function is an anonymous +lambda expression. + +@example +@group +(setq my-c-style + '((c-comment-only-line-offset . 4) +@end group +@group + (c-cleanup-list . (scope-operator + empty-defun-braces + defun-close-semi)) +@end group +@group + (c-offsets-alist . ((arglist-close . c-lineup-arglist) + (substatement-open . 0))))) +@end group + +@group +(add-hook 'c-mode-common-hook + '(lambda () + (c-add-style "my-style" my-c-style t))) +@end group +@end example + + It is best to design your hook functions so that the order in which +they are executed does not matter. Any dependence on the order is +``asking for trouble.'' However, the order is predictable: the most +recently added hook functions are executed first. + +@findex remove-hook + If you play with adding various different versions of a hook +function by calling @code{add-hook} over and over, remember that all +the versions you added will remain in the hook variable together. You +can clear out individual functions by calling @code{remove-hook}, or +do @code{(setq @var{hook-variable} nil)} to remove everything. + +@node Locals +@subsection Local Variables + +@table @kbd +@item M-x make-local-variable @key{RET} @var{var} @key{RET} +Make variable @var{var} have a local value in the current buffer. +@item M-x kill-local-variable @key{RET} @var{var} @key{RET} +Make variable @var{var} use its global value in the current buffer. +@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} +Mark variable @var{var} so that setting it will make it local to the +buffer that is current at that time. +@end table + +@cindex local variables + Almost any variable can be made @dfn{local} to a specific Emacs +buffer. This means that its value in that buffer is independent of its +value in other buffers. A few variables are always local in every +buffer. Every other Emacs variable has a @dfn{global} value which is in +effect in all buffers that have not made the variable local. + +@findex make-local-variable + @kbd{M-x make-local-variable} reads the name of a variable and makes +it local to the current buffer. Changing its value subsequently in +this buffer will not affect others, and changes in its global value +will not affect this buffer. + +@findex make-variable-buffer-local +@cindex per-buffer variables + @kbd{M-x make-variable-buffer-local} marks a variable so it will +become local automatically whenever it is set. More precisely, once a +variable has been marked in this way, the usual ways of setting the +variable automatically do @code{make-local-variable} first. We call +such variables @dfn{per-buffer} variables. Many variables in Emacs +are normally per-buffer; the variable's document string tells you when +this is so. A per-buffer variable's global value is normally never +effective in any buffer, but it still has a meaning: it is the initial +value of the variable for each new buffer. + + Major modes (@pxref{Major Modes}) always make variables local to the +buffer before setting the variables. This is why changing major modes +in one buffer has no effect on other buffers. Minor modes also work +by setting variables---normally, each minor mode has one controlling +variable which is non-@code{nil} when the mode is enabled +(@pxref{Minor Modes}). For many minor modes, the controlling variable +is per buffer, and thus always buffer-local. Otherwise, you can make +it local in a specific buffer like any other variable. + + A few variables cannot be local to a buffer because they are always +local to each display instead (@pxref{Multiple Displays}). If you try to +make one of these variables buffer-local, you'll get an error message. + +@findex kill-local-variable + @kbd{M-x kill-local-variable} makes a specified variable cease to be +local to the current buffer. The global value of the variable +henceforth is in effect in this buffer. Setting the major mode kills +all the local variables of the buffer except for a few variables +specially marked as @dfn{permanent locals}. + +@findex setq-default + To set the global value of a variable, regardless of whether the +variable has a local value in the current buffer, you can use the Lisp +construct @code{setq-default}. This construct is used just like +@code{setq}, but it sets variables' global values instead of their local +values (if any). When the current buffer does have a local value, the +new global value may not be visible until you switch to another buffer. +Here is an example: + +@example +(setq-default fill-column 75) +@end example + +@noindent +@code{setq-default} is the only way to set the global value of a variable +that has been marked with @code{make-variable-buffer-local}. + +@findex default-value + Lisp programs can use @code{default-value} to look at a variable's +default value. This function takes a symbol as argument and returns its +default value. The argument is evaluated; usually you must quote it +explicitly. For example, here's how to obtain the default value of +@code{fill-column}: + +@example +(default-value 'fill-column) +@end example + +@node File Variables +@subsection Local Variables in Files +@cindex local variables in files +@cindex file local variables + + A file can specify local variable values for use when you edit the +file with Emacs. Visiting the file checks for local variable +specifications; it automatically makes these variables local to the +buffer, and sets them to the values specified in the file. + +@menu +* Specifying File Variables:: Specifying file local variables. +* Safe File Variables:: Making sure file local variables are safe. +@end menu + +@node Specifying File Variables +@subsubsection Specifying File Variables + + There are two ways to specify file local variable values: in the first +line, or with a local variables list. Here's how to specify them in the +first line: + +@example +-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- +@end example + +@noindent +You can specify any number of variables/value pairs in this way, each +pair with a colon and semicolon as shown above. @code{mode: +@var{modename};} specifies the major mode; this should come first in the +line. The @var{value}s are not evaluated; they are used literally. +Here is an example that specifies Lisp mode and sets two variables with +numeric values: + +@smallexample +;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- +@end smallexample + + You can also specify the coding system for a file in this way: just +specify a value for the ``variable'' named @code{coding}. The ``value'' +must be a coding system name that Emacs recognizes. @xref{Coding +Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a +particular Lisp file. @xref{Enabling Multibyte}. + + The @code{eval} pseudo-variable, described below, can be specified in +the first line as well. + +@cindex shell scripts, and local file variables + In shell scripts, the first line is used to identify the script +interpreter, so you cannot put any local variables there. To +accommodate this, Emacs looks for local variable specifications in the +@emph{second} line when the first line specifies an interpreter. + + A @dfn{local variables list} goes near the end of the file, in the +last page. (It is often best to put it on a page by itself.) The local +variables list starts with a line containing the string @samp{Local +Variables:}, and ends with a line containing the string @samp{End:}. In +between come the variable names and values, one set per line, as +@samp{@var{variable}:@: @var{value}}. The @var{value}s are not +evaluated; they are used literally. If a file has both a local +variables list and a @samp{-*-} line, Emacs processes @emph{everything} +in the @samp{-*-} line first, and @emph{everything} in the local +variables list afterward. + + Here is an example of a local variables list: + +@example +;; Local Variables: ** +;; mode:lisp ** +;; comment-column:0 ** +;; comment-start: ";; " ** +;; comment-end:"**" ** +;; End: ** +@end example + + Each line starts with the prefix @samp{;; } and each line ends with +the suffix @samp{ **}. Emacs recognizes these as the prefix and +suffix based on the first line of the list, by finding them +surrounding the magic string @samp{Local Variables:}; then it +automatically discards them from the other lines of the list. + + The usual reason for using a prefix and/or suffix is to embed the +local variables list in a comment, so it won't confuse other programs +that the file is intended as input for. The example above is for a +language where comment lines start with @samp{;; } and end with +@samp{**}; the local values for @code{comment-start} and +@code{comment-end} customize the rest of Emacs for this unusual +syntax. Don't use a prefix (or a suffix) if you don't need one. + + If you write a multi-line string value, you should put the prefix +and suffix on each line, even lines that start or end within the +string. They will be stripped off for processing the list. If you +want to split a long string across multiple lines of the file, you can +use backslash-newline, which is ignored in Lisp string constants. +Here's an example of doing this: + +@example +# Local Variables: +# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ +# -Dmumble=blaah" +# End: +@end example + + Some ``variable names'' have special meanings in a local variables +list. Specifying the ``variable'' @code{mode} really sets the major +mode, while any value specified for the ``variable'' @code{eval} is +simply evaluated as an expression (its value is ignored). A value for +@code{coding} specifies the coding system for character code +conversion of this file, and a value of @code{t} for @code{unibyte} +says to visit the file in a unibyte buffer. These four ``variables'' +are not really variables; setting them in any other context has no +special meaning. + + @emph{If @code{mode} is used to set a major mode, it should be the +first ``variable'' in the list.} Otherwise, the entries that precede +it will usually be ignored, since most modes kill all local variables +as part of their initialization. + + You can use the @code{mode} ``variable'' to set minor modes as well +as the major modes; in fact, you can use it more than once, first to +set the major mode and then to set minor modes which are specific to +particular buffers. But most minor modes should not be specified in +the file at all, because they represent user preferences. + + For example, you may be tempted to try to turn on Auto Fill mode with +a local variable list. That is a mistake. The choice of Auto Fill mode +or not is a matter of individual taste, not a matter of the contents of +particular files. If you want to use Auto Fill, set up major mode hooks +with your @file{.emacs} file to turn it on (when appropriate) for you +alone (@pxref{Init File}). Don't use a local variable list to impose +your taste on everyone. + + The start of the local variables list must be no more than 3000 +characters from the end of the file, and must be in the last page if the +file is divided into pages. Otherwise, Emacs will not notice it is +there. The purpose of this rule is so that a stray @samp{Local +Variables:}@: not in the last page does not confuse Emacs, and so that +visiting a long file that is all one page and has no local variables +list need not take the time to search the whole file. + + Use the command @code{normal-mode} to reset the local variables and +major mode of a buffer according to the file name and contents, +including the local variables list if any. @xref{Choosing Modes}. + +@node Safe File Variables +@subsubsection Safety of File Variables + + File-local variables can be dangerous; when you visit someone else's +file, there's no telling what its local variables list could do to +your Emacs. Improper values of the @code{eval} ``variable,'' and +other variables such as @code{load-path}, could execute Lisp code you +didn't intend to run. + + Therefore, whenever Emacs encounters file local variable values that +are not known to be safe, it displays the file's entire local +variables list, and asks you for confirmation before setting them. +You can type @kbd{y} or @key{SPC} to put the local variables list into +effect, or @kbd{n} to ignore it. When Emacs is run in batch mode +(@pxref{Initial Options}), it can't really ask you, so it assumes the +answer @kbd{n}. + + Emacs normally recognizes certain variables/value pairs as safe. +For instance, it is safe to give @code{comment-column} or +@code{fill-column} any integer value. If a file specifies only +known-safe variable/value pairs, Emacs does not ask for confirmation +before setting them. Otherwise, you can tell Emacs to record all the +variable/value pairs in this file as safe, by typing @kbd{!} at the +confirmation prompt. When Emacs encounters these variable/value pairs +subsequently, in the same file or others, it will assume they are +safe. + +@vindex safe-local-variable-values +@cindex risky variable + Some variables, such as @code{load-path}, are considered +particularly @dfn{risky}: there is seldom any reason to specify them +as local variables, and changing them can be dangerous. If a file +contains only risky local variables, Emacs neither offers nor accepts +@kbd{!} as input at the confirmation prompt. If some of the local +variables in a file are risky, and some are only potentially unsafe, you +can enter @kbd{!} at the prompt. It applies all the variables, but only +marks the non-risky ones as safe for the future. If you really want to +record safe values for risky variables, do it directly by customizing +@samp{safe-local-variable-values} (@pxref{Easy Customization}). + +@vindex enable-local-variables + The variable @code{enable-local-variables} allows you to change the +way Emacs processes local variables. Its default value is @code{t}, +which specifies the behavior described above. If it is @code{nil}, +Emacs simply ignores all file local variables. @code{:safe} means use +only the safe values and ignore the rest. Any other value says to +query you about each file that has local variables, without trying to +determine whether the values are known to be safe. + +@vindex enable-local-eval + The variable @code{enable-local-eval} controls whether Emacs +processes @code{eval} variables. The three possibilities for the +variable's value are @code{t}, @code{nil}, and anything else, just as +for @code{enable-local-variables}. The default is @code{maybe}, which +is neither @code{t} nor @code{nil}, so normally Emacs does ask for +confirmation about processing @code{eval} variables. + +@vindex safe-local-eval-forms + But there is an exception. The @code{safe-local-eval-forms} is a +customizable list of eval forms which are safe. Emacs does not ask +for confirmation when it finds these forms for the @code{eval} +variable. + +@node Key Bindings +@section Customizing Key Bindings +@cindex key bindings + + This section describes @dfn{key bindings}, which map keys to commands, +and @dfn{keymaps}, which record key bindings. It also explains how +to customize key bindings. + + Recall that a command is a Lisp function whose definition provides for +interactive use. Like every Lisp function, a command has a function +name, which usually consists of lower-case letters and hyphens. + +@menu +* Keymaps:: Generalities. The global keymap. +* Prefix Keymaps:: Keymaps for prefix keys. +* Local Keymaps:: Major and minor modes have their own keymaps. +* Minibuffer Maps:: The minibuffer uses its own local keymaps. +* Rebinding:: How to redefine one key's meaning conveniently. +* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. +* Function Keys:: Rebinding terminal function keys. +* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. +* Mouse Buttons:: Rebinding mouse buttons in Emacs. +* Disabling:: Disabling a command means confirmation is required + before it can be executed. This is done to protect + beginners from surprises. +@end menu + +@node Keymaps +@subsection Keymaps +@cindex keymap + + The bindings between key sequences and command functions are recorded +in data structures called @dfn{keymaps}. Emacs has many of these, each +used on particular occasions. + + Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence +of @dfn{input events} that have a meaning as a unit. Input events +include characters, function keys and mouse buttons---all the inputs +that you can send to the computer with your terminal. A key sequence +gets its meaning from its @dfn{binding}, which says what command it +runs. The function of keymaps is to record these bindings. + +@cindex global keymap + The @dfn{global} keymap is the most important keymap because it is +always in effect. The global keymap defines keys for Fundamental mode; +most of these definitions are common to most or all major modes. Each +major or minor mode can have its own keymap which overrides the global +definitions of some keys. + + For example, a self-inserting character such as @kbd{g} is +self-inserting because the global keymap binds it to the command +@code{self-insert-command}. The standard Emacs editing characters such +as @kbd{C-a} also get their standard meanings from the global keymap. +Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work +by storing the new binding in the proper place in the global map. +@xref{Rebinding}. + + Meta characters work differently; Emacs translates each Meta +character into a pair of characters starting with @key{ESC}. When you +type the character @kbd{M-a} in a key sequence, Emacs replaces it with +@kbd{@key{ESC} a}. A meta key comes in as a single input event, but +becomes two events for purposes of key bindings. The reason for this is +historical, and we might change it someday. + +@cindex function key + Most modern keyboards have function keys as well as character keys. +Function keys send input events just as character keys do, and keymaps +can have bindings for them. + + On text terminals, typing a function key actually sends the computer a +sequence of characters; the precise details of the sequence depends on +which function key and on the model of terminal you are using. (Often +the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your +terminal type properly, it recognizes the character sequences forming +function keys wherever they occur in a key sequence (not just at the +beginning). Thus, for most purposes, you can pretend the function keys +reach Emacs directly and ignore their encoding as character sequences. + +@cindex mouse + Mouse buttons also produce input events. These events come with other +data---the window and position where you pressed or released the button, +and a time stamp. But only the choice of button matters for key +bindings; the other data matters only if a command looks at it. +(Commands designed for mouse invocation usually do look at the other +data.) + + A keymap records definitions for single events. Interpreting a key +sequence of multiple events involves a chain of keymaps. The first +keymap gives a definition for the first event; this definition is +another keymap, which is used to look up the second event in the +sequence, and so on. + + Key sequences can mix function keys and characters. For example, +@kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix +key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse +events with keyboard events, but we recommend against it, because such +key sequences are inconvenient to use. + + As a user, you can redefine any key; but it is usually best to stick +to key sequences that consist of @kbd{C-c} followed by a letter (upper +or lower case). These keys are ``reserved for users,'' so they won't +conflict with any properly designed Emacs extension. The function +keys @key{F5} through @key{F9} are also reserved for users. If you +redefine some other key, your definition may be overridden by certain +extensions or major modes which redefine the same key. + +@node Prefix Keymaps +@subsection Prefix Keymaps + + A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap, +which holds the definition for the event that immediately follows +that prefix. + + The definition of a prefix key is usually the keymap to use for +looking up the following event. The definition can also be a Lisp +symbol whose function definition is the following keymap; the effect is +the same, but it provides a command name for the prefix key that can be +used as a description of what the prefix key is for. Thus, the binding +of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function +definition is the keymap for @kbd{C-x} commands. The definitions of +@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in +the global map, so these prefix keys are always available. + + Aside from ordinary prefix keys, there is a fictitious ``prefix key'' +which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp +Reference Manual}, for special information about menu bar key bindings. +Mouse button events that invoke pop-up menus are also prefix keys; see +@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more +details. + + Some prefix keymaps are stored in variables with names: + +@itemize @bullet +@item +@vindex ctl-x-map +@code{ctl-x-map} is the variable name for the map used for characters that +follow @kbd{C-x}. +@item +@vindex help-map +@code{help-map} is for characters that follow @kbd{C-h}. +@item +@vindex esc-map +@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta +characters are actually defined by this map. +@item +@vindex ctl-x-4-map +@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. +@item +@vindex mode-specific-map +@code{mode-specific-map} is for characters that follow @kbd{C-c}. +@end itemize + +@node Local Keymaps +@subsection Local Keymaps + +@cindex local keymap + So far we have explained the ins and outs of the global map. Major +modes customize Emacs by providing their own key bindings in @dfn{local +keymaps}. For example, C mode overrides @key{TAB} to make it indent the +current line for C code. Portions of text in the buffer can specify +their own keymaps to substitute for the keymap of the buffer's major +mode. + +@cindex minor mode keymap + Minor modes can also have local keymaps. Whenever a minor mode is +in effect, the definitions in its keymap override both the major +mode's local keymap and the global keymap. + + A local keymap can locally redefine a key as a prefix key by defining +it as a prefix keymap. If the key is also defined globally as a prefix, +then its local and global definitions (both keymaps) effectively +combine: both of them are used to look up the event that follows the +prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as +another keymap, and that keymap defines @kbd{C-z} as a command, this +provides a local meaning for @kbd{C-c C-z}. This does not affect other +sequences that start with @kbd{C-c}; if those sequences don't have their +own local bindings, their global bindings remain in effect. + + Another way to think of this is that Emacs handles a multi-event key +sequence by looking in several keymaps, one by one, for a binding of the +whole key sequence. First it checks the minor mode keymaps for minor +modes that are enabled, then it checks the major mode's keymap, and then +it checks the global keymap. This is not precisely how key lookup +works, but it's good enough for understanding the results in ordinary +circumstances. + +@cindex rebinding major mode keys + Most major modes construct their keymaps when the mode is used for +the first time in a session. If you wish to change one of these +keymaps, you must use the major mode's @dfn{mode hook} +(@pxref{Hooks}). + +@findex define-key + For example, the command @code{texinfo-mode} to select Texinfo mode +runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook +to add local bindings (not very useful, we admit) for @kbd{C-c n} and +@kbd{C-c p} in Texinfo mode: + +@example +(add-hook 'texinfo-mode-hook + '(lambda () + (define-key texinfo-mode-map "\C-cp" + 'backward-paragraph) + (define-key texinfo-mode-map "\C-cn" + 'forward-paragraph))) +@end example + +@node Minibuffer Maps +@subsection Minibuffer Keymaps + +@cindex minibuffer keymaps +@vindex minibuffer-local-map +@vindex minibuffer-local-ns-map +@vindex minibuffer-local-completion-map +@vindex minibuffer-local-must-match-map +@vindex minibuffer-local-filename-completion-map +@vindex minibuffer-local-must-match-filename-map + The minibuffer has its own set of local keymaps; they contain various +completion and exit commands. + +@itemize @bullet +@item +@code{minibuffer-local-map} is used for ordinary input (no completion). +@item +@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits +just like @key{RET}. This is used mainly for Mocklisp compatibility. +@item +@code{minibuffer-local-completion-map} is for permissive completion. +@item +@code{minibuffer-local-must-match-map} is for strict completion and +for cautious completion. +@item +Finally, @code{minibuffer-local-filename-completion-map} and +@code{minibuffer-local-must-match-filename-map} are like the two +previous ones, but they are specifically for file name completion. +They do not bind @key{SPC}. +@end itemize + +@node Rebinding +@subsection Changing Key Bindings Interactively +@cindex key rebinding, this session +@cindex redefining keys, this session + + The way to redefine an Emacs key is to change its entry in a keymap. +You can change the global keymap, in which case the change is effective in +all major modes (except those that have their own overriding local +definitions for the same key). Or you can change the current buffer's +local map, which affects all buffers using the same major mode. + +@findex global-set-key +@findex local-set-key +@findex global-unset-key +@findex local-unset-key +@table @kbd +@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} +Define @var{key} globally to run @var{cmd}. +@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} +Define @var{key} locally (in the major mode now in effect) to run +@var{cmd}. +@item M-x global-unset-key @key{RET} @var{key} +Make @var{key} undefined in the global map. +@item M-x local-unset-key @key{RET} @var{key} +Make @var{key} undefined locally (in the major mode now in effect). +@end table + + For example, suppose you like to execute commands in a subshell within +an Emacs buffer, instead of suspending Emacs and executing commands in +your login shell. Normally, @kbd{C-z} is bound to the function +@code{suspend-emacs} (when not using the X Window System), but you can +change @kbd{C-z} to invoke an interactive subshell within Emacs, by +binding it to @code{shell} as follows: + +@example +M-x global-set-key @key{RET} C-z shell @key{RET} +@end example + +@noindent +@code{global-set-key} reads the command name after the key. After you +press the key, a message like this appears so that you can confirm that +you are binding the key you want: + +@example +Set key C-z to command: +@end example + + You can redefine function keys and mouse events in the same way; just +type the function key or click the mouse when it's time to specify the +key to rebind. + + You can rebind a key that contains more than one event in the same +way. Emacs keeps reading the key to rebind until it is a complete key +(that is, not a prefix key). Thus, if you type @kbd{C-f} for +@var{key}, that's the end; it enters the minibuffer immediately to +read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it +reads another character; if that is @kbd{4}, another prefix character, +it reads one more character, and so on. For example, + +@example +M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} +@end example + +@noindent +redefines @kbd{C-x 4 $} to run the (fictitious) command +@code{spell-other-window}. + + The two-character keys consisting of @kbd{C-c} followed by a letter +are reserved for user customizations. Lisp programs are not supposed to +define these keys, so the bindings you make for them will be available +in all major modes and will never get in the way of anything. + + You can remove the global definition of a key with +@code{global-unset-key}. This makes the key @dfn{undefined}; if you +type it, Emacs will just beep. Similarly, @code{local-unset-key} makes +a key undefined in the current major mode keymap, which makes the global +definition (or lack of one) come back into effect in that major mode. + + If you have redefined (or undefined) a key and you subsequently wish +to retract the change, undefining the key will not do the job---you need +to redefine the key with its standard definition. To find the name of +the standard definition of a key, go to a Fundamental mode buffer in a +fresh Emacs and use @kbd{C-h c}. The documentation of keys in this +manual also lists their command names. + + If you want to prevent yourself from invoking a command by mistake, it +is better to disable the command than to undefine the key. A disabled +command is less work to invoke when you really want to. +@xref{Disabling}. + +@node Init Rebinding +@subsection Rebinding Keys in Your Init File + + If you have a set of key bindings that you like to use all the time, +you can specify them in your @file{.emacs} file by using their Lisp +syntax. (@xref{Init File}.) + + The simplest method for doing this works for @acronym{ASCII} characters and +Meta-modified @acronym{ASCII} characters only. This method uses a string to +represent the key sequence you want to rebind. For example, here's how +to bind @kbd{C-z} to @code{shell}: + +@example +(global-set-key "\C-z" 'shell) +@end example + +@noindent +This example uses a string constant containing one character, +@kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The +single-quote before the command name, @code{shell}, marks it as a +constant symbol rather than a variable. If you omit the quote, Emacs +would try to evaluate @code{shell} immediately as a variable. This +probably causes an error; it certainly isn't what you want. + + Here is another example that binds the key sequence @kbd{C-x M-l}: + +@example +(global-set-key "\C-x\M-l" 'make-symbolic-link) +@end example + + To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the +string, you can use the Emacs Lisp escape sequences, @samp{\t}, +@samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds +@kbd{C-x @key{TAB}}: + +@example +(global-set-key "\C-x\t" 'indent-rigidly) +@end example + + These examples show how to write some other special @acronym{ASCII} characters +in strings for key bindings: + +@example +(global-set-key "\r" 'newline) ;; @key{RET} +(global-set-key "\d" 'delete-backward-char) ;; @key{DEL} +(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC} +@end example + + When the key sequence includes function keys or mouse button events, +or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use +the more general method of rebinding, which uses a vector to specify the +key sequence. + + The way to write a vector in Emacs Lisp is with square brackets around +the vector elements. Use spaces to separate the elements. If an +element is a symbol, simply write the symbol's name---no other +delimiters or punctuation are needed. If a vector element is a +character, write it as a Lisp character constant: @samp{?} followed by +the character as it would appear in a string. + + Here are examples of using vectors to rebind @kbd{C-=} (a control +character not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=} +is not), @kbd{H-a} (a Hyper character; @acronym{ASCII} doesn't have Hyper at +all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a +keyboard-modified mouse button): + +@example +(global-set-key [?\C-=] 'make-symbolic-link) +(global-set-key [?\M-\C-=] 'make-symbolic-link) +(global-set-key [?\H-a] 'make-symbolic-link) +(global-set-key [f7] 'make-symbolic-link) +(global-set-key [C-mouse-1] 'make-symbolic-link) +@end example + + You can use a vector for the simple cases too. Here's how to +rewrite the first six examples above to use vectors: + +@example +(global-set-key [?\C-z] 'shell) +(global-set-key [?\C-x ?l] 'make-symbolic-link) +(global-set-key [?\C-x ?\t] 'indent-rigidly) +(global-set-key [?\r] 'newline) +(global-set-key [?\d] 'delete-backward-char) +(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command) +@end example + +@noindent +As you see, you represent a multi-character key sequence with a vector +by listing all of the characters, in order, within the square brackets +that delimit the vector. + + Language and coding systems can cause problems with key bindings +for non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. + +@node Function Keys +@subsection Rebinding Function Keys + + Key sequences can contain function keys as well as ordinary +characters. Just as Lisp characters (actually integers) represent +keyboard characters, Lisp symbols represent function keys. If the +function key has a word as its label, then that word is also the name of +the corresponding Lisp symbol. Here are the conventional Lisp names for +common function keys: + +@table @asis +@item @code{left}, @code{up}, @code{right}, @code{down} +Cursor arrow keys. + +@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} +Other cursor repositioning keys. + +@item @code{select}, @code{print}, @code{execute}, @code{backtab} +@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} +@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} +Miscellaneous function keys. + +@item @code{f1}, @code{f2}, @dots{} @code{f35} +Numbered function keys (across the top of the keyboard). + +@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} +@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} +@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} +Keypad keys (to the right of the regular keyboard), with names or punctuation. + +@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} +Keypad keys with digits. + +@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} +Keypad PF keys. +@end table + + These names are conventional, but some systems (especially when using +X) may use different names. To make certain what symbol is used for a +given function key on your terminal, type @kbd{C-h c} followed by that +key. + + A key sequence which contains function key symbols (or anything but +@acronym{ASCII} characters) must be a vector rather than a string. +Thus, to bind function key @samp{f1} to the command @code{rmail}, +write the following: + +@example +(global-set-key [f1] 'rmail) +@end example + +@noindent +To bind the right-arrow key to the command @code{forward-char}, you can +use this expression: + +@example +(global-set-key [right] 'forward-char) +@end example + +@noindent +This uses the Lisp syntax for a vector containing the symbol +@code{right}. (This binding is present in Emacs by default.) + + @xref{Init Rebinding}, for more information about using vectors for +rebinding. + + You can mix function keys and characters in a key sequence. This +example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}. + +@example +(global-set-key [?\C-x next] 'forward-page) +@end example + +@noindent +where @code{?\C-x} is the Lisp character constant for the character +@kbd{C-x}. The vector element @code{next} is a symbol and therefore +does not take a question mark. + + You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER}, +@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent +these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-}, +@samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name. +Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a +word: + +@example +(global-set-key [H-M-right] 'forward-word) +@end example + +@cindex keypad + Many keyboards have a ``numeric keypad'' on the right hand side. +The numeric keys in the keypad double up as cursor motion keys, +toggled by a key labeled @samp{Num Lock}. By default, Emacs +translates these keys to the corresponding keys in the main keyboard. +For example, when @samp{Num Lock} is on, the key labeled @samp{8} on +the numeric keypad produces @code{kp-8}, which is translated to +@kbd{8}; when @samp{Num Lock} is off, the same key produces +@code{kp-up}, which is translated to @key{UP}. If you rebind a key +such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. +However, if you rebind a @samp{kp-} key directly, that won't affect +its non-keypad equivalent. + + Emacs provides a convenient method for binding the numeric keypad +keys, using the variables @code{keypad-setup}, +@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and +@code{keypad-numlock-shifted-setup}. These can be found in the +@samp{keyboard} customization group (@pxref{Easy Customization}). You +can rebind the keys to perform other tasks, such as issuing numeric +prefix arguments. + +@node Named ASCII Chars +@subsection Named @acronym{ASCII} Control Characters + + @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} +started out as names for certain @acronym{ASCII} control characters, +used so often that they have special keys of their own. For instance, +@key{TAB} was another name for @kbd{C-i}. Later, users found it +convenient to distinguish in Emacs between these keys and the ``same'' +control characters typed with the @key{CTRL} key. Therefore, on most +modern terminals, they are no longer the same, and @key{TAB} is +distinguishable from @kbd{C-i}. + + Emacs can distinguish these two kinds of input if the keyboard does. +It treats the ``special'' keys as function keys named @code{tab}, +@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and +@code{delete}. These function keys translate automatically into the +corresponding @acronym{ASCII} characters @emph{if} they have no +bindings of their own. As a result, neither users nor Lisp programs +need to pay attention to the distinction unless they care to. + + If you do not want to distinguish between (for example) @key{TAB} and +@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} +(octal code 011). If you do want to distinguish, make one binding for +this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. + + With an ordinary @acronym{ASCII} terminal, there is no way to distinguish +between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), +because the terminal sends the same character in both cases. + +@node Mouse Buttons +@subsection Rebinding Mouse Buttons +@cindex mouse button events +@cindex rebinding mouse buttons +@cindex click events +@cindex drag events +@cindex down events +@cindex button down events + + Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary +mouse events in Emacs are @dfn{click} events; these happen when you +press a button and release it without moving the mouse. You can also +get @dfn{drag} events, when you move the mouse while holding the button +down. Drag events happen when you finally let go of the button. + + The symbols for basic click events are @code{mouse-1} for the leftmost +button, @code{mouse-2} for the next, and so on. Here is how you can +redefine the second mouse button to split the current window: + +@example +(global-set-key [mouse-2] 'split-window-vertically) +@end example + + The symbols for drag events are similar, but have the prefix +@samp{drag-} before the word @samp{mouse}. For example, dragging the +first button generates a @code{drag-mouse-1} event. + + You can also define bindings for events that occur when a mouse button +is pressed down. These events start with @samp{down-} instead of +@samp{drag-}. Such events are generated only if they have key bindings. +When you get a button-down event, a corresponding click or drag event +will always follow. + +@cindex double clicks +@cindex triple clicks + If you wish, you can distinguish single, double, and triple clicks. A +double click means clicking a mouse button twice in approximately the +same place. The first click generates an ordinary click event. The +second click, if it comes soon enough, generates a double-click event +instead. The event type for a double-click event starts with +@samp{double-}: for example, @code{double-mouse-3}. + + This means that you can give a special meaning to the second click at +the same place, but it must act on the assumption that the ordinary +single click definition has run when the first click was received. + + This constrains what you can do with double clicks, but user interface +designers say that this constraint ought to be followed in any case. A +double click should do something similar to the single click, only +``more so.'' The command for the double-click event should perform the +extra work for the double click. + + If a double-click event has no binding, it changes to the +corresponding single-click event. Thus, if you don't define a +particular double click specially, it executes the single-click command +twice. + + Emacs also supports triple-click events whose names start with +@samp{triple-}. Emacs does not distinguish quadruple clicks as event +types; clicks beyond the third generate additional triple-click events. +However, the full number of clicks is recorded in the event list, so +if you know Emacs Lisp you can distinguish if you really want to +(@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}). +We don't recommend distinct meanings for more than three clicks, but +sometimes it is useful for subsequent clicks to cycle through the same +set of three meanings, so that four clicks are equivalent to one +click, five are equivalent to two, and six are equivalent to three. + + Emacs also records multiple presses in drag and button-down events. +For example, when you press a button twice, then move the mouse while +holding the button, Emacs gets a @samp{double-drag-} event. And at the +moment when you press it down for the second time, Emacs gets a +@samp{double-down-} event (which is ignored, like all button-down +events, if it has no binding). + +@vindex double-click-time + The variable @code{double-click-time} specifies how much time can +elapse between clicks and still allow them to be grouped as a multiple +click. Its value is in units of milliseconds. If the value is +@code{nil}, double clicks are not detected at all. If the value is +@code{t}, then there is no time limit. The default is 500. + +@vindex double-click-fuzz + The variable @code{double-click-fuzz} specifies how much the mouse +can move between clicks and still allow them to be grouped as a multiple +click. Its value is in units of pixels on windowed displays and in +units of 1/8 of a character cell on text-mode terminals; the default is +3. + + The symbols for mouse events also indicate the status of the modifier +keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, +@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} +or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. + + A frame includes areas that don't show text from the buffer, such as +the mode line and the scroll bar. You can tell whether a mouse button +comes from a special area of the screen by means of dummy ``prefix +keys.'' For example, if you click the mouse in the mode line, you get +the prefix key @code{mode-line} before the ordinary mouse-button symbol. +Thus, here is how to define the command for clicking the first button in +a mode line to run @code{scroll-up}: + +@example +(global-set-key [mode-line mouse-1] 'scroll-up) +@end example + + Here is the complete list of these dummy prefix keys and their +meanings: + +@table @code +@item mode-line +The mouse was in the mode line of a window. +@item vertical-line +The mouse was in the vertical line separating side-by-side windows. (If +you use scroll bars, they appear in place of these vertical lines.) +@item vertical-scroll-bar +The mouse was in a vertical scroll bar. (This is the only kind of +scroll bar Emacs currently supports.) +@item menu-bar +The mouse was in the menu bar. +@item header-line +The mouse was in a header line. +@ignore +@item horizontal-scroll-bar +The mouse was in a horizontal scroll bar. Horizontal scroll bars do +horizontal scrolling, and people don't use them often. +@end ignore +@end table + + You can put more than one mouse button in a key sequence, but it isn't +usual to do so. + +@node Disabling +@subsection Disabling Commands +@cindex disabled command + + Disabling a command means that invoking it interactively asks for +confirmation from the user. The purpose of disabling a command is to +prevent users from executing it by accident; we do this for commands +that might be confusing to the uninitiated. + + Attempting to invoke a disabled command interactively in Emacs +displays a window containing the command's name, its documentation, +and some instructions on what to do immediately; then Emacs asks for +input saying whether to execute the command as requested, enable it +and execute it, or cancel. If you decide to enable the command, you +must then answer another question---whether to do this permanently, or +just for the current session. (Enabling permanently works by +automatically editing your @file{.emacs} file.) You can also type +@kbd{!} to enable @emph{all} commands, for the current session only. + + The direct mechanism for disabling a command is to put a +non-@code{nil} @code{disabled} property on the Lisp symbol for the +command. Here is the Lisp program to do this: + +@example +(put 'delete-region 'disabled t) +@end example + + If the value of the @code{disabled} property is a string, that string +is included in the message displayed when the command is used: + +@example +(put 'delete-region 'disabled + "It's better to use `kill-region' instead.\n") +@end example + +@findex disable-command +@findex enable-command + You can make a command disabled either by editing the @file{.emacs} +file directly, or with the command @kbd{M-x disable-command}, which edits +the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command} +edits @file{.emacs} to enable a command permanently. @xref{Init File}. + + If Emacs was invoked with the @option{-q} or @option{--no-init-file} +options (@pxref{Initial Options}), it will not edit your +@file{~/.emacs} init file. Doing so could lose information +because Emacs has not read your init file. + + Whether a command is disabled is independent of what key is used to +invoke it; disabling also applies if the command is invoked using +@kbd{M-x}. However, disabling a command has no effect on calling it +as a function from Lisp programs. + +@node Syntax +@section The Syntax Table +@cindex syntax table + + All the Emacs commands which parse words or balance parentheses are +controlled by the @dfn{syntax table}. The syntax table says which +characters are opening delimiters, which are parts of words, which are +string quotes, and so on. It does this by assigning each character to +one of fifteen-odd @dfn{syntax classes}. In some cases it specifies +some additional information also. + + Each major mode has its own syntax table (though related major modes +sometimes share one syntax table), which it installs in each buffer +that uses the mode. The syntax table installed in the current buffer +is the one that all commands use, so we call it ``the'' syntax table. + +@kindex C-h s +@findex describe-syntax + To display a description of the contents of the current syntax +table, type @kbd{C-h s} (@code{describe-syntax}). The description of +each character includes the string you would have to give to +@code{modify-syntax-entry} to set up that character's current syntax, +starting with the character which designates its syntax class, plus +some English text to explain its meaning. + + A syntax table is actually a Lisp object, a char-table, whose +elements are cons cells. For full information on the syntax table, +see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp +Reference Manual}. + +@node Init File +@section The Init File, @file{~/.emacs} +@cindex init file +@cindex Emacs initialization file +@cindex key rebinding, permanent +@cindex rebinding keys, permanently +@cindex startup (init file) + + When Emacs is started, it normally loads a Lisp program from the file +@file{.emacs} or @file{.emacs.el} in your home directory (@pxref{Find Init}). +We call this file your @dfn{init file} because it specifies how to +initialize Emacs for you. You can use the command line switch +@samp{-q} to prevent loading your init file, and @samp{-u} (or +@samp{--user}) to specify a different user's init file (@pxref{Initial +Options}). + + You can also use @file{~/.emacs.d/init.el} as the init file. Emacs +tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}. + +@cindex @file{default.el}, the default init file + There can also be a @dfn{default init file}, which is the library +named @file{default.el}, found via the standard search path for +libraries. The Emacs distribution contains no such library; your site +may create one for local customizations. If this library exists, it is +loaded whenever you start Emacs (except when you specify @samp{-q}). +But your init file, if any, is loaded first; if it sets +@code{inhibit-default-init} non-@code{nil}, then @file{default} is not +loaded. + +@cindex site init file +@cindex @file{site-start.el}, the site startup file + Your site may also have a @dfn{site startup file}; this is named +@file{site-start.el}, if it exists. Like @file{default.el}, Emacs +finds this file via the standard search path for Lisp libraries. +Emacs loads this library before it loads your init file. To inhibit +loading of this library, use the option @samp{--no-site-file}. +@xref{Initial Options}. We recommend against using +@file{site-start.el} for changes that some users may not like. It is +better to put them in @file{default.el}, so that users can more easily +override them. + + You can place @file{default.el} and @file{site-start.el} in any of +the directories which Emacs searches for Lisp libraries. The variable +@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. +Many sites put these files in the @file{site-lisp} subdirectory of the +Emacs installation directory, typically +@file{/usr/local/share/emacs/site-lisp}. + + If you have a large amount of code in your @file{.emacs} file, you +should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte +Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}, +for more information about compiling Emacs Lisp programs. + + If you are going to write actual Emacs Lisp programs that go beyond +minor customization, you should read the @cite{Emacs Lisp Reference Manual}. +@ifnottex +@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference +Manual}. +@end ifnottex + +@menu +* Init Syntax:: Syntax of constants in Emacs Lisp. +* Init Examples:: How to do some things with an init file. +* Terminal Init:: Each terminal type can have an init file. +* Find Init:: How Emacs finds the init file. +* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. +@end menu + +@node Init Syntax +@subsection Init File Syntax + + The @file{.emacs} file contains one or more Lisp function call +expressions. Each of these consists of a function name followed by +arguments, all surrounded by parentheses. For example, @code{(setq +fill-column 60)} calls the function @code{setq} to set the variable +@code{fill-column} (@pxref{Filling}) to 60. + + You can set any Lisp variable with @code{setq}, but with certain +variables @code{setq} won't do what you probably want in the +@file{.emacs} file. Some variables automatically become buffer-local +when set with @code{setq}; what you want in @file{.emacs} is to set +the default value, using @code{setq-default}. Some customizable minor +mode variables do special things to enable the mode when you set them +with Customize, but ordinary @code{setq} won't do that; to enable the +mode in your @file{.emacs} file, call the minor mode command. The +following section has examples of both of these methods. + + The second argument to @code{setq} is an expression for the new +value of the variable. This can be a constant, a variable, or a +function call expression. In @file{.emacs}, constants are used most +of the time. They can be: + +@table @asis +@item Numbers: +Numbers are written in decimal, with an optional initial minus sign. + +@item Strings: +@cindex Lisp string syntax +@cindex string syntax +Lisp string syntax is the same as C string syntax with a few extra +features. Use a double-quote character to begin and end a string constant. + +In a string, you can include newlines and special characters literally. +But often it is cleaner to use backslash sequences for them: @samp{\n} +for newline, @samp{\b} for backspace, @samp{\r} for carriage return, +@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for +escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or +@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. +Backslash and double-quote are the only characters for which backslash +sequences are mandatory. + +@samp{\C-} can be used as a prefix for a control character, as in +@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for +a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for +@kbd{Control-Meta-A}.@refill + +@xref{Init Non-ASCII}, for information about including +non-@acronym{ASCII} in your init file. + +@item Characters: +Lisp character constant syntax consists of a @samp{?} followed by +either a character or an escape sequence starting with @samp{\}. +Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that +strings and characters are not interchangeable in Lisp; some contexts +require one and some contexts require the other. + +@xref{Init Non-ASCII}, for information about binding commands to +keys which send non-@acronym{ASCII} characters. + +@item True: +@code{t} stands for `true'. + +@item False: +@code{nil} stands for `false'. + +@item Other Lisp objects: +Write a single-quote (@code{'}) followed by the Lisp object you want. +@end table + +@node Init Examples +@subsection Init File Examples + + Here are some examples of doing certain commonly desired things with +Lisp expressions: + +@itemize @bullet +@item +Make @key{TAB} in C mode just insert a tab if point is in the middle of a +line. + +@example +(setq c-tab-always-indent nil) +@end example + +Here we have a variable whose value is normally @code{t} for `true' +and the alternative is @code{nil} for `false'. + +@item +Make searches case sensitive by default (in all buffers that do not +override this). + +@example +(setq-default case-fold-search nil) +@end example + +This sets the default value, which is effective in all buffers that do +not have local values for the variable. Setting @code{case-fold-search} +with @code{setq} affects only the current buffer's local value, which +is not what you probably want to do in an init file. + +@item +@vindex user-mail-address +Specify your own email address, if Emacs can't figure it out correctly. + +@example +(setq user-mail-address "rumsfeld@@torture.gov") +@end example + +Various Emacs packages that need your own email address use the value of +@code{user-mail-address}. + +@item +Make Text mode the default mode for new buffers. + +@example +(setq default-major-mode 'text-mode) +@end example + +Note that @code{text-mode} is used because it is the command for +entering Text mode. The single-quote before it makes the symbol a +constant; otherwise, @code{text-mode} would be treated as a variable +name. + +@need 1500 +@item +Set up defaults for the Latin-1 character set +which supports most of the languages of Western Europe. + +@example +(set-language-environment "Latin-1") +@end example + +@need 1500 +@item +Turn off Line Number mode, a global minor mode. + +@example +(line-number-mode 0) +@end example + +@need 1500 +@item +Turn on Auto Fill mode automatically in Text mode and related modes. + +@example +(add-hook 'text-mode-hook + '(lambda () (auto-fill-mode 1))) +@end example + +This shows how to add a hook function to a normal hook variable +(@pxref{Hooks}). The function we supply is a list starting with +@code{lambda}, with a single-quote in front of it to make it a list +constant rather than an expression. + +It's beyond the scope of this manual to explain Lisp functions, but for +this example it is enough to know that the effect is to execute +@code{(auto-fill-mode 1)} when Text mode is entered. You can replace +that with any other expression that you like, or with several +expressions in a row. + +Emacs comes with a function named @code{turn-on-auto-fill} whose +definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler +way to write the above example is as follows: + +@example +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end example + +@item +Load the installed Lisp library named @file{foo} (actually a file +@file{foo.elc} or @file{foo.el} in a standard Emacs directory). + +@example +(load "foo") +@end example + +When the argument to @code{load} is a relative file name, not starting +with @samp{/} or @samp{~}, @code{load} searches the directories in +@code{load-path} (@pxref{Lisp Libraries}). + +@item +Load the compiled Lisp file @file{foo.elc} from your home directory. + +@example +(load "~/foo.elc") +@end example + +Here an absolute file name is used, so no searching is done. + +@item +@cindex loading Lisp libraries automatically +@cindex autoload Lisp libraries +Tell Emacs to find the definition for the function @code{myfunction} +by loading a Lisp library named @file{mypackage} (i.e.@: a file +@file{mypackage.elc} or @file{mypackage.el}): + +@example +(autoload 'myfunction "mypackage" "Do what I say." t) +@end example + +@noindent +Here the string @code{"Do what I say."} is the function's +documentation string. You specify it in the @code{autoload} +definition so it will be available for help commands even when the +package is not loaded. The last argument, @code{t}, indicates that +this function is interactive; that is, it can be invoked interactively +by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. +If the function is not interactive, omit the @code{t} or use +@code{nil}. + +@item +Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} +(@pxref{Init Rebinding}). + +@example +(global-set-key "\C-xl" 'make-symbolic-link) +@end example + +or + +@example +(define-key global-map "\C-xl" 'make-symbolic-link) +@end example + +Note once again the single-quote used to refer to the symbol +@code{make-symbolic-link} instead of its value as a variable. + +@item +Do the same thing for Lisp mode only. + +@example +(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) +@end example + +@item +Redefine all keys which now run @code{next-line} in Fundamental mode +so that they run @code{forward-line} instead. + +@findex substitute-key-definition +@example +(substitute-key-definition 'next-line 'forward-line + global-map) +@end example + +@item +Make @kbd{C-x C-v} undefined. + +@example +(global-unset-key "\C-x\C-v") +@end example + +One reason to undefine a key is so that you can make it a prefix. +Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a +prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix +definition. + +@item +Make @samp{$} have the syntax of punctuation in Text mode. +Note the use of a character constant for @samp{$}. + +@example +(modify-syntax-entry ?\$ "." text-mode-syntax-table) +@end example + +@item +Enable the use of the command @code{narrow-to-region} without confirmation. + +@example +(put 'narrow-to-region 'disabled nil) +@end example + +@item +Adjusting the configuration to various platforms and Emacs versions. + +Users typically want Emacs to behave the same on all systems, so the +same init file is right for all platforms. However, sometimes it +happens that a function you use for customizing Emacs is not available +on some platforms or in older Emacs versions. To deal with that +situation, put the customization inside a conditional that tests whether +the function or facility is available, like this: + +@example +(if (fboundp 'blink-cursor-mode) + (blink-cursor-mode 0)) + +(if (boundp 'coding-category-utf-8) + (set-coding-priority '(coding-category-utf-8))) +@end example + +@noindent +You can also simply disregard the errors that occur if the +function is not defined. + +@example +(condition case () + (set-face-background 'region "grey75") + (error nil)) +@end example + +A @code{setq} on a variable which does not exist is generally +harmless, so those do not need a conditional. +@end itemize + +@node Terminal Init +@subsection Terminal-specific Initialization + + Each terminal type can have a Lisp library to be loaded into Emacs when +it is run on that type of terminal. For a terminal type named +@var{termtype}, the library is called @file{term/@var{termtype}} and it is +found by searching the directories @code{load-path} as usual and trying the +suffixes @samp{.elc} and @samp{.el}. Normally it appears in the +subdirectory @file{term} of the directory where most Emacs libraries are +kept.@refill + + The usual purpose of the terminal-specific library is to map the +escape sequences used by the terminal's function keys onto more +meaningful names, using @code{function-key-map}. See the file +@file{term/lk201.el} for an example of how this is done. Many function +keys are mapped automatically according to the information in the +Termcap data base; the terminal-specific library needs to map only the +function keys that Termcap does not specify. + + When the terminal type contains a hyphen, only the part of the name +before the first hyphen is significant in choosing the library name. +Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use +the library @file{term/aaa}. The code in the library can use +@code{(getenv "TERM")} to find the full terminal type name.@refill + +@vindex term-file-prefix + The library's name is constructed by concatenating the value of the +variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} +file can prevent the loading of the terminal-specific library by setting +@code{term-file-prefix} to @code{nil}. + +@vindex term-setup-hook + Emacs runs the hook @code{term-setup-hook} at the end of +initialization, after both your @file{.emacs} file and any +terminal-specific library have been read in. Add hook functions to this +hook if you wish to override part of any of the terminal-specific +libraries and to define initializations for terminals that do not have a +library. @xref{Hooks}. + +@node Find Init +@subsection How Emacs Finds Your Init File + + Normally Emacs uses the environment variable @env{HOME} +(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what +@samp{~} means in a file name. If @file{.emacs} is not found inside +@file{~/} (nor @file{.emacs.el}), Emacs looks for +@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be +byte-compiled). + + However, if you run Emacs from a shell started by @code{su}, Emacs +tries to find your own @file{.emacs}, not that of the user you are +currently pretending to be. The idea is that you should get your own +editor customizations even if you are running as the super user. + + More precisely, Emacs first determines which user's init file to use. +It gets your user name from the environment variables @env{LOGNAME} and +@env{USER}; if neither of those exists, it uses effective user-ID. +If that user name matches the real user-ID, then Emacs uses @env{HOME}; +otherwise, it looks up the home directory corresponding to that user +name in the system's data base of users. +@c LocalWords: backtab + +@node Init Non-ASCII +@subsection Non-@acronym{ASCII} Characters in Init Files +@cindex international characters in @file{.emacs} +@cindex non-@acronym{ASCII} characters in @file{.emacs} +@cindex non-@acronym{ASCII} keys, binding +@cindex rebinding non-@acronym{ASCII} keys + + Language and coding systems may cause problems if your init file +contains non-@acronym{ASCII} characters, such as accented letters, in +strings or key bindings. + + If you want to use non-@acronym{ASCII} characters in your init file, +you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on +the first line of the init file, and specify a coding system that +supports the character(s) in question. @xref{Recognize Coding}. This +is because the defaults for decoding non-@acronym{ASCII} text might +not yet be set up by the time Emacs reads those parts of your init +file which use such strings, possibly leading Emacs to decode those +strings incorrectly. You should then avoid adding Emacs Lisp code +that modifies the coding system in other ways, such as calls to +@code{set-language-environment}. + + To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init +Rebinding}). The string syntax cannot be used, since the +non-@acronym{ASCII} characters will be interpreted as meta keys. For +instance: + +@example +(global-set-key [?@var{char}] 'some-function) +@end example + +@noindent +Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. + + @strong{Warning:} if you change the keyboard encoding, or change +between multibyte and unibyte mode, or anything that would alter which +code @kbd{C-q} would insert for that character, this keybinding may +stop working. It is therefore advisable to use one and only one +coding system, for your init file as well as the files you edit. For +example, don't mix the @samp{latin-1} and @samp{latin-9} coding +systems. + +@ignore + arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 +@end ignore