@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Customization, Quitting, Amusements, Top
@chapter 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.
-
- All kinds of customization affect only the particular Emacs session
-that you do them in. They are completely lost when you kill the Emacs
-session, and have no effect on other Emacs sessions you may run at the
-same time or later. The only way an Emacs session can affect anything
-outside of it is by writing a file; in particular, the only way to make
-a customization ``permanent'' is to put something in your @file{.emacs}
-file or other appropriate file to do the customization in each session.
-@xref{Init File}.
+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.
+* Easy Customization:: Convenient way to browse and change user options.
* Variables:: Many Emacs commands examine Emacs variables
to decide what to do; by setting variables,
you can control their functioning.
-* Keyboard Macros:: A keyboard macro records a sequence of
- keystrokes to be replayed with a single
- command.
* 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.
+ expressions are parsed.
* Init File:: How to write common customizations in the
- @file{.emacs} file.
+ @file{.emacs} file.
@end menu
@node Minor Modes
argument always turns the mode on, and an explicit zero argument or a
negative argument always turns it off.
- Enabling or disabling some minor modes applies only to the current
-buffer; each buffer is independent of the other buffers. Therefore, you
-can enable the mode in particular buffers and disable it in others. The
-per-buffer minor modes include Abbrev mode, Auto Fill mode, Auto Save
-mode, Font-Lock mode, ISO Accents mode, Outline minor
-mode, Overwrite mode, and Binary Overwrite mode.
+ 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 non-@code{nil}, 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 (@pxref{File Variables}). But please think twice
+before setting minor modes with a local variables list, because most
+minor modes are a matter of user preference---other users editing the
+same file might not want the same minor modes you prefer.
+
+ The most useful buffer-local minor modes include Abbrev mode, Auto
+Fill mode, Auto Save mode, Font-Lock mode, Glasses mode, 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
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.
-@xref{Single-Byte Character Support}.
+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
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}.
+ Here are some useful minor modes that 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
The advantage of Transient Mark mode is that Emacs can display the
region highlighted (currently only when using X). @xref{Mark}.
- 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 non-@code{nil}, 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.
+@node Easy Customization
+@section Easy Customization Interface
-@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 ``non-@code{nil},'' meaning
-that if the variable's value is @code{nil}, the feature is off, but the
-feature is on for @emph{any} other value. The conventional value to use to
-turn on the feature---since you have to pick one particular value when you
-set the variable---is @code{t}.
-
- Emacs uses many Lisp variables for internal record keeping, 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
+ Emacs has many @dfn{user options} which have values that you can set
+in order to customize various commands. Many user options are
+documented in this manual. Most user options are actually Lisp
+variables (@pxref{Variables}), so their names appear in the Variable
+Index (@pxref{Variable Index}). The rest are faces and their
+attributes (@pxref{Faces}).
@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. (Not all Emacs user options are included in this
-structure as of yet, but we are adding the rest.)
-
-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.
+ You can browse interactively through the user options and change
+some of them using @kbd{M-x customize}. This command creates a
+@dfn{customization buffer}, which offers commands to navigate through
+a logically organized structure of the Emacs user options; you can
+also use it to edit and set their values, and to save settings
+permanently in your @file{~/.emacs} file (@pxref{Init File}).
+
+ The appearance of the example buffers in this section is typically
+different under a window system, since faces are then 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.
+* Groups: Customization Groups. How options are classified in a structure.
+* Changing a Variable:: 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.
+ variables, faces, or groups.
@end menu
@node Customization Groups
-@subsubsection Customization Groups
+@subsection Customization Groups
@cindex customization groups
For customization purposes, user options are organized into
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]
+Editing group: [Go to Group]
Basic text editing facilities.
-External group: [Go to Group]
+External group: [Go to Group]
Interfacing to external utilities.
@var{more second-level groups}
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 most
-of them are in other groups. By examining various groups, you will
-eventually find the options and faces that belong to the feature you
-are interested in customizing. Then you can use the customization
-buffer to set them. You can go straight to a particular group by name
-using the command @kbd{M-x customize-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
+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.
+variables 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
+ Each group, variable, or face name in this buffer has an active field
+which says @samp{[Group]}, @samp{[Variable]} 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.
+that group and its contents, just that variable, or just that face.
This is the way to set values in it.
-@node Changing an Option
-@subsubsection Changing an Option
+@node Changing a Variable
+@subsection Changing a Variable
- Here is an example of what a user option looks like in the
+ Here is an example of what a variable looks like in the
customization buffer:
@smallexample
Kill Ring Max: [Hide] 60
- [State]: this option is unchanged from its standard setting.
+ [State]: this variable 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
+the current value of the variable. 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
+of the variable: 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
+variable's documentation string. If there are more lines of
documentation, this line ends with @samp{[More]}; invoke this to show
the full documentation string.
change to say that you have edited the value:
@smallexample
-[State]: you have edited the value as text, but not set the option.
+[State]: you have edited the value as text, but not set the variable.
@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
+ Editing the value does not actually set the variable. To do
+that, you must @dfn{set} it. 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:
+ The state of the variable changes visibly when you set it:
@smallexample
-[State]: you have set this option, but not saved it for future sessions.
+[State]: you have set this variable, 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
+setting the variable 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 @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
+command name, or anything else for which completion is defined, you
+can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion.
+(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.)
- Some options have a small fixed set of possible legitimate values.
-These options don't let you edit the value textually. Instead, an
+ Some variables have a small fixed set of possible legitimate values.
+These variables 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
+ Some variables have values with complex structure. For example, the
value of @code{file-coding-system-alist} is an association list. Here
is how it appears in the customization buffer:
Decoding: undecided
Encoding: nil
[INS]
- [State]: this option is unchanged from its standard setting.
+ [State]: this variable 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,
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. This
-works by writing code into your @file{~/.emacs} file so as to set the
-option variable again each time you start Emacs. To save the option,
-invoke @samp{[State]} and select the @samp{Save for Future Sessions}
-operation.
-
- 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.
+@cindex saving variable value
+@cindex customized variables, saving
+ Setting the variable changes its value in the current Emacs session;
+@dfn{saving} the value changes it for future sessions as well. To
+save the variable, invoke @samp{[State]} and select the @samp{Save for
+Future Sessions} operation. This works by writing code so as to set
+the variable again, each time you start Emacs (@pxref{Saving
+Customizations}).
- You can also restore the option to its standard value by invoking
-@samp{[State]} and selecting the @samp{Erase Customization}
-operation. There are actually three reset operations:
+ You can also restore the variable 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,
+If you have made some modifications and not yet set the variable,
this restores the text in the customization buffer to match
the actual value.
@item Reset to Saved
-This restores the value of the option to the last saved value,
+This restores the value of the variable 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
+This sets the variable 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 variable to a previous value that was set in the
+customization buffer in this session. If you customize a variable
+and then reset it, which discards the customized value,
+you can get the customized value back again with this operation.
@end table
@cindex comments on customized options
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 same variable in a customization buffer, even in another session.
The state of a group indicates whether anything in that group has been
edited, set or saved. You can select @samp{Set for Current Session},
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.
+reset---on each of the options in the buffer that could meaningfully
+be set, saved or reset. They do not operate on options whose values
+are hidden.
+
+@node Saving Customizations
+@subsection 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. Then you should load the
+file by calling @code{load}. For example:
+
+@example
+(setq custom-file "~/.emacs-custom.el")
+(load custom-file)
+@end example
+
+ You can also use @code{custom-file} to specify different
+customization files for different Emacs versions, like this:
+
+@example
+(cond ((< emacs-major-version 21)
+ ;; @r{Emacs 20 customization.}
+ (setq custom-file "~/.custom-20.el"))
+ ((and (= emacs-major-version 21) (< emacs-minor-version 4))
+ ;; @r{Emacs 21 customization, before version 21.4.}
+ (setq custom-file "~/.custom-21.el"))
+ ((< emacs-major-version 22)
+ ;; @r{Emacs version 21.4 or later.}
+ (setq custom-file "~/.custom-21.4.el"))
+ (t
+ ;; @r{Emacs version 22.1 or later.}
+ (setq custom-file "~/.custom-22.el")))
+
+(load custom-file)
+@end example
+
+ If Emacs was invoked with the @option{-q} or @option{--no-init-file}
+options (@pxref{Initial Options}), it will not let you save your
+customizations in your @file{~/.emacs} init file. This is because
+saving customizations from such a session would wipe out all the other
+customizations you might have on your init file.
@node Face Customization
-@subsubsection Customizing Faces
+@subsection 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
+ In addition to variables, some customization groups also include
+faces. When you show the contents of a group, both the variables and
the faces in the group appear in the customization buffer. Here is an
example of how a face looks:
@smallexample
-Custom Changed Face: (sample) [Hide]
+Custom Changed Face:(sample) [Hide]
[State]: this face is unchanged from its standard setting.
-Parent groups: [Custom Magic Faces]
-Attributes: [ ] Font family: [Value Menu] *
- [ ] Width: [Value Menu] *
- [ ] Height: [Value Menu] *
- [ ] Weight: [Value Menu] *
- [ ] Slant: [Value Menu] *
- [ ] Underline: [Value Menu] *
- [ ] Overline: [Value Menu] *
- [ ] Strike-through: [Value Menu] *
- [ ] Box around text: [Value Menu] *
- [ ] Inverse-video: [Value Menu] *
- [X] Foreground: [Value Menu] Color: white (sample)
- [X] Background: [Value Menu] Color: blue (sample)
- [ ] Stipple: [Value Menu] *
- [ ] Inherit:
+Face used when the customize item has been changed.
+Parent groups: => Custom Magic Faces
+Attributes: [ ] Font Family: *
+ [ ] Width: *
+ [ ] Height: *
+ [ ] Weight: *
+ [ ] Slant: *
+ [ ] Underline: *
+ [ ] Overline: *
+ [ ] Strike-through: *
+ [ ] Box around text: *
+ [ ] Inverse-video: *
+ [X] Foreground: white (sample)
+ [X] Background: blue (sample)
+ [ ] Stipple: *
+ [ ] Inherit: *
@end smallexample
Each face attribute has its own line. The @samp{[@var{x}]} field
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.
+ For the colors, you can specify a color name (use @kbd{M-x
+list-colors-display}) for a list of them) or a hexadecimal color
+specification of the form @samp{#@var{rr}@var{gg}@var{bb}}.
+(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is
+green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a
+black-and-white display, the colors you can use for the background are
+@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and
+@samp{gray3}. Emacs supports these shades of gray by using background
+stipple patterns instead of a color.
Setting, saving and resetting a face work like the same operations for
-options (@pxref{Changing an Option}).
+variables (@pxref{Changing a Variable}).
A face can specify different appearances for different types of
display. For example, a face can make text red on a color display, but
to clear out the attribute.
@node Specific Customization
-@subsubsection Customizing Specific Items
+@subsection 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.
+through the structure of groups, you can specify the particular variable,
+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-variable @key{RET} @var{variable} @key{RET}
+Set up a customization buffer with just one variable, @var{variable}.
@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
+Set up a customization buffer with all the variables, 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
+Set up a customization buffer with all the variables, 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
+@item M-x customize-saved
+Set up a customization buffer containing all variables 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
+Set up a customization buffer containing all variables 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-variable
+ If you want to alter a particular variable with the customization
+buffer, and you know its name, you can use the command @kbd{M-x
+customize-variable} and specify the variable name. This sets up the
+customization buffer with just one variable---the one that you asked
+for. Editing, setting and saving the value work as described above,
+but only for the specified variable.
@findex customize-face
Likewise, you can modify a specific face, chosen by name, using
-@kbd{M-x customize-face}.
+@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
+group, including user options, 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-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.
+ 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 that
+you have saved. Use @kbd{M-x customize-customized} to look at the
+options that you have set but not saved.
+
+@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 need a value of a certain type. Often the value should
+always be a string, or should always be a number. Sometimes we say that a
+certain feature is turned on if a variable is ``non-@code{nil},'' meaning
+that if the variable's value is @code{nil}, the feature is off, but the
+feature is on for @emph{any} other value. The conventional value to use to
+turn on the feature---since you have to pick one particular value when you
+set the variable---is @code{t}.
+
+ Emacs uses many Lisp variables for internal record keeping, but the
+most interesting variables for a non-programmer user are those that
+are also @dfn{user options}, the variables that are meant for users to
+change. Each user option that you can set with the customization
+buffer is (if it is not a face) in fact a Lisp variable. 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. Use of the customization buffer is explained above
+(@pxref{Easy Customization}); here we describe other aspects of Emacs
+variables.
+
+@menu
+* Examining:: Examining or setting one variable's value.
+* Hooks:: Hook variables let you specify programs for parts
+ of Emacs to run on particular occasions.
+* Locals:: Per-buffer values of variables.
+* File Variables:: How files can specify variable values.
+@end menu
+
+@node Examining
+@subsection Examining and Setting Variables
+@cindex setting variables
+
+@table @kbd
+@item C-h v @var{var} @key{RET}
+Display the value and documentation of variable @var{var}
+(@code{describe-variable}).
+@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET}
+Change the value of variable @var{var} to @var{value}.
+@end table
+
+ To examine the value of a single variable, use @kbd{C-h v}
+(@code{describe-variable}), which reads a variable name using the
+minibuffer, with completion. It displays both the value and the
+documentation of the variable. For example,
+
+@example
+C-h v fill-column @key{RET}
+@end example
+
+@noindent
+displays something like this:
+
+@smallexample
+fill-column'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 variable is
+with @kbd{M-x set-variable}. This reads the variable name with the
+minibuffer (with completion), and then reads a Lisp expression for the
+new value using the minibuffer a second time. For example,
+
+@example
+M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
+@end example
+
+@noindent
+sets @code{fill-column} to 75.
+
+ @kbd{M-x set-variable} is limited to user option variables, but you can
+set any variable with a Lisp expression, using the function @code{setq}.
+Here is a @code{setq} expression to set @code{fill-column}:
+
+@example
+(setq fill-column 75)
+@end example
+
+ To execute an expression like this one, go to the @samp{*scratch*}
+buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp
+Interaction}.
+
+ Setting variables, like all means of customizing Emacs except where
+otherwise stated, affects only the current Emacs session. The only
+way to alter the variable in future sessions is to put something in
+the @file{~/.emacs} file to set it those sessions (@pxref{Init File}).
@node Hooks
@subsection Hooks
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-hooks} (@pxref{Visiting}) is abnormal because
+@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because
as soon as one hook function returns a non-@code{nil} value, the rest
are not called at all. The documentation of each abnormal hook variable
explains in detail what is peculiar about it.
- 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.
+ You can set a hook variable with @code{setq} like any other Lisp
+variable, but the recommended way to add a hook function to a hook
+(either normal or abnormal) is by calling @code{add-hook}. You can
+specify 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:
``asking for trouble.'' However, the order is predictable: the most
recently added hook functions are executed first.
+ If you play with adding various different versions of a hook
+function by calling @code{add-hook} over and over, remember that all
+the versions you added will remain in the hook variable together. You
+can clear out individual functions with @code{remove-hook}, or do
+@code{(setq @var{hook-variable} nil)} to remove everything.
+
@node Locals
@subsection Local Variables
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}.
+Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a
+particular Lisp file. @xref{Enabling Multibyte}.
The @code{eval} pseudo-variable, described below, can be specified in
the first line as well.
@cindex shell scripts, and local file variables
In shell scripts, the first line is used to identify the script
-interpreter, so you cannot put any local variables there. To accomodate
+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.
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. If @code{mode} is used to
-set a major mode, it should be the first ``variable'' in the list.
-
- 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.
+@code{comment-end} customize the rest of Emacs for this unusual
+syntax. Don't use a prefix (or a suffix) if you don't need one.
+
+ If you write a multi-line string value, you should put the prefix
+and suffix on each line, even lines that start or end within the
+string. They will be stripped off for processing the list. If you
+want to split a long string across multiple lines of the file, you can
+use backslash-newline, which is ignored in Lisp string constants.
+Here's an example of doing this:
+
+@example
+# Local Variables:
+# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \
+# -Dmumble=blaah"
+# End:
+@end example
+
+ Some ``variable names'' have special meanings in a local variables
+list. Specifying the ``variable'' @code{mode} really sets the major
+mode, while any value specified for the ``variable'' @code{eval} is
+simply evaluated as an expression (its value is ignored). A value for
+@code{coding} specifies the coding system for character code
+conversion of this file, and a value of @code{t} for @code{unibyte}
+says to visit the file in a unibyte buffer. These four ``variables''
+are not really variables; setting them in any other context has no
+special meaning.
+
+ @emph{If @code{mode} is used to set a major mode, it should be the
+first ``variable'' in the list.} Otherwise, the entries that precede
+it will usually be ignored, since most modes kill all local variables
+as part of their initialization.
+
+ You can use the @code{mode} ``variable'' to set minor modes as well
+as the major modes; in fact, you can use it more than once, first to
+set the major mode and then to set minor modes which are specific to
+particular buffers. But most minor modes should not be specified in
+the file at all, regardless of how, 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
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
+Therefore, the variable @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
+and certain other variables. The three possibilities for the variable's
value are @code{t}, @code{nil}, and anything else, just as for
@code{enable-local-variables}. The default is @code{maybe}, which is
neither @code{t} nor @code{nil}, so normally Emacs does ask for
confirmation about file settings for these variables.
-@node Keyboard Macros
-@section Keyboard Macros
-
-@cindex defining keyboard macros
-@cindex keyboard macro
- A @dfn{keyboard macro} is a command defined by the user to stand for
-another sequence of keys. For example, if you discover that you are
-about to type @kbd{C-n C-d} forty times, you can speed your work by
-defining a keyboard macro to do @kbd{C-n C-d} and calling it with a
-repeat count of forty.
-
-@c widecommands
-@table @kbd
-@item C-x (
-Start defining a keyboard macro (@code{start-kbd-macro}).
-@item C-x )
-End the definition of a keyboard macro (@code{end-kbd-macro}).
-@item C-x e
-Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
-@item C-u C-x (
-Re-execute last keyboard macro, then add more keys to its definition.
-@item C-x q
-When this point is reached during macro execution, ask for confirmation
-(@code{kbd-macro-query}).
-@item M-x name-last-kbd-macro
-Give a command name (for the duration of the session) to the most
-recently defined keyboard macro.
-@item M-x insert-kbd-macro
-Insert in the buffer a keyboard macro's definition, as Lisp code.
-@item C-x C-k
-Edit a previously defined keyboard macro (@code{edit-kbd-macro}).
-@item M-x apply-macro-to-region-lines
-Run the last keyboard macro on each complete line in the region.
-@end table
-
- Keyboard macros differ from ordinary Emacs commands in that they are
-written in the Emacs command language rather than in Lisp. This makes it
-easier for the novice to write them, and makes them more convenient as
-temporary hacks. However, the Emacs command language is not powerful
-enough as a programming language to be useful for writing anything
-intelligent or general. For such things, Lisp must be used.
-
- You define a keyboard macro while executing the commands which are the
-definition. Put differently, as you define a keyboard macro, the
-definition is being executed for the first time. This way, you can see
-what the effects of your commands are, so that you don't have to figure
-them out in your head. When you are finished, the keyboard macro is
-defined and also has been, in effect, executed once. You can then do the
-whole thing over again by invoking the macro.
-
-@menu
-* Basic Kbd Macro:: Defining and running keyboard macros.
-* Save Kbd Macro:: Giving keyboard macros names; saving them in files.
-* Kbd Macro Query:: Making keyboard macros do different things each time.
-@end menu
-
-@node Basic Kbd Macro
-@subsection Basic Use
-
-@kindex C-x (
-@kindex C-x )
-@kindex C-x e
-@findex start-kbd-macro
-@findex end-kbd-macro
-@findex call-last-kbd-macro
- To start defining a keyboard macro, type the @kbd{C-x (} command
-(@code{start-kbd-macro}). From then on, your keys continue to be
-executed, but also become part of the definition of the macro. @samp{Def}
-appears in the mode line to remind you of what is going on. When you are
-finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
-definition (without becoming part of it!). For example,
-
-@example
-C-x ( M-f foo C-x )
-@end example
-
-@noindent
-defines a macro to move forward a word and then insert @samp{foo}.
-
- The macro thus defined can be invoked again with the @kbd{C-x e}
-command (@code{call-last-kbd-macro}), which may be given a repeat count
-as a numeric argument to execute the macro many times. @kbd{C-x )} can
-also be given a repeat count as an argument, in which case it repeats
-the macro that many times right after defining it, but defining the
-macro counts as the first repetition (since it is executed as you define
-it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro
-immediately 3 additional times. An argument of zero to @kbd{C-x e} or
-@kbd{C-x )} means repeat the macro indefinitely (until it gets an error
-or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}).
-
- If you wish to repeat an operation at regularly spaced places in the
-text, define a macro and include as part of the macro the commands to move
-to the next place you want to use it. For example, if you want to change
-each line, you should position point at the start of a line, and define a
-macro to change that line and leave point at the start of the next line.
-Then repeating the macro will operate on successive lines.
-
- After you have terminated the definition of a keyboard macro, you can add
-to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent
-to plain @kbd{C-x (} followed by retyping the whole definition so far. As
-a consequence it re-executes the macro as previously defined.
-
- You can use function keys in a keyboard macro, just like keyboard
-keys. You can even use mouse events, but be careful about that: when
-the macro replays the mouse event, it uses the original mouse position
-of that event, the position that the mouse had while you were defining
-the macro. The effect of this may be hard to predict. (Using the
-current mouse position would be even less predictable.)
-
- One thing that doesn't always work well in a keyboard macro is the
-command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command
-exits a recursive edit that started within the macro, it works as you'd
-expect. But if it exits a recursive edit that started before you
-invoked the keyboard macro, it also necessarily exits the keyboard macro
-as part of the process.
-
-@findex edit-kbd-macro
-@kindex C-x C-k
- You can edit a keyboard macro already defined by typing @kbd{C-x C-k}
-(@code{edit-kbd-macro}). Follow that with the keyboard input that you
-would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or
-some other key sequence. This formats the macro definition in a buffer
-and enters a specialized major mode for editing it. Type @kbd{C-h m}
-once in that buffer to display details of how to edit the macro. When
-you are finished editing, type @kbd{C-c C-c}.
-
-@findex apply-macro-to-region-lines
- The command @kbd{M-x apply-macro-to-region-lines} repeats the last
-defined keyboard macro on each complete line within the current region.
-It does this line by line, by moving point to the beginning of the line
-and then executing the macro.
-
-@node Save Kbd Macro
-@subsection Naming and Saving Keyboard Macros
-
-@cindex saving keyboard macros
-@findex name-last-kbd-macro
- If you wish to save a keyboard macro for longer than until you define the
-next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
-This reads a name as an argument using the minibuffer and defines that name
-to execute the macro. The macro name is a Lisp symbol, and defining it in
-this way makes it a valid command name for calling with @kbd{M-x} or for
-binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you
-specify a name that has a prior definition other than another keyboard
-macro, an error message is printed and nothing is changed.
-
-@findex insert-kbd-macro
- Once a macro has a command name, you can save its definition in a file.
-Then it can be used in another editing session. First, visit the file
-you want to save the definition in. Then use this command:
-
-@example
-M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
-@end example
-
-@noindent
-This inserts some Lisp code that, when executed later, will define the
-same macro with the same definition it has now. (You need not
-understand Lisp code to do this, because @code{insert-kbd-macro} writes
-the Lisp code for you.) Then save the file. You can load the file
-later with @code{load-file} (@pxref{Lisp Libraries}). If the file you
-save in is your init file @file{~/.emacs} (@pxref{Init File}) then the
-macro will be defined each time you run Emacs.
-
- If you give @code{insert-kbd-macro} a numeric argument, it makes
-additional Lisp code to record the keys (if any) that you have bound to the
-keyboard macro, so that the macro will be reassigned the same keys when you
-load the file.
-
-@node Kbd Macro Query
-@subsection Executing Macros with Variations
-
-@kindex C-x q
-@findex kbd-macro-query
- Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect
-similar to that of @code{query-replace}, where the macro asks you each
-time around whether to make a change. While defining the macro,
-type @kbd{C-x q} at the point where you want the query to occur. During
-macro definition, the @kbd{C-x q} does nothing, but when you run the
-macro later, @kbd{C-x q} asks you interactively whether to continue.
-
- The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}),
-@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}.
-The answers are the same as in @code{query-replace}, though not all of
-the @code{query-replace} options are meaningful.
-
- These responses include @key{SPC} to continue, and @key{DEL} to skip
-the remainder of this repetition of the macro and start right away with
-the next repetition. @key{RET} means to skip the remainder of this
-repetition and cancel further repetitions. @kbd{C-l} redraws the screen
-and asks you again for a character to say what to do.
-
- @kbd{C-r} enters a recursive editing level, in which you can perform
-editing which is not part of the macro. When you exit the recursive
-edit using @kbd{C-M-c}, you are asked again how to continue with the
-keyboard macro. If you type a @key{SPC} at this time, the rest of the
-macro definition is executed. It is up to you to leave point and the
-text in a state such that the rest of the macro will do what you
-want.@refill
-
- @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument,
-performs a completely different function. It enters a recursive edit
-reading input from the keyboard, both when you type it during the
-definition of the macro, and when it is executed from the macro. During
-definition, the editing you do inside the recursive edit does not become
-part of the macro. During macro execution, the recursive edit gives you
-a chance to do some particularized editing on each repetition.
-@xref{Recursive Edit}.
-
- Another way to vary the behavior of a keyboard macro is to use a
-register as a counter, incrementing it on each repetition of the macro.
-@xref{RegNumbers}.
+@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
* 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 non-ASCII characters such as Latin-1.
+* Non-ASCII Rebinding:: Rebinding non-@acronym{ASCII} 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
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
+ On text terminals, typing a function key actually sends the computer a
sequence of characters; the precise details of the sequence depends on
which function key and on the model of terminal you are using. (Often
the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your
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.
-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.
+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
you are binding the key you want:
@example
-Set key C-z to command:
+Set key C-z to command:
@end example
You can redefine function keys and mouse events in the same way; just
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 ASCII characters and
-Meta-modified ASCII characters only. This method uses a string to
+ 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}:
@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
+This example uses a string constant containing one character,
+@kbd{C-z}. (@samp{\C-} is string syntax for a control character.) The
+single-quote before the command name, @code{shell}, marks it as a
constant symbol rather than a variable. If you omit the quote, Emacs
would try to evaluate @code{shell} immediately as a variable. This
probably causes an error; it certainly isn't what you want.
- Here is another example that binds a key sequence two characters long:
+ Here is another example that binds the key sequence @kbd{C-x M-l}:
@example
-(global-set-key "\C-xl" 'make-symbolic-link)
+(global-set-key "\C-x\M-l" 'make-symbolic-link)
@end example
To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the
@example
(global-set-key "\C-x\t" 'indent-rigidly)
+@end example
+
+ These examples show how to write some other special @acronym{ASCII} characters
+in strings for key bindings:
+
+@example
+(global-set-key "\r" 'newline) ;; @key{RET}
+(global-set-key "\d" 'delete-backward-char) ;; @key{DEL}
+(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC}
@end example
When the key sequence includes function keys or mouse button events,
-or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use
+or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, you must use
the more general method of rebinding, which uses a vector to specify the
key sequence.
the character as it would appear in a string.
Here are examples of using vectors to rebind @kbd{C-=} (a control
-character outside of ASCII), @kbd{H-a} (a Hyper character; ASCII doesn't
-have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a
+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:
+ You can use a vector for the simple cases too. Here's how to
+rewrite the first six examples above to use vectors:
@example
(global-set-key [?\C-z] 'shell)
(global-set-key [?\C-x ?l] 'make-symbolic-link)
(global-set-key [?\C-x ?\t] 'indent-rigidly)
+(global-set-key [?\r] 'newline)
+(global-set-key [?\d] 'delete-backward-char)
+(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command)
@end example
+@noindent
+As you see, you represent a multi-character key sequence with a vector
+by listing all of the characters in order within the square brackets that
+delimit the vector.
+
+ Language and coding systems can cause problems with key bindings
+for non-@acronym{ASCII} characters. @xref{Non-ASCII Rebinding}.
+
@node Function Keys
@subsection Rebinding Function Keys
key.
A key sequence which contains function key symbols (or anything but
-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:
+@acronym{ASCII} characters) must be a vector rather than a string.
+Thus, to bind function key @samp{f1} to the command @code{rmail},
+write the following:
@example
(global-set-key [f1] 'rmail)
(global-set-key [H-M-right] 'forward-word)
@end example
+@cindex keypad
+ Many keyboards have a ``numeric keypad'' on the right hand side.
+The numeric keys in the keypad double up as cursor motion keys,
+toggled by a key labelled @samp{Num Lock}. By default, Emacs
+translates these keys to the corresponding keys in the main keyboard.
+For example, when @samp{Num Lock} is on, the key labelled @samp{8} on
+the numeric keypad produces @code{kp-8}, which is translated to
+@kbd{8}; when @samp{Num Lock} is off, the same key produces
+@code{kp-up}, which is translated to @key{UP}. If you rebind a key
+such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too.
+However, if you rebind a @samp{kp-} key directly, that won't affect
+its non-keypad equivalent.
+
+ Emacs provides a convenient method for binding the numeric keypad
+keys, using the variables @code{keypad-setup},
+@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and
+@code{keypad-numlock-shifted-setup}. These can be found in the
+@samp{keyboard} customization group (@pxref{Easy Customization}). You
+can rebind the keys to perform other tasks, such as issuing numeric
+prefix arguments.
+
@node Named ASCII Chars
-@subsection Named ASCII Control Characters
+@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 ASCII control characters, used so often
-that they have special keys of their own. Later, users found it
+started out as names for certain @acronym{ASCII} control characters,
+used so often that they have special keys of their own. For instance,
+@key{TAB} was another name for @kbd{C-i}. Later, users found it
convenient to distinguish in Emacs between these keys and the ``same''
-control characters typed with the @key{CTRL} key.
-
- 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 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.
+control characters typed with the @key{CTRL} key. Therefore, on most
+modern terminals, they are no longer the same, and @key{TAB} is
+distinguishable from @kbd{C-i}.
+
+ Emacs can distinguish these two kinds of input if the keyboard does.
+It treats the ``special'' keys as function keys named @code{tab},
+@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
+@code{delete}. These function keys translate automatically into the
+corresponding @acronym{ASCII} characters @emph{if} they have no
+bindings of their own. As a result, neither users nor Lisp programs
+need to pay attention to the distinction unless they care to.
If you do not want to distinguish between (for example) @key{TAB} and
-@kbd{C-i}, make just one binding, for the ASCII character @key{TAB}
+@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 ASCII character, and another for the ``function key'' @code{tab}.
+this @acronym{ASCII} character, and another for the ``function key'' @code{tab}.
- With an ordinary ASCII terminal, there is no way to distinguish
+ 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 Non-ASCII Characters on the Keyboard
-
-If your keyboard has keys that send non-ASCII characters, such as
-accented letters, rebinding these keys is a bit tricky. There are two
-solutions you can use. One is to specify a keyboard coding system,
-using @code{set-keyboard-coding-system} (@pxref{Specify Coding}).
-Then you can bind these keys in the usual way@footnote{Note that you
-should avoid the string syntax for binding 8-bit characters, since
-they will be interpreted as meta keys. @xref{Strings of
-Events,,,elisp, The Emacs Lisp Reference Manual}.}, like this:
+@subsection Non-@acronym{ASCII} Characters on the Keyboard
+@cindex rebinding non-@acronym{ASCII} keys
+@cindex non-@acronym{ASCII} keys, binding
+
+If your keyboard has keys that send non-@acronym{ASCII}
+characters, such as accented letters, rebinding these keys
+must be done by using a vector like this@footnote{Note that
+you should avoid the string syntax for binding
+non-@acronym{ASCII} characters, since they will be
+interpreted as meta keys. @xref{Strings of Events,,,elisp,
+The Emacs Lisp Reference Manual}.}:
@example
(global-set-key [?@var{char}] 'some-function)
@noindent
Type @kbd{C-q} followed by the key you want to bind, to insert @var{char}.
-If you don't specify the keyboard coding system, that approach won't
-work. Instead, you need to find out the actual code that the terminal
-sends. The easiest way to do this in Emacs is to create an empty buffer
-with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x
-toggle-enable-multibyte-characters @key{RET}}, then type the key to
-insert the character into this buffer.
-
-Move point before the character, then type @kbd{C-x =}. This
-displays a message in the minibuffer, showing the character code in
-three ways, octal, decimal and hexadecimal, all within a set of
-parentheses. Use the second of the three numbers, the decimal one,
-inside the vector to bind:
+Since this puts a non-@acronym{ASCII} character in the @file{.emacs},
+you should specify a coding system for that file that supports the
+character in question. @xref{Init Syntax}.
-@example
-(global-set-key [@var{decimal-code}] 'some-function)
-@end example
-
-If you bind 8-bit characters like this in your init file, you my find it
-convenient to specify that it is unibyte. @xref{Enabling Multibyte}.
+@strong{Warning:} if you change the keyboard encoding, or change
+between multibyte and unibyte mode, or anything that would alter which
+code @kbd{C-q} would insert for that character, you'll need to edit
+the Lisp expression accordingly, to use the character code generated
+by @kbd{C-q} in the new mode.
@node Mouse Buttons
@subsection Rebinding Mouse Buttons
events, if it has no binding).
@vindex double-click-time
- The variable @code{double-click-time} specifies how long may elapse
-between clicks that are recognized as a pair. Its value is measured
-in 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 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-},
@end example
If the value of the @code{disabled} property is a string, that string
-is included in the message printed when the command is used:
+is included in the message displayed when the command is used:
@example
(put 'delete-region 'disabled
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 ASCII character named @key{DEL}.
-@xref{Named ASCII Chars}. Keyboard translations affect only 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
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 sometimes related
-major modes share one syntax table) which it installs in each buffer
+ 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.
@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{Entering Emacs}).
+ When Emacs is started, it normally loads a Lisp program from the
+file @file{.emacs} or @file{.emacs.el} in your home directory. (You
+can also put it in a subdirectory @file{~/.emacs.d} and Emacs will
+still find it.) 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
@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}.
+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
fill-column 60)} calls the function @code{setq} to set the variable
@code{fill-column} (@pxref{Filling}) to 60.
- 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:
+ 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:
sequences are mandatory.
@samp{\C-} can be used as a prefix for a control character, as in
-@samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for
+@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for
a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for
@kbd{Control-Meta-A}.@refill
@cindex international characters in @file{.emacs}
-@cindex non-ASCII characters in @file{.emacs}
-If you want to include non-ASCII characters in strings in your init
+@cindex non-@acronym{ASCII} characters in @file{.emacs}
+If you want to include non-@acronym{ASCII} characters in strings in your init
file, you should consider putting a @w{@samp{-*-coding:
@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 non-ASCII text might
+Coding}. This is because the defaults for decoding non-@acronym{ASCII} text might
not yet be set up by the time Emacs reads those parts of your init file
which use such strings, possibly leading Emacs to decode those strings
incorrectly.
require one and some contexts require the other.
@xref{Non-ASCII Rebinding}, for information about binding commands to
-keys which send non-ASCII characters.
+keys which send non-@acronym{ASCII} characters.
@item True:
@code{t} stands for `true'.
(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.
@item
@cindex loading Lisp libraries automatically
@cindex autoload Lisp libraries
-Tell Emacs to automatically load a Lisp library named @file{mypackage}
-(i.e.@: a file @file{mypackage.elc} or @file{mypackage.el}) when the
-function @code{myfunction} in that library is called:
+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 made available to Emacs even when the package is not loaded
-(e.g., for commands such as @kbd{C-h a}), and @code{t} tells Emacs 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.
+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}.
+Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}
+(@pxref{Init Rebinding}).
@example
(global-set-key "\C-xl" 'make-symbolic-link)
@example
(put 'narrow-to-region 'disabled nil)
@end example
+
+@item
+Adjusting the configuration to various platforms and Emacs versions.
+
+Users typically want Emacs to behave the same on all systems, so the
+same init file is right for all platforms. However, sometimes it
+happens that a function you use for customizing Emacs is not available
+on some platforms or in older Emacs versions. To deal with that
+situation, put the customization inside a conditional that tests whether
+the function or facility is available, like this:
+
+@example
+(if (fboundp 'blink-cursor-mode)
+ (blink-cursor-mode 0))
+
+(if (boundp 'coding-category-utf-8)
+ (set-coding-priority '(coding-category-utf-8)))
+@end example
+
+@noindent
+You can also simply disregard the errors that occur if the
+function is not defined.
+
+@example
+(condition case ()
+ (set-face-background 'region "grey75")
+ (error nil))
+@end example
+
+A @code{setq} on a variable which does not exist is generally
+harmless, so those do not need a conditional.
@end itemize
@node Terminal Init
@subsection 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
-have done @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.
+@file{.emacs}; that's what @samp{~} means in a file name. If @file{.emacs}
+is not found directly inside @file{~/}, Emacs looks for it in
+@file{~/.emacs.d/}.
+
+ However, if you run Emacs from a shell started by @code{su}, Emacs
+tries to find your own @file{.emacs}, not that of the user you are
+currently pretending to be. The idea is that you should get your own
+editor customizations even if you are running as the super user.
More precisely, Emacs first determines which user's init file to use.
It gets the user name from the environment variables @env{LOGNAME} and
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