\input texinfo  @comment -*-Texinfo-*-
@setfilename vm.info
@settitle VM User's Manual
@iftex
@finalout
@end iftex
@c @setchapternewpage odd		% For book style double sided manual.
@c      @smallbook
@tex
\overfullrule=0pt
%\global\baselineskip 30pt      % For printing in double spaces
@end tex
@ifinfo
This file documents the VM mail reader.

Copyright (C) 1989 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.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
@end ifinfo
@c
@titlepage
@sp 6
@center @titlefont{VM User's Manual}
@sp 4
@center First Edition, VM Version 4
@sp 1
@center June 1989
@sp 5
@center Kyle E. Jones
@center @t{kyle@@cs.odu.edu}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1989 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.

@end titlepage
@page
@ifinfo
@node Top, Introduction,, (DIR)

This manual documents the VM mail reader 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.
* Sending Messages::	How to send messages from within VM.
* Saving Messages::	How to save messages.
* Deleting Messages::	How to delete, undelete and expunge messages
* Undoing::		How to undo changes to message attributes.
* Grouping Messages::	How to make VM present messages
* 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.
@end menu
@end ifinfo

@node Introduction, Starting Up, Variable Index, Top
@unnumbered 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 @kbd{M-x vm}.  VM gathers any mail that has
arrived in your system mailbox and appends it to a file known as your
@dfn{primary inbox}, and visits that file for reading.  @xref{Starting Up}.
A file visited for reading by VM is called the @dfn{current folder}.@refill

@findex vm-scroll-forward
@findex vm-scroll-backward
@kindex SPC
@kindex b
If there are any messages in the primary inbox, VM selects the first new
or unread message, and previews it.  @dfn{Previewing} is VM's way of
showing you part of message and allowing you to decide whether you want
to read it.  @xref{Previewing}.  By default VM shows you the message's
sender, recipient, subject and date headers.  Typing @key{SPC}
(@code{vm-scroll-forward}) exposes the body of the message and marks the
message as read.  Subsequent @key{SPC}'s scroll forward through the
message, @kbd{b} scrolls backward.  When you reach the end of a message,
typing a @key{SPC} or @kbd{n} moves you forward to preview the next
message.@refill

If you do not want to read a message that's being previewed, just type
@kbd{n} and VM will move on to the next message (if there is one).
@xref{Selecting Messages}.@refill

To save a message to a mail folder use @kbd{s} (@code{vm-save-message}).
VM will prompt you for the folder name in the minibuffer.
@xref{Saving Messages}.@refill

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

Typing @kbd{h} (@code{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, marked for deletion, etc.  An arrow @samp{->} appears to
the left of the line summarizing the current message.  The summary
format is user configurable, @pxref{Summaries}.@refill

@findex vm-save-folder
@kindex S
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 @kbd{S}
(@code{vm-save-folder}) expunges all deleted messages and saves the
folder.  @kbd{C-x C-s} saves the folder without expunging deleted
messages but the messages are still marked deleted.  The next time the
folder is visited these messages will still be marked for deletion.@refill

@findex vm-quit
@findex vm-quit-no-change
@kindex q
@kindex x
To quit VM you can type @kbd{q} (@code{vm-quit}) or @kbd{x}
(@code{vm-quit-no-change}).  Typing @kbd{q} expunges and saves the
current folder before quitting.  Also, any messages marked new are
changed to be marked unread, before saving.  The @kbd{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.@refill

@findex vm-get-new-mail
@kindex g
At any time while reading mail in the primary inbox you can type @kbd{g}
(@code{vm-get-new-mail}) to check to see if new mail has arrived.  If
new mail has arrived it will be merged into the primary inbox.  If you
are not in the middle of another message, VM will also jump to the first
new message.

@node Starting Up, Selecting Messages, Introduction, Top
@chapter Starting Up

There are two ways to start VM: @kbd{M-x vm} and @kbd{M-x vm-visit-folder}.

@findex vm
@vindex vm-primary-inbox
@kbd{M-x vm} causes VM to gather any mail present in your system mailbox
and append it to a file known as your @dfn{primary inbox}, creating
this file if necessary.  The default name of this file is
@file{~/INBOX}, but VM will use whatever file is named by the variable
@code{vm-primary-inbox}.@refill

@vindex vm-crash-box
VM transfers the mail from the system mailbox to the primary inbox via a
temporary file known as the @dfn{crash box}.  The variable
@code{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.@refill

If the file named by @code{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.@refill

@vindex vm-spool-files
By default, the location of the system mailbox is determined
heuristically by VM based on what type of system you're using.  VM can
be told explicitly where the system mailbox is through the variable
@code{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.@refill

@findex vm-visit-folder
@kindex v
@kbd{M-x vm-visit-folder} (@kbd{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.@refill

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.

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

@vindex vm-mail-window-percentage
The variable @code{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 @code{vm-mutable-windows}
must be @code{t} or VM will not do window resizing regardless of the
value of @code{vm-mail-window-percentage}.@refill

@vindex vm-inhibit-startup-message
A non-@code{nil} value for the variable @code{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 @file{.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.@refill

@node Selecting Messages, Sending Messages, Starting Up, Top
@chapter Selecting Messages

@findex vm-next-message
@findex vm-previous-message
@kindex n
@kindex p
@vindex vm-skip-deleted-messages
@vindex vm-skip-read-messages
The primary commands for selecting messages in VM are @kbd{n}
(@code{vm-next-message}) and @kbd{p} (@code{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
marked for deletion.  This behavior can be disabled by setting the value
of the variable @code{vm-skip-deleted-messages} to @code{nil}.  These
commands can also be made to skip messages that have been read; set
@code{vm-skip-read-messages} to @code{t} to do this.  If all the messages
in the current folder would be skipped (i.e all are read and/or
deleted), @kbd{n} and @kbd{p} simply move to the next message.@refill

The commands @kbd{n} and @kbd{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.@refill

@vindex vm-circular-folders
The variable @code{vm-circular-folders} determines whether VM folders
will be considered circular by various commands.  @dfn{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.@refill

A value of @code{t} causes all VM commands to consider folders circular.
A value of @code{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 moves, saves,
etc. will be done unless they can be done in their entirety.  A value
other than @code{nil} or @code{t} causes only VM's movement
commands to consider folders circular.  Saves, deletes and undeletes
will behave as if the value is @code{nil}.  The default value of
@code{vm-circular-folders} is @code{0}.@refill

Other commands to select messages:

@iftex
@table @asis
@end iftex
@ifinfo
@table @key
@end ifinfo
@findex vm-goto-message
@kindex RET
@item RET (@code{vm-goto-message})
Go to message number @var{n}.  @var{n} is the prefix argument, if
provided, otherwise it is prompted for in the minibuffer.
@findex vm-goto-message
@kindex TAB
@item TAB (@code{vm-goto-message-last-seen})
Go to message last previewed or read.
@findex vm-Next-message
@findex vm-Previous-message
@kindex N
@kindex P
@item N (@code{vm-Next-message})
@itemx P (@code{vm-Previous-message})
Go to the next (previous) message, ignoring the settings of the skip
control variables.
@findex vm-next-unread-message
@findex vm-previous-unread-message
@kindex M-n
@kindex M-p
@item M-n (@code{vm-next-unread-message})
@itemx M-p (@code{vm-previous-unread-message})
Move forward (backward) to the nearest new or unread message.  If no
such message exists then these commands work like @kbd{n} and @kbd{p}.
@findex vm-isearch-forward
@kindex M-s
@vindex vm-search-using-regexps
@item M-s (@code{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 @code{vm-search-using-regexps} is non-@code{nil},
a regular expression may be used instead of a fixed string for the
search pattern.  VM defaults to the fixed string search.
@xref{Incremental Search,,,emacs, the GNU Emacs Manual}.@refill
@end table

Selecting a message within VM normally causes VM to preview it.
@iftex
@xref{Previewing}.
@end iftex

@menu
* Previewing:: Customizing message previews.
@end menu

@node Previewing,, Selecting Messages, Selecting Messages
@section Previewing

@dfn{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
@key{SPC} exposes the body of 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 augmented by the settings of two variables: @code{vm-visible-headers}
and @code{vm-preview-lines}.@refill

@vindex vm-preview-lines
The value of @code{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 @code{vm-preview-lines} is @code{nil},
then previewing is not done at all; when a message is first presented it
is immediately exposed in its entirety and is marked as read.@refill

@vindex vm-visible-headers
The value of @code{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 order of presentation for the headers they match.@refill

@vindex vm-highlighted-header-regexp
Another variable of interest is @code{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 @samp{"^From\\|^Subject"}
causes the From and Subject headers to be highlighted.@refill

@vindex vm-preview-read-messages
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 @code{vm-preview-read-messages} to @code{nil}.

@node Sending Messages, Saving Messages, Selecting Messages, Top
@chapter Sending Messages

When sending messages from within VM, you will be using the standard
Mail major mode provided with GNU Emacs.  @xref{Mail Mode,,,emacs, the
GNU Emacs Manual}.
However, @samp{*mail*} buffers created by VM have extra command keys:

@iftex
@table @asis
@end iftex
@ifinfo
@table @key
@end ifinfo
@findex vm-yank-message
@kindex C-c C-y
@item C-c C-y
Copies a message from the current folder into the @samp{*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
@code{vm-included-text-prefix}.  If a prefix argument is given, this
prepending is not done.@refill
@kindex C-c C-v
@item C-c C-v <Any VM command key>
All VM commands may be accessed in the @samp{*mail*} buffer by prefixing them
with C-c C-v.
@end table

@findex vm-mail
@kindex m
The simplest command is @kbd{m} (@code{vm-mail}) which sends a mail
message much as @kbd{M-x mail} does but allows the added commands
described above.@refill

@menu
* Replying::		Describes the various way to reply to a message.
* Forwarding Messages::	How to forward a message to a third party.
@end menu

@node Replying, Forwarding Messages, Sending Messages, Sending Messages
@section 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.  You
can change these headers manually if you wish.

@vindex vm-included-text-prefix
VM also helps you quote material from a message to which you are
replying by providing @dfn{included text} as a feature of some of the
commands.  @dfn{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
@code{vm-included-text-prefix} specifies what the prepended string will
be.@refill

@vindex vm-included-text-attribution-format
The variable @code{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-@code{nil}, the value of
@code{vm-included-text-attribution-format} should be a string format
specifiation similar to @code{vm-summary-format}.  @xref{Summaries}.  A
@code{nil} value causes the attribution to be omitted.@refill

@vindex vm-in-reply-to-format
The variable @code{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 @code{vm-included-text-attribution-format},
@code{vm-in-reply-to-format} should be a string similar to that of
@code{vm-summary-format}.  A @code{nil} value causes the In-Reply-To
header to be omitted.@refill

@vindex vm-strip-reply-headers
The recipient headers generated for reply messages are normally made 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 @code{vm-strip-reply-headers} is
non-@code{nil}, the reply headers will stripped of all information but
the actual addresses.

The reply commands are:

@iftex
@table @asis
@end iftex
@ifinfo
@table @key
@end ifinfo
@findex vm-reply
@kindex r
@item r (@code{vm-reply})
Replies to the author of the current message.
@findex vm-reply-include-text
@kindex R
@item R (@code{vm-reply-include-text})
Replies to the author of the current message and provides included text.
@findex vm-followup
@kindex f
@item f (@code{vm-followup})
Replies to the all recipients of the current message.
@findex vm-followup-include-text
@kindex F
@item F (@code{vm-followup-include-text})
Replies to the all recipients of the current message and provides
included text.
@end table

All the reply commands mark the message to which you are responding as
``replied'' when the reply is actually sent.@refill

@node Forwarding Messages,, Replying, Sending Messages
@section Forwarding Messages

VM has two commands to forward messages: @kbd{z}
(@code{vm-forward-message}) and @key{@@} (@code{vm-send-digest}).@refill

@findex vm-forward-message
@kindex z
@vindex vm-rfc934-forwarding
@vindex vm-forwarding-subject-format
Typing @kbd{z} puts you into a @samp{*mail*} buffer just like @kbd{m},
except the current message appears as the body of the message in the
@samp{*mail*} buffer. The forwarded message is surrounded by RFC 934
complaint message delimiters.  If the variable
@code{vm-rfc934-forwarding} is non-@code{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 @code{vm-forwarding-subject-format} is non-@code{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 @samp{*mail*} buffer.  A @code{nil} value causes the
Subject header to be left blank.@refill
@findex vm-send-digest
@kindex @@
The command @key{@@} (@code{vm-send-digest}) works like @kbd{z} except
that a digest of all the messages in the current folder is made and
inserted into the @samp{*mail*} buffer.@refill

@node Saving Messages, Deleting Messages, Sending Messages, Top
@chapter Saving Messages

Mail messages are normally saved to files that contain only mail
messages.  Such files are called @dfn{folders}.

@findex vm-save-message
@kindex s
The VM command to save a message to a folder is @kbd{s}
(@code{vm-save-message}); invoking this command causes the current
message to be saved to a folder whose name you specify in the
minibuffer.  If @code{vm-save-message} is given a prefix argument
@var{n}, the current message plus the next @var{n-1} message are saved.
If @var{n} is negative, the current message and the previous @var{n-1}
messages are saved.  Messages saved with @code{vm-save-message} are
marked ``filed''.@refill

@vindex vm-confirm-new-folders
If the value of the variable @code{vm-confirm-new-folders} is
non-@code{nil}, VM will ask for confirmation before creating a new
folder on interactive saves.@refill

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

@vindex vm-auto-folder-alist
Another aid to selecting folders in which to save mail is the variable
@code{vm-auto-folder-alist}.  The value of this variable should be a
list of the form,@refill

@display
((@var{header-name}
   (@var{regexp} . @var{folder-name}) ...)
  ...)
@end display

where @var{header-name} and @var{regexp} are strings, and
@var{folder-name} is a string or an s-expression that evaluates to a
string.@refill

If any part of the contents of the message header named by
@var{header-name} is matched by the regular expression @var{regexp}, VM
will evaluate the corresponding @var{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 @code{vm-folder-directory}, or the @code{default-directory} of
the currently visited folder if @code{vm-folder-directory} is nil.@refill

When @var{folder-name} is evaluated, the current buffer will contain
only the contents of the header named by @var{header-name}.  It is safe
to modify this buffer.  You can use the match data from any
@samp{\( @dots{} \)} grouping constructs in @var{regexp} along with the
function buffer-substring to build a folder name based on the header
information.@refill

All @code{vm-auto-folder-alist} matching is case sensitive.

@vindex vm-visit-when-saving
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
@code{vm-visit-when-saving} controls which method is used.  A @code{nil}
value (the default) causes VM to append directly to the folder file, a
non-@code{nil} value makes VM load the file into a buffer and append to
that.@refill

@vindex vm-delete-after-saving
After a message is saved to a folder, the usual thing to do next is to
delete it.  If the variable @code{vm-delete-after-saving} is
non-@code{nil} VM will mark messages for deletion automatically after
saving them.  This applies only to saves to folders, not for the @key{w}
command (see below).@refill

Other commands:

@iftex
@table @asis
@end iftex
@ifinfo
@table @key
@end ifinfo
@findex vm-save-message-sans-headers
@kindex w
@item w (@code{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 @code{vm-save-message}
does.  Messages saved this way are @emph{not} marked as filed, as ``filed''
is meant to mean saved to a folder.  You should @emph{not} use this
command to save to mail folders.
@findex vm-auto-archive-messages
@kindex A
@item A (@code{vm-auto-archive-messages})
Save all unfiled messages that auto-match a folder via
@code{vm-auto-folder-alist} to their appropriate folders.
@findex vm-pipe-message-to-command
@kindex |
@item | (@code{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 @t{C-u} the text portion of the message is used.@*
If invoked with two @t{C-u}'s the header portion of the message is used.@*
@*
If the shell command generates any output, it is displayed in a
@samp{*Shell Command Output*} buffer.  The message is not altered or
marked as filed.
@end table

@node Deleting Messages, Undoing, Saving Messages, Top
@chapter Deleting Messages

In VM messages are marked for deletion, and then are subsequently
@dfn{expunged} or removed from the folder.  The messages are not removed
from the on-disk copy of the folder until the folder is saved.

@iftex
@table @asis
@end iftex
@ifinfo
@table @key
@end ifinfo
@findex vm-delete-message
@kindex d
@item d (@code{vm-delete-message})
Marks the current message for deletion.  A prefix argument @var{n}
causes the current message and the next @var{n-1} messages to be marked.
A negative @var{n} causes the current message and the previous @var{n-1}
messages to be marked.
@findex vm-undelete-message
@kindex u
@item u (@code{vm-undelete-message})
Removes the deletion mark from the current message.  A prefix argument @var{n}
causes the current message and the next @var{n-1} messages to be unmarked.
A negative @var{n} causes the current message and the previous @var{n-1}
messages to be unmarked.
@findex vm-kill-subject
@kindex k
@item k (@code{vm-kill-subject})
Marks all message with the same subject as the current message (ignoring
``Re:'') for deletion.
@findex vm-expunge-folder
@kindex #
@item # (@code{vm-expunge-folder})
Does the actual removal of messages marked for deletion in the current
folder.
@end table

@vindex vm-move-after-deleting
Setting the variable @code{vm-move-after-deleting} non-@code{nil} causes
VM to move past the messages after marking them for deletion.

@node Undoing, Grouping Messages, Deleting Messages, Top
@chapter Undoing

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

@findex vm-undo
@kindex C-x u
@kindex C-_
Typing @kbd{C-x u} or @key{C-_} (@code{vm-undo}) undoes the last
attribute change.  Consecutive @code{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
@code{vm-undo}.@refill

Note that expunges and saves are @emph{not} undoable.

@node Grouping Messages, Reading Digests, Undoing, Top
@chapter Grouping Messages

@findex vm-group-messages
@kindex G
In order to make numerous related messages easier to cope with, VM
provides the command @kbd{G} (@code{vm-group-messages}), which groups
all message in a folder according to some criterion.  @dfn{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.@refill

The grouping criteria currently supported are:
@table @samp
@item subject
Messages with the same subject (ignoring ``Re:'' prefixes) are grouped
together.
@item author
Messages with the same author are grouped together.
@item date-sent
Messages sent on the same day are grouped together.
@item arrival-time
Message presentation reverts to arrival time ordering (the default).
@end table

@vindex vm-group-by
If the variable @code{vm-group-by} has a non-@code{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
@code{(setq vm-group-by "subject")} in your @file{.emacs} file to get this
behavior.@refill

@node Reading Digests, Summaries, Grouping Messages, Top
@chapter Reading Digests

A @dfn{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.

@findex vm-burst-digest
@kindex *
The command @kbd{*} (@code{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.  @xref{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.@refill

@node Summaries, Miscellaneous, Reading Digests, Top
@chapter Summaries

@findex vm-summarize
@kindex h
Typing @kbd{h} (@code{vm-summarize}) causes VM to display a summary of
contents of the current folder.  An arrow @samp{->} appears to the left
of the line summarizing the current message.  The information in the
summary is automatically updated as changes are made to the current
folder.@refill

@vindex vm-summary-format
The variable @code{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:
@display
   a - attribute indicators (always three characters wide)
       The first char is  `D', `N', `U' or ` ' for deleted, new, unread
       and read message respectively.
       The second char is `F' for filed (saved) messages.
       The third char is `R' if the message has been replied to.
   c - number of characters in message (ignoring headers)
   d - date 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
   n - message number
   s - message subject
   w - day of the week message sent
   y - year message sent
   z - timezone of date when the message was sent
@end display

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,
@pxref{Starting Up}.@refill

@vindex vm-follow-summary-cursor
All VM commands are available in the summary buffer just as they
are in the folder buffer itself.  If you set
@code{vm-follow-summary-cursor} non-@code{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 @emph{only}
when executing a command from the summary buffer window.@refill

@node Miscellaneous,, Summaries, Top
@chapter Miscellaneous

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

@iftex
@table @asis
@end iftex
@ifinfo
@table @code
@end ifinfo
@vindex vm-berkeley-mail-compatibility
@item vm-berkeley-mail-compatibility
A non-@code{nil} value means to read and write BSD @i{Mail(1)} style Status:
headers.  This makes sense if you plan to use VM to read mail archives
created by @i{Mail}.
@vindex vm-gargle-uucp
@item vm-gargle-uucp
A non-@code{nil} value means to use a crufty regular expression that
does surprisingly well at beautifying UUCP addresses that are substituted
for %f as part of summary and attribution formats.
@vindex vm-mode-hooks
@item vm-mode-hooks
A non-@code{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.
@vindex vm-folder-type
@item vm-folder-type
This variable specifies the type of mail folder VM should expect to read
and write.  @code{Nil} means expect the UNIX style folders characterized
by the ``\n\nFrom '' message separators.  The only other supported value
for this variable is the symbol @code{mmdf} which causes VM to use
``^A^A^A^A\n'' MMDF style leaders and trailers.@refill
@vindex vm-delete-empty-folders
@item vm-delete-empty-folders
A non-@code{nil} value for this variable causes VM to remove empty (zero
length) folder files after saving them.
@vindex vm-mutable-windows
@item vm-mutable-windows
This variable's value controls VM's window usage.  A value of @code{t} gives VM
free run of the Emacs display; it will commandeer the entire screen for
its purposes.  A value of @code{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 it's own window.  A value that is neither @code{t}
nor @code{nil} allows VM to use other windows, but it will not create new ones,
or resize or delete the current ones.@refill
@end table

@node Key Index, Command Index, Top, Top
@unnumbered Key Index
@printindex ky

@node Command Index, Variable Index, Key Index, Top
@unnumbered Command Index
@printindex fn

@node Variable Index, Introduction, Command Index, Top
@unnumbered Variable Index
@printindex vr

@summarycontents
@contents
@bye
