DP Tool Club 8/CDASC08.ISO/VRAC/E17INFO.ZIP/EMACS-12

GNU Info File | 1993-07-18 | 47.3 KB | 1,144 lines

This is Info file ../info/emacs, produced by Makeinfo-1.54 from the
input file emacs.texi.


File: emacs,  Node: Saving Abbrevs,  Next: Dynamic Abbrevs,  Prev: Editing Abbrevs,  Up: Abbrevs

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 a 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 definitions in current buffer.

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

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

   `M-x read-abbrev-file' reads a file name using the minibuffer and
reads the file, defining abbrevs according to the contents of the file.
`M-x quietly-read-abbrev-file' is the same except that it does not
display a message in the echo area saying that it is doing its work; it
is actually useful primarily in the `.emacs' file.  If an empty
argument is given to either of these functions, the file name used is
the value of the variable `abbrev-file-name', which is by default
`"~/.abbrev_defs"'.

   Emacs will offer 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').  This feature can be inhibited by setting the variable
`save-abbrevs' to `nil'.

   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.


File: emacs,  Node: Dynamic Abbrevs,  Prev: Saving Abbrevs,  Up: Abbrevs

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.


File: emacs,  Node: Picture,  Next: Sending Mail,  Prev: Abbrevs,  Up: Top

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 `M-x edit-picture' to enter
Picture mode.

   In Picture mode, editing is based on the "quarter-plane" model of
text, according to which 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 nonblank 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
so you can use the `C-c C-c' command (`picture-mode-exit') later to go
back to that mode.  `C-c C-c' also deletes spaces from the ends of
lines, unless given a numeric argument.

   The commands used in Picture mode all work in other modes (provided
the `picture' library is loaded), but are not bound to keys except 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 runs the hook `picture-mode-hook' (*note
Hooks::.).

* Menu:

* Basic Picture::         Basic concepts and simple commands of Picture Mode.
* Insert in Picture::     Controlling direction of cursor motion
                            after "self-inserting" characters.
* Tabs in Picture::       Various features for tab stops and indentation.
* Rectangles in Picture:: Clearing and superimposing rectangles.


File: emacs,  Node: Basic Picture,  Next: Insert in Picture,  Prev: Picture,  Up: Picture

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', a command which moves point one column to the
right, 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 nonblank character
on the line.  There is 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 (*note 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.

   Picture mode provides erasure instead of deletion and killing of
text.  DEL (`picture-backward-clear-column') replaces the preceding
character with a space rather than removing it; this moves point
backwards.  `C-d' (`picture-clear-column') replaces the next character
or characters with spaces, but does not move point.  (If you want to
clear characters to spaces and move forward over them, use SPC.)  `C-k'
(`picture-clear-line') really kills the contents of lines, but does not
delete the newlines from the buffer.

   To do actual insertion, you must use special commands.  `C-o'
(`picture-open-line') still 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 is not changed.  LFD
(`picture-duplicate-line') inserts below the current line another line
with the same contents.

   If you want to do real deletion in Picture mode, use `C-w', `C-c
C-d' (which is defined as `delete-char', as `C-d' is in other modes),
or one of the picture rectangle commands (*note Rectangles in
Picture::.).


File: emacs,  Node: Insert in Picture,  Next: Tabs in Picture,  Prev: Basic Picture,  Up: Picture

Controlling Motion after Insert
===============================

   Since "self-inserting" characters in Picture mode just overwrite and
move point, 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.


File: emacs,  Node: Tabs in Picture,  Next: Rectangles in Picture,  Prev: Insert in Picture,  Up: Picture

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

   Two kinds of tab-like action are provided in Picture mode.  Use
`M-TAB' (`picture-tab-search') for context-based tabbing.  With no
argument, it moves to a point underneath the next "interesting"
character that follows whitespace in the previous nonblank 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', this
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 whose characters are all
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'.  Normally 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.  The use of this command,
together with TAB, can get the effect of context-based tabbing.  But
`M-TAB' is more convenient in the cases where it is sufficient.


File: emacs,  Node: Rectangles in Picture,  Prev: Tabs in Picture,  Up: Picture

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 (*note 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 differs 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 likewise for the
rectangle found in a specified register.


File: emacs,  Node: Sending Mail,  Next: Rmail,  Prev: Picture,  Up: Top

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

   To send a message in Emacs, you start by typing a command (`C-x m')
to select and initialize the `*mail*' buffer.  Then you edit the text
and headers of the message in this buffer, and type another 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-x 5 m'
     Likewise, but make a new frame (`mail-other-frame').

`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.  `C-x 5 m'
(`mail-other-frame') creates a new frame to select the `*mail*' buffer.

   Because the mail composition buffer 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, you
are asked to confirm before the old message is erased.  If you answer
`n', the `*mail*' buffer is left selected with its old contents, so you
can finish the old message and send it.  `C-u C-x m' is another way to
do this.  Sending the message marks the `*mail*' buffer "unmodified",
which avoids the need for confirmation when `C-x m' is next used.

   If you are composing a message in the `*mail*' buffer and want to
send another message before finishing the first, rename the `*mail*'
buffer using `M-x rename-uniquely' (*note Misc Buffer::.).  Then you
can use `C-x m' or its variants described above to make a new `*mail'
buffer.  Once you've done that, you can work with each mail buffer
independently.

* Menu:

* Format: Mail Format.     Format of the mail being composed.
* Headers: Mail Headers.   Details of permitted mail header fields.
* Aliases: Mail Aliases.   Abbreviating and grouping mail addresses.
* Mode: Mail Mode.         Special commands for editing mail being composed.
* Spook: Distracting NSA.  How to distract the NSA's attention.


File: emacs,  Node: Mail Format,  Next: Mail Headers,  Up: Sending Mail

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

   In addition to the "text" or "body", 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: [e-mail]
     CC: [e-mail], [e-mail]
     Subject: The Emacs Manual
     --Text follows this line--
     Please ignore this message.


File: emacs,  Node: Mail Headers,  Next: Mail Aliases,  Prev: Mail Format,  Up: Sending Mail

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.  Upper and lower case are equivalent in field
names (and in mailing addresses also).  After the colon and optional
whitespace comes the contents of the field.

`To'
     This field contains the mailing addresses to which the message is
     addressed.

`Subject'
     The contents of the `Subject' field should be a piece of text that
     says what the message is about.  The reason `Subject' fields are
     useful is that 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, which should not appear in the header of the message
     actually sent.  Copies sent this way are called "blind carbon
     copies".

     To send a blind carbon copy of every outgoing message to yourself,
     set the variable `mail-self-blind' to `t'.

`FCC'
     This field contains the name of one file (in system mail file
     format) to which a copy of the message should be appended when the
     message is sent.  Do not output directly into an Rmail file with
     FCC; instead, output to an inbox file and "get new mail" from that
     inbox file into the Rmail file.  *Note Rmail Inbox::.

`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 this field to direct replies to a different address.  Most
     mail-reading programs (including Rmail) automatically send replies
     to the `Reply-to' address in preference to the `From' address.  By
     adding a `Reply-to' field to your header, you can work around any
     problems your `From' address may cause for replies.

     If you want to put the same `Reply-to' address into every outgoing
     message, set the variable `mail-default-reply-to' to that address
     (as a string).

`In-reply-to'
     This field contains a piece of text describing a message you are
     replying to.  Some mail systems can use this 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 (*note 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: [e-mail], [e-mail],
       [e-mail]3281

   If the variable `mail-archive-file-name' is non-`nil', it should be
a string naming a file; every time you start to edit a message to send,
the message starts out with an `FCC' field specifying that file.
Unless you remove the `FCC' field before sending, the message will be
written into that file when it is sent.


File: emacs,  Node: Mail Aliases,  Next: Mail Mode,  Prev: Mail Headers,  Up: Sending Mail

Mail Aliases
============

   You can define "mail aliases" in a file named `~/.mailrc'.  These
are short mnemonic names stand for mail addresses or groups of mail
addresses.  Like many other mail programs, Emacs expands aliases when
they occur in the `To', `CC', and `BCC' fields.

   To define an alias in `~/.mailrc', write a line in the following
format:

     alias SHORTADDRESS FULLADDRESS

For instance, if you send want to use `maingnu' as a short form of the
address `[e-mail]', put in the line:

     alias maingnu [e-mail]

The file `~/.mailrc' is used primarily by other mail-reading programs;
it can contain various other commands.  Emacs ignores everything in it
except for alias definitions.

   Another way to define a mail alias, within Emacs alone, is with the
`define-mail-alias' command.  It prompts for the alias and then the
full address.  You can use it to define aliases in your `.emacs' file,
like this:

     (define-mail-alias "maingnu" "[e-mail]")

   `define-mail-alias' records aliases by adding them to a variable
named `mail-aliases'.  If your are comfortable with manipulating Lisp
lists, you can set `mail-aliases' directly.  The initial value of
`mail-aliases' is `t', which means that Emacs should read `.mailrc' to
get the proper value.

   Normally, Emacs expands aliases when you send the message.  If you
like, you can have mail aliases expand as abbrevs, as soon as you type
them in.  To enable this feature, execute the following:

     (add-hook 'mail-setup-hook 'mail-abbrevs-setup)

This can go in your `.emacs' file.  *Note Hooks::.

   Note that abbrevs expand only if you insert a word-separator
character afterward.  However, any mail aliases that you didn't expand
in the mail buffer are expanded subsequently when you send the message.
*Note Abbrevs::.


File: emacs,  Node: Mail Mode,  Next: Distracting NSA,  Prev: Mail Aliases,  Up: Sending Mail

Mail Mode
=========

   The major mode used in the `*mail*' buffer is Mail mode, which is
much like Text mode except that various special commands are provided on
the `C-c' prefix.  These commands all have to do 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').

   There are two ways to send the message.  `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.  `C-c C-c' (`mail-send-and-exit')
sends and then deletes the window or switches to another buffer.  It
puts the `*mail*' buffer at the lowest priority for reselection by
default, since you are finished with using it.  This is the usual way
to send the message.

   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 the most common fields for the user to want to edit.

   `C-c C-w' (`mail-signature') adds a standard piece 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.

   To insert signatures automatically, set the variable
`mail-signature' non-`nil'; then starting a mail message automatically
inserts the contents of your `.signature' file.  If you want to omit
your signature from a particular message, delete it from the buffer
before you send the message.

   When mail sending is invoked from the Rmail mail reader using an
Rmail command, `C-c C-y' can be used inside the `*mail*' buffer to
insert the text of the message you are replying to.  Normally it
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.

   You can specify the text for `C-c C-y' to insert at the beginning of
each line: set `mail-yank-prefix' to the desired string.  (A value of
`nil' means to use indentation; this is the default.) However, `C-u C-c
C-y' never adds anything at the beginning of the inserted lines,
regardless of the value of `mail-yank-prefix'.

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

   Mail mode defines the character `%' as part of a word; this is
helpful for using the word commands to edit mail addresses.

   Turning on Mail mode (which `C-x m' does automatically) runs the
normal hooks `text-mode-hook' and `mail-mode-hook'.  Initializing a new
outgoing message runs the normal hook `mail-setup-hook'; if you want to
add special fields to your mail header or make other changes to the
appearance of the mail buffer, use that hook.  *Note Hooks::.

   The main difference between these hooks is just when they are
invoked.  Whenever you type `M-x mail', `mail-mode-hook' runs as soon
as the `*mail*' buffer is created.  Then the `mail-setup' function puts
in the default contents of the buffer.  After these default contents
are inserted, `mail-setup-hook' runs.


File: emacs,  Node: Distracting NSA,  Prev: Mail Mode,  Up: Sending Mail

Distracting the NSA
===================

   `M-x spook' adds a line of randomly chosen keywords to an outgoing
mail message.  The keywords are chosen from a list of words that suggest
you are discussing something subversive.

   The idea behind this feature is that the suspicion that the NSA
snoops on all electronic mail messages that contain keywords suggesting
they might be interested.  (The NSA says they don't, but there is no
way to be certain.)  The idea is that if lots of people add suspicious
words to their messages, the NSA will get so busy with spurious input
that they will have to give up reading it all.

   Whether or not this confuses the NSA, it at least amuses people.


File: emacs,  Node: Rmail,  Next: Dired,  Prev: Sending Mail,  Up: Top

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.
Reading the message in an Rmail file is done 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 message
you haven't read yet, 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".  In more sophisticated usage, you can copy
messages into other Rmail files and then edit those files with Rmail.

   Rmail uses narrowing to hide all but one message in the Rmail file.
The message that is shown is called the "current message".  Rmail
mode's special commands can do such things as delete the current
message, copy into another file, send a reply, or move to another
message.

   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 (*note 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 (*note Rmail Deletion::.).  To save the file without expunging,
use `C-x C-s'.  Rmail saves the Rmail file spontaneously when moving new
mail from an inbox file (*note Rmail Inbox::.).

   You can exit Rmail with `q' (`rmail-quit'); this expunges and saves
the Rmail file and then switches to another buffer.  But 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.  (The Rmail
command `b', `rmail-bury', does this for you.)  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 (*note Saving::.).

* Menu:

* Scroll: Rmail Scrolling.   Scrolling through a message.
* Motion: Rmail Motion.      Moving to another message.
* Deletion: Rmail Deletion.  Deleting and expunging messages.
* Inbox: Rmail Inbox.        How mail gets into the Rmail file.
* Files: Rmail Files.        Using multiple Rmail files.
* Output: Rmail Output.         Copying message out to files.
* Labels: Rmail Labels.      Classifying messages by labeling them.
* Reply: Rmail Reply.        Sending replies to messages you are viewing.
* Summary: Rmail Summary.    Summaries show brief info on many messages.
* Editing: Rmail Editing.    Editing message text and headers in Rmail.
* Digest: Rmail Digest.      Extracting the messages from a digest message.
* Out of Rmail::         Converting an Rmail file to mailbox format.
* Rot13: Rmail Rot13.         Reading messages encoded in the rot13 code.


File: emacs,  Node: Rmail Scrolling,  Next: Rmail Motion,  Up: Rmail

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

   When Rmail displays a message that does not fit on the screen, it is
necessary to scroll through it.  This could be done with `C-v', `M-v'
and `M-<', but in Rmail scrolling is so frequent 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 the selected message.  This is not quite the same as `M-<':
for one thing, it does not set the mark; for another, it resets the
buffer boundaries to the current message if you have changed them.


File: emacs,  Node: Rmail Motion,  Next: Rmail Deletion,  Prev: Rmail Scrolling,  Up: Rmail

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.  The usual practice is
to move sequentially through the file, since this is the order of
receipt of messages.  When you enter Rmail, you are positioned at the
first message that you have not yet made current (that is, the first one
that has the `unseen' attribute; *note Rmail Labels::.).  Move forward
to see the other new messages; move backward to reexamine old messages.

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

`p'
     Move to the previous nondeleted 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').

`<'
     Move to the first message (`rmail-first-message').

`M-s REGEXP RET'
     Move to the next message containing a match for REGEXP
     (`rmail-search').

`- M-s REGEXP RET'
     Move to the previous message containing a match for REGEXP.

   `n' and `p' are the usual way of moving among messages in Rmail.
They 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' and `M-p' (`rmail-next-message' and
`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 typing just the
digits.  You don't need 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 it
searches only within the current message.  The purpose of `M-s' is to
search for another message.  It reads a regular expression (*note
Regexps::.) nonincrementally, then searches starting at the beginning
of the following message for a match.  The message containing the match
is selected.

   If REGEXP is empty, `M-s' reuses the regexp used the previous time.

   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.  *Note
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.  `<' (`rmail-first-message') selects the
first message.


File: emacs,  Node: Rmail Deletion,  Next: Rmail Inbox,  Prev: Rmail Motion,  Up: Rmail

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

   When you no longer need to keep a message, you can "delete" it.  This
flags it as ignorable, and some Rmail commands 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 (*note Rmail Digest::.).

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

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

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

`x'
     Expunge the Rmail file (`rmail-expunge').

   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 nondeleted message.  If there is no nondeleted message
to move to in the specified direction, the message that was just
deleted remains current.

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

   To undelete, type `u' (`rmail-undelete-previous-message'), which is
designed to cancel 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.  But this does not work
when the `d' skips a few already-deleted messages that follow the
message being deleted; then 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 that you intend to undelete.  You can also select a
particular deleted message with `M-p' command, then type `u' to
undelete it.

   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.  *Note Rmail Labels::.


File: emacs,  Node: Rmail Inbox,  Next: Rmail Files,  Prev: Rmail Deletion,  Up: Rmail

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

   Unix places incoming mail for you in a file that we call 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.  It is in this file
that you actually read the mail with Rmail.  This operation is called
"getting new mail".  It can be repeated at any time using the `g' key
in Rmail.  The inbox file name is `/usr/spool/mail/USERNAME' on some
systems (typically Berkeley-derived ones) and `/usr/mail/USERNAME' on
other systems.

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

  1. The inbox file format varies between operating systems and
     according to the other mail software in use.  Only one part of
     Rmail needs to know about the alternatives, and it need only
     understand how to convert all of them to Rmail's own format.

  2. The inbox file format usually doesn't provide a place for all the
     information that Rmail records.

  3. 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 operating 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; then it saves the Rmail file; then it truncates
the inbox file.  This way, a system crash may cause duplication of mail
between the inbox and the Rmail file, but 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 continues to exist and will be
used as an inbox the next time you get new mail.


File: emacs,  Node: Rmail Files,  Next: Rmail Output,  Prev: Rmail Inbox,  Up: Rmail

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

   Rmail operates by default on your "primary mail file", which is named
`~/RMAIL' and receives your incoming mail from your system inbox file.
But 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 with explicit Rmail commands (*note 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 RET'
     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.  The file should be in Rmail format.  You can use `M-x
rmail-input' even when not in Rmail.

   The file you read with `i' should usually be a valid Rmail file.  If
it is not, then Rmail tries to decompose it into a stream of messages
in various known formats.  If it succeeds, it converts the whole file to
an Rmail 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 the Rmail file is brought 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.  As a special
exception, if your primary mail file does not specify any inbox files,
it uses the standard system 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'.  Then it reads a file name and
merges mail from that file.  The inbox file is not deleted or changed
in any way when `g' with an argument is used.  This is, therefore, a
general way of merging one file of messages into another.


File: emacs,  Node: Rmail Output,  Next: Rmail Labels,  Prev: Rmail Files,  Up: Rmail

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, the only way messages get into it is
by means of explicit `o' commands.

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

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

   The `o' and `C-o' commands are actually equivalent when you specify
an existing file; both commands check the file's contents to determine
which format to use (Rmail or inbox).  Which command you use makes a
difference when you specify a nonexistent file.

   Copying a message with `o' or `C-o' gives the original copy of the
message the `filed' attribute, so that `filed' appears in the mode line
when such a message is current.  If you like to keep just a single copy
of every mail message, set the variable `rmail-delete-after-output' to
`t'; then the `o' and `C-o' commands delete the original message after
copying it.  (You can undelete the original afterward.)

   The variable `rmail-output-file-alist' lets you specify intelligent
defaults for the output file, based on the contents of the current
message.  The value should be a list whose elements have this form:

     (REGEXP . FILENAME)

If there's a match for REGEXP in the current message, then the default
file name for output is FILENAME.  If multiple elements match the
message, the first matching element decides the default file name.


File: emacs,  Node: Rmail Labels,  Next: Rmail Reply,  Prev: Rmail Output,  Up: Rmail

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 only by users.

`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 same 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.  The argument
LABELS specifies 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.  *Note 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.  When you start Rmail, it initially shows the first
     message that has this attribute.

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

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

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

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

`edited'
     Means you have edited the text of the message within Rmail.  *Note
     Rmail Editing::.

`resent'
     Means you have resent the message to other users.  Assigned by the
     command `M-x rmail-resend'.  *Note Rmail Reply::.

   All other labels are assigned or removed only by the user, and have
no standard meaning.