[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/man/custom.texi [gnus-5_10-branch]
|
From: |
Miles Bader |
|
Subject: |
[Emacs-diffs] Changes to emacs/man/custom.texi [gnus-5_10-branch] |
|
Date: |
Sat, 04 Sep 2004 08:30:19 -0400 |
Index: emacs/man/custom.texi
diff -c /dev/null emacs/man/custom.texi:1.64.2.1
*** /dev/null Sat Sep 4 12:02:54 2004
--- emacs/man/custom.texi Sat Sep 4 12:01:14 2004
***************
*** 0 ****
--- 1,2303 ----
+ @c This is part of the Emacs manual.
+ @c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002
+ @c 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 minor ways. See @cite{The Emacs Lisp Reference
+ Manual} for how to make more far-reaching 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
+ @file{.emacs} or @file{.Xdefaults} that will affect future sessions.
+ @xref{Init File}. In the customization buffer, when you 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.
+ * 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".
+ * Keyboard Translations::
+ If your keyboard passes an undesired code
+ for a key, you can tell Emacs to
+ substitute another code.
+ * 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 on; for example, @samp{Fill} in the mode line means
+ that Auto Fill mode is on.
+
+ Append @code{-mode} to the name of a minor mode to get the name of a
+ command function that turns the mode on or off. Thus, the command to
+ enable or disable Auto Fill mode is called @kbd{M-x 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 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 which directly controls the mode. The mode is enabled
+ whenever this variable's value is address@hidden, and the minor-mode
+ command works by setting the variable. For example, the command
+ @code{outline-minor-mode} works by setting the value of
+ @code{outline-minor-mode} as a variable; it is this variable that
+ directly turns Outline minor mode on and off. To check whether a
+ given minor mode works this way, use @kbd{C-h v} to ask for
+ documentation on the variable name.
+
+ These minor-mode variables provide a good way for Lisp programs to turn
+ minor modes on and off; they are also useful in a file's local variables
+ list. But please think twice before setting minor modes with a local
+ variables list, because most minor modes are matter of user
+ preference---other users editing the same file might not want the same
+ minor modes you prefer.
+
+ The buffer-local minor modes include Abbrev mode, Auto Fill mode,
+ Auto Save mode, Font-Lock mode, Glasses mode, ISO Accents 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 causes the contents of a buffer to be saved
+ periodically to reduce the amount of work you can lose in case of a
+ system 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 window system that can display multiple fonts.
+ @xref{Faces}.
+
+ 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{Single-Byte Character Support}.
+
+ 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.
+
+ The following minor modes normally apply to all buffers at once.
+ Since each is enabled or disabled by the value of a variable, you
+ @emph{can} set them differently for particular buffers, by explicitly
+ making the corresponding variables 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 (currently only when using X). @xref{Mark}.
+
+ @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.
+
+ Lisp allows any variable to have any kind of value, but most variables
+ that Emacs uses require 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 address@hidden,'' 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, as any
+ Lisp program must, but the most interesting variables for you are the
+ ones that exist for the sake of customization. Emacs does not (usually)
+ change the values of these variables; instead, you set the values, and
+ thereby alter and control the behavior of certain Emacs commands. These
+ variables are called @dfn{user options}. Most user options are
+ documented in this manual, and appear in the Variable Index
+ (@pxref{Variable Index}).
+
+ One example of a variable which is a user option is @code{fill-column},
which
+ specifies the position of the right margin (as a number of characters from
+ the left margin) to be used by the fill commands (@pxref{Filling}).
+
+ @menu
+ * Examining:: Examining or setting one variable's value.
+ * Easy Customization::
+ Convenient and easy customization of variables.
+ * 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's value is 70
+
+ Documentation:
+ *Column beyond which automatic line-wrapping should happen.
+ Automatically becomes buffer-local when set in any fashion.
+ @end smallexample
+
+ @noindent
+ The star at the beginning of the documentation indicates that this
+ variable is a user option. @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 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. 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.
+
+ @node Easy Customization
+ @subsection Easy Customization Interface
+
+ @findex customize
+ @cindex customization buffer
+ A convenient way to find the user option variables that you want to
+ change, and then change them, is with @kbd{M-x customize}. This
+ command creates a @dfn{customization buffer} with which you can browse
+ through the Emacs user options in a logically organized structure,
+ then edit and set their values. You can also use the customization
+ buffer to save settings permanently in your @file{~/.emacs} file
+ (@pxref{Init File}).
+
+ The appearance of the example buffers in the following is typically
+ different under a window system where faces can be used to indicate the
+ active fields and other features.
+
+ @menu
+ * Groups: Customization Groups.
+ How options are classified in a structure.
+ * Changing an Option:: How to edit a value and set an option.
+ * Saving Customizations:: Details of saving customizations.
+ * Face Customization:: How to edit the attributes of a face.
+ * Specific Customization:: Making a customization buffer for specific
+ options, faces, or groups.
+ @end menu
+
+ @node Customization Groups
+ @subsubsection Customization Groups
+ @cindex customization groups
+
+ For customization purposes, user options 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:
+
+ @smallexample
+ /- Emacs group: ---------------------------------------------------\
+ [State]: visible group members are all at standard settings.
+ Customization of the One True Editor.
+ See also [Manual].
+
+ Confirm Kill Emacs: [Hide] [Value Menu] Don't confirm
+ [State]: this option is unchanged from its standard setting.
+ How to ask for confirmation when leaving Emacs. [More]
+
+ 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 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 active fields (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{active fields}; this means a field that does something
+ when you @dfn{invoke} it. To invoke an active field, either click on it
+ with @kbd{Mouse-1}, or move point to it and type @key{RET}.
+
+ For example, the phrase @samp{[Go to Group]} that appears in a
+ second-level group is an active field. Invoking the @samp{[Go to
+ Group]} field for a group creates a new customization buffer, which
+ shows that group and its contents. This field is a kind of hypertext
+ link to another group.
+
+ The @code{Emacs} group includes a few user options itself, but
+ mainly it contains other groups, which contain more groups, which
+ contain the user options. 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 the options and faces
+ pertaining to that feature. You can also go straight to a particular
+ group by name, using the command @kbd{M-x customize-group}.
+
+ @findex customize-browse
+ You can view the structure of customization groups on a larger scale
+ with @kbd{M-x customize-browse}. This command creates a special kind of
+ customization buffer which shows only the names of the groups (and
+ options and faces), and their structure.
+
+ In this buffer, you can show the contents of a group by invoking
+ @samp{[+]}. When the group contents are visible, this button changes to
+ @samp{[-]}; invoking that hides the group contents.
+
+ Each group, option or face name in this buffer has an active field
+ which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking
+ that active field creates an ordinary customization buffer showing just
+ that group and its contents, just that option, or just that face.
+ This is the way to set values in it.
+
+ @node Changing an Option
+ @subsubsection Changing an Option
+
+ Here is an example of what a user option looks like in the
+ customization buffer:
+
+ @smallexample
+ Kill Ring Max: [Hide] 60
+ [State]: this option is unchanged from its standard setting.
+ Maximum length of kill ring before oldest elements are thrown away.
+ @end smallexample
+
+ The text following @samp{[Hide]}, @samp{60} in this case, indicates
+ the current value of the option. If you see @samp{[Show]} instead of
+ @samp{[Hide]}, it means that the value is hidden; the customization
+ buffer initially hides values that take up several lines. Invoke
+ @samp{[Show]} to show the value.
+
+ The line after the option name indicates the @dfn{customization state}
+ of the option: in the example above, it says you have not changed the
+ option yet. The word @samp{[State]} at the beginning of this line is
+ active; you can get a menu of various operations by invoking it with
+ @kbd{Mouse-1} or @key{RET}. These operations are essential for
+ customizing the variable.
+
+ The line after the @samp{[State]} line displays the beginning of the
+ option's documentation string. If there are more lines of
+ documentation, this line ends with @samp{[More]}; invoke this 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.
+
+ When you begin to alter the text, you will see the @samp{[State]} line
+ change to say that you have edited the value:
+
+ @smallexample
+ [State]: you have edited the value as text, but not set the option.
+ @end smallexample
+
+ @cindex setting option value
+ Editing the value does not actually set the option variable. To do
+ that, you must @dfn{set} the option. To do this, invoke the word
+ @samp{[State]} and choose @samp{Set for Current Session}.
+
+ The state of the option changes visibly when you set it:
+
+ @smallexample
+ [State]: you have set this option, but not saved it for future sessions.
+ @end smallexample
+
+ You don't have to worry about specifying a value that is not valid;
+ setting the option checks for validity and will not really install an
+ unacceptable value.
+
+ @kindex M-TAB @r{(customization buffer)}
+ @findex widget-complete
+ While editing a value or field that is a file name, directory name,
+ command name, or anything else for which completion is defined, you can
+ type @address@hidden (@code{widget-complete}) to do completion.
+
+ Some options have a small fixed set of possible legitimate values.
+ These options don't let you edit the value textually. Instead, an
+ active field @samp{[Value Menu]} appears before the value; invoke this
+ field to edit the value. For a boolean ``on or off'' value, the active
+ field says @samp{[Toggle]}, and it changes to the other value.
+ @samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes
+ take effect when you use the @samp{Set for Current Session} operation.
+
+ Some options 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]
+ [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]: this option is unchanged from its standard setting.
+ Alist to decide a coding system to use for a file I/O operation. [Hide]
+ The format is ((PATTERN . VAL) ...),
+ where PATTERN is a regular expression matching a file name,
+ @address@hidden lines of address@hidden
+ @end smallexample
+
+ @noindent
+ Each association in the list appears on four lines, with several
+ editable or ``active'' fields. You can edit the regexps and coding
+ systems using ordinary editing commands. You can also invoke
+ @samp{[Value Menu]} to switch to a 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 association, another at the beginning and another
+ at the end, so you can add the 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 @address@hidden, are useful for
+ moving through the customization buffer. @key{TAB}
+ (@code{widget-forward}) moves forward to the next active or editable
+ field; @address@hidden (@code{widget-backward}) moves backward to the
+ previous active 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 option value
+ @cindex customized options, saving
+ Setting the option changes its value in the current Emacs session;
+ @dfn{saving} the value changes it for future sessions as well. To
+ save the option, invoke @samp{[State]} and select the @samp{Save for
+ Future Sessions} operation. This works by writing code so as to set
+ the option variable again each time you start Emacs (@pxref{Saving
+ Customizations}).
+
+ You can also restore the option to its standard value by invoking
+ @samp{[State]} and selecting the @samp{Erase Customization} operation.
+ There are actually three reset operations:
+
+ @table @samp
+ @item Reset
+ If you have made some modifications and not yet set the option,
+ this restores the text in the customization buffer to match
+ the actual value.
+
+ @item Reset to Saved
+ This restores the value of the option to the last saved value,
+ and updates the text accordingly.
+
+ @item Erase Customization
+ This sets the option to its standard value, and updates the text
+ accordingly. This also eliminates any saved value for the option,
+ so that you will get the standard value in future Emacs sessions.
+
+ @item Use Backup Value
+ This sets the option to a previous value that was set in the
+ customization buffer in this session. If you customize a variable
+ and then reset the variable, which discards the customized value,
+ you can get the customized value back again with this operation.
+ @end table
+
+ @cindex comments on customized options
+ 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 option 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. You can select @samp{Set for Current Session},
+ @samp{Save for Future Sessions} and the various kinds of @samp{Reset}
+ operation for the group; these operations on the group apply to all
+ options in the group and its subgroups.
+
+ Near the top of the customization buffer there are two lines
+ containing several active fields:
+
+ @smallexample
+ [Set for Current Session] [Save for Future Sessions]
+ [Reset] [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-function}; the default is to bury the buffer.
+ Each of the other fields performs an operation---set, save or
+ reset---on each of the items in the buffer that could meaningfully be
+ set, saved or reset.
+
+ @node Saving Customizations
+ @subsubsection Saving Customizations
+
+ @vindex custom-file
+ The customization buffer normally saves customizations in
+ @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. Emacs loads the file
+ right after your @file{.emacs} if you did not load it already. For
+ example:
+
+ @example
+ (setq custom-file "~/.emacs-custom")
+ @end example
+
+ The variable @code{custom-file} is useful if you want to have
+ different customizations for different Emacs versions:
+
+ @example
+ (if (< emacs-major-version 21)
+ ;; @r{Emacs 20 customization.}
+ (setq custom-file "~/.custom-20.el")
+ ;; @r{Emacs 21 customization.}
+ (setq custom-file "~/.custom-21.el"))
+ @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
+ @subsubsection Customizing Faces
+ @cindex customizing faces
+ @cindex bold font
+ @cindex italic font
+ @cindex fonts and faces
+
+ In addition to user options, some customization groups also include
+ faces. When you show the contents of a group, both the user options 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]
+ [State]: this face is unchanged from its standard setting.
+ 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 @address@hidden field
+ before the attribute name indicates whether the attribute is
+ @dfn{enabled}; @samp{X} means that it is. You can enable or disable the
+ attribute by invoking that field. When the attribute is enabled, you
+ can change the attribute value in the usual ways.
+
+ 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
+ options (@pxref{Changing an Option}).
+
+ 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{Show all display specs} 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
+ @subsubsection Customizing Specific Items
+
+ Instead of finding the options you want to change by moving down
+ through the structure of groups, you can specify the particular option,
+ face or group 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 option, @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 options, faces and groups
+ that match @var{regexp}.
+ @item M-x customize-changed-options @key{RET} @var{version} @key{RET}
+ Set up a customization buffer with all the options, faces and groups
+ whose meaning has changed since Emacs version @var{version}.
+ @item M-x customize-saved
+ Set up a customization buffer containing all options and faces that you
+ have saved with customization buffers.
+ @item M-x customize-customized
+ Set up a customization buffer containing all options and faces that you
+ have customized but not saved.
+ @end table
+
+ @findex customize-option
+ If you want to alter a particular user option variable with the
+ customization buffer, and you know its name, you can use the command
+ @kbd{M-x customize-option} and specify the option name. This sets up
+ the customization buffer with just one option---the one that you asked
+ for. Editing, setting and saving the value work as described above, but
+ only for the specified option.
+
+ @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 option variables, faces, and other groups, all appear
+ as well. However, these subgroups' own contents start out hidden. You
+ can show their contents in the usual way, by invoking @samp{[Show]}.
+
+ @findex customize-apropos
+ To control more precisely what to customize, you can use @kbd{M-x
+ customize-apropos}. You specify a regular expression as argument; then
+ all options, faces 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} groups, options and faces in the
+ customization buffer (but that takes a long time).
+
+ @findex customize-changed-options
+ When you upgrade to a new Emacs version, you might want to customize
+ new options and options whose meanings or default values have changed.
+ To do this, use @kbd{M-x customize-changed-options} and specify a
+ previous Emacs version number using the minibuffer. It creates a
+ customization buffer which shows all the options (and groups) whose
+ definitions have been changed since the specified version.
+
+ @findex customize-saved
+ @findex customize-customized
+ If you change option values 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 options and faces that you have
+ saved. Use @kbd{M-x customize-customized} to look at the options and
+ faces that you have set but not saved.
+
+ @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 address@hidden value, the rest
+ are not called at all. The documentation of each abnormal hook variable
+ explains in detail what is peculiar about it.
+
+ The recommended way to add a hook function to a hook (either normal or
+ abnormal) is by calling @code{add-hook}. You can use any valid Lisp
+ function as the hook function, provided it can handle the proper number
+ of arguments (zero arguments, in the case of a normal hook). Of course,
+ not every Lisp function is @emph{useful} in any particular hook.
+
+ 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.
+
+ @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. Further changes in this buffer will not
+ affect others, and further changes in the global value will not affect this
+ buffer.
+
+ @findex make-variable-buffer-local
+ @cindex per-buffer variables
+ @kbd{M-x make-variable-buffer-local} reads the name of a variable and
+ changes the future behavior of the variable so that it will become local
+ automatically when 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.
+
+ 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 address@hidden when the mode is enabled (@pxref{Minor
+ Modes}). For most minor modes, the controlling variable is per buffer.
+
+ Emacs contains a number of variables that are always per-buffer.
+ These include @code{abbrev-mode}, @code{auto-fill-function},
+ @code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
+ @code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
+ @code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},
+ @code{selective-display-ellipses}, @code{selective-display},
+ @code{tab-width}, and @code{truncate-lines}. Some other variables are
+ always local in every buffer, but they are used for internal
+ address@hidden
+
+ 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} reads the name of a variable and makes
+ it 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.
+
+ There are two ways to specify 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}.
+
+ 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
+ for this, when Emacs visits a shell script, it looks for local variable
+ specifications in the @emph{second} line.
+
+ 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
+ @address@hidden:@: @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
+
+ As you see, 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.
+
+ Two ``variable names'' have special meanings in a local variables
+ list: a value for the variable @code{mode} really sets the major mode,
+ and a value for the variable @code{eval} is simply evaluated as an
+ expression and the value is ignored. @code{mode} and @code{eval} are
+ not real variables; setting variables named @code{mode} and @code{eval}
+ 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 in the list of the local
+ variables are likely to 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
+ 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 in
+ any fashion, 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}.
+
+ @findex enable-local-variables
+ The variable @code{enable-local-variables} controls whether to process
+ local variables in files, and thus gives you a chance to override them.
+ Its default value is @code{t}, which means do process local variables in
+ files. If you set the value to @code{nil}, Emacs simply ignores local
+ variables in files. Any other value says to query you about each file
+ that has local variables, showing you the local variable specifications
+ so you can judge.
+
+ @findex enable-local-eval
+ The @code{eval} ``variable,'' and certain actual variables, create a
+ special risk; when you visit someone else's file, local variable
+ specifications for these could affect your Emacs in arbitrary ways.
+ Therefore, the option @code{enable-local-eval} controls whether Emacs
+ processes @code{eval} variables, as well variables with names that end
+ in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions},
+ and certain other variables. The three possibilities for the option'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 file settings for these variables.
+
+ @findex safe-local-eval-forms
+ The @code{safe-local-eval-forms} is a customizable list of eval
+ forms which are safe to eval, so Emacs should not ask for
+ confirmation to evaluate these forms, even if
+ @code{enable-local-variables} says to ask for confirmation in general.
+
+ @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.
+ * Non-ASCII Rebinding:: Rebinding address@hidden characters such as Latin-1.
+ * 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
+ @address@hidden 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 many 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 @address@hidden [}.) 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 @address@hidden 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{Ctl-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.
+
+ @vindex c-mode-map
+ @vindex lisp-mode-map
+ The local keymaps for Lisp mode and several other major modes always
+ exist even when not in use. These are kept in variables named
+ @code{lisp-mode-map} and so on. For major modes less often used, the
+ local keymap is normally constructed only when the mode is used for the
+ first time in a session. This is to save space. If you wish to change
+ one of these keymaps, you must use the major mode's @dfn{mode
+ hook}---see below.
+
+ All minor mode keymaps are created in advance. There is no way to
+ defer their creation until the first time the minor mode is enabled.
+
+ 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 ordinary circumstances.
+
+ @cindex rebinding major mode keys
+ @findex define-key
+ To change the local bindings of a major mode, you must change the
+ mode's local keymap. Normally you must wait until the first time the
+ mode is used, because most major modes don't create their keymaps until
+ then. If you want to specify something in your @file{~/.emacs} file to
+ change a major mode's bindings, you must use the mode's mode hook to
+ delay the change until the mode is first used.
+
+ 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
+
+ @xref{Hooks}.
+
+ @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
+ 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.
+ @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; the minibuffer is entered immediately to
+ read @var{cmd}. But if you type @kbd{C-x}, another character is read;
+ if that is @kbd{4}, another character is read, 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 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}.
+ 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 a key sequence two characters long:
+
+ @example
+ (global-set-key "\C-xl" '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 address@hidden 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 three examples above, using vectors to bind
+ @kbd{C-z}, @kbd{C-x l}, and @kbd{C-x @key{TAB}}:
+
+ @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 each of the characters within the square brackets that
+ delimit the vector.
+
+ Language and coding systems can cause problems with key bindings
+ for address@hidden characters. @xref{Non-ASCII Rebinding}.
+
+ @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. The vector
+ syntax uses spaces between the elements, and square brackets around the
+ whole vector. 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 @address@hidden move forward a
+ word:
+
+ @example
+ (global-set-key [H-M-right] 'forward-word)
+ @end example
+
+ @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. Later, users found it
+ convenient to distinguish in Emacs between these keys and the ``same''
+ control characters typed with the @key{CTRL} key.
+
+ Emacs distinguishes these two kinds of input, when the keyboard
+ reports these keys to Emacs. 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 Non-ASCII Rebinding
+ @subsection address@hidden Characters on the Keyboard
+ @cindex rebinding address@hidden keys
+ @cindex address@hidden keys, binding
+
+ If your keyboard has keys that send address@hidden
+ characters, such as accented letters, rebinding these keys
+ must be done by using a vector like address@hidden that
+ you should avoid the string syntax for binding
+ address@hidden characters, since they will be
+ interpreted as meta keys. @xref{Strings of Events,,,elisp,
+ The Emacs Lisp Reference Manual}.}:
+
+ @example
+ (global-set-key address@hidden 'some-function)
+ @end example
+
+ @noindent
+ Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
+
+ Since this puts a address@hidden character in the @file{.emacs},
+ you should specify for that file a coding system that supports
+ that character. @xref{Init Syntax}.
+
+ @strong{Warning:} if you change the keyboard encoding, such that the code that
+ @kbd{C-q} inserts becomes different, you'll need to edit the
+ Lisp expression accordingly.
+
+ @strong{Warning:} @kbd{C-q} will insert the wrong code if you visit
+ the file @file{.emacs} in a unibyte buffer, so don't do that.
+
+ @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 you
+ can distinguish if you really want to. 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 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.)
+ @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 marks the command as requiring confirmation before it
+ can be executed. The purpose of disabling a command is to prevent
+ beginning users from executing it by accident and being confused.
+
+ An attempt 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 are
+ asked 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
+ address@hidden @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. This is because editing the init file from
+ such a session might overwrite the lines you might have on your init
+ file which enable and disable commands.
+
+ 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}. Disabling a command has no effect on calling it as a
+ function from Lisp programs.
+
+ @node Keyboard Translations
+ @section Keyboard Translations
+
+ Some keyboards do not make it convenient to send all the special
+ characters that Emacs uses. The most common problem case is the
+ @key{DEL} character. Some keyboards provide no convenient way to type
+ this very important character---usually because they were designed to
+ expect the character @kbd{C-h} to be used for deletion. On these
+ keyboards, if you press the key normally used for deletion, Emacs handles
+ the @kbd{C-h} as a prefix character and offers you a list of help
+ options, which is not what you want.
+
+ @cindex keyboard translations
+ @findex keyboard-translate
+ You can work around this problem within Emacs by setting up keyboard
+ translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into
+ @kbd{C-h}, as follows:
+
+ @example
+ ;; @r{Translate @kbd{C-h} to @key{DEL}.}
+ (keyboard-translate ?\C-h ?\C-?)
+
+ ;; @r{Translate @key{DEL} to @kbd{C-h}.}
+ (keyboard-translate ?\C-? ?\C-h)
+ @end example
+
+ Keyboard translations are not the same as key bindings in keymaps
+ (@pxref{Keymaps}). Emacs contains numerous keymaps that apply in
+ different situations, but there is only one set of keyboard
+ translations, and it applies to every character that Emacs reads from
+ the terminal. Keyboard translations take place at the lowest level of
+ input processing; the keys that are looked up in keymaps contain the
+ characters that result from keyboard translation.
+
+ On a window system, the keyboard key named @key{DELETE} is a function
+ key and is distinct from the @acronym{ASCII} character named @key{DEL}.
+ @xref{Named ASCII Chars}. Keyboard translations affect only @acronym{ASCII}
+ character input, not function keys; thus, the above example used on a
+ window system does not affect the @key{DELETE} key. However, the
+ translation above isn't necessary on window systems, because Emacs can
+ also distinguish between the @key{BACKSPACE} key and @kbd{C-h}; and it
+ normally treats @key{BACKSPACE} as @key{DEL}.
+
+ For full information about how to use keyboard translations, see
+ @ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.
+
+ @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 both 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. 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}).
+
+ @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} address@hidden, 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}.
+
+ 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}.
+ @ifinfo
+ @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
+ Manual}.
+ @end ifinfo
+
+ @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.
+ @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
+ @address@hidden 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
+ @address@hidden
+
+ @cindex international characters in @file{.emacs}
+ @cindex address@hidden characters in @file{.emacs}
+ If you want to include address@hidden characters in strings in your init
+ file, you should consider putting a @address@hidden:
+ @var{coding-system}-*-}} tag on the first line which states the coding
+ system used to save your @file{.emacs}, as explained in @ref{Recognize
+ Coding}. This is because the defaults for decoding address@hidden 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.
+
+ @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{Non-ASCII Rebinding}, for information about binding commands to
+ keys which send address@hidden 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 "coon@@yoyodyne.com")
+ @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}.
+
+ @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
+ @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
+ address@hidden
+
+ 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 address@hidden
+
+ @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} to find
+ @file{.emacs}; that's what @samp{~} means in a file name. But 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 the 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
+
+ @ignore
+ arch-tag: c68abddb-4410-4fb5-925f-63394e971d93
+ @end ignore
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/man/custom.texi [gnus-5_10-branch],
Miles Bader <=