@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Customization, Quitting, Emulation, Top
@chapter Customization
@cindex customization

  This chapter talks about various topics relevant to adapting the
behavior of Emacs in minor ways.  See @cite{The Emacs Lisp Reference
Manual} for how to make more far-reaching changes.

  All kinds of customization affect only the particular Emacs job that you
do them in.  They are completely lost when you kill the Emacs job, and have
no effect on other Emacs jobs you may run at the same time or later.  The
only way an Emacs job 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}.

@menu
* Minor Modes::              Each minor mode is one feature you can turn on
                               independently of any others.
* Variables::                Many Emacs commands examine Emacs variables
                               to decide what to do; by setting variables,
                               you can control their functioning.
* 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.
* Init File::                How to write common customizations in the
                               @file{.emacs} file. 
@end menu

@node Minor Modes
@section Minor Modes
@cindex minor modes
@cindex mode, minor

  Minor modes are optional features which you can turn on or off.  For
example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines
between words as you type.  All the minor modes are independent of each
other and of the selected major mode.  Most minor modes say in the mode
line when they are on; for example, @samp{Fill} in the mode line means
that Auto Fill mode is on.

  Append @code{-mode} to the name of a minor mode to get the name of a
command function that turns the mode on or off.  Thus, the command to
enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}.  These
commands are usually invoked with @kbd{M-x}, but you can bind keys to them
if you wish.  With no argument, the function turns the mode on if it was
off and off if it was on.  This is known as @dfn{toggling}.  A positive
argument always turns the mode on, and an explicit zero argument or a
negative argument always turns it off.

  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.

  Auto Fill mode allows you to enter filled text without breaking lines
explicitly.  Emacs inserts newlines as necessary to prevent lines from
becoming too long.  @xref{Filling}.

  Outline minor mode provides the same facilities as the major mode
called Outline mode; but since it is a minor mode instead, you can
combine it with any major mode.  @xref{Outline Mode}.

@cindex Overwrite mode
@cindex mode, Overwrite
@findex overwrite-mode
  Overwrite mode causes ordinary printing characters to replace existing
text instead of shoving it over.  For example, if the point is in front of
the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G}
changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as
usual.@refill

  Auto Save mode causes the contents of a buffer to be saved
periodically to reduce the amount you will lose in case of a system
crash.  @xref{Auto Save}.

  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}.

  Abbrev mode allows you to define abbreviations that automatically expand
as you type them.  For example, @samp{amd} might expand to @samp{abbrev
mode}.  @xref{Abbrevs}, for full information.

  Line Number mode enables continuous display in the mode line of the
line number of point.  @xref{Mode Line}.

  Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}).
Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}).  Both of
these modes are enabled by default when you use the X Window System.

  In Transient Mark mode, every change in the buffer ``deactivates'' the
mark, so that commands that operate on the region will get an error.
This means you must either set the mark, or explicitly ``reactivate''
it, before each command that uses the region.  The advantage of
Transient Mark mode is that Emacs can display the region highlighted
(currently only when using X).  @xref{Setting Mark}.

@node Variables
@section Variables
@cindex variable
@cindex 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 recordkeeping, 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{options}.  Most options are documented in this manual, and
appear in the Variable Index (@pxref{Variable Index}).

  One example of a variable which is an 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.
* Edit Options::        Examining or editing list of all variables' values.
* 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}
Print 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 prints both the value and the
documentation of the variable.  For example, 

@example
C-h v fill-column @key{RET}
@end example

@noindent
prints something like this:

@smallexample
fill-column's value is 75

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 an option.  @kbd{C-h v} is not restricted to options; it allows any
variable name.

@findex set-variable
  The most convenient way to set a specific 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.

  You can set any variable with a Lisp expression using the function
@code{setq}.  Here's how to use it to set @code{fill-column}:

@example
(setq fill-column 75)
@end example

  Setting variables, like all means of customizing Emacs except where
explicitly stated, affects only the current Emacs session.

@node Edit Options
@subsection Editing Variable Values

These two functions make it easy to display all the user edit options
and change some of them.

@table @kbd
@item M-x list-options
Display a buffer listing names, values and documentation of all options.
@item M-x edit-options
Change option values by editing a list of options.
@end table

@findex list-options
  @kbd{M-x list-options} displays a list of all Emacs option variables, in
an Emacs buffer named @samp{*List Options*}.  Each option is shown with its
documentation and its current value.  Here is what a portion of it might
look like:

@smallexample
;; exec-path:
("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
*List of directories to search programs to run in subprocesses.
Each element is a string (directory name)
or nil (try the default directory).
;;
;; fill-column:
75
*Column beyond which automatic line-wrapping should happen.
Automatically becomes buffer-local when set in any fashion.
;;
@end smallexample

@findex edit-options
  @kbd{M-x edit-options} goes one step further and immediately selects the
@samp{*List Options*} buffer; this buffer uses the major mode Options mode,
which provides commands that allow you to point at an option and change its
value:

@table @kbd
@item s
Set the variable point is in or near to a new value read using the
minibuffer.
@item x
Toggle the variable point is in or near: if the value was @code{nil},
it becomes @code{t}; otherwise it becomes @code{nil}.
@item 1
Set the variable point is in or near to @code{t}.
@item 0
Set the variable point is in or near to @code{nil}.
@item n
@itemx p
Move to the next or previous variable.
@end table

  Any changes take effect immediately, and last until you exit from
Emacs.

@node Hooks
@subsection Hooks
@cindex hook

  A @dfn{hook} is a variable where you can store a function or functions
to be called on a particular occasion by an existing program.  Emacs
provides a number of hooks for the sake of customization.

  Most of the hooks in Emacs are @dfn{normal hooks}.  These variables
contain lists of functions to be called with no arguments.  The reason
most hooks are normal hooks is so that you can use them in a uniform
way.  Every variable in Emacs whose name ends in @samp{-hook} is a
normal hook.

  Most major modes run hooks as the last step of initialization.  This
makes it easy for a user to customize the behavior of the mode, by
overriding the local variable assignments already made by the mode.  But
hooks may also be used in other contexts.  For example, the hook
@code{suspend-hook} runs just before Emacs suspends itself
(@pxref{Exiting}).

  The recommended way to add a hook function to a normal hook is by
calling @code{add-hook}.  You can use any valid Lisp function as the
hook function.  For example, here's how to set up a hook to turn on Auto
Fill mode when entering Text mode and other modes based on Text mode:

@example
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end example

  The next example shows how to use a hook to customize the indentation
of C code.  (People often have strong personal preferences for one
format compared to another.)  Here the hook function is an anonymous
lambda expression.

@example
@group
(add-hook 'c-mode-hook 
  (function (lambda ()
              (setq c-indent-level 4
                    c-argdecl-indent 0
                    c-label-offset -4
@end group
@group
                    c-continued-statement-indent 0
                    c-brace-offset 0
                    comment-column 40))))

(setq c++-mode-hook c-mode-hook)
@end group
@end example

  It is best to design your hook functions so that the order in which
they are executed does not matter.  Any dependence on the order is
``asking for trouble.''  However, the order is predictable: the most
recently added hook functions are executed first.

@node Locals
@subsection Local Variables

@table @kbd
@item M-x make-local-variable @key{RET} @var{var} @key{RET}
Make variable @var{var} have a local value in the current buffer.
@item M-x kill-local-variable @key{RET} @var{var} @key{RET}
Make variable @var{var} use its global value in the current buffer.
@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET}
Mark variable @var{var} so that setting it will make it local to the
buffer that is current at that time.
@end table

@cindex local variables
  Any variable can be made @dfn{local} to a specific Emacs buffer.  This
means that its value in that buffer is independent of its value in other
buffers.  A few variables are always local in every buffer.  Every other
Emacs variable has a @dfn{global} value which is in effect in all buffers
that have not made the variable local.

@findex make-local-variable
  @kbd{M-x make-local-variable} reads the name of a variable and makes it
local to the current buffer.  Further changes in this buffer will not
affect others, and further changes in the global value will not affect this
buffer.

@findex make-variable-buffer-local
@cindex per-buffer variables
  @kbd{M-x make-variable-buffer-local} reads the name of a variable and
changes the future behavior of the variable so that it will become local
automatically when it is set.  More precisely, once a variable has been
marked in this way, the usual ways of setting the variable automatically
do @code{make-local-variable} first.  We call such variables
@dfn{per-buffer} variables.

  Major modes (@pxref{Major Modes}) always make the variables they set
local to the buffer.  This is why changing major modes in one buffer has
no effect on other buffers.  Minor modes also work by setting
variables---normally, each minor mode has one controlling variable which
is non-@code{nil} when the mode is enabled (@pxref{Minor Modes}).
For most minor modes, the controlling variable is per buffer.

  Emacs contains a number of variables that are always per-buffer.
These include @code{abbrev-mode}, @code{auto-fill-function},
@code{case-fold-search}, @code{comment-column}, @code{ctl-arrow},
@code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode},
@code{left-margin}, @code{mode-line-format}, @code{overwrite-mode},@*
@code{selective-display-ellipses}, @code{selective-display},
@code{tab-width}, and @code{truncate-lines}.  Some other variables are
always local in every buffer, but they are used for internal
purposes.@refill

@findex kill-local-variable
  @kbd{M-x kill-local-variable} reads the name of a variable and makes it
cease to be local to the current buffer.  The global value of the variable
henceforth is in effect in this buffer.  Setting the major mode kills all
the local variables of the buffer except for a few specially marked
variables that are @dfn{permanent locals}.

@findex setq-default
  To set the global value of a variable, regardless of whether the
variable has a local value in the current buffer, you can use the
Lisp function @code{setq-default}.  It works like @code{setq}.
If there is a local value in the current buffer, the local value is
not affected by @code{setq-default}; thus, the new global value may
not be visible until you switch to another buffer.  For example,

@example
(setq-default fill-column 75)
@end example

@noindent
@code{setq-default} is the only way to set the global value of a variable
that has been marked with @code{make-variable-buffer-local}.

@findex default-value
  Lisp programs can look at a variable's default value with
@code{default-value}.  This function takes a symbol as argument and
returns its default value.  The argument is evaluated; usually you must
quote it explicitly.  For example,

@example
(default-value 'fill-column)
@end example

@node File Variables
@subsection Local Variables in Files
@cindex local variables in files

  A file can specify local variable values for use when you edit the
file with Emacs.  Visiting the file checks for local variables
specifications; it automatically makes these variables local to the
buffer, and sets them to the values specified in the file.

  There are two ways to specify local variable values: in the first line,
or with a local variables list.  Here's how to do this with the first
line:

@example
-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*-
@end example

@noindent
You can specify any number of variables/value pairs in this way, each
pair with a colon and semicolon as shown above.  The major mode should
come first, if it is mentioned at all.  Here is an example that 
specifies Lisp mode and sets two variables with numeric values:

@smallexample
;; -*-Mode: Lisp; fill-column: 75; comment-column: 50; -*-
@end smallexample

  A @dfn{local variables list} goes near the end of the file, in the
last page.  (It is often best to put it on a page by itself.)  The local
variables list starts with a line containing the string @samp{Local
Variables:}, and ends with a line containing the string @samp{End:}.  In
between come the variable names and values, one set per line, as
@samp{@var{variable}:@: @var{value}}.  The @var{value}s are not
evaluated; they are used literally.

Here is an example of a local variables list:

@example
;;; Local Variables: ***
;;; mode:lisp ***
;;; comment-column:0 ***
;;; comment-start: ";;; "  ***
;;; comment-end:"***" ***
;;; End: ***
@end example

  As you see, each line starts with the prefix @samp{;;; } and each line
ends with the suffix @samp{ ***}.  Emacs recognizes these as the prefix
and suffix based on the first line of the list, by finding them
surrounding the magic string @samp{Local Variables:}; so it
automatically discards them from the other lines of the list.

  The usual reason for using a prefix and/or suffix is to embed the
local variables list in a comment, so it won't confuse other programs
that the file is intended as input for.  The example above is for a
language where comment lines start with @samp{;;; } and end with
@samp{***}; the local values for @code{comment-start} and
@code{comment-end} customize the rest of Emacs for this unusual syntax.
Don't use a prefix (or a suffix) if you don't need one.

  Two ``variable names'' have special meanings in a local variables
list: a value for the variable @code{mode} really sets the major mode,
and a value for the variable @code{eval} is simply evaluated as an
expression and the value is ignored.  @code{mode} and @code{eval} are
not real variables; setting such variables in any other context has no
such effect.  If @code{mode} is used in a local variables list, it
should be the first entry in the list.

  The start of the local variables list must be no more than 3000
characters from the end of the file, and must be in the last page if the
file is divided into pages.  Otherwise, Emacs will not notice it is there.
The purpose of this is so that a stray @samp{Local Variables:}@: not in the
last page does not confuse Emacs, and so that visiting a long file that is
all one page and has no local variables list need not take the time to
search the whole file.

  You may be tempted to try to turn on Auto Fill mode with a local variable
list.  That is a mistake.  The choice of Auto Fill mode or not is a matter
of individual taste, not a matter of the contents of particular files.
If you want to use Auto Fill, set up major mode hooks with your @file{.emacs}
file to turn it on (when appropriate) for you alone (@pxref{Init File}).
Don't try to use a local variable list that would impose your taste on
everyone.@refill

@findex enable-local-variables
  The variable @code{enable-local-variables} controls whether to process
local variables lists, and thus gives you a chance to override them.
Its default value is @code{t}, which means to process local variables
lists.  If you set the value to @code{nil}, Emacs simply ignores local
variables lists.  Any other value says to query you about each local
variables list, showing you the local variables list to consider.

@findex enable-local-eval
  The @code{eval} ``variable'' creates special risks, so there is a
separate variable @code{enable-local-eval} to control whether Emacs
processes @code{eval} variables.  The three possibilities for the 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 queries about
@code{eval} variable settings.

  Use the command @code{normal-mode} to reset the local variables and
major mode of a buffer according to the file name and contents,
including the local variables list if any.  @xref{Choosing Modes}.

@node Keyboard Macros
@section Keyboard Macros

@cindex defining keyboard macros
@cindex keyboard macro
  A @dfn{keyboard macro} is a command defined by the user to abbreviate a
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.
@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::     Keyboard macros that do different things each use.
@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).  So, 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}).

  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.

@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 prefix 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.  When you are 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{ESC} (or @kbd{q}), @kbd{C-l} and
@kbd{C-r}.  The answers are the same as in query replace, though not all
of the query-replace options are meaningful.

  Specifically, @key{SPC} means to continue.  @key{DEL} means to skip
the remainder of this repetition of the macro and start right away with
the next repetition.  @key{ESC} means to skip the remainder of this
repetition and cancel further repetition.  @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
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.  @xref{Recursive Edit}.

@node Key Bindings
@section Customizing Key Bindings
@cindex key bindings

  This section describes @dfn{key bindings} which map keys to commands,
and the @dfn{keymaps} which record key bindings.  It also explains how
to customize key bindings.

  Recall that a command is a Lisp function whose definition provides for
interactive use.  Like every Lisp function, a command has a function
name which usually consists of lower case letters and hyphens.

@menu
* Keymaps::          Generalities.  The global keymap.
* Prefix Keymaps::   Keymaps for prefix keys.
* Local Keymaps::    Major and minor modes have their own keymaps.
* Minibuffer Maps::  The minibuffer uses its own local keymaps.
* Rebinding::        How to redefine one key's meaning conveniently.
* Init Rebinding::   Rebinding keys with your init file, @file{.emacs}.
* Function Keys::    Rebinding terminal function keys.
* Mouse Buttons::    Rebinding mouse buttons in Emacs.
* Disabling::        Disabling a command means confirmation is required
                       before it can be executed.  This is done to protect
                       beginners from surprises.
@end menu

@node Keymaps
@subsection Keymaps
@cindex keymap

  The bindings between key sequences and command functions are recorded
in data structures called @dfn{keymaps}.  Emacs has many of these, each
used on particular occasions.

@cindex touch
  Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence
of @dfn{input events} that have a meaning as a unit.  Input events
include characters, function keys and mouse buttons---all the inputs
that you can send to the computer with your terminal.  A key sequence
gets its meaning from its @dfn{binding}, which says what command it
runs.  The function of keymaps is to record these bindings.

@cindex global keymap
  The @dfn{global} keymap is the most important keymap because it is
always in effect.  The global keymap defines keys for Fundamental mode;
most of these definitions are common to all (or most) major modes.  Each
major or minor mode can have its own keymap which overrides the
definitions of some keys.

  For example, a self-inserting character such as @kbd{g} is
self-inserting because the global keymap binds it to the command
@code{self-insert-command}.  The standard Emacs editing characters such
as @kbd{C-a} also get their standard meanings from the global keymap.
Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work
by storing the new binding in the proper place in the global map.
@xref{Rebinding}.

   Meta characters work differently; Emacs translates each Meta
character into a pair of characters starting with @key{ESC}.  When you
type the character @kbd{M-a} in a key sequence, Emacs replaces it with
@kbd{@key{ESC} a}.  A meta key comes in as a single input event, but
becomes two events for purposes of key bindings.  The reason for this is
historical, and we might change in someday.

@cindex function key
  Most modern keyboards have function keys as well as character keys.
Function keys send input events just as character keys do, and keymaps
can have bindings for them.

  On many terminals, typing a function key actually sends the computer a
sequence of characters; the precise details of the sequence depends on
which function key and on the model of terminal you are using.  (Often
he sequence starts with @kbd{@key{ESC} [}.)  If Emacs understands your
terminal type properly, it recognizes the character sequences forming
function keys wherever they occur in a key sequence (not just at the
beginning).  Thus, for most purposes, you can pretend the function keys
reach Emacs directly and ignore their encoding as character sequences.

@cindex mouse
  Mouse buttons also produce input events.  These events come with other
data---the window and position where you pressed or released the button,
and a timestamp.  But only the choice of button matters for key
bindings; the other data matters only if a command looks at it.
(Commands designed for mouse invocation usually do look at the other
data.)

  A keymap records definitions for single events.  Interpreting a key
sequence of multiple events involves a chain of keymaps.  The first
keymap gives a definition for the first event; this definition is
another keymap, which is used to look up the second event in the
sequence, and so on.

  Key sequences can mix function keys and characters.  For example,
@kbd{C-x @key{SELECT}} makes sense.  If you make @key{SELECT} a prefix
key, then @kbd{@key{SELECT} C-n} makes sense.  You can even mix mouse
events with keyboard events, but we recommend against it, because such
sequences are inconvenient to type in.

@node Prefix Keymaps
@subsection Prefix Keymaps

  A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap,
which holds the definition for the event that immediately follows
that prefix.

  The definition of a prefix key is the keymap to use for looking up the
following event.  The definition can also be a Lisp symbol whose
function definition is the following keymap; the effect is the same, but
it provides a command name for the prefix key that can be used as a
description of what the prefix key is for.  Thus, the binding of
@kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function definition
is the keymap for @kbd{C-x} commands.  The definitions of @kbd{C-c},
@kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in the global
map, so these prefix keys are always available.

  Some prefix keymaps are stored in variables with names:

@itemize @bullet
@item
@vindex ctl-x-map
@code{ctl-x-map} is the variable name for the map used for characters that
follow @kbd{C-x}.
@item
@vindex help-map
@code{help-map} is for characters that follow @kbd{C-h}.
@item
@vindex esc-map
@code{esc-map} is for characters that follow @key{ESC}.  Thus, all Meta
characters are actually defined by this map.
@item
@vindex ctl-x-4-map
@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
@item
@vindex mode-specific-map
@code{mode-specific-map} is for characters that follow @kbd{C-c}.
@end itemize

@node Local Keymaps
@subsection Local Keymaps

@cindex local keymap
  So far we have explained the ins and outs of the global map.  Major
modes customize Emacs by providing their own key bindings in @dfn{local
keymaps}.  For example, C mode overrides @key{TAB} to make it indent the
current line for C code.  Portions of text in the buffer can specify
their own keymaps to substitute for the keymap of the buffer's major
mode.

@cindex minor mode keymap
  Minor modes can also have local keymaps.  Whenever a minor mode is
in effect, the definitions in its keymap override both the major
mode's local keymap and the global keymap.

@vindex c-mode-map
@vindex lisp-mode-map
  The local keymaps for Lisp mode, C mode, and several other major modes
always exist even when not in use.  These are kept in variables named
@code{lisp-mode-map}, @code{c-mode-map}, and so on.  For major modes
less often used, the local keymap is normally constructed only when the
mode is used for the first time in a session.  This is to save space.

  All minor mode keymaps are created in advance.  There is no way to
defer their creation until the minor mode is enabled.

  A local keymap can locally redefine a key as a prefix key by defining
it as a prefix keymap.  If the key is also defined globally as a prefix,
then its local and global definitions (both keymaps) effectively
combine: both of them are used to look up the event that follows the
prefix key.  Thus, if the mode's local keymap defines @kbd{C-c} as
another keymap, and that keymap defines @kbd{C-z} as a command, this
provides a local meaning for @kbd{C-c C-z}.  This does not affect other
sequences that start with @kbd{C-c}; If those sequences don't have their
own local bindings, their global bindings remain in effect.

  Another way to think of this is that Emacs handles a multi-event key
sequence by looking in several keymaps, one by one, for a binding of the
whole key sequence.  First it checks the minor mode keymaps for minor
modes that are enabled, then it checks the major mode's keymap, and then
it checks the global keymap.  This is not precisely how key lookup
works, but it's good enough for understanding ordinary circumstances.

@node Minibuffer Maps
@subsection Minibuffer Keymaps

@cindex minibuffer keymaps
@vindex minibuffer-local-map
@vindex minibuffer-local-ns-map
@vindex minibuffer-local-completion-map
@vindex minibuffer-local-must-match-map
  The minibuffer has its own set of local keymaps; they contain various
completion and exit commands.

@itemize @bullet
@item
@code{minibuffer-local-map} is used for ordinary input (no completion).
@item
@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
just like @key{RET}.  This is used mainly for Mocklisp compatibility.
@item
@code{minibuffer-local-completion-map} is for permissive completion.
@item
@code{minibuffer-local-must-match-map} is for strict completion and
for cautious completion.
@end itemize

@node Rebinding
@subsection Changing Key Bindings Interactively
@cindex key rebinding, this session
@cindex rebinding keys, this session
@cindex rebinding keys, this session

  The way to redefine an Emacs key is to change its entry in a keymap.
You can change the global keymap, in which case the change is effective in
all major modes (except those that have their own overriding local
definitions for the same key).  Or you can change the current buffer's
local map, which affects all buffers using the same major mode.
@findex global-set-key
@findex local-set-key
@findex global-unset-key
@findex local-unset-key

@table @kbd
@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
Define @var{key} globally to run @var{cmd}.
@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
Define @var{key} locally (in the major mode now in effect) to run
@var{cmd}.
@item M-x global-unset-key @key{RET} @var{key}
Make @var{key} undefined in the global map.
@item M-x local-unset-key @key{RET} @var{key}
Make @var{key} undefined locally (in the major mode now in effect).
@end table

  For example, suppose you like to execute commands in a subshell within
an Emacs buffer, instead of suspending Emacs and executing commands in
your login shell.  Normally, @kbd{C-z} is bound to the function
@code{suspend-emacs}, but you can change @kbd{C-z} to invoke an
interactive subshell within Emacs, by binding it to @code{shell} as
follows: @refill

@example
M-x global-set-key @key{RET} C-z shell @key{RET}
@end example

@noindent
@code{global-set-key} reads the command name after the key.   After you
press the key, a message like this appears so that you can confirm that
you are binding the key you want:

@example
Set key C-z to command: 
@end example

  You can redefine function keys and mouse events in the same way; just
type the function key or click the mouse when it's time to specify the
key to rebind.

  You can rebind a key that contains more than one event in the same
way.  Emacs keeps reading the key to rebind until it is a complete key
(that is, not a prefix key).  Thus, if you type @kbd{C-f} for
@var{key}, that's the end; the minibuffer is entered immediately to
read @var{cmd}.  But if you type @kbd{C-x}, another character is read;
if that is @kbd{4}, another character is read, and so on.  For
example,

@example
M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
@end example

@noindent
would redefine @kbd{C-x 4 $} to run the (fictitious) command
@code{spell-other-window}.

  You can remove the global definition of a key with
@code{global-unset-key}.  This makes the key @dfn{undefined}; if you
type it, Emacs will just beep.  Similarly, @code{local-unset-key} makes
a key undefined in the current major mode keymap, which makes the global
definition (or lack of one) come back into effect in that major mode.

  If you have redefined (or undefined) a key and you subsequently wish
to retract the change, undefining the key will not do the job---you need
to redefine the key with its standard definition.  To find the name of
the standard definition of a key, go to a Fundamental mode buffer and
use @kbd{C-h c}.  The documentation of keys in this manual also lists
their command names.

  If you want to prevent yourself from invoking a command by mistake, it
is better to disable the command than to undefine the key.  A disabled
command is less work to invoke when you really want to.
@xref{Disabling}.

@node Init Rebinding
@subsection Rebinding Keys in Your Init File

@findex define-key
@findex substitute-key-definition
  If you have a set of default definitions that you like to use all the time,
you can put commands in your @file{.emacs} file by using their Lisp syntax.
Thus, the first @code{global-set-key} command in this section could be put in
an @file{.emacs} file in either of the two following formats:

@example
(global-set-key "\C-z" 'shell)
@end example

or as:

@example
(global-set-key [?\C-z] 'shell)
@end example

@noindent
When the key sequence consists of characters, like this one, you can
write it as a string or as a vector.  The first format specifies the key
sequence as a string, @code{"\C-z"}.  The second format uses a vector to
specify the key sequence.  The square brackets (@samp{[@dots{}]})
delimit the contents of the vector.  The vector in this example contains
just one element, which is the integer code corresponding to @kbd{C-z}.
The question mark is the Lisp syntax for a character constant; the
character must follow with no intervening spaces.

  The single-quote before @code{shell} marks it as a constant symbol
rather than a variable.  If you omit the quote, Emacs tries to evaluate
@code{shell} immediately as a variable.  This probably causes an error;
it certainly isn't what you want.

  Here is another example that binds a key sequence two characters long:

@example
(global-set-key "\C-xl" 'make-symbolic-link)
@end example

or:

@example
(global-set-key [?\C-x ?l] 'make-symbolic-link)
@end example

@node Function Keys
@subsection Rebinding Function Keys

  Key sequences can contain function keys as well as ordinary
characters.  Just as Lisp characters (actually integers) represent
keyboard characters, Lisp symbols represent function keys.  If the
function key has a word as its label, then that word is also the name of
the corresponding Lisp symbol.  Here are the conventional Lisp names for
other function keys:

@table @asis
@item @code{left}, @code{up}, @code{right}, @code{down}
Cursor arrow keys.

@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior}
Other cursor repositioning keys.

@item @code{select}, @code{print}, @code{execute}, @code{backtab}
@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline}
@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar},
Miscellaneous function keys.

@item @code{f1} @dots{} @code{f35}
Numbered function keys (across the top of the keyboard).

@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide}
@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter}
@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal}
Keypad keys (to the right of the regular keyboard), with names or punctuation.

@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9}
Keypad keys with digits.

@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Keypad PF keys.
@end table

  These names are conventional, but some systems (especially when using
X windows) may use different names.  To make certain what symbol is used
for a given function key on your terminal, type @kbd{C-h c} followed by
that key.

  A key sequence which contains non-characters must be a vector rather
than a string.  To write a vector, write square brackets containing the
vector elements.  Write spaces to separate the elements.  If an element
is a symbol, simply write the symbol's name---no delimiters or
punctuation are needed.  If an element is a character, write a Lisp
character constant, which is @samp{?} followed by the character as it
would appear in a string.

  Thus, to bind function key @samp{f1} to the command @code{rmail}, write
the following:

@example
(global-set-key [f1] 'rmail)
@end example

  To bind the right-arrow key to the command @code{forward-char},
you can use this expression:

@example
(global-set-key [right] 'forward-char)
@end example

@noindent
using the Lisp syntax for a vector containing the symbol @code{right}.
(This binding is present in Emacs by default.)

  You can mix function keys and characters in a key sequence.  This
example binds @kbd{C-x @key{RIGHT}} to the command @code{forward-page}.

@example
(global-set-key [?\C-x right] 'forward-page)
@end example

@noindent
where @code{?\C-x} is the Lisp character constant for the character
@kbd{C-x}.  The vector element @code{right} is a symbol and therefore
does not take a question mark.

  You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys.  To represent
these modifiers, prepend the strings @samp{C-}, @samp{M-}, @samp{H-},
@samp{s-}, @samp{A-} and @samp{S-} to the symbol name.  Thus, here is
how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a word:

@example
(global-set-key [H-M-right] 'forward-word)
@end example

@node Mouse Buttons
@subsection Rebinding Mouse Buttons
@cindex mouse button events
@cindex rebinding mouse buttons
@cindex click events
@cindex drag events
@cindex down events
@cindex button down events

  Emacs uses Lisp symbols to designate mouse buttons, too.  The ordinary
mouse events in Emacs are @dfn{click} events; these happen when you
press a button and release it without moving the mouse.  You can also
get @dfn{drag} events, when you move the mouse while holding the button
down.  Drag events happen when you finally let go of the button.

  The symbols for basic click events are @code{mouse-1} for the leftmost
button, @code{mouse-2} for the next, and so on.  Here is how you can
redefine the second mouse button to split the current window:

@example
(global-set-key [mouse-2] 'split-window-vertically)
@end example

  The symbols for drag events are similar, but have the prefix @samp{drag-}
before the word @samp{mouse}.  For example, dragging the left button
generates a @code{drag-mouse-1} event.

  You can also define events that occur when a mouse button is pressed
down.  These events start with @samp{down-} instead of @samp{drag-}.
Such events are generated only if they have key bindings.  When you get
a button-down event, a corresponding click or drag event will always
follow.

@cindex double clicks
@cindex triple clicks
  If you wish, you can distinguish single, double, and triple clicks.  A
double click means clicking a mouse button twice in approximately the
same place.  The first click generates an ordinary click event.  The
second click, if it comes soon enough, generates a double-click event
instead.  The event type for a double click event starts with
@samp{double-}: for example, @samp{double-mouse-3}.

  This means that you can give a special meaning to the second click at
the same place, but it must act on the assumption that the ordinary
single click definition has run when the first click was received.

  This constrains what you can do with double clicks, but user interface
designers say that this constraint ought to be followed in any case.  A
double click should do something similar to the single click, only
``more so''.  The command for the double-click event should perform the
extra work for the double click.

  If a double-click event has no binding, it changes to the
corresponding single-click event.  Thus, if you don't define a
particular double click specially, it executes the single-click command
twice.

  Emacs also supports triple-click events whose names start with
@samp{triple-}.  Emacs does not distinguish quadruple clicks as event
types; clicks beyond the third generate additional triple-click events.
However, the full number of clicks is recorded in the event list, so you
can distinguish if you really want to.  We don't recommend distinct
meanings for more than three clicks, but sometimes it is useful for
subsequent clicks to cycle through the same set of three meanings, so
that four clicks are equivalent to one click, five are equivalent to
two, and six are equivalent to three.

  Emacs also records multiple presses in drag and button-down events.
For example, when you press a button twice, then move the mouse while
holding the button, Emacs gets a @samp{double-drag-} event.  And at the
moment when you press it down for the second time, Emacs gets a
@samp{double-down-} event (which is ignored, like all button-down
events, if it has no binding).

@vindex double-click-time
  The variable @code{double-click-time} specifies how 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 symbols for mouse events also indicate the status of the modifier
keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-},
@samp{s-}, @samp{A-} and @samp{S-}.  These always precede @samp{double-}
or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}.

  A frame includes areas that don't show text from the buffer, such as
the mode line and the scroll bar.  You can tell whether a mouse button
comes from a special area of the screen by means of dummy ``prefix
keys.''  For example, if you click the mouse in the mode line, you get
the prefix key @code{mode-line} before the ordinary mouse-button
symbol.  Thus, here is how to define the command for clicking the left
button in a mode line to run @code{scroll-up}:

@example
(global-set-key [mode-line mouse-1] 'scroll-up)
@end example

  Here is the complete list of these dummy prefix keys and their
meanings:

@table @code
@item mode-line
The mouse was in the mode line of a window.
@item vertical-line
The mouse was in the vertical line separating side-by-side windows.
@item vertical-scroll-bar
The mouse was in a horizontal scroll bar.  This is the kind of scroll
bar people normally use.
@item horizontal-scroll-bar
The mouse was in a horizontal scroll bar.  Horizontal scroll bars do
horizontal scrolling, and people don't use them often.
@end table

  You can put more than one mouse button in a key sequence, but it isn't
usual to do so.

@node Disabling
@subsection Disabling Commands
@cindex disabled command

  Disabling a command marks the command as requiring confirmation before it
can be executed.  The purpose of disabling a command is to prevent
beginning users from executing it by accident and being confused.

  Attempting to invoke a disabled command interactively in Emacs causes the
display of a window containing the command's name, its documentation, and
some instructions on what to do immediately; then Emacs asks for input
saying whether to execute the command as requested, enable it and execute,
or cancel it.  If you decide to enable the command, you are asked whether to
do this permanently or just for the current session.  Enabling permanently
works by automatically editing your @file{.emacs} file.

  The direct mechanism for disabling a command is to have a
non-@code{nil} @code{disabled} property on the Lisp symbol for the
command.  Here is the Lisp program to do this:

@example
(put 'delete-region 'disabled t)
@end example

  If the value of the @code{disabled} property is a string, that string
is included in the message printed when the command is used:

@example
(put 'delete-region 'disabled
     "Text deleted this way cannot be yanked back!\n")
@end example

@findex disable-command
@findex enable-command
  You can make a command disabled either by editing the @file{.emacs}
file directly or with the command @kbd{M-x disable-command}, which edits
the @file{.emacs} file for you.  Likewise, @kbd{M-x enable-command}
edits @file{.emacs} to enable a command permanently.  @xref{Init File}.

  Whether a command is disabled is independent of what key is used to
invoke it; it 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
keyboard, 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.

  For full information about how to use keyboard translations, see
@ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}.

@node Syntax
@section The Syntax Table
@cindex syntax table

  All the Emacs commands which parse words or balance parentheses are
controlled by the @dfn{syntax table}.  The syntax table says which
characters are opening delimiters, which are parts of words, which are
string quotes, and so on.  Each major mode has its own syntax
table (though sometimes related major modes use the same one) which it
installs in each buffer that uses that major mode.  The syntax table
installed in the current buffer is the one that all commands use, so we
call it ``the'' syntax table.  A syntax table is a Lisp object, a vector of
length 256 whose elements are numbers.

@kindex C-h s
@findex describe-syntax
  To display a description of the contents of the current syntax table,
type @kbd{C-h s} (@code{describe-syntax}).  The description of each
character includes both the string you would have to give to
@code{modify-syntax-entry} to set up that character's current syntax,
and some English to explain that string if necessary.

  For full information on the syntax table, see @ref{Syntax Table,,
Syntax Table, elisp, The Emacs Lisp Reference Manual}.

@node Init File
@section The Init File, @file{~/.emacs}
@cindex init file
@cindex Emacs initialization file
@cindex key rebinding, permanent
@cindex rebinding keys, permanently

  When Emacs is started, it normally loads a Lisp program from the file
@file{.emacs} 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 switches @samp{-q} and @samp{-u} to tell Emacs whether
to load an init file, and which one (@pxref{Entering Emacs}).

  There can also be a @dfn{default init file}, which is the library
named @file{default.el}, found via the standard search path for
libraries.  The Emacs distribution contains no such library; your site
may create one for local customizations.  If this library exists, it is
loaded whenever you start Emacs (except when you specify @samp{-q}).
But your init file, if any, is loaded first; if it sets
@code{inhibit-default-init} non-@code{nil}, then @file{default} is not
loaded.

  If you have a large amount of code in your @file{.emacs} file, you
should move it into another file such as @file{~/@var{something}.el},
byte-compile it, and make your @file{.emacs} file load it with
@code{(load "~/@var{something}")}.  @xref{Byte Compilation,, Byte
Compilation, elisp, the Emacs Lisp Reference Manual}, for more
information about compiling Emacs Lisp programs.

@menu
* Init Syntax::     Syntax of constants in Emacs Lisp.
* Init Examples::   How to do some things with an init file.
* Terminal Init::   Each terminal type can have an init file.
* Find Init::	    How Emacs finds the init file.
@end menu

@node Init Syntax
@subsection Init File Syntax

  The @file{.emacs} file contains one or more Lisp function call
expressions.  Each of these consists of a function name followed by
arguments, all surrounded by parentheses.  For example, @code{(setq
fill-column 60)} calls the function @code{setq} to set the variable
@code{fill-column} (@pxref{Filling}) to 60.

  The second argument to @code{setq} is an expression for the new value of
the variable.  This can be a constant, a variable, or a function call
expression.  In @file{.emacs}, constants are used most of the time.  They can be:

@table @asis
@item Numbers:
Numbers are written in decimal, with an optional initial minus sign.

@item Strings:
@cindex Lisp string syntax
@cindex string syntax
Lisp string syntax is the same as C string syntax with a few extra
features.  Use a double-quote character to begin and end a string constant.

In a string, you can include newlines and special characters literally.
But often it is cleaner to use backslash sequences for them: @samp{\n}
for newline, @samp{\b} for backspace, @samp{\r} for carriage return,
@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for
escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or
@samp{\@var{ooo}} for the character whose octal code is @var{ooo}.
Backslash and double-quote are the only characters for which backslash
sequences are mandatory.

@samp{\C-} can be used as a prefix for a control character, as in
@samp{\C-s} for 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

@item Characters:
Lisp character constant syntax consists of a @samp{?} followed by
either a character or an escape sequence starting with @samp{\}.
Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
strings and characters are not interchangeable in Lisp; some contexts
require one and some contexts require the other.

@item True:
@code{t} stands for `true'.

@item False:
@code{nil} stands for `false'.

@item Other Lisp objects:
Write a single-quote (') followed by the Lisp object you want.
@end table

@node Init Examples
@subsection Init File Examples

  Here are some examples of doing certain commonly desired things with
Lisp expressions:

@itemize @bullet
@item
Make @key{TAB} in C mode just insert a tab if point is in the middle of a
line.

@example
(setq c-tab-always-indent nil)
@end example

Here we have a variable whose value is normally @code{t} for `true'
and the alternative is @code{nil} for `false'.

@item
Make searches case sensitive by default (in all buffers that do not
override this).

@example
(setq-default case-fold-search nil)
@end example

This sets the default value, which is effective in all buffers that do
not have local values for the variable.  Setting @code{case-fold-search}
with @code{setq} affects only the current buffer's local value, which
is not what you probably want to do in an init file.

@item
Make Text mode the default mode for new buffers.

@example
(setq default-major-mode 'text-mode)
@end example

Note that @code{text-mode} is used because it is the command for
entering Text mode.  The single-quote before it makes the symbol a
constant; otherwise, @code{text-mode} would be treated as a variable
name.

@item
Turn on Auto Fill mode automatically in Text mode and related modes.

@example
(add-hook 'text-mode-hook
  '(lambda () (auto-fill-mode 1)))
@end example

This shows how to add a hook function to a normal hook variable
(@pxref{Hooks}).  The function we supply is a list starting with
@code{lambda}, with a single-quote in front of it to make it a list
constant rather than an expression.

It's beyond the scope of this manual to explain Lisp functions, but for
this example it is enough to know that the effect is to execute
@code{(auto-fill-mode 1)} when Text mode is entered.  You can replace it
with any other expression that you like, or with several expressions in
a row.

Emacs comes with a function named @code{turn-on-auto-fill} whose
definition is @code{(lambda () (auto-fill-mode 1))}.  Thus, a simpler
way to write the above example is as follows:

@example
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end example

@item
Load the installed Lisp library named @file{foo} (actually a file
@file{foo.elc} or @file{foo.el} in a standard Emacs directory).

@example
(load "foo")
@end example

When the argument to @code{load} is a relative file name, not starting
with @samp{/} or @samp{~}, @code{load} searches the directories in
@code{load-path} (@pxref{Lisp Libraries}).

@item
Load the compiled Lisp file @file{foo.elc} from your home directory.

@example
(load "~/foo.elc")
@end example

Here an absolute file name is used, so no searching is done.

@item
Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.

@example
(global-set-key "\C-xl" 'make-symbolic-link)
@end example

or

@example
(define-key global-map "\C-xl" 'make-symbolic-link)
@end example

Note once again the single-quote used to refer to the symbol
@code{make-symbolic-link} instead of its value as a variable.

@item
Do the same thing for C mode only.

@example
(define-key c-mode-map "\C-xl" 'make-symbolic-link)
@end example

@item
Redefine all keys which now run @code{next-line} in Fundamental mode
so that they run @code{forward-line} instead.

@example
(substitute-key-definition 'next-line 'forward-line
                           global-map)
@end example

@item
Make @kbd{C-x C-v} undefined.

@example
(global-unset-key "\C-x\C-v")
@end example

One reason to undefine a key is so that you can make it a prefix.
Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a
prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix
definition.

@item
Make @samp{$} have the syntax of punctuation in Text mode.
Note the use of a character constant for @samp{$}.

@example
(modify-syntax-entry ?\$ "." text-mode-syntax-table)
@end example

@item
Enable the use of the command @code{eval-expression} without confirmation.

@example
(put 'eval-expression 'disabled nil)
@end example
@end itemize

@node Terminal Init
@subsection Terminal-specific Initialization

  Each terminal type can have a Lisp library to be loaded into Emacs when
it is run on that type of terminal.  For a terminal type named
@var{termtype}, the library is called @file{term/@var{termtype}} and it is
found by searching the directories @code{load-path} as usual and trying the
suffixes @samp{.elc} and @samp{.el}.  Normally it appears in the
subdirectory @file{term} of the directory where most Emacs libraries are
kept.@refill

  The usual purpose of the terminal-specific library is to define the
escape sequences used by the terminal's function keys using the library
@file{keypad.el}.  See the file
@file{term/vt100.el} for an example of how this is done.@refill

  When the terminal type contains a hyphen, only the part of the name
before the first hyphen is significant in choosing the library name.
Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
the library @file{term/aaa}.  The code in the library can use
@code{(getenv "TERM")} to find the full terminal type name.@refill

@vindex term-file-prefix
  The library's name is constructed by concatenating the value of the
variable @code{term-file-prefix} and the terminal type.  Your @file{.emacs}
file can prevent the loading of the terminal-specific library by setting
@code{term-file-prefix} to @code{nil}.

@vindex term-setup-hook
  Emacs runs the hook @code{term-setup-hook} at the end of
initialization, after both your @file{.emacs} file and any
terminal-specific library have been read in.  Add hook functions to this
hook if you wish to override part of any of the terminal-specific
libraries and to define initializations for terminals that do not have a
library.  @xref{Hooks}.

@node Find Init
@subsection How Emacs Finds Your Init File

  Normally Emacs uses the environment variable @code{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.

  More precisely, Emacs first determines which user's init file to use.
It gets the user name from the environment variables @code{USER} and
@code{LOGNAME}; if neither of those exists, it uses effective user-ID.
If that user name matches the real user-ID, then Emacs uses @code{HOME};
otherwise, it looks up the home directory corresponding to that user
name in the system's data base of users.