@c This is part of the Emacs manual.
-@c Copyright (C) 1985,86,87,93,94,95,97,2000,2001,2002,2004
-@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
@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.
+* 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.
* 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.
@end menu
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.
+ 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 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.
+ 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
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
@cindex user option
Emacs has many @dfn{user options} which have values that you can set
-in order to customize various commands. Most user options are
-documented in this manual. Each user option is actually a Lisp
-variable (@pxref{Variables}), so their names appear in the Variable
-Index (@pxref{Variable Index}).
+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
- You can browse interactively through the the user options and change
+ 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
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
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.
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
+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}.
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
-@subsection 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 user option.
+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. 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;
+@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 option, invoke @samp{[State]} and select the @samp{Save for
+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 option again, each time you start Emacs (@pxref{Saving
+the variable again, each time you start Emacs (@pxref{Saving
Customizations}).
- You can also restore the option to its standard value by invoking
+ 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 option to a previous value that was set in the
-customization buffer in this session. If you customize an option
+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
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
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. If you are using Emacs
-version 21.4 or later, Emacs loads the file right after your
-@file{.emacs} if you did not load it already. In earlier versions,
-you have to load the file in your @file{~/emacs}. If you customize
-@code{custom-file} through the @samp{Customize} interface, you still
-need to load it in your @file{.emacs}, but there is no need to set
-it. For example:
+@code{custom-file} to the name of that file. Then you should load the
+file by calling @code{load}. For example:
@example
-;; @r{if not set through the @samp{Customize} interface:}
-(setq custom-file "~/.emacs-custom")
-
-;; @r{in Emacs versions before 21.4 or if set through}
-;; @r{the @samp{Customize} interface.}
-(load "~/.emacs-custom")
+(setq custom-file "~/.emacs-custom.el")
+(load custom-file)
@end example
You can also use @code{custom-file} to specify different
((and (= emacs-major-version 21) (< emacs-minor-version 4))
;; @r{Emacs 21 customization, before version 21.4.}
(setq custom-file "~/.custom-21.el"))
- (t
+ ((< emacs-major-version 22)
;; @r{Emacs version 21.4 or later.}
- (setq custom-file "~/.custom-21.4.el")))
+ (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
@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:
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
@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
+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 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
@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
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 the @dfn{user
-options}, the variables that are meant for users to change. Each user
-option that you can set with the customization buffer is, in fact, a
-Lisp variable. Emacs does not (usually) change the values of these
-variables; instead, you set the values, and thereby alter and control
-the behavior of certain Emacs commands. Use of the customization
-buffer is explained above; here we describe other aspects of Emacs
+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
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,
+ 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}
Interaction}.
Setting variables, like all means of customizing Emacs except where
-otherwise stated, affects only the current Emacs session.
+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
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.
-To clear them out, you can do @code{(setq @var{hook-variable} nil)}.
+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
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
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
@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
@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}}:
+rewrite the first six examples above to use vectors:
@example
(global-set-key [?\C-z] 'shell)
@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
+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
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:
+@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 @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
+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 @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.
+control characters typed with the @key{CTRL} key. Therefore, on most
+modern terminals, they are no longer the same, and @key{TAB} is
+distinguishable from @kbd{C-i}.
+
+ Emacs can distinguish these two kinds of input if the keyboard does.
+It treats the ``special'' keys as function keys named @code{tab},
+@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and
+@code{delete}. These function keys translate automatically into the
+corresponding @acronym{ASCII} characters @emph{if} they have no
+bindings of their own. As a result, neither users nor Lisp programs
+need to pay attention to the distinction unless they care to.
If you do not want to distinguish between (for example) @key{TAB} and
@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB}
@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
@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}).
+ 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
@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
-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.
+@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