4.4BSD/usr/src/contrib/emacs-18.57/info/emacs-11

Info file ../info/emacs, produced by Makeinfo, -*- Text -*- from
input file emacs.tex.

This file documents the GNU Emacs editor.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "The GNU Manifesto", "Distribution" and
"GNU General Public License" are included exactly as in the original,
and provided that the entire resulting derived work is distributed
under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "The GNU Manifesto",
"Distribution" and "GNU General Public License" may be included in a
translation approved by the author instead of in the original English.

File: emacs, Node: Locals, Next: File Variables, Prev: Edit Options, Up: Variables

Local Variables
---------------

`M-x make-local-variable'
Make a variable have a local value in the current buffer.

`M-x kill-local-variable'
Make a variable use its global value in the current buffer.

`M-x make-variable-buffer-local'
Mark a variable so that setting it will make it local to the
buffer that is current at that time.

Any variable can be made "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 "global" value which is in effect in
all buffers that have not made the variable local.

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.

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

`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
will automatically do `make-local-variable' first. We call such
variables "per-buffer" variables.

Some important variables have been marked per-buffer already. These
include `abbrev-mode', `auto-fill-hook', `case-fold-search',
`comment-column', `ctl-arrow', `fill-column', `fill-prefix',
`indent-tabs-mode', `left-margin', `mode-line-format',
`overwrite-mode',
`selective-display-ellipses', `selective-display', `tab-width', and
`truncate-lines'. Some other variables are always local in every
buffer, but they are used for internal purposes.

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

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 `setq-default'. It works like `setq'. If there is a
local value in the current buffer, the local value is not affected by
`setq-default'; thus, the new global value may not be visible until
you switch to another buffer. For example,

(setq-default fill-column 75)

`setq-default' is the only way to set the global value of a variable
that has been marked with `make-variable-buffer-local'.

Programs can look at a variable's default value with `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,

(default-value 'fill-column)

File: emacs, Node: File Variables, Prev: Locals, Up: Variables

Local Variables in Files
------------------------

A file can contain a "local variables list", which specifies the
values to use for certain Emacs variables when that file is edited.
Visiting the file checks for a local variables list and makes each
variable in the list local to the buffer in which the file is
visited, with the value specified in the file.

A 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 `Local
Variables:', and ends with a line containing the string `End:'. In
between come the variable names and values, one set per line, as
`VARIABLE: VALUE'. The VALUEs are not evaluated; they are used
literally.

The line which starts the local variables list does not have to say
just `Local Variables:'. If there is other text before `Local
Variables:', that text is called the "prefix", and if there is other
text after, that is called the "suffix". If these are present, each
entry in the local variables list should have the prefix before it
and the suffix after it. This includes the `End:' line. The prefix
and suffix are included to disguise the local variables list as a
comment so that the compiler or text formatter will not be perplexed
by it. If you do not need to disguise the local variables list as a
comment in this way, do not bother with a prefix or a suffix.

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

Here is an example of a local variables list:

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

Note that the prefix is `;;; ' and the suffix is ` ***'. Note also
that comments in the file begin with and end with the same strings.
Presumably the file contains code in a language which is like Lisp
(like it enough for Lisp mode to be useful) but in which comments
start and end in that way. The prefix and suffix are used in the
local variables list to make the list appear as comments when the
file is read by the compiler or interpreter for that language.

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 `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 `.emacs' file to turn it on (when appropriate) for
you alone (*note Init File::.). Don't try to use a local variable
list that would impose your taste on everyone.

File: emacs, Node: Keyboard Macros, Next: Key Bindings, Prev: Variables, Up: Customization

Keyboard Macros
===============

A "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 `C-n C-d' forty times, you can speed your work by defining a
keyboard macro to do `C-n C-d' and calling it with a repeat count of
forty.

`C-x ('
Start defining a keyboard macro (`start-kbd-macro').

`C-x )'
End the definition of a keyboard macro (`end-kbd-macro').

`C-x e'
Execute the most recent keyboard macro (`call-last-kbd-macro').

`C-u C-x ('
Re-execute last keyboard macro, then add more keys to its
definition.

`C-x q'
When this point is reached during macro execution, ask for
confirmation (`kbd-macro-query').

`M-x name-last-kbd-macro'
Give a command name (for the duration of the session) to the
most recently defined keyboard macro.

`M-x insert-kbd-macro'
Insert in the buffer a keyboard macro's definition, as Lisp code.

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 are defining 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.

File: emacs, Node: Basic Kbd Macro, Next: Save Kbd Macro, Prev: Keyboard Macros, Up: Keyboard Macros

Basic Use
---------

To start defining a keyboard macro, type the `C-x (' command
(`start-kbd-macro'). From then on, your keys continue to be
executed, but also become part of the definition of the macro. `Def'
appears in the mode line to remind you of what is going on. When you
are finished, the `C-x )' command (`end-kbd-macro') terminates the
definition (without becoming part of it!). For example

C-x ( M-F foo C-x )

defines a macro to move forward a word and then insert `foo'.

The macro thus defined can be invoked again with the `C-x e' command
(`call-last-kbd-macro'), which may be given a repeat count as a
numeric argument to execute the macro many times. `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 `C-x )' an argument of 4 executes the macro
immediately 3 additional times. An argument of zero to `C-x e' or
`C-x )' means repeat the macro indefinitely (until it gets an error
or you type `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 `C-u C-x ('. This is
equivalent to plain `C-x (' followed by retyping the whole definition
so far. As a consequence it re-executes the macro as previously
defined.

File: emacs, Node: Save Kbd Macro, Next: Kbd Macro Query, Prev: Basic Kbd Macro, Up: Keyboard Macros

Naming and Saving Keyboard Macros
---------------------------------

If you wish to save a keyboard macro for longer than until you define
the next one, you must give it a name using `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 `M-x' or for binding a key to with `global-set-key' (*note
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.

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 the command

M-x insert-kbd-macro RET MACRONAME RET

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 `insert-kbd-macro' writes
the Lisp code for you. Then save the file. The file can be loaded
with `load-file' (*note Lisp Libraries::.). If the file you save in
is your init file `~/.emacs' (*note Init File::.) then the macro will
be defined each time you run Emacs.

If you give `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.

File: emacs, Node: Kbd Macro Query, Prev: Save Kbd Macro, Up: Keyboard Macros

Executing Macros with Variations
--------------------------------

Using `C-x q' (`kbd-macro-query'), you can get an effect similar to
that of `query-replace', where the macro asks you each time around
whether to make a change. When you are defining the macro, type `C-x
q' at the point where you want the query to occur. During macro
definition, the `C-x q' does nothing, but when the macro is invoked
the `C-x q' reads a character from the terminal to decide whether to
continue.

The special answers are SPC, DEL, `C-d', `C-l' and `C-r'. Any other
character terminates execution of the keyboard macro and is then read
as a command. SPC means to continue. DEL means to skip the
remainder of this repetition of the macro, starting again from the
beginning in the next repetition. `C-d' means to skip the remainder
of this repetition and cancel further repetition. `C-l' redraws the
screen and asks you again for a character to say what to do. `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 `C-M-c', you are asked again how to continue with the keyboard
macro. If you type a 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.

`C-u C-x q', which is `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. *Note Recursive Edit::.

File: emacs, Node: Key Bindings, Next: Syntax, Prev: Keyboard Macros, Up: Customization

Customizing Key Bindings
========================

This section deals with the "keymaps" which define the bindings
between keys and functions, and shows how you can customize these
bindings.

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

* Menu:

* Keymaps:: Definition of the keymap data structure.
Names of Emacs's standard keymaps.
* Rebinding:: How to redefine one key's meaning conveniently.
* Disabling:: Disabling a command means confirmation is required
before it can be executed. This is done to protect
beginners from surprises.

File: emacs, Node: Keymaps, Next: Rebinding, Prev: Key Bindings, Up: Key Bindings

Keymaps
-------

The bindings between characters and command functions are recorded in
data structures called "keymaps". Emacs has many of these. One, the
"global" keymap, defines the meanings of the single-character keys
that are defined regardless of major mode. It is the value of the
variable `global-map'.

Each major mode has another keymap, its "local keymap", which
contains overriding definitions for the single-character keys that
are to be redefined in that mode. Each buffer records which local
keymap is installed for it at any time, and the current buffer's
local keymap is the only one that directly affects command execution.
The local keymaps for Lisp mode, C mode, and many other major modes
always exist even when not in use. They are the values of the
variables `lisp-mode-map', `c-mode-map', and so on. For major modes
less often used, the local keymap is sometimes constructed only when
the mode is used for the first time in a session. This is to save
space.

There are local keymaps for the minibuffer too; they contain various
completion and exit commands.

* `minibuffer-local-map' is used for ordinary input (no completion).

* `minibuffer-local-ns-map' is similar, except that SPC exits just
like RET. This is used mainly for Mocklisp compatibility.

* `minibuffer-local-completion-map' is for permissive completion.

* `minibuffer-local-must-match-map' is for strict completion and
for cautious completion.

* `repeat-complex-command-map' is for use in `C-x ESC'.

Finally, each prefix key has a keymap which defines the key sequences
that start with it. For example, `ctl-x-map' is the keymap used for
characters following a `C-x'.

* `ctl-x-map' is the variable name for the map used for characters
that follow `C-x'.

* `help-map' is used for characters that follow `C-h'.

* `esc-map' is for characters that follow ESC. Thus, all Meta
characters are actually defined by this map.

* `ctl-x-4-map' is for characters that follow `C-x 4'.

* `mode-specific-map' is for characters that follow `C-c'.

The definition of a prefix key is just the keymap to use for looking
up the following character. Actually, the definition is sometimes a
Lisp symbol whose function definition is the following character
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 `C-x' is the symbol `Ctl-X-Prefix',
whose function definition is the keymap for `C-x' commands, the value
of `ctl-x-map'.

Prefix key definitions of this sort can appear in either the global
map or a local map. The definitions of `C-c', `C-x', `C-h' and ESC
as prefix keys appear in the global map, so these prefix keys are
always available. Major modes can locally redefine a key as a prefix
by putting a prefix key definition for it in the local map.

A mode can also put a prefix definition of a global prefix character
such as `C-x' into its local map. This is how major modes override
the definitions of certain keys that start with `C-x'. This case is
special, because the local definition does not entirely replace the
global one. When both the global and local definitions of a key are
other keymaps, the next character is looked up in both keymaps, with
the local definition overriding the global one as usual. So, the
character after the `C-x' is looked up in both the major mode's own
keymap for redefined `C-x' commands and in `ctl-x-map'. If the major
mode's own keymap for `C-x' commands contains `nil', the definition
from the global keymap for `C-x' commands is used.

A keymap is actually a Lisp object. The simplest form of keymap is a
Lisp vector of length 128. The binding for a character in such a
keymap is found by indexing into the vector with the character as an
index. A keymap can also be a Lisp list whose car is the symbol
`keymap' and whose remaining elements are pairs of the form `(CHAR .
BINDING)'. Such lists are called "sparse keymaps" because they are
used when most of the characters' entries will be `nil'. Sparse
keymaps are used mainly for prefix characters.

Keymaps are only of length 128, so what about Meta characters, whose
codes are from 128 to 255? A key that contains a Meta character
actually represents it as a sequence of two characters, the first of
which is ESC. So the key `M-a' is really represented as `ESC a', and
its binding is found at the slot for `a' in `esc-map'.

File: emacs, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings

Changing Key Bindings Interactively
-----------------------------------

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.

`M-x global-set-key RET KEY CMD RET'
Defines KEY globally to run CMD.

`M-x local-set-key RET KEY CMD RET'
Defines KEY locally (in the major mode now in effect) to run CMD.

For example,

M-x global-set-key RET C-f next-line RET

would redefine `C-f' to move down a line. The fact that CMD is read
second makes it serve as a kind of confirmation for KEY.

These functions offer no way to specify a particular prefix keymap as
the one to redefine in, but that is not necessary, as you can include
prefixes in KEY. KEY is read by reading characters one by one until
they amount to a complete key (that is, not a prefix key). Thus, if
you type `C-f' for KEY, that's the end; the minibuffer is entered
immediately to read CMD. But if you type `C-x', another character is
read; if that is `4', another character is read, and so on. For
example,

M-x global-set-key RET C-x 4 $ spell-other-window RET

would redefine `C-x 4 $' to run the (fictitious) command
`spell-other-window'.

The most general way to modify a keymap is the function `define-key',
used in Lisp code (such as your `.emacs' file). `define-key' takes
three arguments: the keymap, the key to modify in it, and the new
definition. *Note Init File::, for an example.
`substitute-key-definition' is used similarly; it takes three
arguments, an old definition, a new definition and a keymap, and
redefines in that keymap all keys that were previously defined with
the old definition to have the new definition instead.

File: emacs, Node: Disabling, Prev: Rebinding, Up: Key Bindings

Disabling Commands
------------------

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.

The direct mechanism for disabling a command is to have a non-`nil'
`disabled' property on the Lisp symbol for the command. These
properties are normally set up by the user's `.emacs' file with Lisp
expressions such as

(put 'delete-region 'disabled t)

If the value of the `disabled' property is a string, that string is
included in the message printed when the command is used:

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

You can make a command disabled either by editing the `.emacs' file
directly or with the command `M-x disable-command', which edits the
`.emacs' file for you. *Note Init File::.

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 `.emacs' file. You can use `M-x
enable-command' at any time to enable any command permanently.

Whether a command is disabled is independent of what key is used to
invoke it; it also applies if the command is invoked using `M-x'.
Disabling a command has no effect on calling it as a function from
Lisp programs.

File: emacs, Node: Syntax, Next: Init File, Prev: Key Bindings, Up: Customization

The Syntax Table
================

All the Emacs commands which parse words or balance parentheses are
controlled by the "syntax table". The syntax table says which
characters are opening delimiters, which are parts of words, which
are string quotes, and so on. Actually, 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.

* Menu:

* Entry: Syntax Entry. What the syntax table records for each character.
* Change: Syntax Change. How to change the information.

File: emacs, Node: Syntax Entry, Next: Syntax Change, Prev: Syntax, Up: Syntax

Information about Each Character
--------------------------------

The syntax table entry for a character is a number that encodes six
pieces of information:

* The syntactic class of the character, represented as a small
integer.

* The matching delimiter, for delimiter characters only. The
matching delimiter of `(' is `)', and vice versa.

* A flag saying whether the character is the first character of a
two-character comment starting sequence.

* A flag saying whether the character is the second character of a
two-character comment starting sequence.

* A flag saying whether the character is the first character of a
two-character comment ending sequence.

* A flag saying whether the character is the second character of a
two-character comment ending sequence.

The syntactic classes are stored internally as small integers, but
are usually described to or by the user with characters. For
example, `(' is used to specify the syntactic class of opening
delimiters. Here is a table of syntactic classes, with the
characters that specify them.

` '
The class of whitespace characters.

`w'
The class of word-constituent characters.

`_'
The class of characters that are part of symbol names but not
words. This class is represented by `_' because the character
`_' has this class in both C and Lisp.

`.'
The class of punctuation characters that do not fit into any
other special class.

`('
The class of opening delimiters.

`)'
The class of closing delimiters.

`''
The class of expression-adhering characters. These characters
are part of a symbol if found within or adjacent to one, and are
part of a following expression if immediately preceding one, but
are like whitespace if surrounded by whitespace.

`"'
The class of string-quote characters. They match each other in
pairs, and the characters within the pair all lose their
syntactic significance except for the `\' and `/' classes of
escape characters, which can be used to include a string-quote
inside the string.

`$'
The class of self-matching delimiters. This is intended for
TeX's `$', which is used both to enter and leave math mode.
Thus, a pair of matching `$' characters surround each piece of
math mode TeX input. A pair of adjacent `$' characters act like
a single one for purposes of matching

`/'
The class of escape characters that always just deny the
following character its special syntactic significance. The
character after one of these escapes is always treated as
alphabetic.

`\'
The class of C-style escape characters. In practice, these are
treated just like `/'-class characters, because the extra
possibilities for C escapes (such as being followed by digits)
have no effect on where the containing expression ends.

`<'
The class of comment-starting characters. Only single-character
comment starters (such as `;' in Lisp mode) are represented this
way.

`>'
The class of comment-ending characters. Newline has this syntax
in Lisp mode.

The characters flagged as part of two-character comment delimiters
can have other syntactic functions most of the time. For example,
`/' and `*' in C code, when found separately, have nothing to do with
comments. The comment-delimiter significance overrides when the pair
of characters occur together in the proper order. Only the list and
sexp commands use the syntax table to find comments; the commands
specifically for comments have other variables that tell them where
to find comments. And the list and sexp commands notice comments
only if `parse-sexp-ignore-comments' is non-`nil'. This variable is
set to `nil' in modes where comment-terminator sequences are liable
to appear where there is no comment; for example, in Lisp mode where
the comment terminator is a newline but not every newline ends a
comment.

File: emacs, Node: Syntax Change, Prev: Syntax Entry, Up: Syntax

Altering Syntax Information
---------------------------

It is possible to alter a character's syntax table entry by storing a
new number in the appropriate element of the syntax table, but it
would be hard to determine what number to use. Therefore, Emacs
provides a command that allows you to specify the syntactic
properties of a character in a convenient way.

`M-x modify-syntax-entry' is the command to change a character's
syntax. It can be used interactively, and is also the means used by
major modes to initialize their own syntax tables. Its first
argument is the character to change. The second argument is a string
that specifies the new syntax. When called from Lisp code, there is
a third, optional argument, which specifies the syntax table in which
to make the change. If not supplied, or if this command is called
interactively, the third argument defaults to the current buffer's
syntax table.

1. The first character in the string specifies the syntactic class.
It is one of the characters in the previous table (*note Syntax
Entry::.).

2. The second character is the matching delimiter. For a character
that is not an opening or closing delimiter, this should be a
space, and may be omitted if no following characters are needed.

3. The remaining characters are flags. The flag characters allowed
are

`1'
Flag this character as the first of a two-character comment
starting sequence.

`2'
Flag this character as the second of a two-character
comment starting sequence.

`3'
Flag this character as the first of a two-character comment
ending sequence.

`4'
Flag this character as the second of a two-character
comment ending sequence.

A description of the contents of the current syntax table can be
displayed with `C-h s' (`describe-syntax'). The description of each
character includes both the string you would have to give to
`modify-syntax-entry' to set up that character's current syntax, and
some English to explain that string if necessary.

File: emacs, Node: Init File, Prev: Syntax, Up: Customization

The Init File, .emacs
=====================

When Emacs is started, it normally loads the file `.emacs' in your
home directory. This file, if it exists, should contain Lisp code.
It is called your "init file". The command line switches `-q' and
`-u' can be used to tell Emacs whether to load an init file (*note
Entering Emacs::.).

There can also be a "default init file", which is the library named
`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. But your init file, if any, is loaded
first; if it sets `inhibit-default-init' non-`nil', then `default' is
not loaded.

If you have a large amount of code in your `.emacs' file, you should
move it into another file named `SOMETHING.el', byte-compile it
(*note Lisp Libraries::.), and make your `.emacs' file load the other
file using `load'.

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

File: emacs, Node: Init Syntax, Next: Init Examples, Prev: Init File, Up: Init File

Init File Syntax
----------------

The `.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, `(setq
fill-column 60)' represents a call to the function `setq' which is
used to set the variable `fill-column' (*note Filling::.) to 60.

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

Numbers:
Numbers are written in decimal, with an optional initial minus
sign.

Strings:
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.

Newlines and special characters may be present literally in
strings. They can also be represented as backslash sequences:
`\n' for newline, `\b' for backspace, `\r' for carriage return,
`\t' for tab, `\f' for formfeed (control-l), `\e' for escape,
`\\' for a backslash, `\"' for a double-quote, or `\OOO' for the
character whose octal code is OOO. Backslash and double-quote
are the only characters for which backslash sequences are
mandatory.

`\C-' can be used as a prefix for a control character, as in
`\C-s' for ASCII Control-S, and `\M-' can be used as a prefix
for a meta character, as in `\M-a' for Meta-A or `\M-\C-a' for
Control-Meta-A.

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

True:
`t' stands for `true'.

False:
`nil' stands for `false'.

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

File: emacs, Node: Init Examples, Next: Terminal Init, Prev: Init Syntax, Up: Init File

Init File Examples
------------------

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

* Make TAB in C mode just insert a tab if point is in the middle
of a line.

(setq c-tab-always-indent nil)

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

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

(setq-default case-fold-search nil)

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

* Make Text mode the default mode for new buffers.

(setq default-major-mode 'text-mode)

Note that `text-mode' is used because it is the command for
entering the mode we want. A single-quote is written before it
to make a symbol constant; otherwise, `text-mode' would be
treated as a variable name.

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

(setq text-mode-hook
'(lambda () (auto-fill-mode 1)))

Here we have a variable whose value should be a Lisp function.
The function we supply is a list starting with `lambda', and a
single quote is written in front of it to make it (for the
purpose of this `setq') a list constant rather than an
expression. Lisp functions are not explained here, but for mode
hooks it is enough to know that `(auto-fill-mode 1)' is an
expression that will be executed when Text mode is entered, and
you could replace it with any other expression that you like, or
with several expressions in a row.

(setq text-mode-hook 'turn-on-auto-fill)

This is another way to accomplish the same result.
`turn-on-auto-fill' is a symbol whose function definition is
`(lambda () (auto-fill-mode 1))'.

* Load the installed Lisp library named `foo' (actually a file
`foo.elc' or `foo.el' in a standard Emacs directory).

(load "foo")

When the argument to `load' is a relative pathname, not starting
with `/' or `~', `load' searches the directories in `load-path'
(*note Loading::.).

* Load the compiled Lisp file `foo.elc' from your home directory.

(load "~/foo.elc")

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

* Rebind the key `C-x l' to run the function `make-symbolic-link'.

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

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

Note once again the single-quote used to refer to the symbol
`make-symbolic-link' instead of its value as a variable.

* Do the same thing for C mode only.

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

* Redefine all keys which now run `next-line' in Fundamental mode
so that they run `forward-line' instead.

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

* Make `C-x C-v' undefined.

(global-unset-key "\C-x\C-v")

One reason to undefine a key is so that you can make it a prefix.
Simply defining `C-x C-v ANYTHING' would make `C-x C-v' a
prefix, but `C-x C-v' must be freed of any non-prefix definition
first.

* Make `$' have the syntax of punctuation in Text mode. Note the
use of a character constant for `$'.

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

* Enable the use of the command `eval-expression' without
confirmation.

(put 'eval-expression 'disabled nil)

File: emacs, Node: Terminal Init, Prev: Init Examples, Up: Init File

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
TERMTYPE, the library is called `term/TERMTYPE' and it is found by
searching the directories `load-path' as usual and trying the
suffixes `.elc' and `.el'. Normally it appears in the subdirectory
`term' of the directory where most Emacs libraries are kept.

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

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 `aaa-48' and `aaa-30-rv' both use the library
`term/aaa'. The code in the library can use `(getenv "TERM")' to
find the full terminal type name.

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

The value of the variable `term-setup-hook', if not `nil', is called
as a function of no arguments at the end of Emacs initialization,
after both your `.emacs' file and any terminal-specific library have
been read in. You can set the value in the `.emacs' file to override
part of any of the terminal-specific libraries and to define
initializations for terminals that do not have a library.

File: emacs, Node: Quitting, Next: Lossage, Prev: Customization, Up: Top

Quitting and Aborting
=====================

`C-g'
Quit. Cancel running or partially typed command.

`C-]'
Abort innermost recursive editing level and cancel the command
which invoked it (`abort-recursive-edit').

`M-x top-level'
Abort all recursive editing levels that are currently executing.

`C-x u'
Cancel an already-executed command, usually (`undo').

There are two ways of cancelling commands which are not finished
executing: "quitting" with `C-g', and "aborting" with `C-]' or `M-x
top-level'. Quitting is cancelling a partially typed command or one
which is already running. Aborting is getting out of a recursive
editing level and cancelling the command that invoked the recursive
edit.

Quitting with `C-g' is used for getting rid of a partially typed
command, or a numeric argument that you don't want. It also stops a
running command in the middle in a relatively safe way, so you can
use it if you accidentally give a command which takes a long time.
In particular, it is safe to quit out of killing; either your text
will ALL still be there, or it will ALL be in the kill ring (or maybe
both). Quitting an incremental search does special things documented
under searching; in general, it may take two successive `C-g'
characters to get out of a search. `C-g' works by setting the
variable `quit-flag' to `t' the instant `C-g' is typed; Emacs Lisp
checks this variable frequently and quits if it is non-`nil'. `C-g'
is only actually executed as a command if it is typed while Emacs is
waiting for input.

If you quit twice in a row before the first `C-g' is recognized, you
activate the "emergency escape" feature and return to the shell.
*Note Emergency Escape::.

Aborting with `C-]' (`abort-recursive-edit') is used to get out of a
recursive editing level and cancel the command which invoked it.
Quitting with `C-g' does not do this, and could not do this, because
it is used to cancel a partially typed command within the recursive
editing level. Both operations are useful. For example, if you are
in the Emacs debugger (*note Lisp Debug::.) and have typed `C-u 8' to
enter a numeric argument, you can cancel that argument with `C-g' and
remain in the debugger.

The command `M-x top-level' is equivalent to "enough" `C-]' commands
to get you out of all the levels of recursive edits that you are in.
`C-]' gets you out one level at a time, but `M-x top-level' goes out
all levels at once. Both `C-]' and `M-x top-level' are like all
other commands, and unlike `C-g', in that they are effective only
when Emacs is ready for a command. `C-]' is an ordinary key and has
its meaning only because of its binding in the keymap. *Note
Recursive Edit::.

`C-x u' (`undo') is not strictly speaking a way of cancelling a
command, but you can think of it as cancelling a command already
finished executing. *Note Undo::.

File: emacs, Node: Lossage, Next: Bugs, Prev: Quitting, Up: Top

Dealing with Emacs Trouble
==========================

This section describes various conditions in which Emacs fails to
work, and how to recognize them and correct them.

* Menu:

* Stuck Recursive:: `[...]' in mode line around the parentheses
* Screen Garbled:: Garbage on the screen
* Text Garbled:: Garbage in the text
* Unasked-for Search:: Spontaneous entry to incremental search
* Emergency Escape:: Emergency escape--
What to do if Emacs stops responding
* Total Frustration:: When you are at your wits' end.

File: emacs, Node: Stuck Recursive, Next: Screen Garbled, Prev: Lossage, Up: Lossage

Recursive Editing Levels
------------------------

Recursive editing levels are important and useful features of Emacs,
but they can seem like malfunctions to the user who does not
understand them.

If the mode line has square brackets `[...]' around the parentheses
that contain the names of the major and minor modes, you have entered
a recursive editing level. If you did not do this on purpose, or if
you don't understand what that means, you should just get out of the
recursive editing level. To do so, type `M-x top-level'. This is
called getting back to top level. *Note Recursive Edit::.

File: emacs, Node: Screen Garbled, Next: Text Garbled, Prev: Stuck Recursive, Up: Lossage

Garbage on the Screen
---------------------

If the data on the screen looks wrong, the first thing to do is see
whether the text is really wrong. Type `C-l', to redisplay the
entire screen. If it appears correct after this, the problem was
entirely in the previous screen update.

Display updating problems often result from an incorrect termcap
entry for the terminal you are using. The file `etc/TERMS' in the
Emacs distribution gives the fixes for known problems of this sort.
`INSTALL' contains general advice for these problems in one of its
sections. Very likely there is simply insufficient padding for
certain display operations. To investigate the possibility that you
have this sort of problem, try Emacs on another terminal made by a
different manufacturer. If problems happen frequently on one kind of
terminal but not another kind, it is likely to be a bad termcap
entry, though it could also be due to a bug in Emacs that appears for
terminals that have or that lack specific features.

File: emacs, Node: Text Garbled, Next: Unasked-for Search, Prev: Screen Garbled, Up: Lossage

Garbage in the Text
-------------------

If `C-l' shows that the text is wrong, try undoing the changes to it
using `C-x u' until it gets back to a state you consider correct.
Also try `C-h l' to find out what command you typed to produce the
observed results.

If a large portion of text appears to be missing at the beginning or
end of the buffer, check for the word `Narrow' in the mode line. If
it appears, the text is still present, but marked off-limits. To
make it visible again, type `C-x w'. *Note Narrowing::.

File: emacs, Node: Unasked-for Search, Next: Emergency Escape, Prev: Text Garbled, Up: Lossage

Spontaneous Entry to Incremental Search
---------------------------------------

If Emacs spontaneously displays `I-search:' at the bottom of the
screen, it means that the terminal is sending `C-s' and `C-q'
according to the poorly designed xon/xoff "flow control" protocol.
You should try to prevent this by putting the terminal in a mode
where it will not use flow control or giving it enough padding that
it will never send a `C-s'. If that cannot be done, you must tell
Emacs to expect flow control to be used, until you can get a properly
designed terminal.

Information on how to do these things can be found in the file
`INSTALL' in the Emacs distribution.

File: emacs, Node: Emergency Escape, Next: Total Frustration, Prev: Unasked-for Search, Up: Lossage

Emergency Escape
----------------

Because at times there have been bugs causing Emacs to loop without
checking `quit-flag', a special feature causes Emacs to be suspended
immediately if you type a second `C-g' while the flag is already set,
so you can always get out of GNU Emacs. Normally Emacs recognizes
and clears `quit-flag' (and quits!) quickly enough to prevent this
from happening.

When you resume Emacs after a suspension caused by multiple `C-g', it
asks two questions before going back to what it had been doing:

Auto-save? (y or n)
Abort (and dump core)? (y or n)

Answer each one with `y' or `n' followed by RET.

Saying `y' to `Auto-save?' causes immediate auto-saving of all
modified buffers in which auto-saving is enabled.

Saying `y' to `Abort (and dump core)?' causes an illegal instruction
to be executed, dumping core. This is to enable a wizard to figure
out why Emacs was failing to quit in the first place. Execution does
not continue after a core dump. If you answer `n', execution does
continue. With luck, GNU Emacs will ultimately check `quit-flag' and
quit normally. If not, and you type another `C-g', it is suspended
again.

If Emacs is not really hung, just slow, you may invoke the double
`C-g' feature without really meaning to. Then just resume and answer
`n' to both questions, and you will arrive at your former state.
Presumably the quit you requested will happen soon.

The double-`C-g' feature may be turned off when Emacs is running
under a window system, since the window system always enables you to
kill Emacs or to create another window and run another program.

File: emacs, Node: Total Frustration, Prev: Emergency Escape, Up: Lossage

Help for Total Frustration
--------------------------

If using Emacs (or something else) becomes terribly frustrating and
none of the techniques described above solve the problem, Emacs can
still help you.

First, if the Emacs you are using is not responding to commands, type
`C-g C-g' to get out of it and then start a new one.

Second, type `M-x doctor RET'.

The doctor will make you feel better. Each time you say something to
the doctor, you must end it by typing RET RET. This lets the doctor
know you are finished.