Mercurial > emacs
changeset 84136:188bfc00a73d
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:34:45 +0000 |
| parents | f4695268a6d7 |
| children | a5fd9622b3d5 |
| files | man/custom.texi |
| diffstat | 1 files changed, 0 insertions(+), 2515 deletions(-) [+] |
line wrap: on
line diff
--- a/man/custom.texi Thu Sep 06 04:34:40 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2515 +0,0 @@ -@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