Info file: vm.info,    -*-Text-*-
produced by texinfo-format-buffer
from file: vm.texinfo

This file documents the VM mail reader.

Copyright (C) 1990 Kyle E. Jones

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.


File: vm.info  Node: Top, Up: (DIR), Next: Introduction

This manual documents the VM mail reader, a Lisp program which runs as a
subsystem under Emacs.  The manual is divided into the following
chapters.

* Menu:

* Introduction::	Overview of the VM interface.
* Starting Up::		What happens when your start VM.
* Selecting Messages::	How to select messages for reading.
* Reading Messages::	Previewing and paging through a message.
* Sending Messages::	How to send messages from within VM.
* Saving Messages::	How to save messages.
* Deleting Messages::	How to delete, undelete and expunge messages
* Editing Messages::    How to alter the text and headers of a message.
* Message Marks::	Running VM commands on arbitrary subsets of messages.
* Undoing::		How to undo changes to message attributes.
* Grouping Messages::	How to make VM present similar message together.
* Reading Digests::	How to read digests under VM.
* Summaries::		How to view and customize the summary of a folder.
* Miscellaneous::	Various customization variables undescribed elsewhere.

Indices:

* Key Index::		Menus of command keys and their references.
* Command Index::	Menus of commands and their references.
* Variable Index::	Menus of variables and their references.


File: vm.info  Node: Introduction, Prev: Variable Index, Up: Top, Next: Starting Up

Introduction
************

VM (View Mail) is an Emacs subsystem that allows UNIX mail to be read
and disposed of within Emacs.  Commands exist to do the normal things
expected of a mail user agent, such as generating replies, saving
messages to folders, deleting messages and so on.  There are other more
advanced commands that do tasks like bursting and creating digests,
message forwarding, and organizing message presentation according to
various criteria.

To invoke VM simply type `M-x vm'.  VM gathers any mail that has arrived
in your system mailbox and appends it to a file known as your "primary
inbox", and visits that file for reading.  *Note Starting Up::.  A file
visited for reading by VM is called the "current folder".

If there are any messages in the primary inbox, VM selects the first new
or unread message, and previews it.  "Previewing" is VM's way of showing
you part of message and allowing you to decide whether you want to read
it.  *Note Previewing::.  By default VM shows you the message's sender,
recipient, subject and date headers.  Typing SPC (`vm-scroll-forward')
exposes the body of the message and flags the message as read.
Subsequent SPC's scroll forward through the message, `b' or DEL scrolls
backward.  When you reach the end of a message, typing SPC or `n' moves
you forward to preview the next message.  *Note Paging::.

If you do not want to read a message that's being previewed, just type
`n' and VM will move on to the next message (if there is one).  *Note
Selecting Messages::.

To save a message to a mail folder use `s' (`vm-save-message').  VM will
prompt you for the folder name in the minibuffer.  *Note Saving
Messages::.

Messages are deleted by typing `d' (`vm-delete-message') while
previewing or reading them.  The message is not deleted right away; it
is simply flagged for deletion.  If you change your mind about deleting
a message just select it and type `u' (`vm-undelete-message'), and the
message will be undeleted.  *Note Deleting Messages::.  The actual
removal of deleted messages from the current folder is called
"expunging" and it is accomplished by typing `#' (`vm-expunge-folder').
The message is still present in the on-disk version of the folder until
the folder is saved.

Typing `h' (`vm-summarize') causes VM to pop up a window containing a
summary of contents of the current folder.  The summary is presented one
line per message, by message number, listing each message's author, date
sent, line and byte count, and subject.  Also various letters appear
beside the message number to indicate that a message is new, unread,
flagged for deletion, etc.  An arrow `->' appears to the left of the
line summarizing the current message.  The summary format is user
configurable, *Note Summaries::.

When you are finished reading mail the current folder must be saved, so
that the next time the folder is visited VM will know which messages
have been already read, replied to and so on.  Typing `S'
(`vm-save-folder') expunges all deleted messages and saves the folder.
`C-x C-s' saves the folder without expunging deleted messages but the
messages are still flagged deleted.  The next time the folder is visited
these messages will still be flagged for deletion.

To quit VM you can type `q' (`vm-quit') or `x' (`vm-quit-no-change').
Typing `q' expunges and saves the current folder before quitting.  Also,
any messages flagged new are changed to be flagged unread, before
saving.  The `x' command quits VM without expunging, saving or otherwise
modifying the current folder.  Quitting is not required; you can simply
switch to another Emacs buffer when you've finished reading mail.

At any time while reading mail in the primary inbox you can type `g'
(`vm-get-new-mail') to check to see if new mail has arrived.  If new
mail has arrived it will be moved from the system spool area and merged into
the primary inbox.  If you are not in the middle of another message, VM
will also jump to the first new message, if you are not in the midst of
reading another message.

If `vm-get-new-mail' is given a prefix argument, it will prompt for
another file from which to gather messages instead of the usual spool
files.  In this case the source folder is copied but not deleted.


File: vm.info  Node: Starting Up, Prev: Introduction, Up: Top, Next: Selecting Messages

Starting Up
***********

There are three ways to start VM: `M-x vm', `M-x vm-visit-folder' and
`vm-mode'.  The first time VM is started in an Emacs session (by any of
these methods), it attempts to load the file `~/.vm'.  If present this
file should contain Lisp code, much like the `.emacs' file.  Since VM
has in excess of forty configuration variables, use of the `~/.vm' can
considerably reduce clutter in the `.emacs' file.  You can force the
reloading of this file on demand by typing `L' from within VM.

`M-x vm' causes VM to gather any mail present in your system mailbox and
append it to a file known as your "primary inbox", creating this file if
necessary.  The default name of this file is `~/INBOX', but VM will use
whatever file is named by the variable `vm-primary-inbox'.

VM transfers the mail from the system mailbox to the primary inbox via a
temporary file known as the "crash box".  The variable `vm-crash-box'
names the crash box file.  VM first copies the mail to the crash box,
deletes the system mailbox, merges the crash box contents into the
primary inbox, and then deletes the crash box.  If the system or Emacs
should crash in the midst of this transfer, any message not present in
the primary inbox will be either in the system mailbox or the crash box.
Some messages may be duplicated but no mail will be lost.

If the file named by `vm-crash-box' already exists when VM is started
up, VM will merge that with the primary inbox before getting any new
messages from the system mailbox.

By default, the location of the system mailbox is determined
heuristically based on what type of system you're using.  VM can be told
explicitly where the system mailbox is through the variable
`vm-spool-files'.  The value of this variable should be a list of
strings naming files VM should try when searching for newly arrived
mail.  Multiple mailboxes can be specified if you receive mail in more
than one place.  The value of `vm-spool-files' will be inherited from
the shell environmental variables MAILPATH or MAIL if either of these
variables are defined.

`M-x vm-visit-folder' (`v' from within VM) allows you to visit some
other mail folder than the primary inbox.  The folder name will be
prompted for in the minibuffer.

Once VM has read the folder, the first new or unread message will be
selected.  If there is no such message, the first message in the folder
is selected.

`M-x vm-mode' can be used on a buffer already loaded into Emacs to put
it into the VM major mode so that VM commands can be executed from within
it.  This command is suitable for use in Lisp programs, and for inclusion in
`auto-mode-alist' to automatically start VM on a file based on a
particular filename suffix.  `vm-mode' foregoes some of VM's startup
procedures (e.g. starting up a summary) to faciliate noninteractive use.

The variable `vm-startup-with-summary' controls whether VM automatically
displays a summary of the folder's contents at startup.  A value of
`nil' gives no summary; a value of `t' gives a full screen summary.  A
value that is neither `t' nor `nil' splits the screen between the
summary and the folder display.  The latter only works if the variable
`pop-up-windows''s value is non-`nil', and the value of
`vm-mutable-windows' is non-`nil'.  The default value of
`vm-startup-with-summary' is `nil'.

The variable `vm-mail-window-percentage' tells VM what percentage of the
screen should be given to the folder display when both it and the folder
summary are being displayed.  Note that Emacs enforces a minimum window
size limit, so a very high or very low value for this variable may
squeeze out one of the displays entirely.  This variable's default value
is 75, which works with Emacs' default minimum window size limit, on a
24 line terminal.  Note that the value of `vm-mutable-windows' must be
`t' or VM will not do window resizing regardless of the value of
`vm-mail-window-percentage'.

A non-`nil' value for the variable `vm-inhibit-startup-message' disables
the display of the VM's copyright, copying and warranty disclaimer.  If
you must, set this variable in your own `.emacs' file; don't set it
globally for everyone.  Users should be told their rights.  The startup
messages abort at the first keystroke after startup, so they do not
impede mail reading.


File: vm.info  Node: Selecting Messages, Prev: Starting Up, Up: Top, Next: Reading Messages

Selecting Messages
******************

The primary commands for selecting messages in VM are `n'
(`vm-next-message') and `p' (`vm-previous-message').
These commands move forward and backward through the current folder.
When they go beyond the end or beginning of the folder they wrap to the
beginning and end respectively.  By default these commands skip messages
flagged for deletion.  This behavior can be disabled by setting the value
of the variable `vm-skip-deleted-messages' to `nil'.  These
commands can also be made to skip messages that have been read; set
`vm-skip-read-messages' to `t' to do this.

The commands `n' and `p' also take prefix arguments that specify the
number of messages to move forward or backward.  If the magnitude of the
prefix argument is greater than 1, no message skipping will be done
regardless of the settings of the previously mentioned skip control
variables.

The variable `vm-circular-folders' determines whether VM folders will be
considered circular by various commands.  "Circular" means VM will wrap
from the end of the folder to the start and vice versa when moving the
message pointer, deleting, undeleting or saving messages before or after
the current message.

A value of `t' causes all VM commands to consider folders circular.  A
value of `nil' causes all of VM commands to signal an error if the start
or end of the folder would have to be passed to complete the command.
For movement commands, this occurs after the message pointer has been
moved as far it can go.  For other commands the error occurs before any
part of the command has been executed, i.e. no deletions, saves, etc.
will be done unless they can be done in their entirety.  A value other
than `nil' or `t' causes only VM's movement commands to consider folders
circular.  Saves, deletes and undeletes will behave as if the value is
`nil'.  The default value of `vm-circular-folders' is `0'.

Other commands to select messages:

RET (`vm-goto-message')
     Go to message number N.  N is the prefix argument, if
     provided, otherwise it is prompted for in the minibuffer.
TAB (`vm-goto-message-last-seen')
     Go to message last previewed or read.
N (`vm-Next-message')
P (`vm-Previous-message')
     Go to the next (previous) message, ignoring the settings of the skip
     control variables.
M-n (`vm-next-unread-message')
M-p (`vm-previous-unread-message')
     Move forward (backward) to the nearest new or unread message.  If no
     such message exists then these commands work like `n' and `p'.
M-s (`vm-isearch-forward')
     This works just like Emacs' normal incremental search except that
     when the search ends, VM selects the message containing point.  If
     the value of the variable `vm-search-using-regexps' is non-`nil', a
     regular expression may be used instead of a fixed string for the
     search pattern.  VM defaults to the fixed string search.  *Note
     Incremental Search: (emacs)Incremental Search.


File: vm.info  Node: Reading Messages, Prev: Selecting Messages, Up: Top, Next: Sending Messages

Reading Messages
****************

Once a message has been selected, VM will present it to you.  By default
presentation is done in two stages: "previewing" and "paging".

* Menu:

* Previewing::	Customizing message previews.
* Paging::	Scrolling and paging through the current message.


File: vm.info  Node: Previewing, Prev: Reading Messages, Up: Reading Messages, Next: Paging

Previewing
==========

"Previewing" is VM's way of showing you a small portion of a message
and allowing you to decide whether you want to read it.  Typing
SPC exposes the body of the message, and from there you can
repeatedly type SPC to page through the message.

By default the sender, recipient, subject and date headers are shown
when previewing; the rest of the message is hidden.  This behavior may
be altered by changing the settings of two variables:
`vm-visible-headers', `vm-invisible-header-regexp' and
`vm-preview-lines'.

The value of `vm-preview-lines' should be a number that tells VM how
many lines of the text of the message should be visible.  The default
value of this variable is 0.  If `vm-preview-lines' is `nil', then
previewing is not done at all; when a message is first presented it is
immediately exposed in its entirety and is flagged as read.

The value of `vm-visible-headers' should be a list of regular
expressions matching the beginnings of headers that should be made
visible when a message is presented.  The regexps should be listed in
the preferred presentation order of the headers they match.

If non-`nil', the variable `vm-invisible-header-regexp' specifies what
headers should *not* be displayed.  Its value should be a string
containing a regular expression that matches all headers you do not want
to see.  Setting this variable non-`nil' implies that you want to see
all headers not matched by it; therefore the value of
`vm-visible-headers' is only used to determine the order of the visible
headers in this case.  Headers not matched by
`vm-invisible-header-regexp' or `vm-visible-headers' are displayed last.

If you change the value of either `vm-visible-headers' or
`vm-invisible-header-regexp' is the middle of a VM sesssion the effects
will not be immediate.  You will need to use the command
`vm-discard-cached-data' on each message (bound to `j' by default) to
force VM rearrange the message headers.  A good way to do this is to
mark all the messages in the folder and apply `vm-discard-cached-data'
to the marked messages.  *Note Message Marks::.

Another variable of interest is `vm-highlighted-header-regexp'.  The
value of this variable should be a single regular expression that
matches the beginnings of any header that should be presented in inverse
video when previewing.  For example, a value of `"^From\\|^Subject"'
causes the From and Subject headers to be highlighted.

By default VM previews all messages, even if they have already been read.
To have VM preview only those messages that have not been read, set the
value of `vm-preview-read-messages' to `nil'.

Typing `t' (`vm-expose-hidden-headers') causes VM toggle between
exposing and hiding headers that would ordinarily be hidden.


File: vm.info  Node: Paging, Prev: Previewing, Up: Reading Messages

Paging
======

Typing SPC during a message preview exposes the body of the
message.  If the message was new or previously unread, it will be flagged
"read".  At this point you can use SPC to scroll forward, and
`b' or DEL to scroll backward a windowful of text at a time.
Typing space at the end of a message moves you to the next message.  If
the value of `vm-auto-next-message' is `nil', SPC will
not move to the next message; you must type `n' explicitly.

If the value of `vm-honor-page-delimiters' is non-`nil', VM
will recognize and honor page delimiters.  This means that when you
scroll through a document, VM will display text only up to the next page
delimiter.  Text ater the delimiter will be hidden until you type
another SPC, at which point the text preceding the delimiter will
becom hidden.  The Emacs variable `page-delimiter' determines what
VM will consider to be a page delimiter.

You can "unread" a message (so to speak) by typing `U'
(`vm-unread-message').  The current message will be flagged unread.


File: vm.info  Node: Sending Messages, Prev: Reading Messages, Up: Top, Next: Saving Messages

Sending Messages
****************

When sending messages from within VM, you will be using the standard
Mail major mode provided with GNU Emacs.  *Note Mail Mode: (emacs)Mail Mode.
However, `*mail*' buffers created by VM have extra command keys:

C-c C-y (`vm-yank-message')
     Copies a message from the current folder into the `*mail*' buffer.
     The message number is read from the minibuffer.  By default each
     line of the copy is prepended with the value of the variable
     `vm-included-text-prefix'.  All message headers are yanked along
     with the text.  Point is left before the inserted text, the mark
     after.  Any hook functions bound to mail-yank-hooks are run, aftert
     inserting the text and setting point and mark.  If a prefix
     argument is given, this tells VM to ignore mail-yank-hooks, don't
     set the mark, don't prepend the value of vm-included-text-prefix to
     every yanked line, and don't yank any headers other than those
     specified in vm-visible-headers/vm-invisible-headers.
C-c y (`vm-yank-message-other-folder')
     Work like `vm-yank-message', but it first prompts for the name of a
     folder from which to yank the message.
C-c C-v <Any VM command key>
     All VM commands may be accessed in the `*mail*' buffer by prefixing them
     with C-c C-v.

The simplest command is `m' (`vm-mail') which sends a mail
message much as `M-x mail' does but allows the added commands
described above.

`vm-mail' can be invoked outside of VM by typing `M-x vm-mail'.
However, of the above commands, only C-c y
(`vm-yank-message-other-folder') will work; all the other commands
require a parent folder.

If you send a message and it is returned by the mail system because it
was undeliverable, you an easily resend the message by typing `C-r'
(`vm-resend-bounced-message').  VM will extract the old message and its
pertinent headers from the returned message, and place you in a `*mail*'
buffer.  You can then change the recipient addresses or do whatever is
necessary to correct the original problem and resend the message.

* Menu:

* Replying::		Describes the various ways to reply to a message.
* Forwarding Messages::	How to forward a message to a third party.


File: vm.info  Node: Replying, Prev: Sending Messages, Up: Sending Messages, Next: Forwarding Messages

Replying
========

VM has special commands that make it easy to reply to a message.  When a
reply command is invoked VM fills in the subject and recipient headers
for you, since it is apparent to whom the message should be sent and
what the subject should be.  There is an old convention of prepending
the string `"Re: "' to the subject of replies if the string isn't
present already.  VM supports this indirectly by providing the variable
`vm-reply-subject-prefix'.  Its value should be a string to prepend to
the subject of replies, if the said string isn't present already.  A
`nil' value means don't prepend anything to the subject (this is the
default).  In any case you can edit any of the message headers manually,
if you wish.

VM also helps you quote material from a message to which you are
replying by providing "included text" as a feature of some of the
commands.  "Included text" is a copy of the message being replied to
with some fixed string prepended to each line so that included text can
be distinguished from the text of the reply.  The variable
`vm-included-text-prefix' specifies what the prepended string will be.

The variable `vm-included-text-attribution-format' specifies the format
for the attribution of included text.  This attribution is a line of
text that tells who wrote the text that is to be included; it will be
inserted before the included text.  If non-`nil', the value of
`vm-included-text-attribution-format' should be a string format
specifiation similar to `vm-summary-format'.  *Note Summaries::.  A
`nil' value causes the attribution to be omitted.

The variable `vm-in-reply-to-format' specifies the format of the
In-Reply-To header that is inserted into header section of the reply
buffer.  Like `vm-included-text-attribution-format',
`vm-in-reply-to-format' should be a string similar to that of
`vm-summary-format'.  A `nil' value causes the In-Reply-To header to be
omitted.

The recipient headers generated for reply messages are created by
simply copying the appropriate headers for the message to which you are
replying.  This includes any full name information, comments, etc. in
these headers.  If the variable `vm-strip-reply-headers' is
non-`nil', the reply headers will stripped of all information but
the actual addresses.

The reply commands are:

r (`vm-reply')
     Replies to the author of the current message.
R (`vm-reply-include-text')
     Replies to the author of the current message and provides included text.
f (`vm-followup')
     Replies to the all recipients of the current message.
F (`vm-followup-include-text')
     Replies to the all recipients of the current message and provides
     included text.

These commands all accept a numeric prefix argument N, which if present,
causes VM to reply to the next (or previous if the argument is negative)
N-1 message as well as the current message.  Also all the reply commands
set the "replied" attribute of the messages to which you are responding,
but only when the reply is actually sent.  The reply commands can also
be applied to marked messages, *Note Message Marks::.

If you are one of multiple recipients of a message and you use `f'
and `F', your address will be included in the recipients of the
reply.  You can avoid this by judicious use of the variable
`vm-reply-ignored-addresses'.  Its value should be a list of
regular expressions that match addresses that VM should automatically
remove from the recipient headers of replies.


File: vm.info  Node: Forwarding Messages, Prev: Replying, Up: Sending Messages

Forwarding Messages
===================

VM has two commands to forward messages: `z' (`vm-forward-message') and
@ (`vm-send-digest').

Typing `z' puts you into a `*mail*' buffer just like `m', except the
current message appears as the body of the message in the `*mail*'
buffer. The forwarded message is surrounded by RFC 934 complaint message
delimiters.  If the variable `vm-rfc934-forwarding' is non-`nil' "^-" to
"- -" character stuffing is done to the forwarded message (this is the
default).  This behavior is required if the recipient of the forwarded
message wants to use a RFC 934 standard bursting agent to access the
message.  If the variable `vm-forwarding-subject-format' is non-`nil' it
should specify the format of the Subject header of the forwarded
message.  This subject will be used as the contents of the Subject
header automatically inserted into the `*mail*' buffer.  A `nil' value
causes the Subject header to be left blank.  The forwarded message is
flagged "forwarded".  The command @ (`vm-send-digest') works like `z'
except that a digest of all the messages in the current folder is made
and inserted into the `*mail*' buffer.  Also, `vm-send-digest' can be
applied to marked messages.  *Note Message Marks::.  When applied to
marked messages, `vm-send-digest' will only bundle marked messages, as
opposed to the usual bundling of all messages in the current folder.  If
you give `vm-send-digest' a prefix argument, VM will insert a list of
preamble lines at the beginning of the digest, one line per digestified
message.  The variable `vm-digest-preamble-format' determines the format
of the preamble lines.  If the value of `vm-digest-center-preamble' is
non-`nil', the preamble lines will be centered.


File: vm.info  Node: Saving Messages, Prev: Sending Messages, Up: Top, Next: Deleting Messages

Saving Messages
***************

Mail messages are normally saved to files that contain only mail
messages.  Such files are called "folders".

The VM command to save a message to a folder is `s' (`vm-save-message');
invoking this command causes the current message to be saved to a folder
whose name you specify in the minibuffer.  If `vm-save-message' is given
a prefix argument N, the current message plus the next N-1 message are
saved.  If N is negative, the current message and the previous N-1
messages are saved.  Messages saved with `vm-save-message' are flagged
"filed".

If the value of the variable `vm-confirm-new-folders' is non-`nil', VM
will ask for confirmation before creating a new folder on interactive
saves.

If you have a directory where you keep all your mail folders, you should
set the variable `vm-folder-directory' to point to it.  If this variable
is set, `vm-save-message' will insert this directory name into the
minibuffer before prompting you for a folder name; this will save you
some typing.

Another aid to selecting folders in which to save mail is the variable
`vm-auto-folder-alist'.  The value of this variable should be a list of
the form,

     ((HEADER-NAME
        (REGEXP . FOLDER-NAME) ...)
       ...)

where HEADER-NAME and REGEXP are strings, and FOLDER-NAME is a string or
an s-expression that evaluates to a string.

If any part of the contents of the message header named by HEADER-NAME
is matched by the regular expression REGEXP, VM will evaluate the
corresponding FOLDER-NAME and use the result as the default when
prompting for a folder to save the message in.  If the resulting folder
name is a relative pathname it resolves to the directory named by
`vm-folder-directory', or the `default-directory' of the currently
visited folder if `vm-folder-directory' is nil.

When FOLDER-NAME is evaluated, the current buffer will contain only the
contents of the header named by HEADER-NAME.  It is safe to modify this
buffer.  You can use the match data from any `\( ...  \)' grouping
constructs in REGEXP along with the function buffer-substring to build a
folder name based on the header information.  If the result of
evaluating FOLDER-NAME is a list, then the list will be treated as
another auto-folder-alist and will be descended recursively.

Whether matching is case sensitive depends on the value of the variable
`vm-auto-folder-case-fold-search'.  A non-`nil' value makes
matching case insensitive.  The default value is `t', which means
matching is case sensitive.  Note that the matching of header names is
always case insensitive becasue RFC 822 specifies that header names are
case indistinct.

VM can save messages to a folder in two distinct ways.  The message can
be appended directly to the folder on disk, or the folder can be visited
as Emacs would visit any other file and the message be appended to that
buffer.  In the latter method you must save the buffer yourself to
change the on-disk copy of the folder.  The variable
`vm-visit-when-saving' controls which method is used.  A value of `t'
cuases VM to always visit a folder before saving message to it.  A `nil'
value causes VM to always append directly to the folder file.  In this
case VM will not save messages to the disk copy of a folder that is
being visited.  This restriction is necessary to insure that the buffer
and on-disk copies of the folder are consistent. If the value of
VM-VISIT-WHEN-SAVING is not `nil' and not `t' (e.g. 0, the default), VM
will append to the folder's buffer if the buffer is currently being
visited, otherwise VM will append to the file itself.

After a message is saved to a folder, the usual thing to do next is to
delete it.  If the variable `vm-delete-after-saving' is non-`nil' VM
will flag messages for deletion automatically after saving them.  This
applies only to saves to folders, not for the w command (see below).

Other commands:

w (`vm-save-message-sans-headers')
     Saves a message or messages to a file without their headers.  This
     command responds to a prefix argument exactly as `vm-save-message'
     does.  Messages saved this way are flagged "written".
A (`vm-auto-archive-messages')
     Save all unfiled messages that auto-match a folder via
     `vm-auto-folder-alist' to their appropriate folders.  Messages that
     are flagged for deletion are not saved by this command.  If invoked with a
     prefix argument, confirmation will be requested for each save.
| (`vm-pipe-message-to-command')
     Runs a shell command with the some or all of the current message as input.
     By default the entire message is used.

     If invoked with one C-u the text portion of the message is used.
     If invoked with two C-u's the header portion of the message is used.

     If the shell command generates any output, it is displayed in a
     `*Shell Command Output*' buffer.  The message itself is not altered.


File: vm.info  Node: Deleting Messages, Prev: Saving Messages, Up: Top, Next: Editing Messages

Deleting Messages
*****************

In VM, messages are flagged for deletion, and then are subsequently
"expunged" or removed from the folder.  The messages are not removed
from the on-disk copy of the folder until the folder is saved.

d (`vm-delete-message')
     Flags the current message for deletion.  A prefix argument N
     causes the current message and the next N-1 messages to be flagged.
     A negative N causes the current message and the previous N-1
     messages to be flagged.
u (`vm-undelete-message')
     Removes the deletion flag from the current message.  A prefix argument N
     causes the current message and the next N-1 messages to be undeleted.
     A negative N causes the current message and the previous N-1
     messages to be undeleted.
k (`vm-kill-subject')
     Flags all message with the same subject as the current message (ignoring
     "Re:") for deletion.
# (`vm-expunge-folder')
     Does the actual removal of messages flagged for deletion in the current
     folder.

Setting the variable `vm-move-after-deleting' non-`nil' causes VM to
move past the messages after flagging them for deletion.  Setting
`vm-move-after-undeleting' non-`nil' causes similar movement after
undeletes.


File: vm.info  Node: Editing Messages, Prev: Deleting Messages, Up: Top, Next: Message Marks

Editing Messages
****************

To edit a message, type `e' (`vm-edit-message').  The current message is
copied into a temporary buffer, and this buffer is selected for editing.
The major mode of this buffer is controlled by the variable
`vm-edit-message-mode'.  The default is Text mode.

Use `C-c ESC' (`vm-edit-message-end') when you have finished editing the
message.  The message will be inserted into its folder, replacing the
old version of the message.  If you want to quit the edit without your
edited version replacing the original, use `C-c C-]'
(`vm-edit-message-abort'), or you can just kill the edit buffer with
`C-x k' (`kill-buffer').

If you give a prefix argument to `vm-edit-message', then the current
message will be flagged unedited.

As with VM `*mail*' buffers, all VM commands can be accessed from the
edit buffer through the command prefix `C-c C-v'.


File: vm.info  Node: Message Marks, Prev: Editing Messages, Up: Top, Next: Undoing

Message Marks
*************

VM provides general purpose "marks" that may be applied to any and
all messages within a given folder.  Certain VM commands can be
subsequently invoked only on those message that are marked.

To mark the current message, type `C-c C-@' (`vm-mark-message').  If you
give a numeric prefix argument N, the next N-1 messages will be marked
as well.  A negative prefix argument means mark the previous N-1.  An
asterisk (`*') will appear to the right of the message numbers of all
marked messages in the summary window.

To remove a mark from the current message, use `C-c SPC'
(`vm-unmark-message'.  Prefix arguments work as with `vm-mark-message'.

Use `C-c C-a' to mark all message in the current folder; `C-c a'
removes marks from all messages.

To apply a VM command to all marked message you must prefix it with the
key sequence `C-c RET' (`vm-next-command-uses-marks').  The next VM
command will apply to all marked messages, provided the command can be
applied to such messages in a meaningful and useful way.  The current
commands that can be applied to marked message are: `vm-delete-message',
`vm-discard-cached-data', `vm-followup', `vm-followup-include-text',
`vm-reply', `vm-reply-include-text', `vm-save-message',
`vm-save-message-sans-headers', `vm-send-digest', `vm-undelete-message',
and `vm-unread-message'.


File: vm.info  Node: Undoing, Prev: Message Marks, Up: Top, Next: Grouping Messages

Undoing
*******

VM provides a special form of undo which allows changes to message attributes
to be undone.

Typing `C-x u' or C-_ (`vm-undo') undoes the last attribute change.
Consecutive `vm-undo''s undo further and further back.  Any intervening
command breaks the undo chain, after which the undos themselves become
undoable by subsequent invocations of `vm-undo'.

Note that expunges, saves and message edits are *not* undoable.


File: vm.info  Node: Grouping Messages, Prev: Undoing, Up: Top, Next: Reading Digests

Grouping Messages
*****************

In order to make numerous related messages easier to cope with, VM
provides the command `G' (`vm-group-messages'), which groups all message
in a folder according to some criterion.  "Grouping" causes messages
that are related in some way to be presented consecutively.  The actual
order of the folder is not altered; the messages are simply numbered and
presented differently.  Grouping should not be confused with sorting;
grouping only moves messages that occur later in the folder backward to
"clump" with other related messages.

The grouping criteria currently supported are:
`subject'
     Messages with the same subject (ignoring "Re:" prefixes) are grouped
     together.
`author'
     Messages with the same author are grouped together.
`recipient'
     Mesage with the same recipients are grouped together.
`date-sent'
     Messages sent on the same day are grouped together.
`physical-order'
     Message presentation reverts to physical message order of the foler (the
     default).

If the variable `vm-group-by' has a non-`nil' value it specifies the
default grouping that will be used for all folders.  So if you like
having your mail presented to you grouped by subject, then put `(setq
vm-group-by "subject")' in your `.emacs' file to get this behavior.


File: vm.info  Node: Reading Digests, Prev: Grouping Messages, Up: Top, Next: Summaries

Reading Digests
***************

A "digest" is one or more mail messages encapsulated in a single message.

VM supports digests by providing a command to "burst" them into their
individual messages.  These messages can then be handled like any other
messages under VM.

The command `*' (`vm-burst-digest') bursts a digest into its individual
messages and appends them to current folder.  These messages are then
assimilated into the current folder using the default grouping.  *Note
Grouping Messages::.  The original digest message is not altered, and
the messages extracted from it are not part of the on-disk copy of the
folder until a save is done.

If you give a prefix argumet to `vm-burst-digest', it will attempt
to cope with non-RFC 934 compliant digests.  If `vm-burst-digest'
seems to be breaking digests at inappropriate places, most likely the
digest is not compliant with the standard.  In this case try using the
prefix arg.


File: vm.info  Node: Summaries, Prev: Reading Digests, Up: Top, Next: Miscellaneous

Summaries
*********

Typing `h' (`vm-summarize') causes VM to display a summary of contents
of the current folder.  The information in the summary is automatically
updated as changes are made to the current folder.  An arrow `->'
appears to the left of the line summarizing the current message.  The
variable `vm-auto-center-summary' controls whether VM will keep the
summary arrow vertically centered within the summary window.  A value of
`t' causes VM to always keep arrow cenered.  A value of `nil' means VM
will never bother centering the arrow.  A value that is not `nil' and
not `t' causes VM to center the arrow only if the summary window is not
the only existing window.

The variable `vm-summary-format' controls the format of each
message's summary.  Its value should be a string.  This string should
contain printf-like "%" conversion specifiers which substitute
information about the message into the final summary.

Recognized specifiers are:
        a - attribute indicators (always four characters wide)
            The first char is  `D', `N', `U' or ` ' for deleted, new, unread
            and read messages respectively.
            The second char is `F', `W' or ` ' for filed (saved) or written
            messages.
            The third char is `R', `Z' or ` ' for messages replied to,
            and forwarded messages.
            The fourth char is `E' if the message has been edited, ` ' otherwise.
        A - longer version of attributes indicators (six characters wide)
            The first char is  `D', `N', `U' or ` ' for deleted, new, unread
            and read messages respectively.
            The second is `r' or ` ', for message replied to.
            The third is `z' or ` ', for messages forwarded.
            The fourth is `f' or ` ', for messages filed.
            The fifth is `w' or ` ', for messages written.
            The sixth is `e' or ` ', for messages that have been edited.
        c - number of characters in message (ignoring headers)
        d - numeric day of month message sent
        f - author's address
        F - author's full name (same as f if full name not found)
        h - hour message sent
        i - message ID
        l - number of lines in message (ignoring headers)
        m - month message sent
        M - numeric month message sent (January = 1)
        n - message number
        s - message subject
        t - addresses of the recipients of the message, in a comma-separated list
        T - full names of the recipients of the message, in a comma-separated list
            If a full name cannot be found, the corresponding address is used
            instead.
        w - day of the week message sent
        y - year message sent
        z - timezone of date when the message was sent
        * - `*' if the current message is marked, ` ' otherwise

Use "%%" to get a single "%".

A numeric field width may be specified between the "%" and the
specifier; this causes right justification of the substituted string.  A
negative field width causes left justification.  The field width may be
followed by a "." and a number specifying the maximum allowed length
of the substituted string.  If the string is longer than this value, it
is truncated.

The summary format need not be one line per message but it must end with
a newline, otherwise the message pointer will not be displayed correctly
in the summary window.

You can have a summary generated automatically at startup, *Note
Starting Up::.

All VM commands are available in the summary buffer just as they are in
the folder buffer itself.  If you set `vm-follow-summary-cursor'
non-`nil', VM will select the message under the cursor in the summary
window before executing commands that operate on the current message.
Note that this occurs *only* when executing a command from the summary
buffer window.


File: vm.info  Node: Miscellaneous, Prev: Summaries, Up: Top

Miscellaneous
*************

Here are some VM customization variables that don't really fit into the
other chapters.

`vm-confirm-quit'
     A value of t causes VM to always ask for confirmation before ending
     a VM visit of a folder.  A nil value means VM will ask only when messages
     will be lost unwittingly by quitting, i.e. not removed by intentional
     delete and expunge.  A value that is not nil and not t causes VM to ask
     only when there are unsaved changes to message attributes or message
     will be lost.
`vm-berkeley-mail-compatibility'
     A non-`nil' value means to read and write BSD Mail(1) style Status:
     headers.  This makes sense if you plan to use VM to read mail archives
     created by Mail.
`vm-gargle-uucp'
     A non-`nil' value means to use a crufty regular expression that
     does surprisingly well at beautifying UUCP addresses that are substituted
     for %f and %t as part of summary and attribution formats.
`vm-mode-hooks'
     A non-`nil' value should be a list of hook functions to run when a
     buffer enters vm-mode.  These hook functions should generally be used to
     set key bindings and local variables.  Mucking about in the folder
     buffer is certainly possible, but it is not encouraged.
`vm-delete-empty-folders'
     A non-`nil' value for this variable causes VM to remove empty (zero
     length) folder files after saving them.
`vm-mutable-windows'
     This variable's value controls VM's window usage.  A value of `t'
     gives VM free run of the Emacs display; it will commandeer the
     entire screen for its purposes.  A value of `nil' restricts VM's
     window usage to the window from which it was invoked.  VM will not
     create, delete, or use any other windows, nor will it resize its
     own window.  A value that is neither `t' nor `nil' allows VM to use
     other windows, but it will not create new ones, or resize or delete
     the current ones.
`mail-yank-hooks'
     Value should be a list of functions to be called after a message is
     yanked into a `*mail*' buffer via `vm-yank-message'.  When
     each hook function is called, point will be at the beginning of the
     yanked text and mark at the end.

     This is not a VM specific variable, but rather an external variable that
     VM honors so that citation packages such as SUPERCITE can be
     used with VM.


File: vm.info  Node: Key Index, Prev: Top, Up: Top, Next: Command Index

Key Index
*********

* Menu:

* #: Deleting Messages.
* @: Forwarding Messages.
* *: Reading Digests.
* |: Saving Messages.
* A: Saving Messages.
* b: Introduction.
* C-_: Undoing.
* C-c C-v: Sending Messages.
* C-c C-y: Sending Messages.
* C-c y: Sending Messages.
* C-x u: Undoing.
* d: Deleting Messages.
* DEL: Introduction.
* F: Replying.
* f: Replying.
* G: Grouping Messages.
* g: Introduction.
* h: Summaries.
* k: Deleting Messages.
* L: Starting Up.
* m: Sending Messages.
* M-n: Selecting Messages.
* M-p: Selecting Messages.
* M-s: Selecting Messages.
* N: Selecting Messages.
* n: Selecting Messages.
* P: Selecting Messages.
* p: Selecting Messages.
* q: Introduction.
* R: Replying.
* r: Replying.
* RET: Selecting Messages.
* S: Introduction.
* s: Saving Messages.
* SPC: Introduction.
* TAB: Selecting Messages.
* u: Deleting Messages.
* v: Starting Up.
* w: Saving Messages.
* x: Introduction.
* z: Forwarding Messages.


File: vm.info  Node: Command Index, Prev: Key Index, Up: Top, Next: Variable Index

Command Index
*************

* Menu:

* vm: Starting Up.
* vm-auto-archive-messages: Saving Messages.
* vm-burst-digest: Reading Digests.
* vm-delete-message: Deleting Messages.
* vm-expose-hidden-headers: Previewing.
* vm-expunge-folder: Deleting Messages.
* vm-followup: Replying.
* vm-followup-include-text: Replying.
* vm-forward-message: Forwarding Messages.
* vm-get-new-mail: Introduction.
* vm-goto-message: Selecting Messages.
* vm-goto-message: Selecting Messages.
* vm-group-messages: Grouping Messages.
* vm-isearch-forward: Selecting Messages.
* vm-kill-subject: Deleting Messages.
* vm-load-rc: Starting Up.
* vm-mail: Sending Messages.
* vm-mode: Starting Up.
* vm-Next-message: Selecting Messages.
* vm-next-message: Selecting Messages.
* vm-next-unread-message: Selecting Messages.
* vm-pipe-message-to-command: Saving Messages.
* vm-Previous-message: Selecting Messages.
* vm-previous-message: Selecting Messages.
* vm-previous-unread-message: Selecting Messages.
* vm-quit: Introduction.
* vm-quit-no-change: Introduction.
* vm-reply: Replying.
* vm-reply-include-text: Replying.
* vm-save-folder: Introduction.
* vm-save-message: Saving Messages.
* vm-save-message-sans-headers: Saving Messages.
* vm-scroll-backward: Introduction.
* vm-scroll-forward: Introduction.
* vm-send-digest: Forwarding Messages.
* vm-summarize: Summaries.
* vm-undelete-message: Deleting Messages.
* vm-undo: Undoing.
* vm-visit-folder: Starting Up.
* vm-yank-message: Sending Messages.
* vm-yank-message-other-folder: Sending Messages.


File: vm.info  Node: Variable Index, Prev: Command Index, Up: Top, Next: Introduction

Variable Index
**************

* Menu:

* mail-yank-hooks: Miscellaneous.
* vm-auto-center-summary: Summaries.
* vm-auto-folder-alist: Saving Messages.
* vm-auto-folder-case-fold-search: Saving Messages.
* vm-auto-next-message: Paging.
* vm-berkeley-mail-compatibility: Miscellaneous.
* vm-circular-folders: Selecting Messages.
* vm-confirm-new-folders: Saving Messages.
* vm-confirm-quit: Miscellaneous.
* vm-crash-box: Starting Up.
* vm-delete-after-saving: Saving Messages.
* vm-delete-empty-folders: Miscellaneous.
* vm-digest-center-preamble: Forwarding Messages.
* vm-digest-preamble-format: Forwarding Messages.
* vm-folder-directory: Saving Messages.
* vm-follow-summary-cursor: Summaries.
* vm-forwarding-subject-format: Forwarding Messages.
* vm-gargle-uucp: Miscellaneous.
* vm-group-by: Grouping Messages.
* vm-highlighted-header-regexp: Previewing.
* vm-included-text-attribution-format: Replying.
* vm-included-text-prefix: Replying.
* vm-inhibit-startup-message: Starting Up.
* vm-in-reply-to-format: Replying.
* vm-invisible-header-regexp: Previewing.
* vm-mail-window-percentage: Starting Up.
* vm-mode-hooks: Miscellaneous.
* vm-move-after-deleting: Deleting Messages.
* vm-move-after-undeleting: Deleting Messages.
* vm-mutable-windows: Miscellaneous.
* vm-preview-lines: Previewing.
* vm-preview-read-messages: Previewing.
* vm-primary-inbox: Starting Up.
* vm-reply-ignored-addresses: Replying.
* vm-reply-subject-prefix: Replying.
* vm-rfc934-forwarding: Forwarding Messages.
* vm-search-using-regexps: Selecting Messages.
* vm-skip-deleted-messages: Selecting Messages.
* vm-skip-read-messages: Selecting Messages.
* vm-spool-files: Starting Up.
* vm-startup-with-summary: Starting Up.
* vm-strip-reply-headers: Replying.
* vm-summary-format: Summaries.
* vm-visible-headers: Previewing.
* vm-visit-when-saving: Saving Messages.


Tag table:
Node: Top332
Node: Introduction1583
Node: Starting Up5918
Node: Selecting Messages10312
Node: Reading Messages13367
Node: Previewing13755
Node: Paging16608
Node: Sending Messages17705
Node: Replying20019
Node: Forwarding Messages23593
Node: Saving Messages25409
Node: Deleting Messages30411
Node: Editing Messages31736
Node: Message Marks32712
Node: Undoing34150
Node: Grouping Messages34673
Node: Reading Digests36072
Node: Summaries37104
Node: Miscellaneous41046
Node: Key Index43490
Node: Command Index44504
Node: Variable Index46125

End tag table
