   This file documents the GNU Emacs editor.

   Copyright (C) 1985, 1986, 1988 Richard M. Stallman.  Copyright (C)
1991, 1992, 1993, 1994 Lucid, Inc.

   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.

Examining and Editing Abbrevs
=============================

`M-x list-abbrevs'
     Print a list of all abbrev definitions.

`M-x edit-abbrevs'
     Edit a list of abbrevs; you can add, alter, or remove definitions.

   The output from `M-x list-abbrevs' looks like this:

     (lisp-mode-abbrev-table)
     "dk"	       0    "define-key"
     (global-abbrev-table)
     "dfn"	       0    "definition"

(Some blank lines of no semantic significance, and some other abbrev
tables, have been omitted.)

   A line containing a name in parentheses is the header for abbrevs in
a particular abbrev table; `global-abbrev-table' contains all the global
abbrevs, and the other abbrev tables that are named after major modes
contain the mode-specific abbrevs.

   Within each abbrev table, each non-blank line defines one abbrev.
The word at the beginning is the abbrev.  The number that appears is
the number of times the abbrev has been expanded.  Emacs keeps track of
this to help you see which abbrevs you actually use, in case you want
to eliminate those that you don't use often.  The string at the end of
the line is the expansion.

   `M-x edit-abbrevs' allows you to add, change or kill abbrev
definitions by editing a list of them in an Emacs buffer.  The list has
the format described above.  The buffer of abbrevs is called
`*Abbrevs*', and is in Edit-Abbrevs mode.  This mode redefines the key
`C-c C-c' to install the abbrev definitions as specified in the buffer.
The  `edit-abbrevs-redefine' command does this.  Any abbrevs not
described in the buffer are eliminated when this is done.

   `edit-abbrevs' is actually the same as `list-abbrevs', except that
it selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely
displays it in another window.

Saving Abbrevs
==============

   These commands allow you to keep abbrev definitions between editing
sessions.

`M-x write-abbrev-file'
     Write a file describing all defined abbrevs.

`M-x read-abbrev-file'
     Read such an abbrev file and define abbrevs as specified there.

`M-x quietly-read-abbrev-file'
     Similar, but do not display a message about what is going on.

`M-x define-abbrevs'
     Define abbrevs from buffer.

`M-x insert-abbrevs'
     Insert all abbrevs and their expansions into the buffer.

   Use `M-x write-abbrev-file' to save abbrev definitions for use in a
later session.  The command reads a file name using the minibuffer and
writes a description of all current abbrev definitions into the
specified file.  The text stored in the file looks like the output of
`M-x list-abbrevs'.

   `M-x read-abbrev-file' prompts for a file name using the minibuffer
and reads the specified file, defining abbrevs according to its
contents.  `M-x quietly-read-abbrev-file' is the same but does not
display a message in the echo area; it is actually useful primarily in
the `.emacs' file.  If you give an empty argument to either of these
functions, the file name Emacs uses is the value of the variable
`abbrev-file-name', which is by default `"~/.abbrev_defs"'.

   Emacs offers to save abbrevs automatically if you have changed any of
them, whenever it offers to save all files (for `C-x s' or `C-x C-c').
Set the variable `save-abbrevs' to `nil' to inhibit this feature.

   The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are
similar to the previous commands but work on text in an Emacs buffer.
`M-x insert-abbrevs' inserts text into the current buffer before point,
describing all current abbrev definitions; `M-x define-abbrevs' parses
the entire current buffer and defines abbrevs accordingly.

Dynamic Abbrev Expansion
========================

   The abbrev facility described above operates automatically as you
insert text, but all abbrevs must be defined explicitly.  By contrast,
"dynamic abbrevs" allow the meanings of abbrevs to be determined
automatically from the contents of the buffer, but dynamic abbrev
expansion happens only when you request it explicitly.

`M-/'
     Expand the word in the buffer before point as a "dynamic abbrev",
     by searching in the buffer for words starting with that
     abbreviation (`dabbrev-expand').

   For example, if the buffer contains `does this follow ' and you type
`f o M-/', the effect is to insert `follow' because that is the last
word in the buffer that starts with `fo'.  A numeric argument to `M-/'
says to take the second, third, etc. distinct expansion found looking
backward from point.  Repeating `M-/' searches for an alternative
expansion by looking farther back.  After the entire buffer before
point has been considered, the buffer after point is searched.

   Dynamic abbrev expansion is completely independent of Abbrev mode;
the expansion of a word with `M-/' is completely independent of whether
it has a definition as an ordinary abbrev.

Editing Pictures
****************

   If you want to create a picture made out of text characters (for
example, a picture of the division of a register into fields, as a
comment in a program), use the command `edit-picture' to enter Picture
mode.

   In Picture mode, editing is based on the "quarter-plane" model of
text.  In this model, the text characters lie studded on an area that
stretches infinitely far to the right and downward.  The concept of the
end of a line does not exist in this model; the most you can say is
where the last non-blank character on the line is found.

   Of course, Emacs really always considers text as a sequence of
characters, and lines really do have ends.  But in Picture mode most
frequently-used keys are rebound to commands that simulate the
quarter-plane model of text.  They do this by inserting spaces or by
converting tabs to spaces.

   Most of the basic editing commands of Emacs are redefined by Picture
mode to do essentially the same thing but in a quarter-plane way.  In
addition, Picture mode defines various keys starting with the `C-c'
prefix to run special picture editing commands.

   One of these keys, `C-c C-c', is pretty important.  Often a picture
is part of a larger file that is usually edited in some other major
mode.  `M-x edit-picture' records the name of the previous major mode.
You can then use the `C-c C-c' command (`picture-mode-exit') to restore
that mode.  `C-c C-c' also deletes spaces from the ends of lines,
unless you give it a numeric argument.

   The commands used in Picture mode all work in other modes (provided
the `picture' library is loaded), but are only  bound to keys in
Picture mode.  Note that the descriptions below talk of moving "one
column" and so on, but all the picture mode commands handle numeric
arguments as their normal equivalents do.

   Turning on Picture mode calls the value of the variable
`picture-mode-hook' as a function, with no arguments, if that value
exists and is non-`nil'.

Basic Editing in Picture Mode
=============================

   Most keys do the same thing in Picture mode that they usually do,
but do it in a quarter-plane style.  For example, `C-f' is rebound to
run `picture-forward-column', which moves point one column to the
right, by inserting a space if necessary, so that the actual end of the
line makes no difference.  `C-b' is rebound to run
`picture-backward-column', which always moves point left one column,
converting a tab to multiple spaces if necessary.  `C-n' and `C-p' are
rebound to run `picture-move-down' and `picture-move-up', which can
either insert spaces or convert tabs as necessary to make sure that
point stays in exactly the same column.  `C-e' runs
`picture-end-of-line', which moves to after the last non-blank
character on the line.  There was no need to change `C-a', as the choice
of screen model does not affect beginnings of lines.

   Insertion of text is adapted to the quarter-plane screen model
through the use of Overwrite mode (see Minor Modes.).
Self-inserting characters replace existing text, column by column,
rather than pushing existing text to the right.  RET runs
`picture-newline', which just moves to the beginning of the following
line so that new text will replace that line.

   Text is erased instead of deleted and killed.  DEL
(`picture-backward-clear-column') replaces the preceding character with
a space rather than removing it.  `C-d' (`picture-clear-column') does
the same in a forward direction.  `C-k' (`picture-clear-line') really
kills the contents of lines, but never removes the newlines from a
buffer.

   To do actual insertion, you must use special commands.  `C-o'
(`picture-open-line') creates a blank line, but does so after the
current line; it never splits a line.  `C-M-o', `split-line', makes
sense in Picture mode, so it remains unchanged.  LFD
(`picture-duplicate-line') inserts another line with the same contents
below the current line.

   To actually delete parts of the picture, use `C-w', or with `C-c
C-d' (which is defined as `delete-char', as `C-d' is in other modes),
or with one of the picture rectangle commands (see Rectangles in Picture.).

Controlling Motion After Insert
===============================

   Since "self-inserting" characters just overwrite and move point in
Picture mode, there is no essential restriction on how point should be
moved.  Normally point moves right, but you can specify any of the eight
orthogonal or diagonal directions for motion after a "self-inserting"
character.  This is useful for drawing lines in the buffer.

`C-c <'
     Move left after insertion (`picture-movement-left').

`C-c >'
     Move right after insertion (`picture-movement-right').

`C-c ^'
     Move up after insertion (`picture-movement-up').

`C-c .'
     Move down after insertion (`picture-movement-down').

`C-c `'
     Move up and left ("northwest") after insertion
     (`picture-movement-nw').

`C-c ''
     Move up and right ("northeast") after insertion
     (`picture-movement-ne').

`C-c /'
     Move down and left ("southwest") after insertion
     (`picture-movement-sw').

`C-c \'
     Move down and right ("southeast") after insertion
     (`picture-movement-se').

   Two motion commands move based on the current Picture insertion
direction.  The command `C-c C-f' (`picture-motion') moves in the same
direction as motion after "insertion" currently does, while `C-c C-b'
(`picture-motion-reverse') moves in the opposite direction.

Picture Mode Tabs
=================

   Two kinds of tab-like action are provided in Picture mode.
Context-based tabbing is done with `M-TAB' (`picture-tab-search').
With no argument, it moves to a point underneath the next "interesting"
character that follows whitespace in the previous non-blank line.
"Next" here means "appearing at a horizontal position greater than the
one point starts out at".  With an argument, as in `C-u M-TAB', the
command moves to the next such interesting character in the current
line.  `M-TAB' does not change the text; it only moves point.
"Interesting" characters are defined by the variable
`picture-tab-chars', which contains a string of characters considered
interesting.  Its default value is `"!-~"'.

   TAB itself runs `picture-tab', which operates based on the current
tab stop settings; it is the Picture mode equivalent of
`tab-to-tab-stop'.  Without arguments it just moves point, but with a
numeric argument it clears the text that it moves over.

   The context-based and tab-stop-based forms of tabbing are brought
together by the command `C-c TAB' (`picture-set-tab-stops'.) This
command sets the tab stops to the positions which `M-TAB' would
consider significant in the current line.  If you use this command with
TAB, you can get the effect of context-based tabbing.  But `M-TAB' is
more convenient in the cases where it is sufficient.

Picture Mode Rectangle Commands
===============================

   Picture mode defines commands for working on rectangular pieces of
the text in ways that fit with the quarter-plane model.  The standard
rectangle commands may also be useful (see Rectangles.).

`C-c C-k'
     Clear out the region-rectangle (`picture-clear-rectangle').  With
     argument, kill it.

`C-c C-w R'
     Similar but save rectangle contents in register R first
     (`picture-clear-rectangle-to-register').

`C-c C-y'
     Copy last killed rectangle into the buffer by overwriting, with
     upper left corner at point (`picture-yank-rectangle').  With
     argument, insert instead.

`C-c C-x R'
     Similar, but use the rectangle in register R
     (`picture-yank-rectangle-from-register').

   The picture rectangle commands `C-c C-k' (`picture-clear-rectangle')
and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the
standard rectangle commands in that they normally clear the rectangle
instead of deleting it; this is analogous with the way `C-d' is changed
in Picture mode.

   However, deletion of rectangles can be useful in Picture mode, so
these commands delete the rectangle if given a numeric argument.

   The Picture mode commands for yanking rectangles differ from the
standard ones in overwriting instead of inserting.  This is the same
way that Picture mode insertion of other text is different from other
modes.  `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting)
the rectangle that was most recently killed, while `C-c C-x'
(`picture-yank-rectangle-from-register') does for the rectangle found
in a specified register.

   Since most region commands in Picture mode operate on rectangles,
when you select a region of text with the mouse in Picture mode, it is
highlighted as a rectangle.

Sending Mail
************

   To send a message in Emacs, start by typing the command (`C-x m') to
select and initialize the `*mail*' buffer.  You can then edit the text
and headers of the message in the mail buffer, and type the command
(`C-c C-c') to send the message.

`C-x m'
     Begin composing a message to send (`mail').

`C-x 4 m'
     Likewise, but display the message in another window
     (`mail-other-window').

`C-c C-c'
     In Mail mode, send the message and switch to another buffer
     (`mail-send-and-exit').

   The command `C-x m' (`mail') selects a buffer named `*mail*' and
initializes it with the skeleton of an outgoing message.  `C-x 4 m'
(`mail-other-window') selects the `*mail*' buffer in a different
window, leaving the previous current buffer visible.

   Because the buffer for mail composition is an ordinary Emacs buffer,
you can switch to other buffers while in the middle of composing mail,
and switch back later (or never).  If you use the `C-x m' command again
when you have been composing another message but have not sent it, a
new mail buffer will be created; in this way, you can compose multiple
messages at once.  You can switch back to and complete an unsent
message by using the normal buffer selection mechanisms.

   `C-u C-x m' is another way to switch back to a message in progress:
it will search for an existing, unsent mail message buffer and select
it.

The Format of the Mail Buffer
=============================

   In addition to the "text" or contents, a message has "header
fields", which say who sent it, when, to whom, why, and so on.  Some
header fields, such as the date and sender, are created automatically
after the message is sent.  Others, such as the recipient names, must
be specified by you in order to send the message properly.

   Mail mode provides a few commands to help you edit some header
fields, and some are preinitialized in the buffer automatically at
times.  You can insert or edit any header fields using ordinary editing
commands.

   The line in the buffer that says:

     --text follows this line--

is a special delimiter that separates the headers you have specified
from the text.  Whatever follows this line is the text of the message;
the headers precede it.  The delimiter line itself does not appear in
the message actually sent.  The text used for the delimiter line is
controlled by the variable `mail-header-separator'.

   Here is an example of what the headers and text in the `*mail*'
buffer might look like.

     To: rms@mc
     CC: mly@mc, rg@oz
     Subject: The Emacs Manual
     --Text follows this line--
     Please ignore this message.

Mail Header Fields
==================

   There are several header fields you can use in the `*mail*' buffer.
Each header field starts with a field name at the beginning of a line,
terminated by a colon.  It does not matter whether you use upper or
lower case in the field name.  After the colon and optional whitespace
comes the contents of the field.

`To'
     This field contains the mailing addresses of the message.

`Subject'
     The contents of the `Subject' field should be a piece of text that
     says what the message is about.  Subject fields are useful because
     most mail-reading programs can provide a summary of messages,
     listing the subject of each message but not its text.

`CC'
     This field contains additional mailing addresses to send the
     message to, but whose readers should not regard the message as
     addressed to them.

`BCC'
     This field contains additional mailing addresses to send the
     message to, but which should not appear in the header of the
     message actually sent.

`FCC'
     This field contains the name of one file (in Unix mail file
     format) to which a copy of the message should be appended when the
     message is sent.

`From'
     Use the `From' field to say who you are, when the account you are
     using to send the mail is not your own.  The contents of the
     `From' field should be a valid mailing address, since replies will
     normally go there.

`Reply-To'
     Use the `Reply-To' field to direct replies to a different address,
     not your own. `From' and `Reply-To' have the same effect on where
     replies go, but they convey a different meaning to the person who
     reads the message.

`In-Reply-To'
     This field contains a piece of text describing a message you are
     replying to.  Some mail systems can use the information to
     correlate related pieces of mail.  Normally this field is filled
     in by Rmail when you are replying to a message in Rmail, and you
     never need to think about it (see Rmail.).

The `To', `CC', `BCC' and `FCC' fields can appear any number of times,
to specify many places to send the message.

The `To', `CC', and `BCC', fields can have continuation lines.  All the
lines starting with whitespace, following the line on which the field
starts, are considered part of the field.  For example,

     To: foo@here, this@there,
       me@gnu.cambridge.mass.usa.earth.spiral3281

If you have a `~/.mailrc' file, Emacs scans it for mail aliases the
first time you try to send mail in an Emacs session.  Emacs expands
aliases found in the `To', `CC', and `BCC' fields where appropriate.
You can set the variable `mail-abbrev-mailrc-file' to the name of the
file with mail aliases.  If `nil', `~/.mailrc' is used.

   Your `.mailrc' file ensures that word-abbrevs are defined for each
of your mail aliases when point is in a `To', `CC', `BCC', or `From'
field.  The aliases are defined in your `.mailrc' file or in a file
specified by the MAILRC environment variable if it exists.  Your mail
aliases expand any time you type a word-delimiter at the end of an
abbreviation.

   In this version of Emacs, what you see is what you get: in contrast
to some other versions, no abbreviations are expanded after you have
sent the mail.  This means you don't suffer the annoyance of having the
system do things behind your back -- if the system rewrites an address
you typed, you know it immediately, instead of after the mail has been
sent and it's too late to do anything about it.  For example, you will
never again be in trouble because you forgot to delete an old alias
from your `.mailrc' and a new local user is given a userid which
conflicts with one of your aliases.

   Your mail alias abbrevs are in effect only when point is in an
appropriate header field. The mail aliases will not expand in the body
of the message, or in other header fields.  The default mode-specific
abbrev table `mail-mode-abbrev-table' is used instead if defined.  That
means if you have been using mail-mode specific abbrevs, this code will
not adversely affect you.  You can control which header fields the
abbrevs are used in by changing the variable `mail-abbrev-mode-regexp'.

   If auto-fill mode is on, abbrevs wrap at commas instead of at word
boundaries, and header continuation lines will be properly indented.

   You can also insert a mail alias with
`mail-interactive-insert-alias'.  This function, which is bound to `C-c
C-a', prompts you for an alias (with completion) and inserts its
expansion at point.

   In this version of Emacs, it is possible to have lines like the
following in your `.mailrc' file:

          alias someone "John Doe <doe@quux.com>"

   That is, if you want an address to have embedded spaces, simply
surround it with double-quotes.  The quotes are necessary because the
format of the `.mailrc' file uses spaces as address delimiters.

   Aliases in the `.mailrc' file may be nested. For example, assume you
define aliases like:
          alias group1 fred ethel
          alias group2 larry curly moe
          alias everybody group1 group2

   When you now type `everybody' on the `To' line, it will expand to:
          fred, ethyl, larry, curly, moe

   Aliases may contain forward references; the alias of `everybody' in
the example above can preceed the aliases of `group1' and `group2'.

   In this version of Emacs, you can use the `source' `.mailrc' command
for reading aliases from some other file as well.

   Aliases may contain hyphens, as in `"alias foo-bar foo@bar"', even
though word-abbrevs normally cannot contain hyphens.

   To read in the contents of another `.mailrc'-type file from Emacs,
use the command `M-x merge-mail-aliases'.  The `rebuild-mail-aliases'
command is similar, but deletes existing aliases first.

   If you want multiple addresses separated by a string other than `,'
(a comma), then set the variable `mail-alias-seperator-string' to it.
This has to be a comma bracketed by whitespace if you want any kind  of
reasonable behavior.

   If the variable `mail-archive-file-name' is non-`nil', it should be
a string naming a file.  Each time you start to edit a message to send,
an `FCC' field is entered for that file.  Unless you remove the `FCC'
field, every message is written into that file when it is sent.

Mail Mode
=========

   The major mode used in the `*mail*' buffer is Mail mode.  Mail mode
is similar to Text mode, but several commands are provided on the `C-c'
prefix.  These commands all deal specifically with editing or sending
the message.

`C-c C-s'
     Send the message, and leave the `*mail*' buffer selected
     (`mail-send').

`C-c C-c'
     Send the message, and select some other buffer
     (`mail-send-and-exit').

`C-c C-f C-t'
     Move to the `To' header field, creating one if there is none
     (`mail-to').

`C-c C-f C-s'
     Move to the `Subject' header field, creating one if there is none
     (`mail-subject').

`C-c C-f C-c'
     Move to the `CC' header field, creating one if there is none
     (`mail-cc').

`C-c C-w'
     Insert the file `~/.signature' at the end of the message text
     (`mail-signature').

`C-c C-y'
     Yank the selected message from Rmail (`mail-yank-original').  This
     command does nothing unless your command to start sending a
     message was issued with Rmail.

`C-c C-q'
     Fill all paragraphs of yanked old messages, each individually
     (`mail-fill-yanked-message').

`button3'
     Pops up a menu of useful mail-mode commands.

   There are two ways to send a message.  `C-c C-c'
(`mail-send-and-exit') is the usual way to send the message.  It sends
the message and then deletes the window (if there is another window) or
switches to another buffer.  It puts the `*mail*' buffer at the lowest
priority for automatic reselection, since you are finished with using
it.  `C-c C-s' (`mail-send') sends the message and marks the `*mail*'
buffer unmodified, but leaves that buffer selected so that you can
modify the message (perhaps with new recipients) and send it again.

   Mail mode provides some other special commands that are useful for
editing the headers and text of the message before you send it.  There
are three commands defined to move point to particular header fields,
all based on the prefix `C-c C-f' (`C-f' is for "field").  They are
`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s'
(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc')
for the `CC' field.  These fields have special motion commands because
they are edited most frequently.

   `C-c C-w' (`mail-signature') adds a standard piece of text at the
end of the message to say more about who you are.  The text comes from
the file `.signature' in your home directory.

   When you use an Rmail command to send mail from the Rmail mail
reader, you can use `C-c C-y' `mail-yank-original' inside the `*mail*'
buffer to insert the text of the message you are replying to.  Normally
Rmail indents each line of that message four spaces and eliminates most
header fields.  A numeric argument specifies the number of spaces to
indent.  An argument of just `C-u' says not to indent at all and not to
eliminate anything.  `C-c C-y' always uses the current message from the
`RMAIL' buffer, so you can insert several old messages by selecting one
in `RMAIL', switching to `*mail*' and yanking it, then switching back
to `RMAIL' to select another.

   After using `C-c C-y', you can use the command `C-c C-q'
(`mail-fill-yanked-message') to fill the paragraphs of the yanked old
message or messages.  One use of `C-c C-q' fills all such paragraphs,
each one separately.

   Clicking the right mouse button in a mail buffer pops up a menu of
the above commands, for easy access.

   Turning on Mail mode (which `C-x m' does automatically) calls the
value of `text-mode-hook', if it is not void or `nil', and then calls
the value of `mail-mode-hook' if that is not void or `nil'.

Reading Mail With Rmail
***********************

   Rmail is an Emacs subsystem for reading and disposing of mail that
you receive.  Rmail stores mail messages in files called Rmail files.
You read the messages in an Rmail file in a special major mode, Rmail
mode, which redefines most letters to run commands for managing mail.
To enter Rmail, type `M-x rmail'.  This reads your primary mail file,
merges new mail in from your inboxes, displays the first new message,
and lets you begin reading.

   Using Rmail in the simplest fashion, you have one Rmail file,
`~/RMAIL', in which all of your mail is saved.  It is called your
"primary mail file".  You can also copy messages into other Rmail files
and then edit those files with Rmail.

   Rmail displays only one message at a time.  It is called the
"current message".  Rmail mode's special commands can move to another
message, delete the message, copy the message into another file, or
send a reply.

   Within the Rmail file, messages are arranged sequentially in order
of receipt.  They are also assigned consecutive integers as their
"message numbers".  The number of the current message is displayed in
Rmail's mode line, followed by the total number of messages in the
file.  You can move to a message by specifying its message number using
the `j' key (see Rmail Motion.).

   Following the usual conventions of Emacs, changes in an Rmail file
become permanent only when the file is saved.  You can do this with `s'
(`rmail-save'), which also expunges deleted messages from the file
first (see Rmail Deletion.).  To save the file without expunging,
use `C-x C-s'.  Rmail saves the Rmail file automatically when moving new
mail from an inbox file (see Rmail Inbox.).

   You can exit Rmail with `q' (`rmail-quit'); this expunges and saves
the Rmail file and then switches to another buffer.  However, there is
no need to `exit' formally.  If you switch from Rmail to editing in
other buffers, and never happen to switch back, you have exited.  Just
make sure to save the Rmail file eventually (like any other file you
have changed).  `C-x s' is a good enough way to do this (see
Saving.).

Scrolling Within a Message
==========================

   When Rmail displays a message that does not fit on the screen, you
have to scroll through it.  You could use `C-v', `M-v', and `M-<', but
scrolling is so frequent in Rmail that it deserves to be easier to type.

`SPC'
     Scroll forward (`scroll-up').

`DEL'
     Scroll backward (`scroll-down').

`.'
     Scroll to start of message (`rmail-beginning-of-message').

   Since the most common thing to do while reading a message is to
scroll through it by screenfuls, Rmail makes SPC and DEL synonyms of
`C-v' (`scroll-up') and `M-v' (`scroll-down')

   The command `.' (`rmail-beginning-of-message') scrolls back to the
beginning of a selected message.  This is not quite the same as `M-<':
first, it does not set the mark; secondly, it resets the buffer
boundaries to the current message if you have changed them.

Moving Among Messages
=====================

   The most basic thing to do with a message is to read it.  The way to
do this in Rmail is to make the message current.  You can make any
message current, given its message number, by using the `j' command, but
people most often move sequentially through the file, since this is the
order of receipt of messages.  When you enter Rmail, you are positioned
at the first new message (new messages are those received after you last
used Rmail), or at the last message if there are no new messages this
time.  Move forward to see other new messages if there are any; move
backward to re-examine old messages.

`n'
     Move to the next non-deleted message, skipping any intervening
     deleted
     messages (`rmail-next-undeleted-message').

`p'
     Move to the previous non-deleted message
     (`rmail-previous-undeleted-message').

`M-n'
     Move to the next message, including deleted messages
     (`rmail-next-message').

`M-p'
     Move to the previous message, including deleted messages
     (`rmail-previous-message').

`j'
     Move to the first message.  With argument N, move to message
     number N (`rmail-show-message').

`>'
     Move to the last message (`rmail-last-message').

`M-s REGEXP RET'
     Move to the next message containing a match for REGEXP
     (`rmail-search').  If REGEXP is empty, the last regexp used is
     used again.

`- M-s REGEXP RET'
     Move to the previous message containing a match for REGEXP.  If
     REGEXP is empty, the last regexp used is used again.

   To move among messages in Rmail, you can use `n' and `p'.  These
keys move through the messages sequentially but skip over deleted
messages, which is usually what you want to do.  Their command
definitions are named `rmail-next-undeleted-message' and
`rmail-previous-undeleted-message'.  If you do not want to skip deleted
messages--for example, if you want to move to a message to undelete
it--use the variants `M-n' (`rmail-next-message') and `M-p'
(`rmail-previous-message').  A numeric argument to any of these
commands serves as a repeat count.

   In Rmail, you can specify a numeric argument by just typing the
digits.  It is not necessary to type `C-u' first.

   The `M-s' (`rmail-search') command is Rmail's version of search.
The usual incremental search command `C-s' works in Rmail, but searches
only within the current message.  The purpose of `M-s' is to search for
another message.  It reads a regular expression (see Regexps.)
non-incrementally, then starts searching at the beginning of the
following message for a match.  The message containing the match is
selected.

   To search backward in the file for another message, give `M-s' a
negative argument.  In Rmail you can do this with `- M-s'.

   It is also possible to search for a message based on labels.  See
Rmail Labels.

   To move to a message specified by absolute message number, use `j'
(`rmail-show-message') with the message number as argument.  With no
argument, `j' selects the first message.  `>' (`rmail-last-message')
selects the last message.

Deleting Messages
=================

   When you no longer need to keep a message, you can "delete" it.  This
flags it as ignorable, and some Rmail commands will pretend it is no
longer present, but it still has its place in the Rmail file and still
has its message number.

   "Expunging" the Rmail file actually removes the deleted messages.
The remaining messages are renumbered consecutively.  Expunging is the
only action that changes the message number of any message, except for
undigestifying (see Rmail Digest.).

`d'
     Delete the current message and move to the next non-deleted message
     (`rmail-delete-forward').

`C-d'
     Delete the current message and move to the previous non-deleted
     message (`rmail-delete-backward').

`u'
     Undelete the current message, or move back to a deleted message and
     undelete it (`rmail-undelete-previous-message').

`e'
`x'
     Expunge the Rmail file (`rmail-expunge').  These two commands are
     synonyms.

   There are two Rmail commands for deleting messages.  Both delete the
current message and select another message.  `d'
(`rmail-delete-forward') moves to the following message, skipping
messages already deleted, while `C-d' (`rmail-delete-backward') moves
to the previous non-deleted message.  If there is no non-deleted
message to move to in the specified direction, the message that was just
deleted remains current.

   To make all deleted messages disappear from the Rmail file, type `e'
(`rmail-expunge').  Until you do this, you can still "undelete" the
deleted messages.

   To undelete, type `u' (`rmail-undelete-previous-message'), which
cancels the effect of a `d' command (usually).  It undeletes the
current message if the current message is deleted.  Otherwise it moves
backward to previous messages until a deleted message is found, and
undeletes that message.

   You can usually undo a `d' with a `u' because the `u' moves back to
and undeletes the message that the `d' deleted.  This does not work
when the `d' skips a few already-deleted messages that follow the
message being deleted; in that case the `u' command undeletes the last
of the messages that were skipped.  There is no clean way to avoid this
problem.  However, by repeating the `u' command, you can eventually get
back to the message you intended to undelete.  You can also reach that
message with `M-p' commands and then type `u'.

   A deleted message has the `deleted' attribute, and as a result
`deleted' appears in the mode line when the current message is deleted.
In fact, deleting or undeleting a message is nothing more than adding
or removing this attribute.  See Rmail Labels.

Rmail Files and Inboxes
=======================

   Unix places your incoming mail in a file called your "inbox".  When
you start up Rmail, it copies the new messages from your inbox into
your primary mail file, an Rmail file which also contains other messages
saved from previous Rmail sessions.  In this file, you actually read
the mail with Rmail.  The operation is called "getting new mail".  You
can repeat it at any time using the `g' key in Rmail.  The inbox file
name is `/usr/spool/mail/USERNAME' in Berkeley Unix,
`/usr/mail/USERNAME' in system V.

   There are two reason for having separate Rmail files and inboxes.

  1. The format in which Unix delivers the mail in the inbox is not
     adequate for Rmail mail storage.  It has no way to record
     attributes (such as `deleted') or user-specified labels; it has no
     way to record old headers and reformatted headers; it has no way
     to record cached summary line information.

  2. It is very cumbersome to access an inbox file without danger of
     losing mail, because it is necessary to interlock with mail
     delivery.  Moreover, different Unix systems use different
     interlocking techniques.  The strategy of moving mail out of the
     inbox once and for all into a separate Rmail file avoids the need
     for interlocking in all the rest of Rmail, since only Rmail
     operates on the Rmail file.

   When getting new mail, Rmail first copies the new mail from the inbox
file to the Rmail file and saves the Rmail file.  It then deletes the
inbox file.  This way a system crash may cause duplication of mail
between the inbox and the Rmail file, but it cannot lose mail.

   Copying mail from an inbox in the system's mailer directory actually
puts it in an intermediate file, `~/.newmail'.  This is because the
interlocking is done by a C program that copies to another file.
`~/.newmail' is deleted after mail merging is successful.  If there is
a crash at the wrong time, this file will continue to exist and will be
used as an inbox the next time you get new mail.

Multiple Mail Files
===================

   Rmail operates by default on your "primary mail file", which is
named `~/RMAIL' and which receives your incoming mail from your system
inbox file. You can also have other mail files and edit them with
Rmail.  These files can receive mail through their own inboxes, or you
can move messages into them by explicit command in Rmail (see Rmail Output.).

`i FILE RET'
     Read FILE into Emacs and run Rmail on it (`rmail-input').

`M-x set-rmail-inbox-list RET FILES RET'
     Specify inbox file names for current Rmail file to get mail from.

`g'
     Merge new mail from current Rmail file's inboxes
     (`rmail-get-new-mail').

`C-u g FILE'
     Merge new mail from inbox file FILE.

   To run Rmail on a file other than your primary mail file, you may use
the `i' (`rmail-input') command in Rmail.  This visits the file, puts
it in Rmail mode, and then gets new mail from the file's inboxes if
any.  You can also use `M-x rmail-input' even when not in Rmail.

   The file you read with `i' does not have to be in Rmail file format.
It could also be Unix mail format, mmdf format, or it could be a mixture
of all three, as long as each message has one of the three formats.
Rmail recognizes all three and converts all the messages to proper Rmail
format before showing you the file.

   Each Rmail file can contain a list of inbox file names; you can
specify this list with `M-x set-rmail-inbox-list RET FILES RET'.  The
argument can contain any number of file names, separated by commas.  It
can also be empty, which specifies that this file should have no
inboxes.  Once a list of inboxes is specified, the Rmail file remembers
it permanently until it is explicitly changed.

   If an Rmail file has inboxes, new mail is merged in from the inboxes
when you bring the Rmail file into Rmail, and when you use the `g'
(`rmail-get-new-mail') command.  If the Rmail file specifies no
inboxes, then no new mail is merged in at these times.  A special
exception is made for your primary mail file: Rmail uses the standard
system inbox for it if it does not specify an inbox.

   To merge mail from a file that is not the usual inbox, give the `g'
key a numeric argument, as in `C-u g'.  Rmail prompts you for a file
name and merges mail from that file.  The inbox file is not deleted or
changed at all when you use `g' with an argument, so this is a general
way of merging one file of messages into another.

Copying Messages Out to Files
=============================

`o FILE RET'
     Append a copy of the current message to the file FILE, writing it
     in Rmail file format (`rmail-output-to-rmail-file').

`C-o FILE RET'
     Append a copy of the current message to the file FILE, writing it
     in Unix mail file format (`rmail-output').

   If an Rmail file has no inboxes, use explicit `o' commands to write
Rmail files.

   `o' (`rmail-output-to-rmail-file') appends the current message in
Rmail format to the end of a specified file.  This is the best command
to use to move messages between Rmail files.  If you are currently
visiting the other Rmail file, copying is done into the other file's
Emacs buffer instead.  You should eventually save the buffer on disk.

   The `C-o' (`rmail-output') command in Rmail appends a copy of the
current message to a specified file, in Unix mail file format.  This is
useful for moving messages into files to be read by other mail
processors that do not understand Rmail format.

   Copying a message with `o' or `C-o' gives the original copy of the
message the `filed' attribute. `filed' appears in the mode line when
such a message is current.

   Normally you should use only `o' to output messages to other Rmail
files, never `C-o'.  But it is also safe if you always use `C-o', never
`o'.  When a file is visited in Rmail, the last message is checked, and
if it is in Unix format, the entire file is scanned and all Unix-format
messages are converted to Rmail format.  (The reason for checking the
last message is that scanning the file is slow and most Rmail files
have only Rmail format messages.)  If you use `C-o' consistently, the
last message is guaranteed to be in Unix format, so Rmail will convert
all messages properly.

   When you and other users want to append mail to the same file, you
probably always want to use `C-o' instead of `o'.  Other mail
processors may not know Rmail format but will know Unix format.

   In any case, always use `o' to add to an Rmail file that is being
visited in Rmail.  Adding messages with `C-o' to the actual disk file
will trigger a "simultaneous editing" warning when you ask to save the
Emacs buffer, and the messages will be lost if you do save.

Labels
======

   Each message can have various "labels" assigned to it as a means of
classification.  A label has a name; different names mean different
labels.  Any given label is either present or absent on a particular
message.  A few label names have standard meanings and are given to
messages automatically by Rmail when appropriate; these special labels
are called "attributes".  All other labels are assigned by the user.

`a LABEL RET'
     Assign the label LABEL to the current message (`rmail-add-label').

`k LABEL RET'
     Remove the label LABEL from the current message
     (`rmail-kill-label').

`C-M-n LABELS RET'
     Move to the next message that has one of the labels LABELS
     (`rmail-next-labeled-message').

`C-M-p LABELS RET'
     Move to the previous message that has one of the labels LABELS
     (`rmail-previous-labeled-message').

`C-M-l LABELS RET'
     Make a summary of all messages containing any of the labels LABELS
     (`rmail-summary-by-labels').

Specifying an empty string for one these commands means to use the last
label specified for any of these commands.

   The `a' (`rmail-add-label') and `k' (`rmail-kill-label') commands
allow you to assign or remove any label on the current message.  If the
LABEL argument is empty, it means to assign or remove the label most
recently assigned or removed.

   Once you have given messages labels to classify them as you wish,
there are two ways to use the labels: in moving and in summaries.

   The command `C-M-n LABELS RET' (`rmail-next-labeled-message') moves
to the next message that has one of the labels LABELS.  LABELS is one
or more label names, separated by commas.  `C-M-p'
(`rmail-previous-labeled-message') is similar, but moves backwards to
previous messages.  A preceding numeric argument to either one serves
as a repeat count.

   The command `C-M-l LABELS RET' (`rmail-summary-by-labels') displays
a summary containing only the messages that have at least one of a
specified set of messages.  The argument LABELS is one or more label
names, separated by commas.  See Rmail Summary, for information on
summaries.

   If the LABELS argument to `C-M-n', `C-M-p' or `C-M-l' is empty, it
means to use the last set of labels specified for any of these commands.

   Some labels such as `deleted' and `filed' have built-in meanings and
are assigned to or removed from messages automatically at appropriate
times; these labels are called "attributes".  Here is a list of Rmail
attributes:

`unseen'
     Means the message has never been current.  Assigned to messages
     when they come from an inbox file, and removed when a message is
     made current.

`deleted'
     Means the message is deleted.  Assigned by deletion commands and
     removed by undeletion commands (see Rmail Deletion.).

`filed'
     Means the message has been copied to some other file.  Assigned by
     the file output commands (see Rmail Files.).

`answered'
     Means you have mailed an answer to the message.  Assigned by the
     `r' command (`rmail-reply').  See Rmail Reply.

`forwarded'
     Means you have forwarded the message to other users.  Assigned by
     the `f' command (`rmail-forward').  See Rmail Reply.

`edited'
     Means you have edited the text of the message within Rmail.  See
     Rmail Editing.

   All other labels are assigned or removed only by the user, and it is
up to the user to decide what they mean.

Summaries
=========

   A "summary" is a buffer Rmail creates and displays to give you an
overview of the mail in an Rmail file.  It contains one line per
message; each line shows the message number, the sender, the labels,
and the subject.  When you select the summary buffer, you can use a
number of commands to select messages by moving in the summary buffer,
or to delete or undelete messages.

   A summary buffer applies to a single Rmail file only; if you are
editing multiple Rmail files, they have separate summary buffers.  The
summary buffer name is generated by appending `-summary' to the Rmail
buffer's name.  Only one summary buffer is displayed at a time unless
you make several windows and select the summary buffers by hand.