\input texinfo
@documentencoding ISO-8859-1
@setfilename vm.info
@settitle VM User's Manual
@dircategory Emacs
@direntry
* VM: (vm).                             A mail reader.
@end direntry
@defindex in

@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.
@table @asis
@item Copyright @copyright{} 1989, 1991, 1999 Kyle E. Jones
@item Copyright @copyright{} 2003 - 2008 Robert Widhopf-Fenk
@item Copyright @copyright{} 2008 - 2012 Uday S. Reddy
@item Copyright @copyright{} 2024-2025 The VM Developers
@end table

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
@include version.texinfo
@titlepage
@sp 6
@center @titlefont{VM User's Manual}
@sp 4
@center VM Version @value{VERSION}
@sp 5
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1989, 1991, 1999, 2002, 2003 Kyle E. Jones
Copyright @copyright{} 2003 - 2008 Robert Widhopf-Fenk
Copyright @copyright{} 2008 - 2009 Uday S. Reddy
Copyright @copyright{} 2024-2025 The VM Developers

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
@ifnottex
@node Top, Preface,, (DIR)

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.

This manual corresponds to VM version @value{VERSION}.

@menu
* Preface::             What is VM?
* Introduction::        Overview of the VM interface.
* Starting Up::         What happens when you start VM.
* Navigating::  How to select messages for reading.
* Reading Messages::    Previewing and paging through a message.
* Sending Messages::    How to send messages from within VM.
* Selecting Messages::    Running VM commands on arbitrary sets of messages.
* 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 Attributes::  How to change and undo changes to message attributes.
* Sorting Messages::    How to make VM present similar messages together.
* Digests::             How to read digests under VM.
* Summaries::           How to view and customize the summary of a folder.
* Virtual Folders::     Blurring the boundaries of different physical folders.
* @acronym{IMAP} Server Folders:: Working with IMAP server folders.
* Frames and Windows::  How to customize VM's use of windows and frames.
* Toolbar::             How to configure VM's toolbar.
* Menus::               How to configure VM's menus.
* Faces::               How to configure VM's use of faces.
* Using the Mouse::     Understanding the VM mouse interface.
* Hooks::               How you can make VM run your code at certain times.
* Configuration::       Hints on how to configure VM to read and send mail

Add-ons and Customizations:

* Preface to Add-ons::  What are these?
* Customizations::	Making VM behave the way you might want.

About VM:

* History and Administration:: Information about VM
* Highlights::          Most valuable features of VM, as per the users.
* Future Plans::	Planned extensions of VM for the future
* Bugs::                How to report VM bugs

For developers:

* Internals::           Information on VM internals for developers

Indices:

* Concept Index::       Menus of key concepts
* 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.
* Internals Index::     Menus of concepts in VM Internals

Rights:
* License::             Copying and distribution terms for VM.


@end menu
@end ifnottex

@node Preface, Introduction, Top, Top
@unnumbered What is VM?

@cindex Rmail
@cindex Gnus
@cindex Gnu Emacs
@cindex XEmacs
@cindex Emacs
VM, short for ``View Mail,'' is a mail reader that runs within the
Emacs editor.  If you are already an Emacs-user, you will be working
in a familiar environment.  You might have even used other Emacs-based
mail readers such as Rmail and Gnus.  If you are new to Emacs, you can
start using VM via the menubar and toolbar until you become familiar
with it.  Then you can move on to keyboard shortcuts and advanced
features.  You should be aware that there are two major strands of
Emacs versions, called ``Gnu Emacs'' and ``XEmacs.''  VM works in both
of them.  XEmacs might be a bit easier for new users due to its
advanced support for menus and other interactive features.  Please be
sure to try both of them before deciding on your choice.

Emacs provides a powerful text-based user interface for VM users, with
facilities for quick navigation, incremental searching , sophisticated
customization and powerful add-on functions.  You also have all the
editing features of Emacs available for composing mail, without having
to switch environments.

@cindex virtual folders
@cindex archiving
@cindex address book
@cindex @acronym{MIME}
@cindex encryption
@cindex @acronym{BBDB}
@cindex Org mode
@cindex @acronym{GPG}
VM was developed by Kyle Jones starting in 1989.  It was a leader
in mail-reading functionality by introducing features like thread
management, virtual folders, automatic archiving of messages and a
full treatment of @acronym{MIME}.  VM can interface to other packages
available in Emacs, for remote file access, @acronym{BBDB} address book,
@acronym{GPG} 
encryption and Org mode task management etc.  It can also invoke
external utilities available on your system such as mail filtering
tools and html rendering tools.

@cindex @acronym{POP}
@cindex @acronym{IMAP}
@cindex mail servers
@cindex mbox
@cindex Thunderbird
VM can read and store mail on your file system (both local and
remote).  It can also handle mail stored in remote file servers
running @acronym{POP} and @acronym{IMAP} protocols.  The local folders are stored in a
Unix-standard @code{mbox} format, which is also used by most other
mail readers including Thunderbird.  In fact, VM can seamlessly
operate on Thunderbird folders and, if you use a remote mail server,
you can view the same folders in VM and Thunderbird concurrently.  In
addition, VM can also store mail in the @code{Babyl} format used by
Emacs Rmail.  So, it is also possible to inter-operate with Rmail if
you have archived mail in that format.

@cindex maildir
@cindex newsgroups
@cindex @acronym{RSS} feeds
@cindex @acronym{S/MIME}
There are also a few things that VM cannot (yet) do.  It does not have the
ability to deal with maildir folders.  It cannot be used to read newsgroups
and @acronym{RSS} feeds.  It does not have its own mail filtering tools.  It
does not have support for the Secure @acronym{MIME} (@acronym{S/MIME})
protocol.  However, active development of VM is continuing.  It may acquire
some of these features before long.

VM has been found most useful by professional users who must deal with
large quantities of email in the course of their work, and deal with
it efficiently and reliably.  We enjoy using VM and find that it is
better than any other mail tool in its flexibility and efficiency.  We
hope you will too!

-- VM Development Team


@node Introduction, Starting Up, Preface, Top
@unnumbered Overview

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.

You can make VM your default mail user agent by setting @code{mail-user-agent}
to @code{vm-user-agent}, e.g. by @kbd{M-x} @code{customize-variable} @key{RET}
@code{mail-user-agent} @key{RET}.

To invoke VM, type @kbd{M-x vm}.  VM gathers any mail that has
arrived in your system mailbox and appends it to a mail folder known as your
@dfn{primary inbox}, and visits that folder for reading.  @xref{Starting Up}.
Depending on how you have configured VM, the primary inbox might be a
file on your file system (in a format understood by VM) or it could be
a folder on a remote mail server.

If you type @kbd{?} in a VM folder buffer you will get some help, i.e.
@code{vm-help} is called.

@findex vm-scroll-forward
@findex vm-scroll-backward
@kindex SPC
@kindex DEL
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 a 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 flags the
message as read.  Subsequent @key{SPC}'s scroll forward through the
message, @key{DEL} scrolls backward.  When you reach the end
of a message, typing @key{SPC} or @kbd{n} moves you forward to preview
the next message.  @xref{Paging}.

@findex vm-next-message
@kindex n
If you do not want to read a message that's being previewed, type
@kbd{n} and VM will move to the next message (if there is one).
@xref{Navigating}.

@findex vm-save-message
@kindex s
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}.

@findex vm-delete-message
@findex vm-undelete-message
@findex vm-expunge-folder
@findex vm-compact-folder
@kindex d
@kindex u
@kindex ###
@cindex expunging
@cindex compacting
Messages are deleted by typing @kbd{d} (@code{vm-delete-message}) while
previewing or reading them.  The message is not removed right away; VM
makes a note that you want the message to be removed later.  If you
change your mind about deleting a message, 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} or @dfn{compacting}, and it is
accomplished by 
typing @kbd{###} (@code{vm-expunge-folder}, @code{vm-compact-folder}).  The
deleted messages are still present 
in the on-disk version of the folder until the folder is saved.

@findex vm-summarize
@findex vm-headers-summary
@kindex h
Typing @kbd{h} (@code{vm-summarize}, @code{vm-headers-summary}) causes VM to
display a window containing a summary of the 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 @samp{->} appears to
the left of the line summarizing the current message.  The summary format is
user configurable, @pxref{Summaries}.

@findex vm-save-folder
@kindex S
@cindex expunging
@cindex compacting
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}) saves the folder.  The default behavior is
that deleted messages are @emph{not} expunged automatically when you
save a folder. 
The next time you visit the folder any deleted
messages will still be flagged for deletion.  @pxref{Deleting Messages}.

@vindex vm-folder-file-precious-flag
When a folder is first visited, the value of the variable
@code{vm-folder-file-precious-flag} is used to initialize a
buffer-local instance of @code{file-precious-flag}, which
determines how folders are saved.  A non-nil value causes
folders to be saved by writing to a temporary file and then
replacing the folder with that file.  A nil value causes
folders to be saved by writing directly to the folder without
the use of a temporary file.

@vindex vm-delete-empty-folders
If the folder is empty at the time you save it and the variable
@code{vm-delete-empty-folders} is non-@code{nil}, VM will remove
the zero length folder after saving it.

@findex vm-quit
@findex vm-quit-no-change
@kindex q
@kindex x
To quit visiting a folder you can type @kbd{q} (@code{vm-quit}) or
@kbd{x} (@code{vm-quit-no-change}).  Typing @kbd{q} saves the current
folder before quitting.  Also, any messages flagged new are changed to
be flagged as old and unread, before saving.  The @kbd{x} command quits
a folder without changing the status of new messages, saving or
otherwise modifying the current folder.

@vindex vm-confirm-quit
If the variable @code{vm-confirm-quit} is set to @code{t}
VM will always ask for confirmation before ending a VM
visit of a folder.  A @code{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
neither @code{nil} nor @code{t} causes VM to ask only when
there are unsaved changes to message attributes or when messages
will be lost.

@findex vm-quit-just-bury
@findex vm-switch-to-folder
You do not have to quit a folder to continue using Emacs for other
purposes.  @code{M-x vm-quit-just-bury} buries the buffers associated with
the current folder deep in Emacs' stack of buffers, but otherwise leaves
the folder visited so that you can resume reading messages quickly.
You can return to the folder using @code{M-x vm-switch-to-folder}.
Or, you can locate the folder's buffers again by using @code{list-buffers},
which is normally bound to @kbd{C-x C-b}.

@findex vm-quit-just-iconify
@findex vm-quit-just-bury
Another command you can use if you are using a window system like X
Windows is @code{vm-quit-just-iconify}.  This command buries the
folder's buffers like @code{vm-quit-just-bury} and also iconifies the
current frame.

@findex vm-get-new-mail
@kindex g
At any time while reading mail in any folder you can type @kbd{g}
(@code{vm-get-new-mail}) to check to see if new mail for that folder has
arrived.  If new mail has arrived it will be moved from the spool files
or maildrops associated with the current folder and merged into the
folder.  If you are not in the middle of another message, VM will also
move to the first new or unread message.

If @code{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 no messages are
deleted from it as they would be for a spool file.

@cindex primary inbox
@cindex spool file
By default your primary inbox has your system mailbox associated with
it, e.g. @file{/var/spool/mail/kyle}, and so typing @kbd{g} will retrieve
mail from this file.  Your system mailbox is one example of a @dfn{spool
file}, a file that the mail transport system delivers messages into.
You can associate other spool files with your primary inbox and spool
files with other folders by setting the variable
@code{vm-spool-files}.  @xref{Spool Files}.

@node Starting Up, Navigating, Introduction, Top
@chapter Starting Up

@findex vm-load-init-file
@vindex vm-init-file
@cindex configuration settings
@cindex .vm
The first time VM is started in an Emacs session, it attempts to load
the file specified by the variable @code{vm-init-file}, normally
@file{~/.vm}.  If present this file should contain Lisp code, much
like the @file{.emacs} file.  It should contain the ``configuration
settings'' for VM, i.e., variables that define where the mail folders
are stored, where the incoming mail is to be found, the various
directories that VM needs to use for its operation and the external
applications that VM can invoke.  You can reload this file by typing
@code{M-x vm-load-init-file} from within VM.

@vindex vm-preferences-file
@cindex .vm.preferences
@cindex preferences settings
In addition, VM also attempts to load a file specified by the variable
@code{vm-preferences-file}, normally @file{~/.vm.preferences}.  This
file should contain your preferential settings for various VM
variables affecting how VM works.  Since VM has well over one
hundred configuration variables, use of the @file{~/.vm.preferences}
can considerably reduce clutter in the @file{.vm} file.

Invoking @code{vm-load-init-file} with a prefix argument (e.g.,
@kbd{C-u}) causes the @code{vm-init-file} to be loaded without the
@code{vm-preferences-file}.  VM will work with all its default
settings for the variables.  This is similar to invoking emacs via
@code{emacs -Q}.  If you ever find a problem with VM's behavior, it is
a good idea to run it without the @code{vm-preferences-file} in order
to check if the problem might have been caused by the preferences
settings.

@findex vm
@vindex vm-primary-inbox
@vindex vm-auto-get-new-mail
@cindex primary inbox
@kbd{M-x vm} causes VM to visit a folder known as your @dfn{primary
inbox}, specified by the variable @code{vm-primary-inbox}.  If the
variable @code{vm-auto-get-new-mail} is set 
non-@code{nil}, VM will gather any new mail that has arrived
and integrate it into your primary inbox.  The default setting for your
primary inbox is the local file @file{~/Mail/inbox}, but a variety of
other options are available.

VM can work with mail folders saved on the local file system.
@xref{Local Folders}.  It can also work with mail folders stored on
remote mail servers, such as @acronym{POP} and @acronym{IMAP} servers.  @xref{@acronym{POP} and @acronym{IMAP}
Folders}.  Server folders have the advantage that they can be accessed
from multiple locations on the internet.  VM might appear to have a
bias towards local folders due to its history of development.  But it
treats server folders with equal facility.

@findex vm-visit-folder
@findex vm-visit-pop-folder
@findex vm-visit-imap-folder
@kindex v
@kbd{M-x vm-visit-folder} (@kbd{v} from within VM) allows you to visit
any local mail folder.  The folder name will be
prompted for in the minibuffer.  @kbd{M-x vm-visit-pop-folder} and
@kbd{M-x vm-visit-imap-folder} perform similar function for server
folders. 

@cindex read-only folders
@vindex vm-preserve-read-only-folders-on-disk
With a prefix argument @kbd{M-x vm-visit-folder} visits a folder in
``read-only'' mode.  In read-only mode, no attribute changes, messages
additions or deletions will be allowed in the visited folder.  However, VM
might still make internal changes to the visited folder (with the effect
that you might see the buffer-modified indicator in the modeline).  These
changes will be discarded when the folder is quit.  The variable
@code{vm-preserve-read-only-folders-on-disk} should be set to @code{nil} if
you want to save VM's internal modifications.

Once VM has read the folder and assimilated any new mail, the first new or
unread message will be selected, if any.  If there is no such message,
VM will select whatever the selected message was when this folder was last
saved.  If this folder has never been visited and saved by VM, then the
first message in the folder is selected.

@findex vm-mode
@kbd{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
on it.  This command is suitable for use in Lisp programs, and for
inclusion in @code{auto-mode-alist} to automatically start VM on a
file based on a particular filename suffix.  @code{vm-mode} skips
some of VM's start-up procedures (e.g. starting up a summary) to make
non-interactive use easier.

@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} always gives a
summary.  A value that is a positive integer @var{n} means that VM
should generate a summary if there are @var{n} or more messages in
the folder.  A negative value @var{-n} means generate a summary only if
there are @var{n} or fewer messages.  The default value of
@code{vm-startup-with-summary} is @code{t}.

@menu
* Local Folders::       Working with folders on the local file system
* @acronym{POP} and @acronym{IMAP} Folders::        Working with folders on mail servers
* Thunderbird Folders::         Working with folders managed by Thunderbird
* External Messages::           Working with messages stored externally.
* Getting New Mail::  Retrieving mail from spool files.
* Crash Recovery::    Recovering changes after Emacs or your system dies.
@end menu

@node Local Folders, @acronym{POP} and @acronym{IMAP} Folders, Starting Up, Starting Up
@section Local Folders

@cindex mbox
@cindex Babyl
@cindex Rmail
@vindex vm-default-folder-type
A local mail folder is simply a file that can be stored on the local
file system.  VM works with the Unix @dfn{mbox} format to store
messages in folders.  It can also work with the @dfn{Babyl} format
used by the Emacs Rmail package.  The subtypes of mboxes handled by VM
are listed under @b{Folder types} below.

@vindex vm-folder-directory
It is a good idea to create directory, e.g., @code{~/Mail}, where all
of VM's local folders will be kept.  If you create such a directory,
you should set the variable @code{vm-folder-directory} to point to it.

@cindex spool file
@cindex file locking
A @dfn{spool file} is a file where the mail transport system delivers
messages intended for you.  On Unix systems, a program called
@file{/bin/mail} or @file{/bin/mail.local} does this delivery.
It is also possible for agents such as @file{procmail}, @file{filter} and
@file{slocal} to be invoked from a user's @file{~/.forward} or
@file{~/.qmail} files, sorting the incoming mail into separate spool
files.  On other systems, incoming mail may be
delivered to mailboxes on remote mail servers, from where it can be
retrieved through protocols like @acronym{POP} and @acronym{IMAP}.  No matter what the
delivery agent, what all spool files have in common is that mail is
delivered into them by one or more entities apart from VM and that all
access to spool files must therefore be accompanied by the use of some
file locking protocol.

@vindex vm-movemail-program
@vindex vm-movemail-program-switches
When spool files are on the local file system, VM uses the program
@file{movemail}, a program distributed with Emacs to extract mail from
a spool file.  The variable @code{vm-movemail-program} specifies the
name of the movemail program and defaults to @samp{"movemail"}.  The
variable @code{vm-movemail-program-switches} lets you specify some
initial command line argument to pass to the movemail program.

@cindex crash box
@vindex vm-crash-box
VM transfers the mail from a spool file to a folder via a
temporary file known as the @dfn{crash box}.  The variable
@code{vm-crash-box} names the crash box file for the primary inbox.
Or a crash-box name may be created from @code{vm-crash-box-suffix}
described below. 
(@pxref{Spool Files}.)
VM first copies the mail to the crash box, truncates the spool file
to zero messages, 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 activity, any message not present in
the primary inbox will be either in the spool file or the crash
box.  Some messages may be duplicated but no mail will be lost.

If the file named by @code{vm-crash-box} already exists when VM is
started up, VM will merge that file with the primary inbox before
retrieving any new messages from the system mailbox.

@menu
* Spool Files::         Specifying where mail comes from
* @acronym{POP} Spool Files::     How to use a @acronym{POP} mailbox as a spool file
* @acronym{IMAP} Spool Files::    How to use an @acronym{IMAP} mailbox as a spool file
* Index Files::         Using an index to speed up VM starting
* Folder types::        About the mail folder formats handled by VM
@end menu

@node Spool Files, @acronym{POP} Spool Files, Local Folders, Local Folders
@unnumberedsubsec Spool Files

@vindex vm-spool-files
Every folder, including the primary inbox, can have one or more spool
files associated with it.  You make these associations known to VM by
setting the variable @code{vm-spool-files}.

If you only want to associate spool files with your primary inbox, you
can set @code{vm-spool-files} to a list of strings.  By default, the location
of your system mailbox (the spool file that is associated with your
primary inbox) is determined heuristically based on what type of system
you're using.  VM can be told explicitly where the system mailbox is by
setting @code{vm-spool-files} like this:

@example
(setq vm-spool-files '("/var/spool/mail/kyle" "~/Mailbox"))
@end example

@noindent With this setting, VM will retrieve mail for the primary
inbox from first @file{/var/spool/mail/kyle} and then @file{~/Mailbox}.

If the value of @code{vm-spool-files} is @code{nil}, a default value for
@code{vm-spool-files} will be inherited from the shell environmental
variables MAILPATH or MAIL if either of these variables are defined.
This inheritance happens before your init file is loaded, so setting
@code{vm-spool-files} in your init file will override any environmental
variables.

If you want to associate spool files with folders other than or in
addition to the primary inbox, the value of @code{vm-spool-files} must be a
list of lists.  Each sublist specifies three entities, a folder, a spool
file and a crash box.  When retrieving mail for a particular folder, VM
will scan @code{vm-spool-files} for folder names that match the current
folder's name.  The spool file and crash box found in any matching
entries will be used to gather mail for that folder.

For example, you can set @code{vm-spool-files} like this

@example
@group
(setq vm-spool-files
      '(
        ("~/INBOX"      "/var/spool/mail/kyle"      "~/INBOX.CRASH")
        ("~/INBOX"      "~/Mailbox"                 "~/INBOX.CRASH")
        ("~/Mail/bugs"  "/var/spool/mail/answerman" "~/Mail/bugs.crash")
       )
)
@end group
@end example

@noindent The folder @file{~/INBOX} has two spool files associated
with it in this 
example, @file{/var/spool/mail/kyle} and @file{~/Mailbox}.  Another
folder, @file{"~/Mail/bugs"} has one spool file
@file{/var/spool/mail/answerman} associated with it.  Note that both of
the @file{~/INBOX} entries used the same crash box.  The crash box can be
the same if the folder name is the same.  Different folders should use
different crashboxes.

@vindex vm-crash-box-suffix
@vindex vm-spool-file-suffixes
An alternate way of specifying folder/spool file associations
is to use the variables @code{vm-spool-file-suffixes} and
@code{vm-crash-box-suffix}.

The value of @code{vm-spool-file-suffixes} should be a list of string suffixes
to be used to create possible spool file names for folders.  Example:

@example
@group
(setq vm-spool-file-suffixes '(".spool" "-"))
@end group
@end example

@noindent With @code{vm-spool-file-suffixes} set this way, if you
visit a 
folder @file{~/mail/beekeeping}, when VM attempts to retrieve new mail for
that folder it will look for mail in @file{~/mail/beekeeping.spool}
and @file{~/mail/beekeeping-} in addition to scanning @code{vm-spool-files}
for matches.  The value of @code{vm-spool-files-suffixes} will not be used
unless @code{vm-crash-box-suffix} is also defined, since a crash box is
required for all mail retrieval from spool files.

The value of @code{vm-crash-box-suffix} should be a string suffix used to
create possible crash box file names for folders.  When VM uses
@code{vm-spool-file-suffixes} to create a spool file name, it will append
the value of @code{vm-crash-box-suffix} to the folder's file name to
create a crash box name.  If the value of @code{vm-spool-files-suffixes}
is @code{nil}, then the value of @code{vm-crash-box-suffix} is not used
by VM.

@vindex vm-make-crash-box-name
@vindex vm-make-spool-file-name
The idea behind @code{vm-spool-file-suffixes} and
@code{vm-crash-box-suffix} is to give you a way to have many
folders with individual spool files associated with them, without
having to list them all in @code{vm-spool-files}.  If you need
even more control of spool file and crash box names, use
@code{vm-make-spool-file-name} and @code{vm-make-crash-box-name}.
The value of both of these should be a function or the name of a
function.  When VM visits a folder, it will call the function
with the name of the folder as an argument, and the function
should return the spool file name or crash box name to be used
for that folder.

If your spool file is on another host, VM supports accessing
spool files on remote hosts using the @acronym{POP} and @acronym{IMAP} protocols.

@node @acronym{POP} Spool Files,@acronym{IMAP} Spool Files,Spool Files,Local Folders
@unnumberedsubsec @acronym{POP} Spool Files

@cindex @acronym{POP} spool files
@cindex maildrop specification
VM can access spool files on mail servers via the @dfn{Post Office Protocol}
(@dfn{@acronym{POP}}).  To use a @acronym{POP} mailbox as a spool file, you
need to use a @acronym{POP} 
maildrop specification (@ref{maildrop specification},
@ref{@acronym{POP} and @acronym{IMAP} Folders}).  Once this is done, VM will
retrieve new mail 
from the @acronym{POP} mailbox in the same way as it retrieves it from system
mailbox.  The retrieved messages can be automatically removed from the
@acronym{POP} mailbox or retained until a later expunge (compact) operation.

By default VM will retrieve all the messages from a @acronym{POP} mailbox
before returning control of Emacs to you.  If the mailbox is
large, the wait could be considerable.

@vindex vm-pop-bytes-per-session
@vindex vm-pop-messages-per-session
The variable @code{vm-pop-messages-per-session} controls how many messages
VM will retrieve from a @acronym{POP} mailbox before returning control to
you.  Similarly, the variable @code{vm-pop-bytes-per-session} limits the
number of bytes VM will retrieve from a @acronym{POP} mailbox before returning
control to you.  By default, the value of both variables is nil, which
tells VM to retrieve all the messages in the @acronym{POP} mailbox regardless
of how many messages there are and how large the mailbox is.

@vindex vm-pop-max-message-size
@findex vm-get-new-mail
@vindex vm-auto-get-new-mail
Another way to reduce the amount of wait is to control how the large messages
should be handled.  If you set @code{vm-pop-max-message-size} to a positive
numeric value, VM will not automatically retrieve messages larger than this
size.  If VM is retrieving messages because you invoked
@code{vm-get-new-mail} interactively, then VM will ask whether it should
retrieve the large message.  If VM is retrieving messages automatically
(e.g. @code{vm-auto-get-new-mail} is set non-@code{nil}) then VM will skip
the large messages and you can retrieve them later.

@cindex expunging, @acronym{POP} servers
@cindex compacting, @acronym{POP} servers
@findex vm-expunge-pop-messages
After VM retrieves messages from the mailbox, the default action is to
leave the original messages on the server unchanged.  They can be
expunged from the server by running @code{vm-expunge-pop-messages};
only those messages that VM has retrieved into the current folder will
be expunged.

@vindex vm-pop-expunge-after-retrieving
@vindex vm-pop-auto-expunge-alist
If you want VM to expunge the messages automatically after retrieving
them, you can set @code{vm-pop-expunge-after-retrieving} to @code{t}.
But a better method is to set the variable
@code{vm-pop-auto-expunge-alist}, which gives you a way to specify, on
a per-mailbox basis, which @acronym{POP} mailboxes should have messages
automatically 
removed after retrieving and which ones should leave the messages on the
@acronym{POP} 
server.  The value of @code{vm-pop-auto-expunge-alist} should be a
list of @acronym{POP} mailboxes and values specifying whether messages should
be automatically deleted from the mailbox after retrieval.  The format
of the list is:

@example
((@var{MAILDROP} . @var{VAL}) (@var{MAILDROP} . @var{VAL}) ...)
@end example

@var{MAILDROP} should be a @acronym{POP} maildrop specification as described
in the documentation for the variable @code{vm-spool-files}.  If
you have the @acronym{POP} password specified in the @code{vm-spool-files}
entry, you do not have to specify it here as well.  Use @samp{*}
instead; VM will still understand that this mailbox is the same as
the one in @code{vm-spool-files} that contains the password.

@var{VAL} should be @code{nil} if retrieved messages should be left in the
corresponding @acronym{POP} mailbox, @code{t} if retrieved messages should be
removed from the mailbox immediately after retrieval.

Here is an example:

@example
(setq vm-pop-auto-expunge-alist
   '(
     ("odin.croc.net:110:pass:kyle:*" . nil)  ;; leave message on the server
     ("hilo.harkie.org:110:pass:kyle:*" . t)  ;; expunge immediately
    )
)
@end example

@node @acronym{IMAP} Spool Files, Index Files, @acronym{POP} Spool Files, Local Folders
@unnumberedsubsec @acronym{IMAP} Spool Files
@cindex @acronym{IMAP} spool files
@cindex maildrop specification
VM can also use @dfn{@acronym{IMAP}} (@dfn{Internet Message Access Protocol}) to
retrieve mail from a mail server. 
As with @acronym{POP}, instead of specifying a local file name in the
@code{vm-spool-files} definition, you would give an @acronym{IMAP} maildrop
specification (@ref{maildrop specification}, @ref{@acronym{POP} and @acronym{IMAP} Folders}).
Once this is done, VM will retrieve new mail from the @acronym{IMAP} mailbox in
the same way as it retrieves it from system mailbox.  The retrieved
messages can be automatically removed from the @acronym{IMAP} mailbox or
retained until a later expunge operation.

By default VM will retrieve all the messages from an @acronym{IMAP} mailbox
before returning control of Emacs to you.  If the mailbox is
large, the wait could be considerable.

@vindex vm-imap-bytes-per-session
@vindex vm-imap-messages-per-session
The variable @code{vm-imap-messages-per-session} controls how many messages
VM will retrieve from an @acronym{IMAP} mailbox before returning control to
you.  Similarly, the variable @code{vm-imap-bytes-per-session} limits the
number of bytes VM will retrieve from an @acronym{IMAP} mailbox before returning
control to you.  By default, the value of both variables is nil, which
tells VM to retrieve all the messages in the @acronym{IMAP} mailbox regardless
of how many messages there are and how large the mailbox is.

@vindex vm-imap-max-message-size
@findex vm-get-new-mail
@vindex vm-auto-get-new-mail
Another way to reduce the amount of wait is to control how the large messages
should be handled.  If you set @code{vm-imap-max-message-size} to a positive
numeric value, VM will not automatically retrieve messages larger than this
size.  If VM is retrieving messages because you invoked
@code{vm-get-new-mail} interactively, then VM will ask whether it should
retrieve the large message.  If VM is retrieving messages automatically
(e.g. @code{vm-auto-get-new-mail} is set non-@code{nil}) then VM will skip
the large messages and you can retrieve them later.

@cindex expunging, @acronym{IMAP} messages
@cindex compacting, @acronym{IMAP} servers
@findex vm-expunge-imap-messages
After VM retrieves messages from the mailbox, the default action is to
leave the original messages on the server unchanged.  They can be
@dfn{expunged} from the server by running @code{vm-expunge-imap-messages};
only those messages that VM has retrieved into the current folder will
be expunged.

@vindex vm-imap-expunge-after-retrieving
@vindex vm-imap-auto-expunge-alist
If you want VM to expunge the messages automatically after retrieving them,
you can set @code{vm-imap-expunge-after-retrieving} to @code{t}.  But a
better method is to set the variable @code{vm-imap-auto-expunge-alist},
which gives you a way to specify, on a per-mailbox basis, which
@acronym{IMAP} mailboxes should have messages automatically removed after
retrieving and which ones should leave the messages on the @acronym{IMAP}
server.  The value of @code{vm-imap-auto-expunge-alist} should be a list of
@acronym{IMAP} mailboxes and values specifying whether messages should be
automatically deleted from the mailbox after retrieval.  The format of the
list is:

@example
((@var{MAILDROP} . @var{VAL}) (@var{MAILDROP} . @var{VAL}) ...)
@end example

@var{MAILDROP} should be an @acronym{IMAP} maildrop specification as described
in the documentation for the variable @code{vm-spool-files}.  If
you have the @acronym{IMAP} password specified in the @code{vm-spool-files}
entry, you do not have to specify it here as well.  Use @samp{*}
instead; VM will still understand that this mailbox is the same as
the one in @code{vm-spool-files} that contains the password.

@var{VAL} should be @code{nil} if retrieved messages should be left in the
corresponding @acronym{IMAP} mailbox, @code{t} if retrieved messages should be
removed from the mailbox immediately after retrieval.

Here is an example:

@example
(setq vm-imap-auto-expunge-alist
   '(
     ;; leave message on the server
     ("imap:odin.croc.net:143:inbox:login:kyle:*" . nil)
     ;; expunge immediately
     ("imap:hilo.harkie.org:143:inbox:login:kyle:*" . t)
    )
)
@end example

@unnumberedsubsubsec Multiple access to @acronym{IMAP} spool files

A principal idea behind the @acronym{IMAP} protocol is that messages can be
retained on the server so that you can read them from multiple
locations, e.g., from office and home, or from other places on the
Internet while you travel.  If you access your @acronym{IMAP} mailbox from
multiple locations then you would need to plan your strategy for
expunging messages carefully.  For instance, if you access your work
mailbox from home, and both your office machine and home machine
expunge messages after retrieving them, then some of your mail will
end up on your office machine and some on your home machine.  That is
unlikely to be a successful strategy.

The best way to access @acronym{IMAP} mailboxes from multiple locations is
to use the facility of @acronym{IMAP} folders.  (@xref{@acronym{POP} and
@acronym{IMAP} Folders}.)  However, if you prefer to download all mail to
local folders, then your best bet is to designate one of your machines as
the principal location for downloading mail and treat the other machines as
temporary mail reading sites.  In that case, you should set the principal
downloading location to expunge messages on the server and set the other
reading sites to leave the messages on the server intact.  You can also
manually run @code{vm-expunge-imap-messages} if you are careful to remember
which site should expunge messages and which site should retain them.

@cindex X-VM-@acronym{IMAP}-Retrieved header
VM remembers the messages you have downloaded from an @acronym{IMAP} spool
file so that it can avoid downloading them again on your next visit.  The
list of these messages is written into a special mail header titled
@code{X-VM-@acronym{IMAP}-Retrieved} in your mail folder.  When you expunge
@acronym{IMAP} messages, their entries are deleted from the list.  However,
when you designate one of your machines as a reading site and never expunge
messages from there, then the @code{X-VM-IMAP-Retrieved} header on
that machine will only grow over time.  When the list gets excessively long,
it will slow down the saving of folders.

@findex vm-prune-imap-retrieved-list
To avoid the problem, you should periodically run the command
@code{vm-prune-imap-retrieved-list}.  It will examine the @acronym{IMAP} server
to see which messages still exist and retain only their information in
the @code{X-VM-IMAP-Retrieved} header.


@node Index Files, Folder types,@acronym{IMAP} Spool Files, Local Folders
@unnumberedsubsec Index Files
@cindex index file

VM can create an @dfn{index} file, which describes the messages contained in
a folder.  If such an index file exists and is up to date, then VM
will read the contents of the index file first while starting up in
order to quickly form the summary of the folder.

@vindex vm-index-file-suffix
To use this feature, set the variable @code{vm-index-file-suffix} to a
file name extension, e.g., 

@example
(setq vm-index-file-suffix "idx")
@end example


@node Folder types,,Index Files, Local Folders
@unnumberedsubsec Folder types
@cindex folder types

@vindex vm-default-folder-type
VM can handle a variety of formats for mail folders, which differ in
details.  The variable @code{vm-default-folder-type} can be used to
set the default format that is suitable for your environment.  This
setting is used when VM creates new folders.

When VM reads a folder from the file system, it examines contents of the
folder to determine what format it is stored in and decodes it
appropriately.  (However, such inference is not fully automatic.  See
below.)

@findex vm-change-folder-type
After a folder is loaded into VM, you can convert it to a different
format using the command @code{vm-change-folder-type}.  It is a good
idea to keep all your mail folders in a single format in order to avoid
incompatibilities.

@cindex Unix
@cindex From_
The system default format on most flavors of Unix (except Solaris, AIX and
System V) is referred to as
@code{From_}.  It is the Unix mbox format described in RFC 4155.  In this
format, a leading separator line and a trailing separator line are added to
each message.  The leading separator line starts with the string ``From ''.
The trailing separator line is a blank line.  VM actually adds two blank
lines at the end for clarity.

@cindex BellFrom_
A variant of this format is referred to as @code{BellFrom_}.  It has a
leading separator line that starts with the string ``From ''.  However,
it does not have a trailing blank line.

Since VM cannot reliably infer whether a mail folder is of type
@code{From_} or @code{BellFrom_}, you must tell VM which one your system
uses by setting the variable @code{vm-default-From_-folder-type}.  Some
of the old folders created by VM prior to 2000 were in the
@code{BellFrom_} format.  If you will be using both @code{From_} and
@code{BellFrom_} style folders, it is not possible to choose an
appropriate setting for this variable.  It is recommended that you
convert all the old @code{BellFrom_} folders to the @code{From_} format using
the command @code{vm-change-folder-type}.

@cindex Solaris
@cindex System V
@cindex AIX
@cindex Content-Length
@vindex vm-trust-From_-with-Content-Length
@cindex From_-with-Content-Length
Solaris, System V and AIX operating systems use another variant of the
mbox format where the content-length is specified in the ``From '' line.
VM refers to this format as @code{From_-with-Content-Length}.  Since the
content lengths may be unreliable, you must also set the variable
@code{vm-trust-From_-with-Content-Length} to a non-Nil value in order to
convince VM that you really want to use this format.

@cindex MMDF
@cindex Babyl
@cindex Rmail
Two additional formats are @code{mmdf} used by @acronym{MMDF} systems and
@code{babyl} used by the Emacs Rmail mode.  These formats are recognized
automatically when read from the file system.


@node @acronym{POP} and @acronym{IMAP} Folders, Thunderbird Folders, Local Folders, Starting Up
@section @acronym{POP} and @acronym{IMAP} Folders

@cindex primary inbox
@cindex maildrop specification
@vindex vm-primary-inbox
VM supports accessing remote mailboxes on mail servers via the Post
Office Protocol (@acronym{POP}) and the Internet Message Access Protocol (@acronym{IMAP}).
Instead of a local file name, you can set the @code{vm-primary-inbox} to
a string that tells VM how to access a server mailbox. Called a
@dfn{maildrop specification}, the string is of one of the
following formats:

@example
``pop:@var{HOST}:@var{PORT}:@var{AUTH}:@var{USER}:@var{PASSWORD}''
``imap:@var{HOST}:@var{PORT}:@var{MAILBOX}:@var{AUTH}:@var{USER}:@var{PASSWORD}''
@end example

@noindent Remote mailboxes accessed by VM in this fashion are referred
to as @dfn{server folders} (and @dfn{@acronym{POP} folders} or @dfn{@acronym{IMAP}
folders}, more specifically).

@cindex cache folders
VM retrieves mail from the server folders into internal Emacs buffers
for its normal operation.  It also saves copies of the folders on the
local file system for speed of operation.  These are referred to as
@dfn{cache folders}.  However, the @emph{only}
permanent copies of the folders are on the mail server.  This should
be contrasted with using server mailboxes as spool files (@pxref{@acronym{POP}
Spool Files} and @pxref{@acronym{IMAP} Spool Files}), where the permanent
folders are on the @emph{local} file system and only the incoming mail
is held on the servers.

Server folders have the advantage that they can be transparently
accessed from multiple locations on the internet.  However, you must
ensure that you have access to enough storage on the mail server to
store all your email.

@anchor{maildrop specification}
@unnumberedsubsec Maildrop specification
The format of a @acronym{POP} or @acronym{IMAP} maildrop specification is as
follows:

@example
``pop:@var{HOST}:@var{PORT}:@var{AUTH}:@var{USER}:@var{PASSWORD}''
``imap:@var{HOST}:@var{PORT}:@var{MAILBOX}:@var{AUTH}:@var{USER}:@var{PASSWORD}''
@end example

@noindent Replace @samp{pop} in the example with @samp{pop-ssl} to
have VM speak @acronym{POP} over an @acronym{SSL} connection.  Use
@samp{pop-ssh} to use @acronym{POP} over an SSH connection.  Similarly,
replace @samp{imap} with @samp{imap-ssl} or @samp{imap-ssh}, as needed.

@cindex @acronym{SSL}
@cindex @acronym{TLS}        
@dfn{@acronym{SSL}} refers to a protocol called @dfn{secure sockets layer},
which allows you to securely communicate with a mail server using encryption
technology.  A newer version of the same protocol is called
@dfn{@acronym{TLS}} (@dfn{transport layer security}).  We refer to both of
them as ``@acronym{SSL}'' in this manual.

@cindex stunnel
@vindex vm-stunnel-program
@vindex vm-stunnel-program-additional-configuration-file
For @acronym{SSL}, you must either be using a version of Emacs that has
@acronym{SSL} capability or have the @command{stunnel} program installed and
the variable @code{vm-stunnel-program} naming it.  The default value of this
variable, @samp{"stunnel"}, which will work if an @samp{stunnel} program is
installed in your normal command search path.  In order to use the built-in
@acronym{SSL} capability of your Emacs, set
@code{vm-stunnel-program} to @code{nil}.  Depending on the version of
@samp{stunnel} program you are using, you may need to define a configuration
file for @samp{stunnel}.  If you need it, you should set the variable
@code{vm-stunnel-program-additional-configuration-file} to the location of
the configuration file.  (Consult the doc string of the variable and the
manual of the @samp{stunnel} program 
to find out what to put in the configuration file.)

@cindex SSH
@vindex vm-ssh-program
@vindex vm-ssh-remote-command
For SSH, you must have the @command{ssh} program installed and the variable
@code{vm-ssh-program} must name it in order for @acronym{POP}/@acronym{IMAP}
over SSH to work.  When VM makes the SSH connection it must run a command on
the remote server so that the SSH session is maintained long enough for the
@acronym{POP}/@acronym{IMAP} connection to be established.  By default that
command is @samp{"echo ready; sleep 10"}, but you can specify another
command by setting @code{vm-ssh-remote-command}.  Whatever command you use
must produce some output and hold the connection open long enough for VM to
establish a port-forwarded connection to the mail server.  (SSH must be able
to authenticate without a password, which means you must be using .shosts
authentication or RSA.)

@var{HOST} is the host name of the mail server.  

@cindex port, TCP
@var{PORT} is the TCP port number to connect to.  The normal port
numbers are:
@multitable @columnfractions 0.20 0.80
@item 110 @tab for @acronym{POP}
@item 995 @tab for @acronym{POP} over @acronym{SSL}
@item 143 @tab for @acronym{IMAP}
@item 993 @tab for @acronym{IMAP} over @acronym{SSL}
@end multitable

@var{MAILBOX} is the name of the mailbox on the @acronym{IMAP} server.  This
should be @samp{"inbox"}, to access your default @acronym{IMAP} mailbox on
the server.  No @var{MAILBOX} component is needed for @acronym{POP}
maildrops because @acronym{POP} does not support multiple mailboxes.

@vindex vm-pop-md5-program
@var{AUTH} is the authentication method used to convince the
server you should have access to the mailbox.  Acceptable
values for @acronym{POP} are @samp{pass}, @samp{rpop} and @samp{apop}.  For
@samp{pass}, the @var{PASSWORD} is sent to the server with
the @acronym{POP} PASS command.  For @samp{rpop}, the @var{PASSWORD}
should be the string to be sent to the server via the @acronym{RPOP}
command.  In this case the string is not really a secret;
authentication is done by other means.  For @samp{apop}, an
MD5 digest of the @var{PASSWORD} appended to the server
time-stamp will be sent to the server with the @acronym{APOP} command.
If Emacs does not have built in MD5 support, you will have
to set the value of @code{vm-pop-md5-program} appropriately
to point at the program that will generate the MD5 digest
that VM needs.

@cindex CRAM-MD5
@vindex vm-imap-session-preauth-hook
Acceptable values of @var{AUTH} for @acronym{IMAP}
are @samp{"preauth"}, @samp{"cram-md5"}, and @samp{"login"}.
@samp{"preauth"} causes VM to skip the authentication stage of
the protocol with the assumption that the session was
authenticated in some way external to VM.  The hook
@code{vm-imap-session-preauth-hook} is run, and it is expected to
return a process connected to an authenticated @acronym{IMAP} session.
@samp{"cram-md5} tells VM to use the CRAM-MD5 authentication
method as specified in RFC 2195.  The advantage of this method
over the @samp{"login"} method is that it avoids sending your
password over the net unencrypted.  Not all @acronym{IMAP} servers support
@samp{"cram-md5"}; if you're not sure, ask your mail
administrator or just try it.  The other value, @samp{"login"},
tells VM to use the @acronym{IMAP} LOGIN command for authentication, which
sends your user name and password in clear text to the server.

@var{USER} is the user name used in authentication methods that
require such an identifier.  @samp{"login"} and @samp{"cram-md5"}
use it currently.

@var{PASSWORD} is the
secret shared by you and the server for authentication purposes.  How
it is used depends on the value of the @var{AUTH} parameter.  If the
@var{PASSWORD} is @samp{*}, VM will prompt you for the password the
first time you try to retrieve mail from the mailbox.  If the password
is valid, VM will not ask you for the password again during this Emacs
session.

@cindex EasyPG
@cindex epa-file library
@cindex auth-source library
@cindex authinfo
@cindex passwords, storing
If your environment has the @dfn{EasyPG} utility and your version of Emacs
supports it, i.e., has the @samp{epa-file} and @samp{auth-source} libraries,
then you can store password information in a file such as
@file{.authinfo.gpg}.  The @samp{EasyPG} protocol allows you to store
this information in an encrypted form so that it cannot be read by third
parties.  Each line in the @file{.authinfo.gpg} file should be of the
form

@example
machine HOST login USER password PASSWORD port PORT
@end example

@noindent where HOST, USER, PASSWORD and PORT are as detailed above.
Ensure that the variable @code{auth-sources} is customized to refer to
your authinfo file.  
@xref{Help for users,, Help for users, auth , Emacs auth-source}.
Then VM will read passwords from the file and you
don't need to type them in when accessing mail servers.

If you have multiple login accounts on the same HOST then VM will only
use the first login listed in the authinfo file.  To allow for multiple
login's, the HOST entry in the authinfo line can be replaced by an
account name as defined internally in VM.  These account names are
defined via the variables @code{vm-pop-folder-alist} and
@code{vm-imap-account-alist}, described below.

@anchor{troubleshooting mail servers}
@unnumberedsubsec Troubleshooting mail servers

Since a number of components have to be brought together to establish
connections to mail servers, it is not uncommon for problems to arise.

@cindex stunnel
To find out what could be going wrong, you can look at the Emacs buffer that
store a trace of the session with mail server.  Such buffers have names
beginning with ``trace of @acronym{POP} session'' or ``trace of
@acronym{IMAP} session''.  There could be multiple buffers of this kind for
different servers and multiple sessions.  In the trace buffer, you will find
the commands that VM sent to the server and the responses it has received.
Typical problems are protocol mismatches between VM and the mail server, or
malfunctions in other components such as the @code{stunnel} program.

@vindex vm-pop-keep-trace-buffer
@vindex vm-imap-keep-trace-buffer
The variables @code{vm-pop-keep-trace-buffer} and
@code{vm-imap-keep-trace-buffer} specify how many trace buffers to keep for
such server sessions.  The default is 1.  Setting these variables to nil
will have the effect that no trace buffers are kept.

@menu
* @acronym{POP} Folders::         How to use mailboxes on @acronym{POP} servers
* @acronym{IMAP} Folders::        How to use mail folders on @acronym{IMAP} servers
@end menu

@node @acronym{POP} Folders, @acronym{IMAP} Folders, @acronym{POP} and @acronym{IMAP} Folders, @acronym{POP} and @acronym{IMAP} Folders
@unnumberedsubsec @acronym{POP} Folders
@cindex @acronym{POP}
@cindex message attributes


@findex vm-visit-pop-folder
@findex vm-save-folder
@vindex vm-folder-directory
@vindex vm-pop-folder-cache-directory
The command @code{vm-visit-pop-folder} allows you to visit a @acronym{POP}
mailbox as a folder.  When you visit a @acronym{POP} folder, VM will download
copies of the messages that it finds there for you to read.  These
messages are saved locally in cache folders, in the directory
specified by @code{vm-pop-folder-cache-directory} (or
@code{vm-folder-directory} if the former is not defined).
@vindex vm-pop-folder-cache-directory
If you delete and expunge messages in the folder, the
corresponding messages on the @acronym{POP} server will be removed when you
save the changes with @code{vm-save-folder}.

@dfn{Message attributes} (new, replied, filed, etc.) and labels cannot be
stored on the @acronym{POP} server but they will be maintained in the cache
folder.  This means that if you access the same @acronym{POP} mailbox from
multiple locations on the internet, you will see different attributes at
different locations.  To be able to store message attributes and labels on
the server, you should use @acronym{IMAP} folders (@ref{@acronym{IMAP}
Folders}) resident on an @acronym{IMAP} server.

@vindex vm-pop-folder-alist
In order for VM to know about @acronym{POP} folders that you can access, you
must declare them by setting the variable @code{vm-pop-folder-alist}.
The variable's value should be an associative list of the form:

@example
 ((@var{POPDROP} @var{NAME}) ...)
@end example

@var{POPDROP} is a @acronym{POP} maildrop specification (@ref{maildrop
specification}).

@var{NAME} is a string that should give a less cumbersome name that you
will use to refer to this maildrop when using @code{vm-visit-pop-folder}.

For example:

@example
(setq vm-pop-folder-alist
      '(
         ("pop:pop.mail.yahoo.com:110:pass:someuser:*" "Yahoo! mail")
         ("pop:localhost:110:pass:someuser:*" "local mail")
       )
)
@end example

@samp{Yahoo! mail} and @samp{local mail} are what you would type
when @code{vm-visit-pop-folder} asks for a folder name.  There is no
need to specify the password for @acronym{POP} accounts in this definition.

@node @acronym{IMAP} Folders,, @acronym{POP} Folders, @acronym{POP} and @acronym{IMAP} Folders
@unnumberedsubsec @acronym{IMAP} Folders
@cindex @acronym{IMAP}
@cindex message attributes 
@cindex message labels

@findex vm-visit-imap-folder
The command @code{vm-visit-imap-folder} allows you to visit an
@acronym{IMAP} mailbox as a folder.  The name of the @acronym{IMAP} mailbox
should be input via the minibuffer in the format account-name:folder-name.
Here, ``account-name'' is the name of an @acronym{IMAP} account declared in
@code{vm-imap-account-alist} and ``folder-name'' is the name of an
@acronym{IMAP} mailbox in this account.

@findex vm-save-folder
@vindex vm-folder-directory
@vindex vm-imap-folder-cache-directory
When you visit an @acronym{IMAP} folder, VM will
download copies of the messages that it finds there for you to read.
These messages are saved locally in a cache folder on the disk, in the 
directory specified by @code{vm-imap-folder-cache-directory} (or
@code{vm-folder-directory} if the former is not defined).
@vindex vm-imap-folder-cache-directory
If you delete and expunge messages, these changes are made to both the
cache folder and the folder on the @acronym{IMAP} server when saved
with @code{vm-save-folder}.

Message attributes (new, replied, filed, etc.) are stored on the @acronym{IMAP}
server and are also cached locally.  Message labels are also stored on
the @acronym{IMAP} server as user-defined permanent flags.  (This assumes that
the @acronym{IMAP} server has the ability to store user-defined permanent
flags.)

@vindex vm-imap-account-alist
In order for VM to know about @acronym{IMAP} accounts that you can access, you
must declare them by setting the variable @code{vm-imap-account-alist}.
The variable's value should be an associative list of the form:

@example
 ((@var{IMAPDROP} @var{NAME}) ...)
@end example

@var{IMAPDROP} is an @acronym{IMAP} maildrop specification (@ref{maildrop
specification}).  

@var{NAME} is a string that should give a less cumbersome name that you
will use to refer to this maildrop when using @code{vm-visit-imap-folder}.
For example:

@example
(setq vm-imap-account-alist
      '(
        ("imap-ssl:mail.foocorp.com:993:*:login:becky:*" "becky")
        ("imap:crickle.lex.ky.us:143:*:login:becky:*" "crickle")
       )
)
@end example

@noindent The mailbox and password fields (@samp{*} in the example) are
ignored.  When @code{vm-visit-imap-folder} asks for a folder name, you
enter an account name followed by ``:'' and a folder name.  Any folder
that is accessible to you on the @acronym{IMAP} server can be specified.  For
example, @code{becky:inbox} or @code{crickle:drafts}.

@vindex vm-imap-refer-to-inbox-by-account-name
When you visit an @acronym{IMAP} folder inside VM, the folder is referred to
by its folder name as it exists on the server.  For example, visiting
@code{becky:INBOX} creates a folder called @code{INBOX} inside VM.  If you
visit multiple @acronym{IMAP} accounts within a VM session, then you would
end up with multiple folder buffers all named @code{INBOX}.  To avoid this
problem, you can set the variable
@code{vm-imap-refer-to-inbox-by-account-name} to t, which causes the
@code{INBOX} folder buffers to be named by their @acronym{IMAP} account
names instead.  For example, visiting @code{becky:INBOX} would create a VM
folder named @code{becky} and visiting @code{crickle:INBOX} would create a
VM folder named @code{crickle}.

@vindex vm-imap-server-list
The customization variable @code{vm-imap-server-list}, used in older
versions of VM, is deprecated.  Please use @code{vm-imap-account-alist}
instead.

@anchor{@acronym{IMAP} Synchronization}
@unnumberedsubsec @acronym{IMAP} Synchronization
@vindex vm-get-new-mail
The cache folder and the folder on the @acronym{IMAP} server are partially
synchronized every time @code{vm-get-new-mail} is invoked.  This involves
(i) writing the changed attributes and labels to the server, (ii) updating
the attributes and labels in the cache folder based on the server data,
(iii) expunging messages in the cache folder that have been expunged on the
server, and finally, (iv) retrieving any new messages on the server.
@vindex vm-imap-sync-on-get
The variable @code{vm-imap-sync-on-get} specifies whether
such synchronization should be done as part of @code{vm-get-new-mail}.
If the variable is set to nil then @code{vm-get-new-mail} simply
retrieves any new messages.

@findex vm-save-folder
The cache folder and the folder on the @acronym{IMAP} server are also
synchronized every time @code{vm-save-folder} is invoked.  This involves (i)
writing the changed attributes and labels to the server, (ii) updating the
attributes and labels in the cache folder based on the server data, (iii)
expunging messages in the cache folder that have been expunged on the
server, (iv) deleting and expunging the locally expunged messages on the
server folder, and finally, (v) saving a copy of the folder on the file
system.

@findex vm-imap-synchronize
The command @code{vm-imap-synchronize} can always be used to perform
full synchronization with the server.




@node Thunderbird Folders, External Messages, @acronym{POP} and @acronym{IMAP} Folders, Starting Up
@section Thunderbird Folders

@cindex Thunderbird
VM can work with local folders managed by Mozilla Thunderbird.  You can find
the location of Thunderbird's folders by examining the Account Settings for
``Local Folders'' inside Thunderbird.  You can visit any of the folders in
that directory using VM and make changes.  Such changes will be propagated
to Thunderbird in an appropriate way.

@findex vm-visit-thunderbird-folder
@vindex vm-thunderbird-folder-directory
Alternatively, you can set the variable
@code{vm-thunderbird-folder-directory} to the directory where Thunderbird
stores its folders, and use the command @code{M-x
vm-visit-thunderbird-folder} to visit its folders.  This works the same way
as @code{vm-visit-folder} except that the default directory for visiting
folders as well as saving messages will be the value of
@code{vm-thunderbird-folder-directory}.  On the other hand, the folders
visited using @code{vm-visit-folder} will continue to be in
@code{vm-folder-directory}, allowing you to manage the two spaces
separately.

If, on the other hand, you want to maintain a single space where VM
and Thunderbird can jointly operate, then you should set the variable
@code{vm-folder-directory} to that place and leave
@code{vm-thunderbird-folder-directory} with its default value of
@code{nil}.

@unnumberedsubsec Differences in folder summary
Most current versions of Thunderbird hide deleted messages from the summary
window.  However, the deleted messages are still present in the folder.
They are expunged from the folder only when you do some bulk operation such
as ``purge'' or ``compact''.  Since the deleted messages are still present
in the folder, when you visit the folder in VM, the deleted messages will
appear in the VM summary buffer.  This is normal.

If you want VM's summary buffer to appear similar to Thunderbird's, you can
use the @command{vm-summary-faces-hide} command.  @xref{Hiding summary
lines}. 


@unnumberedsubsec How the inter-operation works
Thunderbird stores the folders in the @samp{From_} folder type.
@xref{Folder types}.  Within such folders, Thunderbird stores the
message status flags (message attributes such as whether a message is
read, replied to, deleted etc.) under special header fields called
@code{X-Mozilla-Status} and @code{X-Mozilla-Status2}.  In addition to
these headers, Thunderbird also stores a quick copy of the message
status flags in a separate file with the extension @code{.msf}.

When you visit a Thunderbird folder, VM reads the status flags stored in
the special headers and uses them for processing.  As you make changes
to the folder by reading messages, replying to them or deleting them,
the changes are propagated to the Thunderbird status flags and written
to the disk when saved.  VM also deletes the @code{.msf} file maintained
by Thunderbird so that Thunderbird will recompute the status information
from the headers.  Thus, the changes made to the Thunderbird folders
will be visible inside Thunderbird.

@vindex vm-sync-thunderbird-status
The variable @code{vm-sync-thunderbird-status} controls how VM deals
with Thunderbird folders.  The default value @code{t} gives the behavior
described above.  You can also set it to @code{'read-only}, in which
case VM reads the Thunderbird status flags, but makes no changes to
them.  So, the changes made to the folders will be lost after you quit
VM.  If you set it to @code{nil}, then VM refrains from reading and
writing the Thunderbird status flags.  In this case, the changes made to
the folders are visible inside VM even after revisiting, but they will have
no effect for Thunderbird.  

WARNING: Keep in mind that all this applies to changes to message attributes
only.  If you @i{expunge} (@i{compact}) a folder, then the deleted messages
are physically purged from the folder.  They will be lost both inside VM as
well as Thunderbird.

The variable @code{vm-sync-thunderbird-status} is a buffer-local
variable.  You may set its default value in your @code{.vm} file.  To
change it in a running Emacs session, you must use @code{setq-default}.
@xref{Locals,, Local Variables, emacs, Gnu Emacs manual}.


@node External Messages, Getting New Mail, Thunderbird Folders, Starting Up
@section External Messages

Under certain circumstances, it is possible to maintain VM folders in which
only the headers of messages are loaded into the Folder buffer.  The message
bodies are retained in external sources (file system or remote servers) and
fetched on demand when the messages are viewed or other operations are
performed on them.  Using external messages results in a smaller folder size
and allows a faster operation on machines with limited resources.  However,
the fetching of message bodies on demand can introduce short delays when
messages are viewed.  It is also not possible to search in the message
bodies of external messages.

@vindex vm-enable-external-messages
To enable external messages, set the variable
@code{vm-enable-external-messages} to a list of contexts in which external
messages may be maintained by VM.

@vindex vm-imap-max-message-size
As of version 8.2.0, the only context in which external messages are
implemented is that of @acronym{IMAP} folders.  Setting
@code{vm-enable-external-messages} to @code{(imap)} enables @acronym{IMAP}
messages to be maintained externally.  When new messages are retrieved, this
causes all messages with size below @code{vm-imap-max-message-size} to be
loaded immediately, and larger messages will be left on the server to be
fetched on demand.  To treat all messages as external messages, you can set
@code{vm-imap-max-message-size} to 0.

@vindex vm-external-fetch-message-for-presentation
Normally, the messages that are not present in the folder are fetched
automatically when an attempt is made to view them.  You can disable this by
setting the variable @code{vm-external-fetch-message-for-presentation} to
@code{nil}.  In that case, the messages are displayed with an empty message
body.  You can load the missing message body using the @kbd{o} command
described below.

@vindex vm-fetched-message-limit
After fetching the bodies of external messages, VM stores them in the Folder
buffer temporarily, so that repeated fetching is avoided.  The variable
@code{vm-external-fetched-message-limit} controls how many message bodies are stored
in this way.  You can set it to an integer (10 is the default), or to
@code{nil}, signifying that there is no limit.  All the fetched message
bodies are removed from the folders before they are saved to disk.

@findex vm-load-message
@findex vm-unload-message
@findex vm-refresh-message
@kindex o
@kindex O
You can manually load message bodies into the Folder using the command
@kbd{o} (@code{vm-load-message}).  The command @kbd{O}
(@code{vm-unload-message}) unloads a previously loaded message body.  Both
the commands can take numerical prefix arguments or operate on marked
messages.  Note that ``loading'' a message body is different from on-demand
``fetching''.  Loaded messages are permanently stored in the Folder buffer
and written to disk when the folder is saved.  In contrast, fetched message
bodies are always discarded before writing to disk.  The command
@code{vm-refresh-message} reloads an already loaded message with a fresh
copy retrieved from the server.

@node Getting New Mail, Crash Recovery, External Messages, Starting Up
@section Getting New Mail

@findex vm-get-new-mail
@kindex g
Pressing @kbd{g} runs @code{vm-get-new-mail}, which will retrieve mail from
all the spool files associated with the current folder.  @xref{Local
Folders}.  For @acronym{POP} and @acronym{IMAP} folders, any newly arrived
messages at the mail server will be incorporated into the local copy of the
folders.

@vindex vm-auto-get-new-mail
If the value of the variable @code{vm-auto-get-new-mail} is non-@code{nil} VM
will retrieve mail for a folder whenever the folder is visited.  If the
value is a positive integer @var{n}, VM will also check for new mail
every @var{n} seconds for all folders currently being visited.  If new
mail is present, VM will retrieve it.

@vindex vm-mail-check-interval
@vindex vm-mail-check-always
If the value of the variable @code{vm-mail-check-interval} is a
positive integer @var{n}, VM will check for new mail every @var{n}
seconds, but instead of retrieving mail, the word ``Mail'' will appear
on the Emacs mode line of folders that have mail waiting.  Normally,
once VM finds new mail, it will turn on the ``Mail'' indicator and
refrain from checking again until you retrieve the new mail.  However,
if multiple mail clients are trying to retrieve mail from the same
spool, it is possible that the new mail might get retrieved into
another mail client and your ``Mail'' indicator won't reflect the
situation.  If you need to be particular about new mail in such a
situation, then you should set the variable
@code{vm-mail-check-always}. 

@node Crash Recovery,, Getting New Mail, Starting Up
@section Crash Recovery
@cindex crash recovery
@cindex message attributes
@cindex message labels
@cindex auto-save

When Emacs crashes, its last action before dying is to try to
write out an @dfn{auto-save} file that contains changes to files that
you were editing.  VM folders are file buffers inside Emacs, so
folders are auto-saved also.  For VM folders, @dfn{changes}
means attribute changes, label additions and deletions, message
edits, and expunges.  VM keeps track of whether a message is new
or old, whether it has been replied to, whether it is flagged
for deletion and so on, by writing special headers into the
folder buffer.  These headers are saved to disk when you save
the folder.  If Emacs crashes before the folder has been saved,
VM may forget some attribute changes unless they were written to
the auto-save file.

Note that when VM retrieves mail from spool files it @emph{always}
writes them to disk immediately and at least one copy of the message is
on disk at all times.  So while you can lose attribute changes from
crashes, you should not lose messages unless the disk itself is
compromised.

@unnumberedsubsec Recovering Folders

When you visit a folder, VM checks for the existence of an
auto-save file that has been modified more recently than the
folder file.  If such an auto-save file exists, there is a good
chance that Emacs or your operating system crashed while VM
was visiting a folder.  VM will then write a message to the echo
area informing you of the existence of the auto-save file and
visit the folder in @emph{read-only} mode.  Visiting the folder in
read-only mode prevents you from modifying the folder, which
in turn prevents Emacs from wanting to write new changes to
the auto-save file.  VM will not retrieve new mail for a folder
that is in read-only mode.  VM also skips summary
generation and @acronym{MIME} decoding to help catch your attention.

@findex vm-recover-folder
@findex recover-file
If you want to recover the lost changes, run @kbd{M-x
vm-recover-folder} or use the Recover Folder entry in Folder menu.  At
the @samp{Recover File:} prompt press @key{RET}.  Emacs's built-in
@kbd{recover-file} command is @emph{not recommended} for this purpose because
VM is unable to obtain reliable data regarding mail folders from
Emacs.

In response to @code{vm-recover-folder}, Emacs will display a detailed
directory listing showing the folder file and the auto-save file and ask you
whether you want to recover from the auto-save file.  A good rule of thumb is
to answer ``yes'' if the auto-save file is larger than the folder file.  If
the auto-save file is significantly smaller, Emacs might not have completed
writing the auto-save file during the previous crash.  Or it could be that
the smaller auto-save file reflects the results of an expunge that you had
not yet committed to disk before the crash.  If so, answering ``no'' means
you might have to do that expunge again, but this is better than not knowing
whether the auto-save file was truncated.

Assuming you answered ``yes'', the folder buffer's contents will be
replaced by the contents of the auto-save file and VM will re-parse the
folder.  At this point the contents of the folder buffer and the disk
copy of the folder are different.  Therefore VM will not get new mail
for this folder until the two copies of the folder are synchronized.
When you are satisfied that the recovered folder is whole and intact,
type @kbd{S} to save it to disk.  After you do this, VM will allow you
to use @kbd{g} to retrieve any new mail that has arrived in the spool
files for the folder.

Assuming you answered ``no'' to the recovery question, you should type
@kbd{C-x C-q}, which is bound to @code{vm-toggle-read-only} in VM folder
buffers.  The folder will be taken out of read-only mode and you can
read and retrieve your mail normally, ignoring the auto-save file that is
still on disk.

If you are visiting a @acronym{POP} or @acronym{IMAP} folder (rather than a
local folder) that was modified during a previous crash, the process of
recovery is similar.  However, there will be less useful information in the
auto-save file in this case.  When you synchronize an @acronym{IMAP} folder
with the server, only the changes made during the current VM session are
saved to the server.  Changes stored in the auto-save file were made in a
previous session of VM and, so, cannot be saved to the server.  So, saying
``no'' to the recovery question and toggling the read-only status (@kbd{C-x
C-q}) is a better option in the case of server folders.

@unnumberedsubsec Recovering Message Compositions

@vindex vm-mail-auto-save-directory
@findex vm-postpone-message
Any messages you were in the midst of composing when Emacs crashed, would
also have auto-save files in the disk.  They would be saved in the
@code{vm-mail-auto-save-directory}, if you have set that variable, or
@code{vm-folder-directory}, or the directory that was current when you
started composing the message.  You can visit the auto-save file, which
would get loaded as a text file by default, and then run @kbd{M-x
mail-mode}.  VM's mail-mode command keys are not available in this mode.
The best option is to run @kbd{M-x vm-postpone-message} to save the
unfinished message composition and then continue it using
@code{vm-continue-postponed-message}.  @xref{Postponing Messages}.

@unnumberedsubsec Recovering Sessions

Emacs also provides a way to recover the entire Emacs session after a crash.
@xref{Recover,,, emacs, the GNU Emacs Manual}.  However, the Emacs
@code{recover-session} command will recover VM folders as if they were
ordinary files.  As mentioned above, this is not a good method of recovering
VM folders.  You should use @code{vm-recover-folder} command instead.  So,
when Emacs @code{recover-session} command asks you whether to recover a VM
folder, the best option is to answer ``no''.  Then you should recover the
folders separately, using the @code{vm-recover-folder} command.

If you do answer ``yes'', then Emacs loads the auto-save file into a buffer.
The auto-save file still exists on the disk, but it will get deleted when
you save the buffer.  So, you should examine the folder before you save it.
Run @kbd{M-x vm-mode} in the buffer corresponding to the VM folder, make
sure that it is not damaged, and then save the folder.  If you do not
believe that the auto-saved version is good, you can kill the buffer.  At
this point, VM asks you for confirmation whether you really want to kill the
buffer and, secondly, whether you want to delete the auto-save file.  If you
answer ``yes'' to the last question, then the auto-saved folder will be
gone for ever.



@unnumberedsubsec Reverting a Folder

@findex vm-revert-folder
@findex revert-file
If you have made changes to a mail folder which you would like to
cancel and go back to the version currently on the disk, you can use
the function @kbd{vm-revert-folder} or the ``Revert Folder'' entry in the
Folder menu.  (Emacs's built-in @kbd{revert-file} is not recommended.)

@node Navigating, Reading Messages, Starting Up, Top
@chapter Navigating

@findex vm-next-message
@findex vm-previous-message
@kindex n
@kindex p
@vindex vm-skip-deleted-messages
@vindex vm-skip-read-messages
In order to read, delete, or do anything to a message, you need to
select it.  In other words, make the message the @dfn{current message}.

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.  By default, these commands
skip messages flagged 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.

@cindex prefix argument
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
skip variables.

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

A value of @code{t} causes all VM commands to consider folders circular.
A value of @code{nil} causes all 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 as 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 @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{nil}.

@vindex vm-follow-summary-cursor
You can also select messages by using the summary window.
@xref{Summaries}.  Move the cursor to the summary line for the message
you want to select and press @key{RET}.  VM will select this message.
Instead of pressing @key{RET} you could run some other VM command that
operates based on the notion of a `current message'.  VM will select the
message under the cursor in the summary window before executing such
commands.  Example, if you type @kbd{d}, VM will select the message
under the cursor and then delete it.  Note that this occurs @emph{only}
when you execute a command when the cursor is in the summary buffer
window and only if the variable @code{vm-follow-summary-cursor} is
non-@code{nil}.

@vindex vm-jump-to-unread-messages
@vindex vm-jump-to-new-messages
When a folder is visited or when you type @kbd{g} and VM retrieves some
mail, the default action is to move to the first new or unread message
in the folder.  New messages are favored over old but unread messages.
If you set @code{vm-jump-to-new-messages} to @code{nil}, VM will favor old,
unread messages over new messages if the old, unread message appears
earlier in the folder.  If you set @code{vm-jump-to-unread-messages} to
@code{nil} also, VM will not search for new or unread messages.

@cindex searching
Other commands to select messages:

@table @kbd
@findex vm-goto-message
@kindex RET
@item @key{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-last-seen
@kindex TAB
@item TAB (@code{vm-goto-message-last-seen})
Go to message last previewed or read.
@findex vm-next-message-no-skip
@findex vm-previous-message-no-skip
@kindex N
@kindex P
@item N (@code{vm-next-message-no-skip})
@itemx P (@code{vm-previous-message-no-skip})
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.
@findex vm-isearch-forward
@findex vm-isearch-backward
@kindex M-s
@comment @kindex M-r
@vindex vm-search-using-regexps
@item M-s (@code{vm-isearch-forward})
@item M-x vm-isearch-backward
These work just like Emacs' normal forward and backward incremental
search commands, 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.  If a prefix argument is given,
the value of @code{vm-search-using-regexps} is temporarily reversed for
the search.
@xref{Incremental Search,,,emacs, the GNU Emacs Manual}.
@end table

@node Reading Messages, Sending Messages, Navigating, Top
@chapter Reading Messages

Once a message has been selected, VM will show it to you.  By default,
presentation is done in two stages: @dfn{previewing} and @dfn{paging}.

@menu
* Previewing::                  Customizing message previews.
* Paging::                      Viewing the current message.
* @acronym{MIME} Messages::     Using VM's @acronym{MIME} display features.
@end menu

@node Previewing, Paging, Reading Messages, Reading Messages
@section Previewing

@dfn{Previewing} means 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, and from there you can
repeatedly type @key{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 three variables:
@code{vm-visible-headers}, @code{vm-invisible-header-regexp} and
@code{vm-preview-lines}.

@vindex vm-preview-lines
If the value of @code{vm-preview-lines} is a number, it 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 flagged as read.  If
@code{vm-preview-lines} is @code{t}, the message body is displayed fully
but the message is not flagged as read until you type @key{SPC}.

@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 presentation order of the headers they match.

@vindex vm-invisible-header-regexp
If non-@code{nil}, the variable @code{vm-invisible-header-regexp}
specifies what headers should @emph{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-@code{nil} implies that
you want to see all headers not matched by it; therefore the value of
@code{vm-visible-headers} is only used to determine the order of the
visible headers in this case.  Headers not matched by
@code{vm-invisible-header-regexp} or @code{vm-visible-headers} are
displayed last.

If you change the value of either @code{vm-visible-headers} or
@code{vm-invisible-header-regexp} in the middle of a VM session the
effects will not be immediate.  You will need to use the command
@code{vm-discard-cached-data} on each message (bound to @kbd{j} by
default) to force VM to rearrange the message headers.  A good way to do
this is to mark all the messages in the folder and apply
@code{vm-discard-cached-data} to the marked messages.
@xref{Selecting Messages}.

@vindex vm-highlighted-header-regexp
@vindex vm-highlighted-header-face
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.  Highlighted headers will be displayed using the face
specified by @code{vm-highlighted-header-face}, which defaults to
'bold.

@vindex vm-preview-read-messages
By default, VM will not preview messages that are flagged as read.  To
have VM preview all messages, set the value of
@code{vm-preview-read-messages} to @code{t}.

@findex vm-expose-hidden-headers
@kindex t
Typing @kbd{t} (@code{vm-expose-hidden-headers}) makes VM toggle
between exposing and hiding headers that would ordinarily be hidden.

@node Paging, @acronym{MIME} Messages, Previewing, Reading Messages
@section Paging

@kindex SPC
@kindex DEL
@vindex vm-auto-next-message
Typing @key{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 @key{SPC} to scroll
forward, and @key{DEL} to scroll backward a windowful of
text at a time.  A prefix argument @var{n} applied to these commands
causes VM to scroll forward or backward @var{n} lines.  Typing space
at the end of a message moves you to the next message.  If the value
of @code{vm-auto-next-message} is @code{nil}, @key{SPC} will not
move to the next message; you must type @kbd{n} explicitly.

If the value of @code{vm-honor-page-delimiters} is non-@code{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 after the delimiter will be hidden until you type
another @key{SPC}, at which point the text preceding the delimiter will
become hidden.  The Emacs variable @code{page-delimiter} determines what
VM will consider to be a page delimiter.

@findex vm-unread-message
@findex vm-mark-message-read
@findex vm-mark-message-unread
@kindex U
@kindex .
@vindex vm-move-after-reading
You can ``unread'' a message (so to speak) by typing @kbd{U}
(@code{vm-unread-message}, also called @code{vm-mark-message-unread}).
The current message will be marked unread.  Conversely, you can mark an
unread message as read by typing @kbd{.}  (@code{vm-mark-message-read}).
Setting the variable @code{vm-move-after-reading} will cause vm to move
to the next undeleted message after marking the current message as read.

@findex vm-toggle-flag-message
@kindex !
As you read messages, you might want to flag important messages so
that you can come back to them later.  You can do so by typing
@code{!} (@code{vm-toggle-flag-message}).  You can also turn off the
flag on a flagged message by typing @code{!} again.  In the Summary
display, the flagged messages are highlighted using the
@code{vm-summary-high-priority-face}.  (@xref{predefined summary
faces}.)


@cindex longlines.el
@cindex filling paragraphs
@cindex word wrapping
@cindex visual line mode
@vindex vm-paragraph-fill-column
@vindex vm-fill-paragraphs-containing-long-lines
@vindex vm-word-wrap-paragraphs
Sometimes you will receive messages that contain lines that are
too long to fit on your screen without wrapping.  Setting
@code{vm-word-wrap-paragraphs} to t will cause VM to use the 
@file{longlines.el} library by Grossjohann, Schroeder and Yidong to
carry out word wrapping.  You must have this library installed
somewhere on your @code{load-path}.  Another way to deal with the
problem is to use the @code{visual-line-mode} in Emacs 23.  You can
activate it automatically for viewing messages by adding the function
@code{turn-on-visual-line-mode} to the
@code{vm-presentation-mode-hook}. 

If you are unable to use either of these solutions, then you can use
Emacs's paragraph filling facility.  If you set
@code{vm-fill-paragraphs-containing-long-lines} to a positive numeric
value @var{N}, VM will call @code{fill-paragraph} on all paragraphs that
contain lines spanning @var{N} columns or more.  You can also set this
variable to the symbol @code{window-width}, in which case the width of
the current window is used the limiting width beyond which paragraph
filling is invoked.  As with other things that VM does for presentation
purposes, this does not change the message contents.  VM copies the
message contents to a ``presentation'' buffer before altering them.  The
fill column that VM uses is controlled by
@code{vm-paragraph-fill-column}.  Unlike the Emacs variable
@code{fill-column}, this variable is not buffer-local by default.


@node @acronym{MIME} Messages,, Paging, Reading Messages
@section Reading @acronym{MIME} Messages

@cindex @acronym{MIME}
@vindex vm-display-using-mime
@dfn{@acronym{MIME}} is a set of extensions to the standard Internet message
format that allows reliable transmission of arbitrary data including images,
audio and video, as well as ordinary text in different languages.  By
default, VM will recognize @acronym{MIME} encoded messages and display them
as specified by the various @acronym{MIME} standards specifications.  This
can be turned off by setting the variable @code{vm-display-using-mime} to
@code{nil} and VM will then display @acronym{MIME} messages as plain text
messages.

At its most basic level, @acronym{MIME} is a set of transfer encodings used
to ensure error free transport, and a set of content types.  VM understands
the two standard @acronym{MIME} transport encodings, @dfn{Quoted-Printable}
and @dfn{BASE64}, and will decode messages that use them as necessary.  VM
will also try to recognize and decode messages using the UNIX @dfn{uuencode}
encoding system.  While this is not an official @acronym{MIME} transfer
encoding and never will be, enough old mailers still use it that it is
worthwhile to attempt to decode it.

@menu
* Viewing @acronym{MIME}::                Decoding @acronym{MIME} for viewing
* Attachments::                 Operating on @acronym{MIME} attachments
* Internal display::            Viewing attachments internally in Emacs
* @acronym{HTML} display::                Reading @acronym{HTML} content using Emacs-w3m browser
* External display::            Viewing attachments with external viewers
* Displaying images::           Using Emacs facilities for images
* @acronym{MIME} type conversion::        Converting external attachments to internal
* Character sets::              @acronym{MIME} character sets
* multipart/alternative::       @acronym{MIME} content in alternative formats
* multipart/related::           Attachments embedded in message display
* Inferring @acronym{MIME} types::        Inferring types from attachment file names
* Reading Secure @acronym{MIME}:: Reading PKCS7 Secure @acronym{MIME} (@acronym{S/MIME}) messages
@end menu


@node Viewing @acronym{MIME}, Attachments,, @acronym{MIME} Messages
@subsection Viewing @acronym{MIME} messages
By default VM will display as many content types as possible
within Emacs.  Images and audio are also supported if
support for images and audio has been compiled in.  Types that
cannot be displayed internally within Emacs can be converted to a
type that can, or be displayed using an external viewer.

@vindex vm-auto-decode-mime-messages
@vindex vm-mime-decode-for-preview
@kindex D
The first step in displaying a @acronym{MIME} message is decoding it to
determine what object types it contains.  The variable
@code{vm-auto-decode-mime-messages} controls when this happens.
A value of @code{t} means VM should decode the message as soon as
the message body is exposed, or during previewing if
@code{vm-mime-decode-for-preview} is also set non-@code{nil}.  A
@code{nil} value means wait until decoding is explicitly
requested.  Type @kbd{D} (@code{vm-decode-mime-message}) to
manually initiate @acronym{MIME} decoding.

@vindex vm-mime-button-format-alist
@cindex @acronym{MIME} button
When VM does not display a @acronym{MIME} object immediately, it displays a
@b{@acronym{MIME} button} or tag line in its place that describes the object
and what you have to do to display it.  The value of
@code{vm-mime-button-format-alist} determines the format of the text in
those buttons.

After decoding, you will see either the decoded @acronym{MIME} objects or
button lines that must be activated to attempt display of the
@acronym{MIME} object.  

@vindex vm-mime-auto-displayed-content-types
@vindex vm-mime-auto-displayed-content-type-exceptions
The variable @code{vm-mime-auto-displayed-content-types} specifies the types
that are displayed immediately and
@code{vm-mime-auto-displayed-content-type-exceptions} specifies
any exceptions to the types specified in
@code{vm-mime-auto-displayed-content-types}.


@vindex vm-mime-auto-displayed-content-types
A value of t for @code{vm-mime-auto-displayed-content-types} means that
all types should be displayed immediately.  A nil value means
never display @acronym{MIME} objects immediately; only use buttons.  If
the value of @code{vm-mime-auto-displayed-content-types} is a list, it
should be a list of strings, which should all be @acronym{MIME} types or
type/subtype pairs.  Example:

@example
(setq vm-mime-auto-displayed-content-types '("text" "image/jpeg"))
@end example

@noindent If a top-level type is listed without a subtype then all
subtypes of that type are assumed to be included.  The example above
says that all text types should be displayed immediately, but only
JPEG images should be displayed this way.

@vindex vm-mime-auto-displayed-content-type-exceptions
The variable @code{vm-mime-auto-displayed-content-type-exceptions}
should be a list of @acronym{MIME} content types that should not be
displayed immediately after decoding.  This variable acts as
an exception list for @code{vm-mime-auto-displayed-content-types};
all types listed there will be auto-displayed except those in
the exception list.

@example
(setq vm-mime-auto-displayed-content-type-exceptions '("text/html"))
@end example

@noindent If ``text'' has been included in
@code{vm-mime-auto-displayed-content-types} then the effect of this
setting is to allow the auto-display of all text types @i{except} for
html.

@unnumberedsubsubsec Content-Disposition (inline or attachment)
@cindex Content-Disposition
@vindex vm-mime-honor-content-disposition
@cindex attachments
The @acronym{MIME} objects in messages come with a header called
@dfn{Content-Disposition}, which specifies whether the @acronym{MIME} object
should be displayed as part of the message display (the ``inline''
disposition) or whether it should be displayed as a button that should be
invoked to view the object (the @dfn{attachment} disposition).  However, not
all mail clients do a good job of adding this header.  It is not uncommon to
find mail clients that declare all @acronym{MIME} objects to be ``inline''
and others that declare all @acronym{MIME} objects to be ``attachment''.
The variable @code{vm-mime-honor-content-disposition} can be customized to
tell VM whether it should follow the suggestions in the Content-Disposition
headers.  A value of @code{t} means that they should be always honored and a
value of @code{nil} means that they should be ignored.  It can also be set
to the symbol @code{internal-only}, which means that the Content-Disposition
suggestions should be honored for only the internally displayable types.
(@xref{Internal display of @acronym{MIME} attachments}.)

@unnumberedsubsubsec Viewing @acronym{MIME} structure

@findex vm-mime-list-part-structure
The @acronym{MIME} structure of a message can be displayed using the command
@code{vm-mime-list-part-structure}.   It causes VM to display a pop-up
window listing the hierarchical structure of the message in VM's internal
format, which should be normally discernible.

@node Attachments, Internal display, Viewing @acronym{MIME}, @acronym{MIME} Messages
@subsection  Operating on @acronym{MIME} attachments
@anchor{Operating on @acronym{MIME} attachments}
@findex vm-next-button
@findex vm-previous-button
@kindex [
@kindex ]
The commands @kbd{[} and @kbd{]} (@code{vm-previous-button}) and
@code{vm-next-button}, respectively) can be
used to move to attachment buttons within the message presentation.


@cindex attachments
@kindex $ |
@kindex $ d
@kindex $ RET
@kindex $ s
@kindex $ w
@kindex $ p
@kindex $ d
@kindex $ e  
@findex vm-mime-reader-map-pipe-to-command
@findex vm-delete-mime-object
@findex vm-mime-reader-map-display-using-default
@findex vm-mime-reader-map-display-object-as-type
@findex vm-mime-reader-map-save-message
@findex vm-mime-reader-map-save-file
@findex vm-mime-reader-map-pipe-to-printer
@findex vm-delete-mime-object
@findex vm-mime-reader-map-display-using-external-viewer
@findex vm-mime-reader-map-attach-to-composition
To activate a button, either click mouse-2 over it, or move
the cursor to the line and press @key{RET}.  If you are running under a
window system, you can use mouse-3 over a @acronym{MIME}
button to display a menu of actions you can take on the @acronym{MIME}
object.  If you prefer using keyboard commands, you can save the
@acronym{MIME} object with @kbd{$ w}, print it with @kbd{$ p}, or pipe it to
a shell command with @kbd{$ |}.  Use @kbd{$ s} to append an encapsulated
message or USENET news article to a folder.  If you want to display the
object with its characters displayed using Emacs' default face, use @kbd{$
@key{RET}}.  To display the object using an external viewer, type @kbd{$ e}.

@multitable @columnfractions .20 .80
@item $ w   @tab @code{vm-mime-reader-map-save-file}
@item $ s   @tab @code{vm-mime-reader-map-save-message}
@item $ p   @tab @code{vm-mime-reader-map-pipe-to-printer}
@item $ |   @tab @code{vm-mime-reader-map-pipe-to-command}
@item $ @key{RET} @tab @code{vm-mime-reader-map-display-using-default}
@item $ e   @tab @code{vm-mime-reader-map-display-using-external-viewer}
@item $ v   @tab @code{vm-mime-reader-map-display-object-as-type}
@item $ d   @tab @code{vm-delete-mime-object}
@item $ a   @tab @code{vm-mime-reader-map-attach-to-composition}
@end multitable

@vindex vm-mime-delete-after-saving
@vindex vm-mime-attachment-save-directory
@vindex vm-mime-confirm-delete
The @acronym{MIME} attachments can be saved to disk with @kbd{$ w}
(@code{vm-mime-reader-map-save-file}).  They can be deleted at the
same time by setting the variable @code{vm-mime-delete-after-saving}.
In this case, the attachment is deleted and replaced by a @acronym{MIME} part
that refers to the saved copy.  The variable
@code{vm-mime-attachment-save-directory} specifies the default
directory to save the attachments in.  The @acronym{MIME} attachments can also
be deleted directly from the message bodies with @kbd{$ d}
(@code{vm-delete-mime-object}).  The variable
@code{vm-mime-confirm-delete} controls whether a confirmation is asked
for.  

It is a good idea to use @code{vm-mime-delete-after-saving} to delete
saved attachments instead of deleting them manually, because with the
former approach the message will have a handle to the saved copy,
which can be retrieved when desired.

Saving attachments to the file system and deleting them from message
bodies has the beneficial effect of reducing the size of VM folders.
That leads to a better utilization of the computer resources and
usually a faster operation of VM.

@findex vm-save-all-attachments
@findex vm-delete-all-attachments
@vindex vm-mime-deletable-types
@vindex vm-mime-deletable-type-exceptions
@vindex vm-mime-savable-types
@vindex vm-mime-savable-type-exceptions
The commands @code{vm-save-all-attachments} and
@code{vm-delete-all-attachments} can be used to save or delete
@i{all} the attachments in a message.  An "attachment" in this context
is any @acronym{MIME} part that has "attachment" as its content-disposition or
simply has a file name.  In addition, all @acronym{MIME} parts that have types
matching @code{vm-mime-savable-types} or @code{vm-mime-deletable-types}
(but not the corresponding @code{-exceptions}) are included.

@node Internal display, @acronym{HTML} display, Attachments, @acronym{MIME} Messages
@subsection Internal display of @acronym{MIME} attachments
@anchor{Internal display of @acronym{MIME} attachments}

@vindex vm-mime-internal-content-types
The variable @code{vm-mime-internal-content-types} specifies which
types should be displayed internally within Emacs.  Like
@code{vm-mime-auto-displayed-content-types} its value should be a list
of @acronym{MIME} content types.  A value of t means that VM should always
display an object internally if possible.  VM knows which object types
can be displayed internally, so you can specify the types you want
without worrying about potential errors.  If the value is a list, it
should be a list of strings.  Example:

@example
(setq vm-mime-internal-content-types '("text" "message" "image/jpeg"))
@end example

@cindex multipart types
@noindent If a top-level type is listed without a subtype then all
subtypes of that type are assumed to be included.  Note that multipart
types are always handled internally regardless of the setting of this
variable.

@vindex vm-mime-internal-content-type-exceptions
The variable @code{vm-mime-internal-content-type-exceptions} serves as
the exception list for @code{vm-mime-internal-content-types}.  Its value 
should be a list of types that should not be displayed internally.

@cindex @acronym{HTML}
@vindex vm-mime-text/html-handler
The @acronym{HTML} content in text/html @acronym{MIME} parts can be
displayed in Emacs using a variety of packages.  VM knows about:

@cindex lynx
@cindex w3m
@cindex w3
@cindex Emacs-w3m
@multitable @columnfractions .15 .85
@item lynx   
  @tab The @command{lynx} browser used externally to convert @acronym{HTML}
  to plain text
@item w3m    
  @tab The @command{w3m} browser used externally to convert @acronym{HTML}
  to plain text
@item emacs-w3 
  @tab  The @samp{Emacs/W3} browser used internally in Emacs
@item emacs-w3m 
  @tab  The @samp{Emacs-W3M} browser used internally in Emacs.
        @xref{top,, Emacs-w3m, emacs-w3m, Emacs-w3m User's Manual}.
@end multitable

You can set the variable @code{vm-mime-text/html-handler} to one of
these values to use the appropriate package.  A value of
@code{auto-select} causes VM to select the best package available.  A
value of @code{nil} asks VM not to display @acronym{HTML} content internally.
The default value is @code{auto-select}, allowing VM to give you the
best display possible in your environment.  If you do not like the
results, you may set the variable to a different value or
@code{nil}.

@node @acronym{HTML} display, External display, Internal display, @acronym{MIME} Messages
@subsection @acronym{HTML} display

@cindex Emacs-w3m
The preferred method of displaying @acronym{HTML} content in email messages
is through the Emacs-w3m browser.  @xref{top,, Emacs-w3m, emacs-w3m,
Emacs-w3m User's Manual}.  VM has special facilities for using this browser,
which are described in this section.

@vindex vm-use-presentation-minor-modes
@vindex vm-presentation-minor-modes
The Emacs-w3m browser has its own key bindings for use within HTML text.
These are disabled by default so that VM's key bindings will continue to
have effect.  To switch to the Emacs-w3m key bindings, set the variable
@code{vm-use-presentation-minor-modes} to @code{t}.  The minor mode to be
used for the Emacs-w3m generated text can be set using the variable
@code{vm-presentation-minor-modes}. 

@vindex vm-w3m-display-inline-images
@cindex multipart/related
@acronym{HTML} content may have embedded images.  Such images might be
shipped with the email message (via the @acronym{MIME} type
@samp{multipart/related}) or they might be provided via @acronym{URL}'s to
be retrieved when you view the message.  The variable
@code{vm-w3m-display-inline-images} controls whether VM should allow images
to be retrieved via @acronym{URL}'s.  Set it to @code{t} to retrieve them
and @code{nil} otherwise.

@vindex vm-w3m-safe-url-regexp
@acronym{URL}'s embedded in @acronym{HTML} content are in general unsafe,
because you cannot see where they point to.  (The fraudulent technique of
``phishing'' operates by asking you to click on innocuous links, which under
the surface, link to the fraudster's web sites.)  By default, the Emacs-w3m
browser treats all external @acronym{URL}'s as unsafe and gives you a warning
when you attempt to follow the links.  To get around the warning, you can
customize the variable @code{vm-w3m-safe-url-regexp}.  You can set it to
@code{t}, to regard all @acronym{URL}'s as being safe, or to a regular
expression that identifies which @acronym{URL}'s should be regarded as safe.

The Emacs-w3m browser has numerous 
option settings that may customize.  Some important
settings for use with VM are the following:

@table @code
@vindex w3m-force-redisplay
@item w3m-force-redisplay
You may set this to @code{nil} if you find the HTML display ``jittery''
(which is caused by Emacs-w3m redisplaying the text during formatting).

@vindex w3m-pop-up-frames
@item w3m-pop-up-frames
You may set this to @code{t} if you find that Emacs-w3m is too liberal with
your Emacs windows.

@vindex w3m-goto-article-function
@item w3m-goto-article-function
Set this to an Emacs function that opens a @code{URL}.  If you have already
set @code{vm-url-browser}, you may copy its value into this variable.
@end table


@node External display, Displaying images, @acronym{HTML} display, @acronym{MIME} Messages
@subsection External display of @acronym{MIME} attachments

@vindex vm-mime-external-content-types-alist
For types that you want displayed externally, set the value
of @code{vm-mime-external-content-types-alist} to specify external
viewers for the types.  The value of this variable should be an
associative list of @acronym{MIME} content types and the external programs
used to display them.  If VM cannot display a type internally or
a type is not listed in @code{vm-mime-internal-content-types} VM will
try to launch an external program to display that type.

The alist format is a list of lists, each sublist having the form

@example
(@var{TYPE} @var{FUNCTION} @var{ARG} @var{ARG} ... )
@end example

@noindent or

@example
(@var{TYPE} @var{PROGRAM} @var{ARG} @var{ARG} ... )
@end example

@noindent or

@example
(@var{TYPE} @var{COMMAND-LINE})
@end example

@noindent @var{TYPE} is a string specifying a @acronym{MIME} type or
type/subtype pair.  For example ``text'' or ``image/jpeg''.  If a
top-level type is listed without a subtype, all subtypes of that type
are assumed to be included.

In the first form, @var{FUNCTION} is a lisp function that is responsible
for displaying the attachment in an external application.  Any
@var{ARG}s will be passed to the function as arguments.  The octets that
compose the object will be written into a temporary file and the name of
the file is passed as an additional argument.

In the second form, @var{PROGRAM} is a string naming a program to
run to display an object.  Any @var{ARG}s will be passed to the
program as arguments.  The octets that compose the object will be
written into a temporary file and the name of the file can be
inserted into an @var{ARG} string by writing @samp{%f} in the
@var{ARG} string.  In earlier versions of VM the filename was
always added as the last argument; as of VM 6.49 this is only done
if @samp{%f} does not appear in any of the @var{ARG} strings.

If the @var{COMMAND-LINE} form is used, the program and its
arguments are specified as a single string and that string is
passed to the shell ("sh -c" typically) for execution.  Since
the command line will be passed to the shell, you can use shell
variables and input/output redirection if needed.  As with the
@var{PROGRAM/ARGS} form, the name of the temporary file that
contains the @acronym{MIME} object will be appended to the command line if
@samp{%f} does not appear in the command line string.

In either the @var{PROGRAM/ARG} or @var{COMMAND-LINE} forms, all the
program and argument strings will have any %-specifiers in
them expanded as described in the documentation for the
variable @code{vm-mime-button-format-alist}.  The only difference
is that @samp{%f} refers to the temporary file VM creates to store
the object to be displayed, not the filename that the sender
may have associated with the attachment.

Example:

@example
(setq vm-mime-external-content-types-alist
      '(
         ("text/html"   browse-url-of-file)
         ("image/gif"   "xv")
         ("image/jpeg"  "xv")
         ("video/mpeg"  "mpeg_play")
         ("video"       w32-shell-execute "open")
       )
)
@end example

The first matching list element will be used.

No multipart message will ever be sent to an external viewer.

External viewer processes are normally killed when you select
a new message in the current folder.  If you want viewer
processes to not be killed, set
@code{vm-mime-delete-viewer-processes} to a @code{nil} value.

Any type that cannot be displayed internally or externally or
converted to a type that can be displayed, will be displayed as a
button that allows you to save the body to a file.

@vindex vm-mime-external-content-type-exceptions
As with the internal type list, there is an exception list that
you can use to specify types that you do not want displayed
externally.  When VM is considering whether it should
automatically launch an external viewer, it will consult the
variable @code{vm-mime-external-content-type-exceptions}.  If the 
type to be displayed is listed, VM will not launch a viewer.
This allows you to setup viewers for types that ordinarily you
would not want VM to display or for types that you normally want
to convert to some other type using @code{vm-mime-type-converter-alist}.
You can still display such a type with an external viewer by using 
@kbd{$ e}.

@vindex vm-mime-attachment-auto-suffix-alist

When a @acronym{MIME} object is displayed using an external viewer VM must
first write the object to a temporary file.  The external viewer
then opens and displays that file.  Some viewers will not open a
file unless the filename ends with some extension that it
recognizes such as @samp{.html} or @samp{.jpg}.  You can use the
variable @code{vm-mime-attachment-auto-suffix-alist} to map @acronym{MIME}
types to extensions that your external viewers will recognize.
The value of this variable should be a list of type and suffix
pairs.  The list format is:

@example
((@var{TYPE} . @var{SUFFIX}) ...)
@end example

@var{TYPE} is a string specifying a @acronym{MIME} top-level type or a type/subtype pair.
If a top-level type is listed without a subtype, all subtypes of
that type are matched.

@var{SUFFIX} is a string specifying the suffix that should be used for
the accompanying type.

Example:

@example
(setq vm-mime-attachment-auto-suffix-alist
      '(
        ("image/jpeg"           .       ".jpg")
        ("image/gif"            .       ".gif")
        ("image/png"            .       ".png")
        ("text"                 .       ".txt")
       )
)
@end example

@noindent VM will search the list for a matching type.  The suffix 
associated with the first type that matches will be used for the
temporary filename.

@node Displaying images, @acronym{MIME} type conversion, External display, @acronym{MIME} Messages
@subsection Displaying inline images in messages

@cindex images
Most versions of Emacs can display images when used on graphical
screens.  You can verify if the Emacs version is able to do so by
calling the function @code{display-images-p}.  However, Emacs relies
on external libraries to create graphical images, which are specified
through the variable @code{image-library-alist}.  Even if Emacs has
the ability to display some image type, it cannot display such images
unless appropriate libraries are installed and specified to Emacs.  You
can verify which image types are really available by calling the
function @code{image-type-available-p} with an image type such as
@samp{tiff} or @samp{gif} as the argument.

@vindex vm-mime-internal-content-types
@vindex vm-mime-auto-displayed-content-types
Assuming that a particular image type, say @samp{tiff} is available,
you can include its @acronym{MIME} type in
@code{vm-mime-internal-content-types}, e.g., 
@example
(add-to-list 'vm-mime-internal-content-types "image/tiff")
@end example
You can also add the @acronym{MIME} type to the variable
@code{vm-mime-auto-displayed-content-types} so that VM will
automatically display all images of the type.  
If the type is not included among the auto-displayed types, then the
image is initially shown as a button with a thumbnail image.  Clicking on the
button with the middle mouse button expands the image to its full size.

@cindex ImageMagick
@vindex vm-imagemagick-identify-program
@vindex vm-imagemagick-convert-program
Once an image is displayed, you can use the right mouse button to do
various image manipulations on it, such as enlarging/reducing it,
rotating it etc.  To do such operations, VM uses the @samp{ImageMagick}
graphics manipulation software.  You can install ImageMagick on your
system and specify the location of its @command{identify} and
@command{convert} programs to VM via the variables
@code{vm-imagemagick-identify-program} and
@code{vm-imagemagick-convert-program}.

@vindex vm-mime-use-image-strips
By default, VM displays images by slicing them into contiguous
horizontal strips and displaying the strips in order.  This
facilitates vertical scrolling within an image.  The variable
@code{vm-mime-use-image-strips} controls whether VM uses strips for
image display.  It is @samp{t} by default.

VM also uses the ImageMagick's @code{convert} program to convert
between image formats, so that an image that is not displayable in
Emacs is converted to another format that is displayable.  You can
turn off such conversion by setting the variable
@code{vm-imagemagick-convert-program} to @samp{nil}.


@node @acronym{MIME} type conversion, Character sets, Displaying images, @acronym{MIME} Messages
@subsection @acronym{MIME} type conversion

@vindex vm-mime-type-converter-alist
Types that cannot be displayed internally or externally are
checked against an associative list of types that can be converted to other
types.  If an object can be converted to a type that VM can
display, then the conversion is done and the new object is
subject to the auto-display rules which determine whether the
object is displayed immediately or a button is displayed in its
place.  The conversion list is stored in the variable
@code{vm-mime-type-converter-alist}.

The alist format is

@example
( (START-TYPE END-TYPE COMMAND-LINE ) ... )
@end example

@var{START-TYPE} is a string specifying a @acronym{MIME} type or type/subtype pair.
Example @samp{"text"} or @samp{"image/jpeg"}.  If a top-level type is
listed without a subtype, all subtypes of that type are assumed
to be included.

@var{END-TYPE} must be an exact type/subtype pair.  This is the type
to which @var{START-TYPE} will be converted.

@var{COMMAND-LINE} is a string giving a command line to be passed to
the shell.  The octets that compose the object will be written to
the standard input of the shell command.

Example:

@example
(setq vm-mime-type-converter-alist
       '(
         ("image/jpeg"  "image/gif"     "jpeg2gif")
         ("text/html"   "text/plain"    "striptags")
        )
)
@end example

@noindent The first matching list element will be used.

@node Character sets, multipart/alternative, @acronym{MIME} type conversion, @acronym{MIME} Messages
@subsection @acronym{MIME} character sets

For text type messages, @acronym{MIME} also requires that a character set
be specified, so that the recipient's mail reader knows what
character glyphs to use to display each character code.  To
display a message properly VM needs to know how to choose a font
for a given character set.

@vindex vm-mime-default-face-charsets
@cindex character sets
@cindex Windows-1252
@cindex CP1252
@cindex GB2312
@cindex ISO-8859-1
@cindex US-ASCII
The variable @code{vm-mime-default-face-charsets} tells VM what character
sets your default face can display.  For most American and European
users using X Windows, Emacs' default face displays the ISO-8859-1
and US-ASCII characters, US-ASCII being a subset of ISO-8859-1.
Additional character sets can be included if you think that the
messages only contain characters that your system can display.  For
example, messages sent by a Chinese sender might declare the character
set to be GB2312 but the message might contain only English characters
that you might be able to display and read.  Messages sent by Microsoft
Windows users might declare the character set to be Windows-1252 or
CP1252, but the majority of the characters might be in ISO-8859-1.  By
including such character sets in @code{vm-mime-default-face-charsets},
you might be able to view the majority of the characters even if your
system cannot fully handle the character set.

The value of @code{vm-mime-default-face-charsets} must be a list of
strings specifying the character sets that your default face can
display.  Example:

@example
(add-to-list 'vm-mime-default-face-charsets "Windows-1251")
(add-to-list 'vm-mime-default-face-charsets "Windows-1252")
(add-to-list 'vm-mime-default-face-charsets "Windows-1257")
@end example

Note that for character sets listed in this variable, VM's @acronym{MIME}
decoding is bypassed.  So you should not add charsets like "UTF-8"
that require additional decoding.

@vindex vm-mime-charset-converter-alist
@cindex UTF-8
@cindex ISO-2022-JP
Sometimes a charset that VM cannot display can be converted to a
one that VM can display.  An example would be a message encoded
using UTF-8 but in fact only contains Japanese characters.  In
that case the message text could probably be converted to
iso-2022-jp which VM running on a MULE-enabled Emacs could
display.

VM offers a way to do such conversions.  The variable
@code{vm-mime-charset-converter-alist} is an associative list of @acronym{MIME}
charsets and programs that can convert between them.  If VM
cannot display a particular character set, it will scan this list
to see if the charset can be converted into a charset that it can
display.

The alist format is:

@example
 ( ( START-CHARSET END-CHARSET COMMAND-LINE ) ... )
@end example

@var{START-CHARSET} is a string specifying a @acronym{MIME} charset.
Example @samp{"iso-8859-1"} or @samp{"utf-8"}.

@var{END-CHARSET} is a string specifying the charset to which
@var{START-CHARSET} will be converted.

@var{COMMAND-LINE} is a string giving a command line to be passed to
the shell.  The characters in @var{START-CHARSET} will be written to the
standard input of the shell command and VM expects characters
encoded in @var{END-CHARSET} to appear at the standard output of the
@var{COMMAND-LINE}.  @var{COMMAND-LINE} is passed to the shell, so you can
use pipelines, shell variables and redirections.

@cindex iconv
Example:

@example
(setq vm-mime-charset-converter-alist
      '(
         ("utf-8" "iso-2022-jp" "iconv -f utf-8 -t iso-2022-jp -c")
       )
)
@end example

The first matching list element will be used.  Be sure to include the
@code{-c} option so that nonconvertible characters are ignored instead
of causing error messages.

@vindex vm-mime-charset-font-alist
The variable @code{vm-mime-charset-font-alist} tells VM what font to use 
to display a character set that cannot be displayed using
the default face.  The value of this variable should be an
assoc list of character sets and fonts that can be used to display
them.  The format of the list is:
 
( (@var{CHARSET} . @var{FONT}) ...) 
 
@var{CHARSET} is a string naming a @acronym{MIME} registered character set such 
as @samp{"iso-8859-5"}.
 
@var{FONT} is a string naming a font that can be used to display
@var{CHARSET}.
 
An example setup might be: 
 
@example
(setq vm-mime-charset-font-alist
  '(
    ("iso-8859-5" . "-*-*-medium-r-normal-*-16-160-72-72-c-80-iso8859-5")
   )
)
@end example

@noindent This variable is only useful for character sets whose
characters can all be encoded in single 8-bit bytes.  Also multiple
fonts can only be displayed if you're running under a window system
e.g. X Windows.  So this variable will have no effect if you're
running Emacs on a tty.

Note that under FSF Emacs 19 any fonts you use must be the
same height as your default font.  XEmacs and Emacs 21 do not
have this limitation.  Under Emacs 20 and beyond, and under
any XEmacs version compiled with MULE support, the value of
@code{vm-mime-charset-font-alist} has no effect.  This is
because all characters are displayed using fonts discovered by
MULE and VM has no control over them.

@node multipart/alternative, multipart/related, Character sets, @acronym{MIME} Messages
@subsection @acronym{MIME} multipart/alternative

@cindex @acronym{MIME} alternatives
@cindex multipart/alternative
@acronym{MIME} allows a message to be sent with its content encoded in multiple
formats, simultaneously, in the same message.  Such messages have a
content type of @dfn{multipart/alternative}.  The idea is that the sender
might have different @acronym{MIME} decoding or display capabilities than some
of his recipients.  For instance, the sender may be able to compose a
message using fancy text formatting constructs like tables, italics
and equations but some of the recipients may only be able to display
plain text.  The @samp{multipart/alternative} type message is the solution
to this dilemma.  Such a message would contain at least two text
subparts, one in plain text and the other in the full featured text
formatting language that the sender used.

@vindex vm-mime-alternative-show-method
@cindex @acronym{MIME} alternative, best
@cindex @acronym{MIME} alternative, best-internal
To control how VM displays @samp{multipart/alternative} messages, you must
set the variable @code{vm-mime-alternative-show-method}.  Its value must be
a symbol.  A value of @code{best} tells VM to display the message
using the subpart closest in appearance to what the sender used to
compose the message.  In the example above this would mean displaying
the fully featured text subpart, if VM knows how to display that type.
VM will display the type either internally or externally.  A
value of @code{best-internal} tells VM to use the closest subpart that
it can display internally.  External viewers won't be used in this
case.  A value of @code{all} asks VM to display all the alternatives.

@cindex @acronym{MIME} alternative, favorite
@cindex @acronym{MIME} alternative, favorite-internal
The value can also be a list of the form

@example
  (favorite @var{TYPE} ...)
@end example

@noindent with the first element of the list being the symbol @code{favorite}.
The remaining elements of the list are strings specifying @acronym{MIME} types.
VM will look for each TYPE in turn in the list of alternatives and
choose the first matching alternative found that can be displayed.  If
instead of the symbol @code{favorite}, @code{favorite-internal} is
used then the first @var{TYPE} that matches an alternative that can be
displayed internally will be chosen.

@findex vm-nuke-alternative-text/html
Messages with multiple alternatives use up extra file space and slow
down the operation of vm.  If you would like keep the text/plain
alternatives but erase the text/html alternatives, you can use the
@code{vm-nuke-alternative-text/html} command.  This operation may not
always be safe because the @code{text/html} alternative is often the
most faithful representation of the sender's message and it may
include attachments that are not replicated in the other
alternatives.  Please use caution.

@node multipart/related, Inferring @acronym{MIME} types, multipart/alternative, @acronym{MIME} Messages
@subsection @acronym{MIME} multipart/related

@cindex multipart/related
@cindex multipart/mixed
@cindex Emacs-w3m
The content type @dfn{multipart/related} is used to add attachments that
should be displayed embedded in the message, typically a @samp{text/html}
message.  If you use Emacs-W3M to view @samp{text/html} content, then VM will
automatically ship the @samp{multipart/related} attachments to Emacs/W3M so
that it can embed them in the message display.

However, if you do not use an internal viewer for the @samp{text/html}
content, then the attachments will not get displayed.  In this case, VM will
display all the attachments individually, either as buttons or as images.
In effect, VM falls down to the method of displaying @samp{multipart/mixed}
content. 

@vindex vm-mime-multipart/related-show-method
You can ask VM to always treat @samp{multipart/related} content in a way
similar to @samp{multipart/mixed} by setting the variable
@code{vm-mime-multipart/related-show-method} to @code{'mixed}.

@node Inferring @acronym{MIME} types, Reading Secure @acronym{MIME}, multipart/related, @acronym{MIME} Messages
@subsection Inferring @acronym{MIME} types

Some mailers incorrectly use the generic
@samp{application/octet-stream} type when sending files that
really have a specific @acronym{MIME} type.  For example, a JPEG image
might be sent using @samp{application/octet-stream} type instead
of @samp{image/jpeg}, which would be the correct type.  In many
cases the filename sent along with the mistyped file
(e.g. @file{foo.jpg}) suggests the correct type.  

@vindex vm-infer-mime-types
If the variable
@code{vm-infer-mime-types} is set non-@code{nil}, VM will attempt to use 
the filename sent with a @acronym{MIME} attachment to guess an attachment's 
type if the attachment is of type @samp{application/octet-stream}.

@vindex vm-infer-mime-types-for-text
If the variable
@code{vm-infer-mime-types-for-text} is set non-@code{nil}, VM will
attempt to use file names for attachments of type @samp{text/plain} as
well. 

@node Reading Secure @acronym{MIME}, , Inferring @acronym{MIME} types, @acronym{MIME} Messages
@subsection Reading Secure @acronym{MIME} Messages

VM supports reading @acronym{S/MIME} messages if your Emacs version includes
@samp{smime.el}
package.
Typically, a secure message part (identified
by @acronym{MIME} type ``application/pkcs7-smime'') will be presented as a
button which, when pushed, will decrypt that part of the message.
It is also
possible to auto-decrypt whenever you read the message by adding
@code{"application/x-pkcs7-smime"} and @code{"application/pkcs7-smime"} to
the
variable @code{vm-auto-displayed-mime-content-types} But beware that, at
present, the @samp{smime.el} library always asks for a private key passcode,
even for non-encrypted private keys.
So, you will be prompted while
paging through messages, which may be undesirable. 
In addition, since the
content of the @acronym{S/MIME}-encoded message should be considered
private, auto-decrypting could compromise security.

In order to get started reading @acronym{S/MIME} messages, you need to
first have at least one RSA public/private key pair to be associated
with your email address and a certificate generated from them. There
are numerous ways to obtain these sets.  We will highlight only the
simplest one as a way to just get you started. We can create a self-signed
certificate (which should only be used with people you already trust)
using ``openssl'' on the command line:

@example
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem
@end example

@vindex smime-keys
@noindent This will generate an encrypted private key in @samp{key.pem} and
certificate in @samp{cert.pem}.  Next we need to tell Emacs about the
certificate and its association to an email address.  This is done by
setting the variable @code{smime-keys}.  (Consult its documentation for
further info.)  More importantly, the @samp{cert.pem} file (second element of
each association) is expected to also have the private key within it. Simply
concatenate @samp{key.pem} and @samp{cert.pem} files and store it in a file:

@example
cat key.pem cert.pem > key-cert.pem
@end example

@noindent Then @code{smime-keys} might be

@example
(("joe@@example.com" "~/.ssl/key-cert.pem"))
@end example

@noindent Multiple addresses with different certificates are allowed.  When
reading @acronym{S/MIME} messages, VM will search for recipients of
the message that match email addresses in @code{smime-keys} and
attempt to decrypt the message with one of those keys. Should there be
no matches in the "To:" or "Cc:" fields, @code{user-mail-address} will
be used. Finally, should decryption fail with that key, you will
be prompted to supply another private key with which to attempt
decryption or simply give up.

@vindex vm-mime-verify-signatures
Secure @acronym{MIME} messages can arrive with a signature using a MIME type
``application/pkcs7-signature''.  
VM verifies such signatures automatically,
provided you have set the variable @code{vm-mime-verify-signatures} to
@code{t}. 
It is assumed that the signer's certificate is embedded in the
message (this is typically the case when sending @acronym{S/MIME} messages).
Success or failure does not affect the reading of the message.
It merely
emits a success message or a warning.
The signers certificate will be
available for download to a file (default is the sender's email address under
the @code{smime-certificate-directory}), which is useful for automatically
choosing certificates when sending mail. See @ref{Sending Secure @acronym{MIME},
Sending Secure @acronym{MIME}} for more information.

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

When sending messages from within VM, you will be using the standard
mail sending facility provided with Emacs, plus some extensions added
by VM.  @xref{Sending Mail,,,emacs, the GNU Emacs Manual}.  Emacs
comes with two versions of mail sending packages, called ``mail mode''
and ``message mode''.  VM currently uses the ``mail mode'' package,
which is not too dissimilar to the ``message mode'' package.

Even though VM's mail composition buffers will be in ``mail mode'',
they have some extra command keys.

@table @kbd

@findex vm-yank-message
@findex vm-yank-message-other-folder
@kindex C-c C-y
@item C-c C-y (@code{vm-yank-message})
Copies a message from the folder that is the parent of this
composition into the mail composition 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}.  All message headers are yanked along
with the text.  Point is left before the inserted text, the mark after.
Any hook functions bound to @code{mail-yank-hooks} are run, after inserting
the text and setting point and mark.  If a prefix argument is given,
this tells VM: ignore @code{mail-yank-hooks}, don't set the mark, don't 
prepend the 
value of @code{vm-included-text-prefix} to every yanked line, and don't yank
any headers other than those specified in
@code{vm-visible-headers} and @code{vm-invisible-headers}.  

@item @code{M-x vm-yank-message-other-folder}
This allows one to yank a message from a different folder than the
parent of this composition.

@kindex C-c C-v
@item C-c C-v <Any VM command key>
All VM commands may be accessed in a VM Mail mode buffer by prefixing them
with C-c C-v.
@kindex C-c C-a
@vindex vm-send-using-mime
@cindex drag and drop
@item C-c C-a (@code{vm-attach-file}) or drag-and-drop a file
Attaches a file to the composition.  When you send the message, VM 
will insert the file and @acronym{MIME} encode it.  The variable
@code{vm-send-using-mime} must be set non-@code{nil} for this command to work.
You will be asked for the file's type, and a brief description of 
the attachment.  The description is optional.  If the file's type
is a text type, you will also be asked for the character set
in which the text should be displayed.
The new attachment will appear as a highlighted tag in the
composition buffer.  You can use mouse button 3 on this tag
to set the default content disposition of the attachment.  The
content disposition gives a hint to the recipient's mailer how to 
treat the attachment.  Specifically the disposition will indicate 
whether the attachment should be displayed along with the message 
or saved to a file.  Any text in the composition that appears
before the tag will appear in a @acronym{MIME} text part before the
attachment when the message is encoded and sent.  Similarly, any
text after the tag will appear after the attachment in the
encoded message.  If you change your mind about using the
attachment, you can remove it from the composition with @key{C-k}.
If you want to move the attachment to some other part of the message,
you can kill it @key{C-k} and yank it back with @key{C-y}.

@kindex C-c C-m
@item C-c C-m (@code{vm-attach-message})
Attaches a mail message to the composition.  If invoked with a
prefix argument, the name of a folder is read from the minibuffer and
the message or messages to be attached are copied from that
folder.  You will be prompted for the message number of the
message to be attached.  If you invoke the command on marked
messages by running
@code{vm-next-command-uses-marks} first, the marked messages in
the selected folder will be attached as a @acronym{MIME} digest.
@kindex C-c C-b
@item C-c C-b (@code{vm-attach-buffer})
Attaches an Emacs buffer to the composition.

@findex vm-mime-encode-composition
@kindex C-c C-e
@kindex C-c C-c
@item C-c C-e (@code{vm-mime-encode-composition})
Encodes the composition using @acronym{MIME}, but does not send it.  This
is useful if you want to use PGP to sign a message before sending
it.  After signing the message, you would use @kbd{C-c C-c} as usual to
send the message.  Emacs' @code{undo} command can be used to undo
the encoding, so that you can continue composing the unencoded
message.

@findex vm-preview-composition
@kindex C-c C-p
@item C-c C-p (@code{vm-preview-composition})
Previews the current composition.  The message is copied into a
temporary folder and you can read the message and interact with
it using normal VM mode commands to see how it might look to a
recipient.  Type @key{q} to quit the temporary folder and resume
composing your message.

@end table

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

@findex vm-mail
@anchor{vm-mail}
The alternative command @code{vm-mail} can be invoked outside of VM by
typing @kbd{M-x vm-mail}.  However, only
(@code{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 can resend the message by
typing @kbd{M-r} (@code{vm-resend-bounced-message}).  VM will
extract the old message and its pertinent headers from the
returned message, and place you in a VM Mail mode buffer.  A
Resent-To header will be added, which you can fill in with
the corrected addresses of the recipients that bounced.  You
can also added a Resent-Cc header, which has the same meaning
as a Cc header in a normal message.  Mail will only be sent to
the addresses in the Resent-To and Resent-Cc headers unless
you delete both of those headers.  In that case the To and Cc
headers will be used.

@menu
* Sending Options::        Variables that control mail sending.
* Sending @acronym{MIME} Messages::  Sending a message using @acronym{MIME} attachments.
* Sending Secure @acronym{MIME}::  Sending a secure message using the @acronym{S/MIME} extension.
* Replying::               Describes the various ways to reply to a message.
* Forwarding Messages::    How to forward a message to a third party.
* Saving copies::          Saving copies of sent mail.
* Personality Crisis::     Programmable customization of message composition.
* Postponing Messages::    Saving draft messages for later.
@end menu

@node Sending Options, Sending @acronym{MIME} Messages, Sending Messages, Sending Messages
@section Mail Sending Options

As already mentioned, VM uses Emacs @ref{Mail Mode,,,emacs, the Gnu
Emacs Manual} for sending email.  Therefore, Mail Mode options
should be set to configure the mail sending.  The extra options
provided by VM are described below.

@vindex vm-mail-auto-save-directory
The variable @code{vm-mail-auto-save-directory} can be used to specify the
directory in which the message composition buffers should be auto-saved.  If
it is nil, the @code{vm-folder-directory} is used for auto-saving.

@vindex vm-mail-header-from
@vindex vm-mail-mode-hidden-headers
When a mail composition buffer is created, VM initializes it with
header lines that you can fill in.  The @code{From} header is usually
standard and contains your email address.  You can have VM fill it in
for you
automatically by setting the variable @code{vm-mail-header-from}.  (It is
@code{nil} by default.)  

@findex vm-mail-from-folder
@vindex vm-mail-use-sender-address
The variable @code{vm-mail-use-sender-address}, if set to @code{t}, asks VM
to fill in the @code{To} header from the sender's name and address of the
current message.  This has effect only when @code{vm-mail-from-folder} is
invoked from a VM folder.  When @code{vm-mail} is invoked, possibly from
other buffers, the @code{To} headers is unfilled.  (Some people tend to use
@code{vm-reply} to get this effect, but that is a bad practice because it
also tags the new message as a reply to an older message.)

The variable
@code{vm-mail-mode-hidden-headers} can be used to hide some of the
header lines from the mail composition buffer.  By default, the
headers ``References'' and ``X-Mailer'' are hidden. 

@vindex vm-mail-header-insert-date
@vindex vm-mail-header-insert-message-id
@vindex vm-mail-reorder-message-headers
@vindex vm-mail-header-order
Additional header lines are created by VM before the composed message
is sent.  The variable @code{vm-mail-header-insert-date} can be set to
@code{t} (which is the default value) asking VM to insert a Date
header into a message before it is sent.  You should set it to
@code{nil} if you would like to insert a Date header yourself.  The
variable @code{vm-mail-header-insert-message-id} asks VM to insert a
Message-ID header before sending the message. The variable
@code{vm-mail-reorder-message-headers} asks VM to reorder the message
headers into a particular order before sending.  The order is
determined by the variable @code{vm-mail-header-order}.


@node Sending @acronym{MIME} Messages, Sending Secure @acronym{MIME}, Sending Options, Sending Messages
@section Sending @acronym{MIME} Messages

@vindex vm-send-using-mime
To use VM's @acronym{MIME} composition features, you must have
@code{vm-send-using-mime} set to a non-@code{nil} value.  With @acronym{MIME} composition
enabled, VM will allow you to add file attachments to your
composition and will analyze your message when you send it and
@acronym{MIME} encode it as necessary.

@menu
* @acronym{MIME} attachments::    Sending a message using @acronym{MIME} attachments.
* @acronym{MIME} characters::     Sending a message with @acronym{MIME}-encoded characters.
* @acronym{MIME} headers::        Sending a message with @acronym{MIME}-encoded headers.
* @acronym{MIME} preview::        Previewing a @acronym{MIME} message before sending.
@end menu

@node @acronym{MIME} attachments, @acronym{MIME} characters, Sending @acronym{MIME} Messages, Sending @acronym{MIME} Messages
@unnumberedsec @acronym{MIME} attachments

@kindex C-c C-a
@findex vm-attach-file
To attach a file to your composition, use @kbd{C-c C-a}
(@code{vm-attach-file}).  VM will ask you for the name of the
file, its type, a brief description and its character set if it is a
text attachment.  

An attachment will be represented in the composition as a tag line
like this

  [ATTACHMENT ~/sounds/chronophasia_scream.au, audio/basic]

@noindent You can type text before and after this tag and it will appear
before or after the text in the final @acronym{MIME} message when VM encodes
it.  You can kill the tag with @kbd{C-k} and yank it back with
@kbd{C-y} to move it to another place in the message.  You can
yank back the tag multiple times to duplicate the attachment in
the message.  Or you can leave the tag killed and the attachment
won't appear in the message when it is sent.

@cindex Content-Disposition
If you click the right mouse button on the attachment tag, a menu
will appear that allows you to change the content disposition of
the attachment.  The @dfn{Content-Disposition} of a @acronym{MIME} object
gives a mail reader a hint as to whether the object should be
displayed inline or as an inert tag or button that you must
activate in some fashion.  @dfn{Inline} display usually means
that the object will be displayed within or alongside the message
text, if that is possible.  @dfn{Attachment}, when used as a
content disposition, means that the object will likely be
displayed as a tag.  By default, VM specifies an inline
disposition for all @acronym{MIME} types except @samp{application} and
@samp{model} types.

@kindex C-c C-b
@findex vm-attach-buffer
To attach a buffer instead of a file, use @kbd{C-c C-b} (normally 
bound to @code{vm-attach-buffer}.  You must not kill the
buffer that you attach until after the message has been sent.

@kindex C-c C-m
@findex vm-attach-message
You can attach a message from another folder by using @kbd{C-c C-m}
(@code{vm-attach-message}).  By default, the folder is the parent
folder of the message composition.  If there is no parent folder, then
a folder name will be read from the minibuffer.  The message number of
the message to be attached is also read from the minibuffer.
Alternatively, you can mark one or more messages in the parent folder
before invoking this command.  All the marked messages will be
attached as a digest in the outgoing message.

@unnumberedsubsec Point-to-point attachment operations

@cindex point-to-point attachment operations
A number of @dfn{point-to-point operations} allow you to attach objects
from other editing contexts to a message you are composing.

@findex vm-dired-attach-file
@findex vm-dired-do-attach-files
You can visit a directory in Emacs (@pxref{Dired,,,emacs, the GNU
Emacs Manual}), and run @code{vm-dired-attach-file} on any file.  The
file will be be attached to your message composition.  You can also mark a set
of files in a Dired buffer and run @code{vm-dired-do-attach-files} to attach
all of them.

@findex vm-dnd-attach-file
@cindex drag and drop
You can use your Window system to drag and drop a file into a
composition buffer (@code{vm-dnd-attach-file}).

@kindex $ a
@findex vm-mime-reader-map-attach-to-composition
@findex vm-attach-message-to-composition
When you visit a folder in VM, you can attach a message from the
folder by running @code{vm-attach-message-to-composition}.  When
viewing a message that has @acronym{MIME} attachments, you can attach any of
those attachments to your message composition by using the @kbd{$ a}
(@code{vm-reader-map-attach-to-composition}) function.
(@xref{Operating on @acronym{MIME} attachments}.)  This operation is also
available on the pop-up menu for attachments.

In all these cases, you will be prompted for the message composition
buffer to which you would like to attach the objects.  The default is
the latest message you have been composing, as indicated by the Emacs
buffer ring.



@node @acronym{MIME} characters, @acronym{MIME} headers, @acronym{MIME} attachments, Sending @acronym{MIME} Messages
@unnumberedsec @acronym{MIME} characters

@vindex vm-mime-7bit-composition-charset
By default, when you type text into a composition buffer VM
assumes that if all the character codes are less than 128, you
are using the US-ASCII character set and that is the character
set declared in the encoding of the message when it is sent.  If
you are using some other character set, you must specify it by
setting the variable @code{vm-mime-7bit-composition-charset}.  The
value of this variable should be a string specifying the character
set.

@vindex vm-mime-8bit-composition-charset
If there are character codes in the composition greater than 128, the
variable @code{vm-mime-8bit-composition-charset} tells VM what character 
set to assume when encoding the message.  The default is
@samp{iso-8859-1}.

Character codes greater than 128 may not be transported reliably
across the Internet in mail messages.  Some machines will refuse
to accept messages containing such characters and some will accept
them but zero the eighth bit, garbling the message.  To avoid
these problems, VM transfer encodes 8-bit text by default.

@acronym{MIME} has two transfer encodings that convert 8-bit data to 7-bit data
for safe transport.  @dfn{Quoted-printable} leaves the text mostly
readable even if the recipient does not have a @acronym{MIME}-capable mail
reader.  @dfn{BASE64} is unreadable without a @acronym{MIME}-capable mail
reader.

@vindex vm-mime-8bit-text-transfer-encoding
VM's text transfer encoding behavior is controlled by the
variable @code{vm-mime-8bit-text-transfer-encoding}.  Its value should
be a symbol that specifies what kind of transfer encoding to do
for 8-bit text.  A value of @samp{quoted-printable}, means to use
quoted-printable encoding.  A value of @samp{base64} means to use
BASE64 encoding.  A value of @samp{8bit} means to send the message as
is.  Note that this variable usually only applies to textual @acronym{MIME}
content types.  Images, audio, video, etc. typically will have
some attribute that makes VM consider them to be ``binary'',
which moves them outside the scope of this variable.  For
example, messages with line lengths of 1000 characters or more
are considered binary, as are messages that contain carriage
returns (ASCII code 13) or NUL's (ASCII code 0).

@node @acronym{MIME} headers, @acronym{MIME} preview, @acronym{MIME} characters, Sending @acronym{MIME} Messages
@unnumberedsec @acronym{MIME} headers

The internet standards specify that the header lines of messages should
always be in 7 bit ASCII, even if the body of a message can use an
8 bit character set.  If you use other non-ASCII characters in typing
the headers then VM encodes their words using the @acronym{MIME} encoded-word
syntax, which is of the form @code{=?charset?encoding?encoded text?=}.  

@vindex vm-mime-encode-headers-regexp
@vindex vm-mime-encode-headers-type
The variable @code{vm-mime-encode-headers-regexp} specifies which
headers should be encoded in this way.  By default, @samp{Subject},
@samp{Organization}, @samp{From}, @samp{To}, @samp{CC}, @samp{Bcc} and
@samp{Resent-} header lines encoded.  The words are encoded using
quoted-printable encoding (@kbd{Q}).  You can ask VM to use the base64
encoding by setting the variable @code{vm-mime-encode-headers-type}.

@vindex vm-mime-encode-words.regexp
@vindex vm-mime-encode-headers-words-regexp
The variables @code{vm-mime-encode-words.regexp} and
@code{vm-mime-encode-headers-words-regexp} control what is 
meant by a ``word'' for VM for the purpose of encoding.  By default, the
words are those containing any 8 bit character and delimited by white
space characters.

@node @acronym{MIME} preview, , @acronym{MIME} headers, Sending @acronym{MIME} Messages
@unnumberedsec @acronym{MIME} preview

@kindex C-c C-p
To preview what a @acronym{MIME} message will look like to a recipient,
use @kbd{C-c C-p} (@code{vm-mime-preview-composition}).  VM
will encode a copy of the message and present it to you in a
temporary mail folder.  You can scroll through the message
using normal VM mail reading commands.  Typing @kbd{q} in this
folder will return you to your composition where you can make
further changes.

@kindex C-c C-e
@kindex C-c C-c
To encode a @acronym{MIME} message without sending it, use @kbd{C-c C-e}
(@code{vm-mime-encode-composition}).  This is useful if you use
PGP and want to sign a message before sending it.  VM will encode
the message for transport, inserting all necessary headers and
boundary markers.  You can then sign the message and send it with
C-c C-c and be confident that VM won't invalidate the signature
by making further modifications to the message.  Or if you want
to resume editing the message you can run the Emacs @code{undo}
(normally bound to @kbd{C-x u}) command which will revert the
encoded @acronym{MIME} bodies back to tags and you can continue entering
your composition.

@node Sending Secure @acronym{MIME}, Replying, Sending @acronym{MIME} Messages, Sending Messages
@section Sending Secure @acronym{MIME} Messages

@vindex vm-get-recipient-certificate-method
VM supports sending @acronym{S/MIME} messages utilizing the @samp{smime.el}
package included in Emacs. Sending signed, secure, or signed secure
messages is essentially no different from sending any other message, except
that, sometime before hitting send (@kbd{C-c C-c}), you would use one
of the following functions

@itemize
@item @code{vm-smime-sign-message}
@item @code{vm-smime-encrypt-message}
@item @code{vm-smime-sign-encrypt-message}
@end itemize

@noindent These can be used in any combination, but note that VM, when
instructed to both encrypt and sign, will always sign before
encrypting. Also, signing and encrypting (at present) is only supported for
the entire message, including any attachments and text parts.

@vindex vm-smime-get-recipient-certificate-method
The functions above only set flags, the actual job of signing and encrypting
is done at the very last stage before sending the message.  There are several
ways VM can choose which certificates to use in encrypting a message.  The
preferred way is specified via the variable
@code{vm-smime-get-recipient-certificate-method}. At present,
the options are one of 'ask or 'links.

@itemize
@item 'ask 

Tells VM to prompt the user for all certificates, after entering
one the user will be prompted to add more or just send.

@item 'links

This method tells VM that recipient certificates are stored
under @code{smime-certificate-directory} using the recipients email
address as a file name, e.g.

@example
~/.ssl/jow@@example.com -> joes-cert.pem
@end example

@noindent This doesn't require prompting the user @emph{unless} a
particular recipient address could not be associated with a file, in
which case the user will be promoted to provide a replacement.
@end itemize

If errors occur during signing or encrypting or thereafter, VM will stop
sending the message and whatever steps were completed before will not be
repeated.  For example, if you request a message to be signed and encrypted,
and signing was successful but encryption failed due to a bad certificate
file for one of the recipients, then the message will remain signed and the
sign flag will be turned off.  You can then fix the problem and send the
message again with the assurance that it won't be double-signed but it
@emph{will} be encrypted.

@node Replying, Forwarding Messages, Sending Secure @acronym{MIME}, Sending Messages
@section Replying

@vindex vm-reply-subject-prefix
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 whom the message should be sent to and
what the subject should be.  There is an old convention of prepending
the string @samp{Re: } to the subject of replies if the string isn't
present already.  You can customize the string to be prepended in this
way by setting the variable @code{vm-reply-subject-prefix}.  Its value
should be a string to prepend to the subject of replies, if the string
isn't present already.  A @code{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.

@vindex vm-included-text-prefix
VM also helps you cite material from the 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 prefix to each line so that the included text
can be distinguished from the text of the reply.  By default, the
prefix string is @samp{> }.  This can be customized via the variable
@code{vm-included-text-prefix}.

The reply commands are:

@table @kbd
@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.
@findex vm-mail-to-sender
@item vm-mail-to-sender
Writes a message to the sender of the current message.  (This is similar to
@code{vm-reply} but meant for writing a message about a new subject.)
@end table

These commands all accept a numeric prefix argument @var{n}, which if
present, causes VM to reply to the next (or previous if the argument is
negative) @var{n-1} messages 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. (@pxref{Marking
Messages}.) 

@vindex vm-reply-ignored-addresses
If you are one of multiple recipients of a message and you use @kbd{f}
and @kbd{F}, your address will be included in the recipients of the
reply.  You can avoid this by judicious use of the variable
@code{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.  The default value is
@code{nil}, which means that no addresses are removed.

@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 the 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.  If the format includes elements that can contain
non-ASCII characters, then @samp{In-Reply-To} should be added to
@code{vm-mime-encode-headers-regexp}.

@vindex vm-strip-reply-headers
The recipient headers generated for reply messages are created by
copying the appropriate headers from 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 recipient headers will be stripped of all information
except the actual addresses.

@unnumberedsubsec Included text

As mentioned above, the commands @code{vm-reply-include-text} and
@code{vm-followup-include-text} provide ``included text'' from the
original message in your reply.  In addition, you can use @kbd{C-c C-y}
(@code{vm-yank-message}) inside a mail buffer to include text from any
desired mail message.  This is a more general mechanism for citing
message text in the composed message.  (The composed message does not
have to be a reply.  Neither do the cited messages have to be the
messages you are replying to.)

@cindex attachment button
Citing message text is a tricky business because the original message
could be a @acronym{MIME} message with encoded text or formatted text along with
embedded images and attachments.  By default, VM uses its @acronym{MIME}
displaying mechanism to extract the included text to be cited in
replies.  The quoted text is then similar to what appears in the
message Presentation buffer.  However, the @acronym{MIME} attachments are not
included by default.  They are shown in the message composition buffer
with @b{attachment buttons} labelled similar to:

@example
[DELETED ATTACHMENT mary.jpg, image/jpeg]
@end example

@noindent If you set the variable @code{vm-include-mime-attachments} then
the attachment buttons are converted to actual attachments before the
message is sent.  The format of the button in this case looks like:

@example
[ATTACHMENT mary.jpg, image/jpeg]
@end example

@cindex @acronym{MIME} alternatives
@vindex vm-mime-alternative-yank-method
When citing a @code{multipart/alternative} @acronym{MIME} component, VM
uses the variable @code{vm-mime-alternative-yank-method}
to decide which alternative should be cited.  It can 
be defined in a similar way to the variable
@code{vm-mime-alternative-show-method}. (@pxref{multipart/alternative}.) 

@unnumberedsubsec Filling included text

If the included text contains long lines, i.e., lines longer than the
normal window width, you might want to fill paragraphs.  It is not necessary
to do so.  If you send a message with long lines in it, VM will MIME-encode
the text so that it can be transported reliably and your recipients can use
their own email readers to format the long lines.  Keep in mind also that
only running text should be filled.  Tables, figures and program code have
line breaks that are significant, and they may be destroyed by filling.

@vindex vm-fill-paragraphs-containing-long-lines-in-reply
@vindex vm-fill-long-lines-in-reply-column
You can invoke
automatic filling of paragraphs by setting the variable
@code{vm-fill-paragraphs-containing-long-lines-in-reply}.  Like its
namesake used in message presentation (@pxref{Paging}), it should be
set to a positive numerical value N or the symbol @code{window-width}.
Setting it to @code{nil} disables paragraph filling.  If filling is
used, the fill column is controlled by the variable
@code{vm-fill-long-lines-in-reply-column}.

@findex vm-fill-long-lines-in-reply
You can also invoke the command @code{vm-fill-long-lines-in-reply}
interactively.  It uses the two variables mentioned above to decide when and
how to fill text.  If the
@code{vm-fill-paragraphs-containing-long-lines-in-reply} is @code{nil}, it
assumes that it should fill any lines longer than the current window width. 

Finally, you can fill individual paragraphs manually using
@kbd{C-c C-q} (@code{mail-fill-yanked-message}).

@unnumberedsubsec Alternative methods to include text

The method of @acronym{MIME} decoding for included text is relatively new in VM.
The older methods are the inclusion of plain text, due to Kyle Jones,
and the inclusion of text from the Presentation buffer, due to Robert
Fenk. 

@vindex vm-included-mime-types-list
@vindex vm-include-text-basic
The Kyle Jones method of plain text inclusion is enabled by setting
the variable @code{vm-include-text-basic} to @code{t}.  Setting the
variable to nil returns you to the default behaviour.  You can set the
variable @code{vm-included-mime-types-list} to additional @acronym{MIME}
type/subtype pairs that should be included in cited text.  But it may
not produce good results because the handling of @acronym{MIME} types is not
available in the basic text inclusion method.

@vindex vm-include-text-from-presentation
The Robert Fenk method of text inclusion from the Presentation buffer is
enabled by setting the variable @code{vm-include-text-from-presentation}
to t.  In this case, the text display from the Presentation buffer is
copied verbatim as the quoted text.

@unnumberedsubsec Options

@vindex vm-included-text-attribution-format
The variable @code{vm-included-text-attribution-format} specifies the
format for the attribution of the included text.  The @dfn{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
specification similar to @code{vm-summary-format}.  @xref{Summaries}.  A
@code{nil} value causes the attribution to be omitted.

@vindex vm-included-text-headers
@vindex vm-included-text-discard-header-regexp
VM normally includes only the body text from the cited messages.  If you
wish, you can include also the message headers by customizing
the variables @code{vm-included-text-headers} and
@code{vm-included-text-discard-header-regexp}.

@node Forwarding Messages, Saving copies, Replying, Sending Messages

@section Forwarding Messages

VM has four commands to forward messages: @kbd{z}
(@code{vm-forward-message}), 
@kbd{Z} (@code{vm-forward-message-plain}),
@kbd{@@} (@code{vm-send-digest}) and
@kbd{B} (@code{vm-resend-message}).

@unnumberedsubsec Forwarding

@findex vm-forward-message
@kindex z
Typing @kbd{z} (@code{vm-forward-message}) puts you into a VM Mail
mode buffer just like @kbd{m}, except that the current message appears
as the body of the message in the VM Mail mode buffer.  

@vindex vm-forwarding-digest-type
The forwarded message is encapsulated as specified by the variable
@code{vm-forwarding-digest-type}.  Recognized values are @code{nil}, "mime",
"rfc934" and "rfc1153".  The default is "mime".  

If @code{vm-forwarding-digest-type} is set to @code{nil}, the forwarded
message is not encapsulated.  It is included in a plain text form.  Any
attachments of the original message appear as attachment buttons in the
composition.  They will be replaced by actual attachments when the message
is sent.

@findex vm-forward-message-plain
@kindex Z
The key @kbd{Z} (@code{vm-forward-message-plain}) allows you to use
plain-text forwarding directly, without needing to alter
@code{vm-forwarding-digest-type}.

If you have previously saved any attachments in the messages being
forwarded, those attachments are normally fetched and included in the
forwarded messages.  You can inhibit this by setting the variable
@code{vm-mime-forward-saved-attachments} to @code{nil}.  Messages are then
forwarded with external references to saved attachments.  If the recipients
have access to the file system where attachments are saved, they will still
be able to view them.  (This may be appropriate if the attachemnts are saved
in some shared file space, or if you wish to suppress the attachments in the
forwarded messages.)

@vindex vm-forwarded-headers
@vindex vm-unforwarded-header-regexp
@vindex vm-forwarded-headers-plain
@vindex vm-unforwarded-header-regexp-plain
You can control which header lines are included in forwarded messages via
the variables @code{vm-forwarded-headers} and
@code{vm-unforwarded-header-regexp} (and their counterparts
@code{vm-forwarded-headers-plain} and
@code{vm-unforwarded-header-regexp-plain} for plain-text forwarding).  How
they are used differs based on the form of forwarding used.

@itemize
@item 
For encapsulated forwarding, the default is to forward all
the headers, but you can limit the forwarded headers by setting
@code{vm-unforwarded-header-regexp} to a regular expression.  All the
headers matching the regular expression will be omitted.  If this variable
is set to @code{nil}, then its value is ignored and only the headers listed
in @code{vm-forwarded-headers} are forwarded.
@item
For plain-text forwarding, done by the @kbd{Z} command, the variables
@code{vm-forwarded-headers-plain} and
@code{vm-unforwarded-header-regexp-plain} are used in a similar way.  If the
latter is set to a regular expression, then the headers matching it are
omitted.  Otherwise, only the headers listed in
@code{vm-forwarded-headers-plain} are included.  The default settings
forward only the headers ``From'', ``To'', ``Cc'', ``Subject'', ``Date'' and
``In-Reply-To''. 
@end itemize

@findex vm-forward-message-all-headers
The command @code{vm-forward-message-all-headers} forwards the
message with all headers intact, irrespective of the values of these
variables. 

@vindex vm-forwarding-subject-format
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.  A @code{nil}
value causes the Subject header to be left blank.  The forwarded message
is flagged ``forwarded'' when the message is sent.

@unnumberedsubsec Digests

@findex vm-send-digest
@vindex vm-digest-send-type
@kindex @@
The command @kbd{@@} (@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 VM Mail mode buffer.  Also, @code{vm-send-digest} can
be applied to just marked messages.  @xref{Selecting Messages}.
The message encapsulation method is specified by the
variable @code{vm-digest-send-type}, which accepts the same values as
@code{vm-forwarding-digest-type}.  All the messages included in the digest will
be flagged ``forwarded'' when the digest message is sent.

@vindex vm-digest-preamble-format
@vindex vm-digest-center-preamble
If you give @code{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 @code{vm-digest-preamble-format}
determines the format of the preamble lines.  If the value of
@code{vm-digest-center-preamble} is non-@code{nil}, the preamble lines
will be centered.

@unnumberedsubsec Resending

@findex vm-resend-message
@kindex B
@cindex resending messages
@cindex Resent-To header
You can forward a message ``as is'', without appearing to
intervene, by @dfn{resending} it.
Use  the @kbd{B} (@code{vm-resend-message}) command.  VM will
resend the same original message with its original headers and add
a @samp{Resent-To} header that you should fill in with the new
recipients.  Use @kbd{C-c C-c} as usual to send the message.  The
resent message will be flagged as ``redistributed''.  Note that a
re-sent message will appear to the recipients as if it came from the
original sender.  They will notice that you have re-sent the message
only if they are careful to look for the @code{Resent-To} header.  If
they reply to the message, the reply will go to the original sender.
This behavior can be confusing to many users and, so, should be used
with caution.

@node Saving copies, Personality Crisis, Forwarding Messages, Sending Messages
@section Saving copies of sent mail

@cindex FCC
@cindex file CC
@findex vm-imap-save-composition
You can save copies of outgoing mail messages in 'sent' folders by
adding an @samp{FCC:} header line to the composed message.  The value
of the header should be either the full path name of a mail folder on
the file system or the maildrop specification of a folder on an @acronym{IMAP}
server.  If you use @acronym{IMAP} folders for saving sent mail, you should also
add the function @code{vm-imap-save-composition} to the mail-mode's
@code{mail-send-hook} variable.

@cindex @acronym{IMAP}-FCC
@vindex vm-imap-default-account
If you have multiple @acronym{IMAP} accounts, you might wish to save copies of
your replies separately in each @acronym{IMAP} account.  This can be done by
adding an @samp{@acronym{IMAP}-FCC:} header line.  The value of the header field
should be a plain folder name on the ``current'' @acronym{IMAP} account, e.g.,
`Sent'.  The ``current'' @acronym{IMAP} account will be determined by the @acronym{IMAP}
folder from which you start composing the new message (which is called
the ``parent folder'' for you composition).  If the parent folder is
not an @acronym{IMAP} folder or if there is no parent folder, then the message
copy will be saved in a folder on @code{vm-imap-default-account}.

@vindex vm-do-fcc-before-mime-encode
The variable @code{vm-do-fcc-before-mime-encode} allows you save the fcc
copy to the sent folder @i{before} mime-encoding the message.  This is
useful if you want to save an unencrypted version of the message or
avoid saving attachments.  However, the character coding of the sent
folder should be chosen carefully to allow proper storage of the
messages.

@node Personality Crisis, Postponing Messages, Saving copies, Sending Messages
@section Personality Crisis: Programmable customization of message composition
@cindex vmpc
@cindex Personality Crisis

Personality Crisis (also known as ``vm-pcrisis'') is a powerful
feature that allows you to automatically customize message
compositions based on their parent messages.  The most immediate application
is for composing replies where, for instance, you might want
to set the ``From:'' header of the outgoing message to be the same as the
email address at which you received the message.  This matters clearly if
you have multiple email accounts.

To use Personality Crisis, place the following in your @code{vm-init-file}:

@lisp
(require 'vm-pcrisis)
@end lisp

@findex vmpc-my-identities
As a quick start, you can add a line to define your email identities:

@lisp
(vmpc-my-identities "me@@work.com" "me@@home.net" "me@@other.org")
@end lisp

@noindent This sets up each email address as a ``From'' header option.  When
you compose a message to an unknown recipient, Personality Crisis will prompt you to
choose which identity to use.  For more control, use the condition-action
rules described below.

@vindex vmpc-conditions
@vindex vmpc-actions
Personality Crisis is based on condition-action rules.  You define a variable
@code{vmpc-conditions} to contain a collection of named conditions that you
can test for in the parent message, and a variable @code{vmpc-actions} to
contain a collection of name actions that you can perform on the outgoing
message.  These take the form:

@example
(set-variable 'vmpc-conditions
              '(("condition-name1" @var{condition})
                ("condition-name2" @var{condition})
                ...))
(set-variable 'vmpc-actions
              '(("action-name1" @var{action}...)
                ("action-name2" @var{action}...)
                ...))
@end example

Then, you can set the following variables to contain
a collection of condition-action rules, each of which is of the form:

@example
(@var{CONDITION-NAME} @var{ACTION-NAME1} @var{ACTION-NAME2}...)
@end example
@table @code
@vindex vmpc-default-rules
@item vmpc-default-rules
@vindex vmpc-reply-rules
@vindex vmpc-forward-rules
@vindex vmpc-resend-rules
@vindex vmpc-mail-rules
Condition-action rules for composing messages based on a parent message,
such as replying, forwarding, resending and mailing
(@pxref{vm-mail-from-folder}).

There are also specialized variables @code{vmpc-reply-rules},
@code{vmpc-forward-rules}, @code{vmpc-resend-rules} and
@code{vmpc-mail-rules}, which can override the general default rules in
@code{vmpc-default-rules}.

@vindex vmpc-newmail-rules
@item vmpc-newmail-rules
Condition-action rules for new message compositions with no parent message.
(@pxref{vm-mail}).

@vindex vmpc-automorph-rules
@item vmpc-automorph-rules
Condition-action rules for message compositions based on their own content
(called ``automorphing'').
@end table

The @i{conditions} are typically checked in the ``parent folder'' of a mail
composition, which may be the message you are responding to, forwarding,
resending etc.  Personality Crisis provides a collection of useful condition-checking
functions.  Others can be defined as needed.

@table @code
@findex vmpc-header-match
@item vmpc-header-match
This condition checks if a header field of the message matches a regular
expression pattern.  For example, the condition

@example
(vmpc-header-match "To\\|Cc" (regexp-quote "me@@myisp.net"))
@end example

@noindent checks if either the ``To'' or ``Cc'' header contains the pattern
@code{me@@myisp.net}.

@findex vmpc-only-from-match
@item vmpc-only-from-match
This is similar to @code{vmpc-header-match}, but assumes that the header
field contains email addresses, and matches every one of the email addresses
against the regular expression pattern.  For example, the condition

@example
(vmpc-only-from-match "To\\|Cc" (regexp-quote "@@mycompany.com"))
@end example

@noindent if every email address in the ``To'' and ``Cc'' headers is at
@code{mycompany.com}.

@findex vmpc-body-match
@item vmpc-body-match
This condition checks if the body of the message contains the
given regular expression pattern.

@findex vmpc-folder-match
@item vmpc-folder-match
This condition checks if the name of the folder contains the
given regular expression pattern.

@findex vmpc-folder-account-match
@item vmpc-folder-account-match
This condition checks if the @acronym{POP}/@acronym{IMAP} account of the
folder contains the given regular expression pattern.

@findex vmpc-check-virtual-selector
@item vmpc-check-virtual-selector
(This function is provided by the @code{vm-avirtual} package.)  This
condition checks if the message matches a given virtual selector.

@findex vmpc-other-cond
@item vmpc-other-cond
This condition returns true if another named condition (defined earlier
in @code{vmpc-conditions}) evaluated to true.  This allows building
complex conditions from simpler ones.

@findex vmpc-none-true-yet
@item vmpc-none-true-yet
This condition returns true if none of the conditions that came before it
in @code{vmpc-conditions} have returned true.  This is useful as a fallback
to prompt for a profile when no other conditions match.
@end table

@noindent The conditions are just normal functions.  So, you can combine
them with connectives like @code{and}, @code{or} and @code{not}, and add
other functions that are defined in Emacs or VM or new functions of your
own.

The @i{actions} are typically executed in the mail composition buffer for
the message you are composing.

@table @code
@findex vmpc-substitute-header
@item vmpc-substitute-header
This action substitutes a specified header field of the outgoing message
with a given string.  For example, the action

@example
(vmpc-substitute-header "From" "me@@myisp.net")
@end example

@noindent sets the ``From'' header of the outgoing message to
@code{me@@myisp.net}.

@findex vmpc-add-header
@item vmpc-add-header
This action adds a specified header field to the outgoing message
with a given string.  If the header field already exists, nothing is done.

@findex vmpc-insert-header
@item vmpc-insert-header
This action appends a given string to a specified header field of the
outgoing message.

@findex vmpc-delete-header
@item vmpc-delete-header
This action deletes a specified header field of the outgoing message
with a given string.  Either the contents of the header field or the header
itself can be deleted.

@findex vmpc-signature
@item vmpc-signature

The action @code{(vmpc-signature "signature-file")} inserts the signature
from @code{signature-file}.  If there is already a signature in the outgoing
message, then it replaces with the new signature.

@findex vmpc-pre-signature
@item vmpc-pre-signature
This action is similar to @code{vmpc-signature}, but inserts the new
signature at the top, above the message body.

@findex vmpc-substitute-replied-header
@item vmpc-substitute-replied-header
This action takes a header value from the message being replied to and
inserts it as a header in the reply.  For example:

@example
(vmpc-substitute-replied-header "To" "From")
@end example

@noindent copies the ``From'' header of the original message to the ``To''
header of the reply.

@findex vmpc-pre-function
@item vmpc-pre-function
This action evaluates a Lisp expression before VM creates the mail
composition buffer.  This is useful for setting VM variables that need
to be set early, such as message encoding.

@findex vmpc-composition-buffer
@item vmpc-composition-buffer
This action evaluates a Lisp expression in the composition buffer.
Use this to set buffer-local variables or call functions that need the
composition buffer to exist.

@findex vmpc-prompt-for-profile
@item vmpc-prompt-for-profile
This action prompts the user to choose a profile (action) to run.
With an optional argument, it can remember the choice for future messages
to the same recipient:

@example
(vmpc-prompt-for-profile)        ; prompt but don't remember
(vmpc-prompt-for-profile t)      ; prompt and remember automatically
(vmpc-prompt-for-profile 'prompt) ; prompt and ask whether to remember
@end example
@end table

@subsection Automorph

@findex vmpc-automorph
The @code{vmpc-automorph} function automatically customizes a mail
composition based on its current headers.  This is useful for new mail
compositions where you want to set up headers, signatures, etc. based on
the ``To'' address you have typed.

To use automorph, bind it to a key in @code{vm-mail-mode-map}:

@lisp
(define-key vm-mail-mode-map [f7] 'vmpc-automorph)
@end lisp

@noindent Or attach it to moving between headers:

@lisp
(define-key vm-mail-mode-map [tab] 'vmpc-tab-header-or-tab-stop)
@end lisp

@subsection Debugging Personality Crisis

To debug Personality Crisis configurations, examine these variables after composing
a message:

@itemize @bullet
@item @code{vmpc-true-conditions} --- the list of conditions that evaluated to true
@item @code{vmpc-actions-to-run} --- the list of actions that will be executed
@end itemize

You can also call @code{vmpc-build-true-conditions-list} interactively
to test your conditions.

@node Postponing Messages,, Personality Crisis, Sending Messages
@section Postponing Messages
@cindex vm-postpone
@cindex postponing message composition
Sometimes, you might want to interrupt the composing of a message and
continue it later.  This is called @dfn{postponing}.

@findex vm-postpone-message
@kindex C-c C-d
@vindex vm-postponed-folder
In a message composition buffer, the command @key{C-c C-d}
(@code{vm-postpone-message})
postpones the current composition.  The postponed message is stored in the
folder specified in @code{vm-postponed-folder}.   (The default is a folder
called ``postponed'').   When called with a prefix argument,
@code{vm-postpone-message} will ask you for the folder to save the draft
to.  You might also save it to your inbox in this way.

@findex vm-continue-postponed-message
You can continue composing the postponed messages by visiting
@code{vm-postponed-folder}, selecting a message and running @kbd{M-x
vm-continue-postponed-message}.  This constructs a new message composition
buffer by copying the text from the VM Presentation buffer.  It also
converts any @acronym{MIME} buttons into attachment buttons, which will be encoded as
valid @acronym{MIME} attachments when the message is sent.  Unfortunately, any
attachments that are displayed inline in the Presentation buffer will not be
encoded.  This is a limitation of this feature.

@vindex vm-auto-expunge-postponed-folder
When you continue composition of a postponed message and send it, its
previous draft is still retained in the postponed folder. To expunge such
drafts automatically set @code{vm-auto-expunge-postponed-folder} to @code{t}
in your VM configuration file.

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

In the following sections, you will see various operations that you can do
on messages such as saving, deleting or running external applications.  All
such operations work on either single messages or collections of
messages you can select using VM's features.  The mechanisms for selecting
collections of messages for operations are described in this section.

@cindex prefix argument
All VM operations take a prefix argument, which may be a positive integer,
negative integer or 0.  If it is a positive integer @var{n}, then the
current message and the next @var{n-1} are selected for the operation.  If
it is a negative integer @var{-n}, then the current message and the previous
@var{n-1} are selected.  If it is @var{0}, then all the messages in the
current folder are selected.

When you have thread-folding enabled, you can execute VM operations on
entire threads in the Summary window.  @xref{Thread Operations}.

In addition, a collection of messages can be explicitly marked for the
purpose of operating on them.

@menu
* Marking Messages::    Marking messages for operations.
@end menu

@node Marking Messages, , Selecting Messages, Selecting Messages
@section Marking Messages

@cindex marking
@cindex searching
@cindex virtual folders
VM provides a way to @dfn{mark} selected messages so that subsequent
operations can be applied to them.  This is similar to marking in other
parts of Emacs, e.g., @pxref{Marks vs Flags, Dired Marks, Dired Marks,
emacs}, but arguably more powerful.  For example, one can mark all
messages from a particular sender and save them to a folder, or mark all
messages with a particular subject and print them.  One can also mark
messages by searching for particular strings in their text.

@kindex M M
To mark the current message, type @kbd{M M}
(@code{vm-mark-message}).  If you give a numeric prefix argument
@var{n}, the next @var{n-1} messages will be marked as well.  A negative
prefix argument means mark the previous @var{n-1}.  An asterisk
(@samp{*}) will appear to the right of the message numbers of all marked
messages in the summary window.

@kindex M U
To remove a mark from the current message, use @kbd{M U}
(@code{vm-unmark-message}).  Prefix arguments work as with
@code{vm-mark-message}.

@kindex M m
@kindex M u
Use @kbd{M m} to mark all messages in the current folder; @kbd{M u}
removes marks from all messages.

Other marking commands:

@table @kbd
@findex vm-mark-messages-by-selector
@kindex M C
@item M C (@code{vm-mark-messages-by-selector})
Mark all messages matching a virtual selector.
@xref{Virtual Folders}.
@findex vm-unmark-messages-by-selector
@kindex M c
@item M c (@code{vm-unmark-messages-by-selector})
Unmark all messages matching a virtual selector.
@findex vm-mark-messages-by-virtual-folder
@kindex M X
@item M X (@code{vm-mark-messages-by-virtual-folder})
Mark all messages matching the selectors of a virtual folder.
@xref{Virtual Folders}.
@findex vm-unmark-unmark-messages-by-virtual-folder
@kindex M x
@item M x (@code{vm-unmark-messages-by-virtual-folder})
Unmark all messages matching the selectors of a virtual folder.
@findex vm-mark-thread-subtree
@kindex M T
@item M T (@code{vm-mark-thread-subtree})
Mark all messages in the thread tree rooted at current message.
@xref{Threading}.
@findex vm-unmark-thread-subtree
@kindex M t
@item M t (@code{vm-unmark-thread-subtree})
Unmark all messages in the thread tree rooted at current message.
@findex vm-mark-messages-same-subject
@kindex M S
@item M S (@code{vm-mark-same-subject})
Mark messages with the same subject as the current message.
@findex vm-unmark-messages-same-subject
@kindex M s
@item M s (@code{vm-unmark-same-subject})
Unmark messages with the same subject as the current message.
@findex vm-mark-messages-same-author
@kindex M A
@item M A (@code{vm-mark-same-author})
Mark messages with the same author as the current message.
@findex vm-unmark-messages-same-author
@kindex M a
@item M a (@code{vm-unmark-same-author})
Unmark messages with the same author as the current message.
@end table

While the above commands can be used in any VM buffer, the following
commands can be used in a Summary buffer to mark or unmark a region of
message summary lines.

@table @kbd
@findex vm-mark-summary-region
@kindex M R
@item M R (@code{vm-mark-summary-region})
Mark all messages in the current region in a Summary buffer
@findex vm-unmark-summary-region
@kindex M r
@item M r (@code{vm-unmark-summary-region})
Unmark all messages in the current region in a Summary buffer
@end table

To apply a VM command to all marked messages you must prefix it with the
key sequence @kbd{M N} (@code{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.  Unfortunately,
as of this writing, this mechanism works only if the next command
invoked is a keyboard command.  Commands invoked by @kbd{M-x} are
unable to access the marked messages.  So, to invoke a complex command,
you might temporarily bind it to an unused key, e.g.,

@example
M-x local-set-key C vm-forward-message-all-headers
M N C
@end example

@noindent forwards marked messages with all headers included.

It is possible to use marking to execute operations on message
threads.  For example, the sequence of key strokes:

@example
MuMTMNsMu
@end example

@noindent saves a thread of messages.  However, there are faster methods to
operate on message threads.  @xref{Thread Operations}.

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

@cindex file locking
Mail messages are normally saved to files that contain only mail
messages.  Such files are called @dfn{folders}.  Folders are
distinguished from spool files in that VM does not expect other
programs to modify them while VM is visiting them.  This is
important to remember.  VM does no locking of folders when
visiting them.  If the disk copy of a folder is modified behind
VM's back, Emacs will complain with the dreaded ``File changed
on disk'' message when you try to save the folder.

@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.  It can be given a prefix argument @var{n} to indicate how
many messages should be saved.  Messages saved with
@code{vm-save-message} are flagged ``filed''.

@vindex vm-folder-directory
@vindex vm-thunderbird-folder-directory
Messages can be saved to folders on the local file system or to
folders on an @acronym{IMAP} server.
If @code{vm-folder-directory} 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.   If
@code{vm-thunderbird-folder-directory} is set and you enter a Thunderbird
folder using @code{vm-visit-thunderbird-folder}, then that directory
will be the default place for saving messages.

@vindex vm-auto-folder-alist
Another aid to selecting folders in which to save mail is the variable
@code{vm-auto-folder-alist}, described in detail below.  Using the data
given in this alist, VM can examine the headers of the message and
automatically suggest an appropriate save folder where the message
should be saved.

@vindex vm-imap-save-to-server
@cindex @acronym{IMAP}
If you use an @acronym{IMAP} server and prefer to save messages on other folders
on the same @acronym{IMAP} server, you can set the variable
@code{vm-imap-save-to-server} to t.  You will be prompted for the name
of the @acronym{IMAP} folder in which to save the message.  The variable
@code{vm-auto-folder-alist} can also be used to suggest appropriate save
folders on the @acronym{IMAP} server.

@findex vm-save-message-to-local-folder
@findex vm-save-message-to-imap-folder
You can override the effect of @code{vm-imap-save-to-server} by using
the specialized commands @code{vm-save-message-to-local-folder}
and @code{vm-save-message-to-imap-folder}, which do what their names
indicate. 

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


@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 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 value of @code{t} causes VM to always
visit a folder before saving message to it.  A @code{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 @code{vm-visit-when-saving} is
not @code{nil} and not @code{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.

@vindex vm-delete-after-saving
@vindex vm-delete-after-archiving
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 flag messages for deletion automatically after
saving them.  This applies only to saves to folders, not for the @kbd{w}
command.  There is a separate variable
@code{vm-delete-after-archiving}, which
works like @code{vm-delete-after-saving} but applies to the @kbd{A}
(@code{vm-auto-archive-messages}) command (see below).

@unnumberedsec Automatic save folders

@cindex save folders
VM can automatically suggest folders for saving messages, using rules that
you specify.  It saves the work of having to type in a folder for saving
messages. 

@vindex vm-auto-folder-alist
@vindex vm-save-using-auto-folders
The variable @code{vm-auto-folder-alist} is used to specify pattern-matching
rules by which VM determines the save folder for a message.  It is also
possible to specify rules using virtual folder selectors.
@xref{vm-virtual-auto-folder-alist}.  The suggestion of save folders via
both the methods can be turned on or off using the variable
@code{vm-save-using-auto-folders}.  (Its default value is @code{t}.)

The value of @code{vm-auto-folder-alist} should be a
list of the form:

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

@noindent 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.  The value of @var{folder-name} can be 

@itemize
@item 
the absolute path name of a local folder,
@item 
a relative path name -- relative to @code{vm-folder-directory} or the
@code{default-directory} of the currently visited folder, whichever is
non-nil, or
@item
the maildrop specification of an @acronym{IMAP} folder.
@end itemize

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.  

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
@code{buffer-substring} to build a folder name based on the header information.
If the result of evaluating @var{folder-name} is a list, then the list will
be treated as another auto-folder-alist and will be descended
recursively.

@vindex vm-auto-folder-case-fold-search
Whether matching is case-sensitive depends on the value of the variable
@code{vm-auto-folder-case-fold-search}.  A non-@code{nil} value makes
matching case-insensitive.  The default value is @code{t}, which means
matching is case-insensitive.  Note that the matching of header names is
always case-insensitive because the Internet message standard RFC 822
specifies that header names are case indistinct.

@unnumberedsec Other commands

@table @kbd
@findex vm-save-message-sans-headers
@item M-x 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 flagged ``written''.
@findex vm-auto-archive-messages
@kindex A
@vindex vm-confirm-for-auto-archive
@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.  Messages that
are flagged for deletion are not saved by this command.  This command asks
for confirmation before archiving because it is a wholesale operation that
cannot be easy reversed.  (Set @code{vm-confirm-for-auto-archive} to
@code{nil} to override the confirmation dialogue.)  If the command is
invoked with a 
prefix argument, confirmation will be requested for each save.
@findex vm-pipe-message-to-command
@kindex ||
@item || (@code{vm-pipe-message-to-command})
Runs a shell command with some or all of the current message as input.
By default, the entire message is used.  However, the leading and
trailing message separator lines are not included.  When applied to
multiple messages, the command is invoked on each message individually.@* 
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.@*
In invoked with three @t{C-u}'s the visible headers and the text
portions of the message are used.@*
If the shell command generates any output, it is displayed in a
@samp{*Shell Command Output*} buffer.  The message itself is not altered.
@findex vm-pipe-message-to-command-discard-output
@kindex |d
@item |d (@code{vm-pipe-message-to-command-discard-output})
Runs a shell command with some or all of the current message as input,
like the above, but will not display the output.
@findex vm-pipe-messages-to-command
@vindex vm-pipe-messages-to-command-start
@vindex vm-pipe-messages-to-command-end
@kindex |s
@item |s (@code{vm-pipe-messages-to-command})
Runs a shell command using as input the current message or marked
messages in the mbox format.  In contrast to
@code{vm-pipe-message-to-command}, the leading and trailing separator
lines are included.  This behaviour can be altered using the variables
@code{vm-pipe-messages-to-command-start} and
@code{vm-pipe-messages-to-command-end}. 
@findex vm-pipe-messages-to-command-discard-output
@kindex |n
@item |n (@code{vm-pipe-messages-to-command-discard-output})
Runs a shell command using as input the current message or marked
messages in the mbox format, but will not display the output.
@end table

@vindex vm-berkeley-mail-compatibility
A non-@code{nil} value of @code{vm-berkeley-mail-compatibility}
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}.


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

In VM, messages are flagged 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.

@table @kbd
@findex vm-delete-message
@kindex d
@item d (@code{vm-delete-message})
Flags the current message for deletion.  A prefix argument @var{n}
causes the current message and the next @var{n-1} messages to be flagged.
A negative @var{n} causes the current message and the previous @var{n-1}
messages to be flagged.
@findex vm-undelete-message
@kindex u
@item u (@code{vm-undelete-message})
Removes the deletion flag from the current message.  A prefix argument @var{n}
causes the current message and the next @var{n-1} messages to be undeleted.
A negative @var{n} causes the current message and the previous @var{n-1}
messages to be undeleted.
@findex vm-kill-subject
@kindex k
@item k (@code{vm-kill-subject})
Flags all messages with the same subject as the current message (ignoring
``Re:'') for deletion.
@findex vm-kill-thread-subtree
@kindex K
@item K (@code{vm-kill-thread-subtree})
Flags all messages in the thread subtree of the current message for
deletion. 
@findex vm-delete-duplicate-messages
@item @code{vm-delete-duplicate-messages}
Flags duplicate messages for deletion.  The duplicate messages are
detected by comparing message ID's.
@findex vm-delete-duplicate-messages-by-body
@item @code{vm-delete-duplicate-messages-by-body}
Flags duplicate messages for deletion.  The duplicate messages are
detected by comparing message bodies.
@findex vm-expunge-folder
@findex vm-compact-folder
@kindex ###
@item ### (@code{vm-expunge-folder}, @code{vm-compact-folder})
Does the actual removal of messages flagged for deletion in the current
folder.
@end table

@vindex vm-move-after-deleting
@vindex vm-move-after-killing
@vindex vm-move-after-undeleting
Setting the variable @code{vm-move-after-deleting} non-@code{nil} causes
VM to move past the messages after flagging them for deletion.  Setting
@code{vm-move-after-undeleting} non-@code{nil} causes similar movement
after undeletes.  Setting @code{vm-move-after-killing} non-@code{nil}
causes VM to move after killing messages with @code{vm-kill-subject}.
Note that the movement is done by calling @code{vm-next-message} which
means that the value of @code{vm-circular-folders} applies to the
post-command motion as for a motion command, not as for a non-motion
command.

@vindex vm-expunge-before-save
@vindex vm-expunge-before-quit
Normally, deleted messages are preserved in folders until an explicit
@code{vm-expunge-folder} (@code{vm-compact-folder}) operation is done.  This
default behavior can be altered by setting the variables
@code{vm-expunge-before-save} and @code{vm-expunge-before-quit}.  If
@code{vm-expunge-before-save} is set to non-@code{nil}, then deleted
messages are expunged whenever a folder is saved.  This is not an undo-able
operation and no confirmation is asked for.  So you should use this setting
only if your normal workflow includes expunging messages as part of save.
The variable @code{vm-expunge-before-quit} can be similarly set to
non-@code{nil} to cause VM to expunge deleted messages whenever you quit the
folder.

@findex vm-save-folder-no-expunge
@findex vm-quit-no-expunge
The commands @code{vm-save-folder-no-expunge} and
@code{vm-quit-no-expunge} can be used to preserve deleted messages in
the saved folders, irrespective of the settings of the above
variables.  Giving a prefix argument to the @code{vm-quit} command has
the same effect as @code{vm-quit-no-expunge}.

@findex vm-delete-duplicate-messages
The function @code{vm-delete-duplicate-messages} can be used to delete
duplicate copies of messages that arrive through various means.  For
instance, if you are a member of a mailing list, every time somebody
responds to one of your messages, they might send the response to you
as well as the mailing list.  You then receive two copies of the
response.  If you get a lot of such duplicate copies, you might
consider invoking @code{vm-delete-duplicate-messages} automatically.
For instance, the customization in your VM init file can have:

@example
(add-hook 'vm-arrived-messages-hook 'vm-delete-duplicate-messages)
@end example

@noindent This causes the duplicate-deletion function
to be invoked every time new messages arrive so that you don't have to
worry about the duplicate copies any further.  (@xref{Hooks}.)


@node Editing Messages, Message Attributes, Deleting Messages, Top
@chapter Editing Messages

@kindex C-c C-e
@findex vm-edit-message
To edit a message, type @kbd{C-c C-e} (@code{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 @code{vm-edit-message-mode}.  The default is Text mode.

@kindex C-c ESC
@findex vm-edit-message-end
@kindex C-c C-]
@findex vm-edit-message-abort
Use @kbd{C-c ESC} (@code{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 @kbd{C-c C-]}
(@code{vm-edit-message-abort}), or you can just kill the edit buffer
with @kbd{C-x k} (@code{kill-buffer}).

If you give a prefix argument to @code{vm-edit-message}, then the
current message will be flagged unedited.

As with VM Mail mode buffers, all VM commands can be accessed from
the edit buffer through the command prefix @kbd{C-c C-v}.

@node Message Attributes, Sorting Messages, Editing Messages, Top
@chapter Message Attributes
@cindex message attributes

Each message in a folder has a set of attributes that VM will remember
from session to session.  Various VM commands set and unset these
attributes.  Here are the attributes maintained by VM.

@table @code
@item new
The message was retrieved from a spool file during this
visit of the current folder.
@item unread
The message was retrieved from a spool file during some
past visit of the folder but is still unread.
@item filed
The message has been saved to some folder.
@item written
The body of the message has been saved to a file.
@item edited
The message has been altered (with @code{vm-edit-message}) since it arrived.
@item deleted
The message is deleted and will be removed from the folder
at the next expunge.
@item forwarded
The message has been forwarded with either
@code{vm-forward-message}, @code{vm-send-digest} or one of their variants.
@item redistributed
The message has been forwarded with the
@code{vm-resend-message} command.
@item replied
The message has been replied to.
@end table

@findex vm-set-message-attributes
You can set and unset these attributes directly by using 
@code{M-x vm-set-message-attributes}.  You will be prompted in the
minibuffer for names of the attributes and you can enter them with
completion.  Every attribute has an ``un-'' prefixed name you can use
to unset the attribute, excepting ``new'' and ``unread'', which are both
negated by ``read''.  You can use a prefix argument with this command to
affect multiple messages, and you can apply this command to marked
messages with @kbd{M N}.

@findex vm-undo
@kindex C-x u
@kindex C-_
@cindex undo
VM provides a special form of undo which allows changes to message
attributes to be undone.  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 undo's themselves become undoable
by subsequent invocations of @code{vm-undo}.

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

@findex vm-add-message-labels
@findex vm-delete-message-labels
@kindex l a
@kindex l d
@cindex message labels
@dfn{Labels} are user-defined message attributes.  They can have any
name and be assigned any meaning by you.  Labels are added with
@kbd{l a} (@code{vm-add-message-labels} and @kbd{l e}
(@code{vm-add-existing-message-labels}, and are removed by @kbd{l d}
(@code{vm-delete-message-labels}).  BABYL format folders use labels to
store basic attributed like ``deleted'' and ``unread''.  When visiting a
BABYL folder VM uses these labels also in order to be compatible with
other BABYL mailers.  The labels used are ``recent'', ``unseen'',
``deleted'', ``answered'', ``forwarded'', ``redistributed'', ``filed'',
``edited'' and ``written''.  If (and only if) you are using BABYL format
folders, you should not use these label names for your own purposes.

@findex vm-expunge-label
To completely remove a label from a folder, use @kbd{M-x vm-expunge-label}.
This removes the label from all messages that have it and also removes
it from the folder's label list, so it will no longer appear in label
completions.  This operation can be undone with @code{vm-undo}.

@vindex vm-flush-interval
@cindex auto-save
All message attributes are stored in the folder.  In order for
attribute changes to be saved to disk, they must be written to
the folder's buffer prior to the buffer being saved.  The
variable @code{vm-flush-interval} controls how often that is done.  A
value of @code{t} means write the new attributes to the folder
buffer whenever a change occurs.  A value of @code{nil} means
wait until just before the folder is saved before writing out the
attributes.  VM will work faster with this setting, but if Emacs
or your system crashes, the auto-save file will contain no useful
data pertaining to message attribute changes.  The auto-save file
will still reflect message edits and expunges.  @xref{Crash
Recovery}.  A positive integer value @var{n} instructs VM to write
out attribute changes every @var{n} seconds.  The default value
of this variable is @code{t}.

@node Sorting Messages, Digests, Message Attributes, Top
@chapter Sorting Messages

@cindex sorting
@findex vm-sort-messages
@vindex vm-move-messages-physically
@kindex G
In order to make numerous related messages easier to cope with, VM
provides the command @kbd{G} (@code{vm-sort-messages}), which sorts
all messages in a folder using one or more sort keys.
By default the actual order of the messages in the folder is not
altered; that is, if you looked at the folder file outside of VM the
message order would be unchanged.  VM numbers and presents the messages
in a different order internally.  If you want the message order to be
changed in the folder so that other programs can see the change, you
can either invoke @code{vm-sort-messages} with a prefix argument, or
you can set @code{vm-move-messages-physically} non-@code{nil} before
sorting.  Either way, VM will shift the actual messages around in the
folder buffer, and when you save the folder, the order change will be
visible to other programs.

@cindex spam
Valid sort keys are:
@multitable @columnfractions 0.35 0.60
@item date @tab reversed-date
@item activity @tab reversed-activity
@item author @tab reversed-author
@item subject @tab reversed-subject
@item recipients @tab reversed-recipients
@item line-count @tab reversed-line-count
@item byte-count @tab reversed-byte-count
@item physical-order @tab reversed-physical-order
@item spam-score @tab reversed-spam-score
@end multitable

@cindex delivery date
@vindex vm-sort-messages-by-delivery-date
The sort key @code{date} represents the date and time of the message.
Normally, this is the date when the message was sent by the sender.  Note
that the message could have been ``queued'' after it was sent, either on the
sender's machine, on some server on the network, or in a mailing list
moderator's tray.  It is not uncommon for messages to arrive much later than
their sent date.  Setting the variable
@code{vm-sort-messages-by-delivery-date} to @code{t} causes VM to use the
delivery dates of messages rather than sent dates for sorting purposes.
(This assumes that your own mail server records the delivery date in a
@samp{Delivery-Date} header.  If no such header is present, then VM uses the
sent date.)

The sort key @code{activity} represents the date of the most recent
activity.  This is the default sort order used with threads.
@xref{Threading}.  It allows even old threads that have recent messages to
be brought to the front.

@vindex vm-subject-ignored-prefix
@vindex vm-subject-ignored-suffix
When sorting by subject (or threading using subjects, or killing
messages by subject) the subject of the message is
@dfn{normalized} before comparisons are done.  A @dfn{normalized}
subject has uninteresting prefixes and suffixes stripped off, and
multiple consecutive white space characters are collapsed to a single
space.  The variable @code{vm-subject-ignored-prefix} should be
a regular expression that matches all strings at the beginning of
a subject that you do not want to be considered when message
subjects are compared.  A @code{nil} value means VM should not ignore
any prefixes.  The analogous variable for subject suffixes is
@code{vm-subject-ignored-suffix}.  By default,
@code{vm-subject-ignored-prefix} is set to remove the prefix ``Re:'', which
is often added in replying to messages.  The default value of
@code{vm-subject-ignored-suffix} is set to remove the suffix ``(fwd)'',
which is sometimes added when messages are forwarded.

@cindex subject tags
@vindex vm-subject-tag-prefix
@vindex vm-subject-tag-prefix-exceptions
In addition to these uninteresting prefixes/suffixes, you also have the
option of removing @dfn{subject tags} that are added by mailing lists when
forwarding messages to members.  For example, the @samp{viewmail-info}
mailing list adds the subject tag ``[VM]'' at the beginning of each subject
line.  Bug report handling systems often add tags indicating reference
numbers, e.g., a tag of the form ``bug#nnnn'' added by the
Gnu Emacs bug reports system.  To remove such subject tags, set the variable
@code{vm-subject-tag-prefix} to a regular expression that matches all
subject tags you want removed.  For example, the setting

@example
(setq vm-subject-tag-prefix "\\[[^]][ \n\t]*")
@end example

@noindent asks VM to strip all subject tags enclosed in square brackets
(along with the white space following them).  The default value of
@code{vm-subject-tag-prefix} is nil.  The additional variable
@code{vm-subject-tag-prefix-exceptions} can specify a regular expression
pattern whose matching subject tags are @i{not} removed.

@vindex vm-summary-strip-subject-tags
In addition to ignoring subject tags during sorting, you can also ask VM to
remove subject tags from the summary lines in the Summary buffer.
The variable @code{vm-summary-strip-subject-tags} should be set to a non-nil
value to achieve this effect.

@vindex vm-subject-significant-chars
Once the subject has been normalized, the variable
@code{vm-subject-significant-chars} controls how much of what
remains is considered significant for matching purposes.  The
first @code{vm-subject-significant-chars} will be considered
significant.  Characters beyond this point in the subject string
will be ignored.  A @code{nil} value for this variable means all
characters in the subject are significant.

@vindex vm-spam-score-headers
@cindex spam
The sorting by @code{spam-score} is done by extracting spam scores
listed in the headers of the message, which are usually placed there by
external spam scoring programs such as SpamAssassin.  Spam scores are
expected to be numbers, either integers or real numbers.  The headers
that should be used for extracting spam scores are listed in the variable
@code{vm-spam-score-headers}.  The variable is a list of triples, where each
triples contains a regular expression identifying the name of the header, a
regular expression matching the spam-score string on that header and a
function that VM can invoke to convert the spam-score string to a number.
Here is an example triple:

@example
("X-Spam-Status:" "[-+]?[0-9]*\\.?[0-9]+" string-to-number)
@end example

@noindent This triple causes VM to extract a spam-score from
@code{X-Spam-Status} headers.  The first string on the header line that
matches the second regular expression is extracted and converted to a number
using the @code{string-to-number} function.  The order in which the headers
are listed in @code{vm-spam-score-headers} is significant.  The first header
that is found in the message is used as the spam score.

If you want to move messages around by hand, use @kbd{C-M-n}
(@code{vm-move-message-forward}) and @kbd{C-M-p}
(@code{vm-move-message-backward}).  The default is to move the current
message forward or backward by one message in the message list.  A
prefix argument @var{n} can specify a longer move.  The value of
@code{vm-move-messages-physically} applies to these commands.

@menu
* Threading::   Using subjects and message IDs to group messages.
@end menu

@node Threading,, Sorting Messages, Sorting Messages
@section Threading
@cindex threading
A @dfn{thread} is a group of messages that are either related by subject
or that have a common ancestor.  @dfn{Threading} is the process of
determining the relationship between such messages and displaying them so
that those relationships are evident.

@findex vm-toggle-threads-display
@vindex vm-summary-thread-indent-level
@vindex vm-summary-maximum-thread-indentation
To enable and disable threading, type @kbd{C-t}
(@code{vm-toggle-threads-display}).  You will find that, in the
summary buffer, all related messages are grouped together and the
subject titles are indented to show hierarchical relationships.

@vindex vm-thread-using-subject
@cindex header: References
@cindex header: In-Reply-To
@cindex header: Subject
Message relationships are discovered by examining the
@code{References}, @code{In-Reply-To}, and @code{Subject} headers.
The first two headers are more reliable sources of information but not
all mailers provide them.  Therefore, all messages with similar
@code{Subject} headers are also grouped into threads.  If you don't
want VM to use Subject headers for threading, set the variable
@code{vm-thread-using-subject} to @code{nil}.

Unlike in previous versions of VM, threading is not a form of sorting.
You can sort threads by the usual sort keys and the sort order will
apply to at least the root messages of threads.  Sorting threads by
subject, for instance, can be a quick way to find threads with similar
subject lines.  Sorting them by date would sort them chronologically
according to when the threads were initiated.  Sorting them by activity
is a variant of the chronological order where the dates of latest
activity are given prominence instead of the dates of the initial
messages. 

@vindex vm-sort-subthreads
Normally, thread-based grouping applies to entire threads as well as
all their subthreads.  You can block subthread grouping by
setting the variable @code{vm-sort-subthreads} to @code{nil}.  In that
case, all the internal messages of the threads are sorted by the
chosen sort order, e.g., by date, author etc. instead of being grouped
into subthreads.

The value of the variable @code{vm-move-messages-physically} applies
to threading just as it applies to sorting.

@node Digests, Summaries, Sorting Messages, Top
@chapter Digests

A @dfn{digest} is one or more mail messages encapsulated within another
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
The command (@code{vm-burst-digest}) bursts a digest into its
individual messages and appends them to the current folder.  These
messages are then assimilated into the current folder as new 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.  You will be prompted for the type of digest to burst.  VM
understands three formats, ``rfc934'', ``rfc1154'' and ``mime''.  If you
don't know what kind of digest you've received, type ``guess'' and VM
will try to figure out the digest type on its own.  VM is pretty smart
about digests and will usually make the correct choice if the digest is
properly formatted.

@node Summaries, Virtual Folders, Digests, Top
@chapter Summaries

@findex vm-summarize
@findex vm-headers-summary
@vindex vm-auto-center-summary
@vindex vm-summary-arrow
@kindex h
Typing @kbd{h} (@code{vm-summarize}, @code{vm-headers-summary}) 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 @samp{->} appears to the left of the line summarizing the current
message.  The variable @code{vm-auto-center-summary} controls whether VM
will keep the summary arrow vertically centered within the summary window.
A value of @code{t} causes VM to always keep the arrow centered.  A value of
@code{nil} (the default) means VM will never bother centering the arrow.  A
value that is not @code{nil} and not @code{t} causes VM to center the arrow
only if the summary window is not the only existing window.  You can change
what the summary arrow looks like by setting @code{vm-summary-arrow} to a
string depicting the new arrow.  You should set this variable before VM
creates the summary buffer.


You can have a summary generated automatically at VM startup
by setting the variable @code{vm-startup-with-summary} non-nil.
@xref{Starting Up}.

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

@vindex vm-gargle-uucp
A non-@code{nil} value of @code{vm-gargle-uucp} means to use a crufty
regular expression that does surprisingly well at beautifying UUCP
addresses that are substituted for @samp{%f} and @samp{%t} as part
of summary and attribution formats.

@menu
* Summary Format::     Customizing the summary format
* Threaded Summaries:: How threading affects summaries
* Thread Folding::     Collapsing message threads in the summary
* Thread Operations::  Running bulk operations on message threads
* Summary Faces::      Decorating summary with fonts and colors
@end menu

@node Summary Format, Threaded Summaries, Summaries, Summaries
@section Summary Format

@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:
@table @code

@item a
attribute indicators (always four characters wide)
@*
The first char is  `D', `N', `U' or `!' for deleted, new, unread
and flagged messages respectively, and ` ' if none of the conditions apply.
@*
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.


@item A
longer version of attributes indicators (seven characters
wide).@*
@*
The first char is  `D', `N', `U' or `!' for deleted, new, unread
and flagged messages respectively, and ` ' if none of the conditions apply.
@*
The second is `R' or ` ', for message replied to.
@*
The third is `Z' or ` ', for messages forwarded.
@*
The fourth is `B' or ` ', for messages redistributed.
@*
The fifth is `F' or ` ', for messages filed.
@*
The sixth is `W' or ` ', for messages written.
@*
The seventh is `e' or ` ', for messages that have been edited.


@item b
shorter version of the attribute indicators (one character wide).
@*
`D', `N', `U' or `!' for deleted, new, unread
and flagged messages respectively, and ` ' if none of the conditions apply.

@item *
message mark, `*' if the message is marked, ` ' otherwise

@vindex vm-summary-postponed-indicator
@item p
indicator for a postponed message: @kbd{P} or the string customized by
@code{vm-summary-postponed-indicator}

@vindex vm-summary-attachment-indicator
@item P
indicator for a message with attachments: @kbd{$} or the string customized
via @code{vm-summary-attachment-indicator}

@item I
thread indentation

@item n
message number

@item i
message ID

@item c
number of characters in message (ignoring headers)

@item S
human readable size of the message

@item l
number of lines in message (ignoring headers)

@item d
numeric day of month message sent

@item w
day of the week message sent

@item m
month message sent

@item M
numeric month message sent (January = 1)

@item y
year message sent

@item h
hour:min:sec message sent

@item H
hour:min message sent

@item z
timezone of date when the message was sent

@item f
author's address

@item F
author's full name (same as f if full name not found)

@item t
email addresses of the addressees of the message (listed in the ``To''
header), in a comma-separated list

@item T
full names of the addressees of the message (listed in the ``To''
header), in a comma-separated list

@item r
addresses of the recipients of the message (listed in the ``To'' or ``Cc''
headers), in a comma-separated list

@item R
full names of the recipients of the message, in a comma-separated list (or
their email addresses if full names are not given)

@item s
message subject

@item L
labels (as a comma list)

@item U
user defined specifier.  The next character in the format
string should be a letter.  VM will call the function
vm-summary-function-<letter> (e.g. vm-summary-function-A for
``%UA'') in the folder buffer with the message being summarized
bracketed by (point-min) and (point-max).  The function
will be passed a message struct as an argument.
The function should return a string, which VM will insert into
the summary as it would for information from any other summary
specifier.

@item (
starts a group, terminated by %).  Useful for specifying
the field width and precision for the concatenation of
group of format specifiers.  Example: \"%.35(%I%s%)\"
specifies a maximum display width of 35 characters for the
concatenation of the thread indentation and the subject.

@item )
ends a group.
@end table

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.

@vindex vm-summary-uninteresting-senders
@vindex vm-summary-recipient-marker
@vindex vm-summary-uninteresting-senders-arrow
If you save copies of all your outbound messages in a folder and
later visit that folder, the @samp{%F} format specifier will normally
display your own name.  If you would rather see the recipient
addresses in this case, set the variable
@code{vm-summary-uninteresting-senders}. This variable's value,
if non-@code{nil}, should be a regular expression that matches
addresses that you don't consider interesting enough to appear in
the summary.  When such senders would be displayed by the @samp{%F} or
@samp{%f} summary format specifiers VM will substitute the value of
@code{vm-summary-recipient-marker} (default "To: ")
followed by what would be shown by the @samp{%T} and @samp{%t} specifiers
respectively.

If the recipients of the message are also ``uninteresting'' in this way,
then VM will substitute the value of @code{vm-summary-principal-marker}
(default "For: ") followed by the name or address in the @samp{Reply-To}
header.   

(For compatibility with older versions, the variable
@code{vm-summary-recipient-marker} is also referred to by its old name,
@code{vm-summary-uninteresting-senders-arrow}.)

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.

@findex vm-fix-my-summary
Summary lines are pre-computed and cached in the folder buffer.  If you
change the @code{vm-summary-format}, you need to force the cache to be
updated.  You can do this by the command@code{vm-fix-my-summary}.

@vindex vm-restore-saved-summary-format
Every folder can have its own summary format.  The format is written
into the folder and saved on the disk.  When you visit the folder
again, you can reuse the saved summary format.  Set the variable
@code{vm-restore-saved-summary-format} to t to achieve this effect.

@node Threaded Summaries, Thread Folding, Summary Format, Summaries
@section Threaded Summaries

@findex vm-toggle-threads-display
@vindex vm-summary-thread-indent-level
@vindex vm-summary-maximum-thread-indentation
When message threading is enabled (@pxref{Threading}),
you will find that the 
Summary buffer has all related messages are grouped together and the
subject titles are indented to show hierarchical relationships.
Parent messages are displayed before their children and children are
indented by a default two spaces to the right.  The amount of
indentation per level is controlled by the variable
@code{vm-summary-thread-indent-level}.  The default is two spaces.
The variable @code{vm-summary-maximum-thread-indentation} says how
many levels should be displayed via indentation.  The default is 20.

@vindex vm-summary-show-threads
If you want VM to always display summaries using threads, you should
set the default value of the variable @code{vm-summary-show-threads}
non-@code{nil} in your VM init file.  Example:

@example
(setq-default vm-summary-show-threads t)
@end example

@noindent Do not use @code{setq}, as this will only set the value of
the variable in a single buffer.  Once you've started VM you should
not change the value of this variable.  Rather you should use
@kbd{C-t} to control the thread display.  @xref{Threading}. 

@unnumberedsubsec Manual control of thread indentation

When you deal with long discussions in mailing lists or newsgroups,
you would find that threads get very deep and their indentation in the
Summary window is not entirely helpful.  You can temporarily promote
the subthreads to higher level so that you can view the threading
relationships more clearly.

@kindex <
@findex vm-promote-subthread
The command @kbd{<} (@code{vm-promote-subthread}) temporarily
decreases the indentation of the current message and its subthread by
one step.  You can give the command a numeric prefix argument N asking
it to decreasing indentation by N steps.  Giving 0 as the prefix
argument has a special meaning.  It says that the current message
should not be indented at all, effectively making it appear as the
root message of a thread.

@kindex >
@findex vm-demote-subthread
The command @kbd{>} (@code{M-x vm-demote-subthread}) does the
opposite.  It increases the indentation of the current message and its
subthread.  You can specify the level of increased indentation as the
prefix argument.  Giving 0 as the prefix argument has the special
meaning of asking VM to return the message to its standard indentation
as determined by its thread level.

Both of these commands alter the thread indentation for the current
session only.  The next time you visit the folder, the threads will be
displayed using the standard indentation.


@node Thread Folding, Thread Operations, Threaded Summaries, Summaries
@section Thread Folding

A new feature in VM version 8.2 is that of ``folding'' message threads
in the summary window.  This feature allows you to collapse all the
messages in a thread into a single line of the summary window, so that
you can see a more compact summary of the folder.

@vindex vm-summary-enable-thread-folding
@findex vm-toggle-thread
@findex vm-expand-thread
@findex vm-collapse-thread
@findex vm-collapse-all-threads
@findex vm-expand-all-threads
@kindex T
Thread folding is enabled by setting the variable
@code{vm-summary-enable-thread-folding} to a non-nil value.  The summary
window then has a folding indicator in the first column: with @code{-}
for threads that are expanded and @code{+} for threads that are
collapsed.  The command @kbd{T}
(@code{vm-toggle-thread}) allows you to expand a collapsed thread or
collapse an expanded thread.  The commands @code{vm-expand-thread} and
@code{vm-collapse-thread} implement the more specific versions of the
function. 

@vindex vm-summary-visible
When threads are folded, not all messages in the threads are hidden.
New messages that are yet unread continue to be visible.  Which
messages remain visible in folded threads is controlled by the
variable @code{vm-summary-visible}, whose value must be a list of VM
selectors in the same format as those in
@code{vm-virtual-folder-alist}.  @xref{Virtual Folders}.

@vindex vm-summary-thread-folding-on-motion
The variable @code{vm-summary-thread-folding-on-motion} allows a more
automatic expansion/collapsing of threads.  If the variable is set to
a non-nil value, then the usual motion commands @kbd{N} and @kbd{P}
(@code{vm-next-message-no-skip} and
@code{vm-previous-message-no-skip}) cause the threads to be expanded
or collapsed as needed when you move into or out of threads.

@vindex vm-summary-show-thread-count
The variable @code{vm-summary-show-thread-count} allows a more
elaborate display of the thread information in the summary window.  If
it is set to non-nil then the message number field of the summary line
includes a count of the messages in its thread, in the format
@code{N+C} where @code{N} is the message number and @code{C} is the
message count in the thread.  This takes up 3 extra columns in the
summary lines.  Set the variable to nil to obtain the more standard
format of the summary.

@findex vm-expand-all-threads
@findex vm-collapse-all-threads
@kindex E
@kindex C
When thread folding is enabled, the Summary window starts out with all
the threads folded.  You can expand all the threads in the folder
using the command @kbd{E} (@code{vm-expand-all-threads}).  The command
@kbd{C} (@code{vm-collapse-all-threads}) does the reverse.


@node Thread Operations, Summary Faces, Thread Folding, Summaries
@section Thread Operations

@vindex vm-enable-thread-operations
@findex vm-toggle-thread-operations
When you have thread-folding enabled, you can execute VM operations
such as saving and deleting messages on entire threads.  To obtain
this functionality, set the variable
@code{vm-enable-thread-operations} to a non-@code{nil} value in your
vm-init-file.  Setting it to `t' enables thread operations
unconditionally.  Setting it to the symbol `ask' allows a confirmation
dialog before a thread operation is invoked.  You can use the
command @code{vm-toggle-thread-operations} in a running VM session to
enable or disable thread operations.

As an example, doing an @kbd{s} (@code{vm-save-message}) operation on
an ordinary message saves just the single message.  However, if thread
operations are enabled and you invoke @kbd{s} on the
root message of a collapsed thread, then the entire thread is saved.
The same effect can be obtained using message marking.  @xref{Marking
Messages}.  The following sequence of key strokes can achieve the
effect of saving an entire thread:

@example
MuMTMNsMu
@end example

@noindent However, the thread-operation is simpler and more convenient.

All operations that can be sensibly invoked on multiple messages
extend to thread operations in this way.  They include deleting,
undeleting, marking, unmarking, forwarding, saving/deleting
attachments etc.  Replying to messages cannot be invoked as a thread
operation.  This is to avoid accidentally sending replies to unintended
recipients. 

The thread operations can give rise to surprising behavior.  Even
though it appears that an operation was invoked on a single message,
it actually applies to all the messages in a thread.  So, care and
practice are warranted before you enable thread operations
unconditionally.  A safer option is to set
`vm-enable-thread-operations' to `ask'.  In that case, VM asks for
confirmation every time an operation is applicable to all the messages
in a collapsed thread.  You can override the confirmation dialog by
giving a prefix argument `C-u' to your operation.  

@node Summary Faces,, Thread Operations, Summaries
@section Summary Faces

@cindex faces
@cindex summary faces
By default, the summary of a folder is shown in a black-and-white
window with plain text.  This is suitable for terminal mode Emacs
users.  The variable @code{vm-summary-highlight-face}, which is set to
the standard Emacs @code{bold} face by default, is used to highlight
the currently selected message.  You can set the variable to any other
face, or to nil if you wan to turn off highlighting.

@findex vm-summary-faces-mode
@vindex vm-summary-enable-faces
You can turn on more elaborate faces support, suitable for color
graphics terminals, by setting the variable
@code{vm-summary-enable-faces} to t in your vm-init-file.  You can
also run @code{M-x vm-summary-faces-mode} in the middle of a VM
session to turn on summary faces. Then VM decorates the summary lines
with different faces based on the attributes of the message.
@xref{Faces,,,emacs, the GNU Emacs Manual}, for basic information on
faces. The predefined faces used to highlight the summary window are
listed below.  It is possible for you to change the definitions of
these faces in your vm-init-file as well as to define new faces of
your own.

@vindex vm-summary-faces-alist
The variable @code{vm-summary-faces-alist} defines a list of
condition-action pairs for decorating the summary with faces.
It has the following form:

@example
( ((@var{SELECTOR} [@var{ARG} ...])    @var{vm-summary-FACE})
  ... )
@end example

The first element of each pair is a VM selector in the same
format as used for @code{vm-virtual-folder-alist}.  @xref{Virtual
Folders}.  The second element is a face name of the form
@code{vm-summary-FACE} where @code{FACE} is one of the face types
listed below.  The first condition
satisfied by the message wins, and the face listed there is used to
decorate its summary line.

The faces @code{vm-summary-selected}, @code{vm-summary-collapsed} and
@code{vm-summary-expanded} are special.  They are @i{added} to the face
specified by @code{vm-summary-faces-alist} instead of replacing it.
This allows VM to add highlighting for the selected message and the
collapsed/expanded thread roots, without scrubbing the natural face
determined by the message attributes.

@vindex vm-mouse-track-summary
The variable @code{vm-mouse-track-summary} controls whether summary
entries are highlighted when the mouse pointer passes over
them.  The highlighting is done using the standard Emacs
@code{highlight} face.

@subsubheading Hiding summary lines
@anchor{Hiding summary lines}
@cindex hiding summary lines
@cindex vm-summary-faces-hide
The command @code{vm-summary-faces-hide} allows you to hide the
summary lines of messages with a particular face type.  By default, it
hides messages with the @code{deleted} face type.  By invoking it with
a prefix argument, you can specify other face types that you might
like to hide.  (Note that @code{deleted} face type does not necessarily
mean deleted messages.  Whatever messages satisfy the condition
associated with the @code{vm-summary-deleted-face} in
@code{vm-summary-faces-alist} will be hidden.)

@subsubheading Predefined summary faces
@cindex predefined summary faces
@anchor{predefined summary faces}
@itemize
@item vm-summary-high-priority:
Messages that are flagged or have other priority headers.
@item vm-summary-low-priority:
Messages that might be of low priority, by user-defined criteria.
@item vm-summary-deleted:
Deleted messages.
@item vm-summary-new:
New messages that have arrived during the session.
@item vm-summary-unread:
Messages that have not been read.
@item vm-summary-marked:
Messages currently marked.
@item vm-summary-replied:
Messages for which a reply has been sent.
@item vm-summary-saved:
Messages saved to a folder on disk.  (Subsumes the earlier categories
filed and written.)
@item vm-summary-forwarded:
Messages forwarded to other recipients.  (Subsumes the earlier
category redistributed.)
@item vm-summary-edited:
Messages edited after receipt.
@item vm-summary-outgoing:
Messages sent by you.
@item vm-summary-default:
Messages not matching any of the above criteria.
@item vm-summary-collapsed:
Root messages of threads that are collapsed.
@item vm-summary-expanded:
Root messages of threads that are expanded.
@item vm-summary-selected:
Message that is currently selected.
@end itemize


@node Virtual Folders, @acronym{IMAP} Server Folders, Summaries, Top
@chapter Virtual Folders

@cindex searching
@cindex virtual folders

A @dfn{virtual folder} is a mapping of messages from one or more
real folders into a container that in most ways acts like a
real folder but has no real existence outside of VM.  You can have a
virtual folder that contains a subset of messages in a real folder
or several real folders.  A virtual folder can also contain a
subset of messages from another virtual folder.

@cindex search folders
@cindex interactive virtual folders
There are two ways of working with virtual folders.  When you are
visiting a folder, you can use one or more selectors or search keys to
interactively create a virtual folder.  We call such folders @dfn{search
folders}.  You can browse through the
messages in the search folder and carry out actions on them which
will be reflected back to the original folder.  When you are done, you
can quit the search folder and return to the original folder.

@cindex defined virtual folders
@vindex vm-virtual-folder-alist
@kindex V V
@findex vm-visit-virtual-folder
A second way of using virtual folders is to define them through the
variable @code{vm-virtual-folder-alist}.  You can visit such virtual
folders by typing @kbd{V V} (@code{vm-visit-virtual-folder}).  Any
actions carried out on the virtual folder messages will be reflected
back to the underlying real folders.  When you quit a virtual folder, all
its underlying real folders will also be quit, unless they were previously
visited in the Emacs session.  We call such virtual folders
@dfn{defined virtual folders}.

@menu
* Search Folders::	Virtual folders created interactively
* Defined Folders::	Virtual folders defined in advance
* Virtual Selectors::	Selectors used for creating virtual folders
* Working with Virtual Folders:: What you can do in a virtual folder
* vm-avirtual::		Automatic operations using virtual selectors
@end menu

@node Search Folders, Defined Folders, Virtual Folders, Virtual Folders
@section Search Folders

@findex vm-create-virtual-folder
@findex vm-create-search-folder
@findex vm-create-search-folder-other-window
@findex vm-create-search-folder-other-frame
@kindex V C
The command @code{vm-create-search-folder} (bound to @kbd{V C}) lets you
interactively create a virtual folder from the messages of the current
folder, using exactly one selector to choose the messages.  If you type
@kbd{V C header @key{RET} greeting}, VM will create a folder containing only
those 
messages that contain the string @samp{greeting} in one of its headers.
@xref{Virtual Selectors}, for virtual selectors you can use for this
purpose.  The variants @code{vm-create-search-folder-other-frame} and
@code{vm-create-search-folder-other-window} provide similar functionality.

@findex vm-create-virtual-folder-of-threads
@findex vm-create-search-folder-of-threads
@kindex V T
The command @code{vm-create-search-folder-of-threads} (bound to @kbd{V T})
lets you create a virtual folder in the same way, but consisting of entire
message threads.  If a message thread contains any message matching the
given selector then it is included in the virtual folder.  For instance, if
you type @kbd{V T author @key{RET} Peter} then all threads containing a message
authored by @samp{Peter} will be included in the virtual folder.

@findex vm-apply-virtual-folder
@kindex V X
The command @code{vm-apply-virtual-folder} (bound to @kbd{V X}) tries
the selectors of a defined virtual folder against the messages of
the current folder and creates a virtual folder containing the
matching messages.

@kindex V S
@kindex V A
@findex vm-create-virtual-folder-same-subject
@findex vm-create-virtual-folder-same-author
@findex vm-create-virtual-folder-same-recipient
The commands @code{vm-create-virtual-folder-same-subject} (bound to @kbd{V
S}), @code{vm-create-virtual-folder-same-author} (bound
to @kbd{V A}) and @code{vm-create-virtual-folder-same-recipient} (bound to
@kbd{V R}) create virtual folders containing all the
messages in the current folder with the same subject, author or recipient as the
current message.  There are also short-cut key bindings for a number of
frequently used selectors:

@kindex V a
@kindex V r
@kindex V s
@kindex V t
@kindex V d
@kindex V l
@kindex V !
@kindex V n
@kindex V u
@findex vm-create-author-virtual-folder
@findex vm-create-author-or-recipient-virtual-folder
@findex vm-create-subject-virtual-folder
@findex vm-create-text-virtual-folder
@findex vm-create-date-virtual-folder
@findex vm-create-label-virtual-folder
@findex vm-create-flagged-virtual-folder
@findex vm-create-new-virtual-folder
@findex vm-create-unseen-virtual-folder
@table @kbd
@item V a (@code{vm-create-author-virtual-folder})
@item V r (@code{vm-create-author-or-recipient-virtual-folder})
@item V s (@code{vm-create-subject-virtual-folder})
@item V t (@code{vm-create-text-virtual-folder})
@item V d (@code{vm-create-date-virtual-folder})
@item V l (@code{vm-create-label-virtual-folder})
@item V ! (@code{vm-create-flagged-virtual-folder})
@item V n (@code{vm-create-new-virtual-folder})
@item V u (@code{vm-create-unseen-virtual-folder})
@end table


@cindex searching
When you run @code{vm-quit} on a search folder, the currently selected
message in the search folder becomes the current message in the underlying
folder.  So, you can use the search folder facility to search for particular
messages.  For example, if you knew that one of the messages with the
subject @samp{greeting} had a hotel offer and you wanted to find it, you can
first create a search folder of messages with subject @samp{greeting},
browse through them to find the message that had the hotel offer, and then
quit the search folder.  VM will return you to the copy of the same message
in the original folder.  (You can go back to the previously viewed message
in the original folder by doing @code{vm-goto-mesasge-last-seen}.  To
inhibit changing the current message in the original message entirely, quit
the search folder using @code{vm-quit-no-change}.)

Search folders also form an efficient way to search for some string in the
text of messages.  The key binding @kbd{V t}
(@code{vm-create-text-virtual-folder}) can be used to find all messages with
the string.  This is more efficient than the @code{vm-isearch-forward}
command (@pxref{Navigating}) because it only searches in the text part
of message bodies, not inside @acronym{MIME} attachments. 

@node Defined Folders, Virtual Selectors, Search Folders, Virtual Folders
@section Defined Virtual Folders

@vindex vm-virtual-folder-alist
@findex vm-visit-virtual-folder
@kindex V V
A defined virtual folder is defined by its name, the folders that it
contains and its selectors.  The variable
@code{vm-virtual-folder-alist} is a list of the definitions of all
such virtual folders.  You can  visit a virtual folder listed in
@code{vm-virtual-folder-alist} with the
@code{vm-visit-virtual-folder} (@kbd{V V}) command.

Each virtual folder definition should have the following form:

@example
(@var{VIRTUAL-FOLDER-NAME}
  ( (@var{FOLDER} ...)
    (@var{SELECTOR} [@var{ARG} ...]) ... )
  ... )
@end example

@var{VIRTUAL-FOLDER-NAME} is the name of the virtual folder being defined.
This is the name by which you and VM will refer to this folder.

@var{FOLDER} should be the specification of a real folder: a file path for a
local folder or a maildrop specification for a @acronym{POP}/@acronym{IMAP}
folder.  There may be more than one @var{FOLDER} listed, the @var{SELECTOR}s
within that sublist will apply to them all.  If @var{FOLDER} is a directory,
VM will assume this to mean that all the folders in that directory should be
searched.

The @var{SELECTOR} is a Lisp symbol that tells VM how to
decide whether a message should be included in the virtual
folder.  (See below for a complete list of the possible selectors.)
Some @var{SELECTOR}s require an argument @var{ARG};
unless otherwise noted, @var{ARG} may be omitted.  When several
selectors are listed, messages matching any one of them are included.

@cindex searching
@findex vm-isearch-forward
@findex vm-isearch-backward
The @code{text} selector provides a particularly effective way to search
for strings in messages.  It is better than the
@code{vm-isearch-forward/backward} functions because it avoids searching
inside encoded attachments, hence faster.

Here is an example that you may find useful as a template for
creating virtual folder definitions.

@example
(setq vm-virtual-folder-alist
   '(
     ;; start virtual folder definition
     ("virtual-folder-name"
      (("/path/to/folder" "/path/to/folder2")
       (header "foo")
       (header "bar")
      )
      (("/path/to/folder3" "/path/to/folder4")
       (and (header "baz") (header "woof"))
      )
     )
     ;; end of virtual folder definition
   )
)
@end example

When you visit a defined virtual folder, all the underlying folders
that it depends on will be visited automatically.  Likewise, when you
quit the virtual folder, all the underlying folders that were
purposely visited as part of the virtual folder will be closed
automatically.  But any other underlying folders that you might have
previously visited for independent reasons will remain open.

@node Virtual Selectors, Working with Virtual Folders, Defined Folders, Virtual Folders
@section Virtual Selectors

@unnumberedsubsec Generic selectors

@cindex @acronym{BBDB}
@table @code
@item any
matches any message.
@item header
matches message if @var{ARG} matches any part of the header
portion of the message; @var{ARG} should be a
regular expression.
@item text
matches message if @var{ARG} matches any part of the text
portion of the message; @var{ARG} should be a
regular expression.
@item header-or-text
matches message if @var{ARG} matches any part of the
headers or the text portion of the message;
@var{ARG} should be a regular expression.
@item header-field
matches messages if the header field named @var{ARG1} has text matching
@var{ARG2}. 
@end table

@unnumberedsubsec Selectors based on message headers

@table @code
@item author
matches message if @var{ARG} matches the author; @var{ARG} should be a
regular expression.
@item author-or-recipient
matches message if @var{ARG} matches the author of
the message or any of its recipients; @var{ARG}
should be a regular expression.
@item recipient
matches message if @var{ARG} matches any part of the recipient
list of the message.  @var{ARG} should be a regular expression.
@item principal
matches message if @var{ARG} matches any part of the @samp{Reply-To} header
of the message.  @var{ARG} should be a regular expression.
@vindex vm-summary-uninteresting-senders
@item outgoing
matches message if your are the author of it, i.e. if the author matches
@code{vm-summary-uninteresting-senders}.
@cindex @acronym{BBDB}
@item in-bbdb
matches message if its addresses are in the @acronym{BBDB}.  With an optional
first argument you can specify the address class (@code{authors} or
@code{recipients}) .  With an optional second argument @code{t}, the
selector checks only the first address specified in the message.
Examples: 

@example
(in-bbdb authors)
@end example
@example
(in-bbdb recipients t)
@end example
@item subject
matches message if @var{ARG} matches any part of the message's
subject; @var{ARG} should be a regular expression.
@item sent-after
matches message if it was sent after the date @var{ARG}.
A fully specified date looks like this:
@example
``31 Dec 1999 23:59:59 GMT''
@end example
@noindent although the parts can appear in any order.
You can leave out any part and it will
default to the current date's value for that
part, with the exception of the @samp{hh:mm:ss}
part which defaults to midnight.
@item sent-before
matches message if it was sent before the date @var{ARG}.
A fully specified date looks like this:
@example
``31 Dec 1999 23:59:59 GMT''
@end example
@noindent although the parts can appear in any order.
You can leave out any part and it will
default to the current date's value for that
part, with the exception of the hh:mm:ss
part which defaults to midnight.
@item older-than
matches message if it is more than @var{ARG} days old (today = 0)
@item newer-than
matches message if it is at most @var{ARG} days old (today = 0)
@item message-id
matches message if its Message ID has a string matching @var{ARG}
@item uid
matches message if its IMAP UID is @var{ARG} (for IMAP folders)
@item uidl
matches message if its POP UIDL is @var{ARG} (for POP folders)
@item spam-score
matches message if its spam score is at least @var{ARG}.  See
@code{vm-spam-score-headers} for configuration.
@end table

@unnumberedsubsec Selectors based on message attributes

@table @code
@item deleted
matches message if it is flagged for deletion.
@item undeleted
matches message if it has not been deleted.
@item edited
matches message if it has been edited.
@item unedited
matches message if it has not been edited.
@item filed
matches message if it has been saved with its headers.
@item unfiled
matches message if it has not been saved with its
headers.
@item written
matches message if it has been saved without its headers.
@item new
matches message if it is new.
@item recent
matches message if it is new.  Same as the @code{new} selector.
@item read
matches message if it is neither new nor unread.
@item unread
matches message if it is not new and hasn't been read.
@item unseen
matches message if it is not new and hasn't been read.
Same as the @code{unread} selector.
@item flagged
matches message if it is flagged.
@item unflagged
matches message if it is not flagged.
@item replied
matches message if it has been replied to.
@item answered
matches message if it has been replied to.  Same as the @code{replied}
selector. 
@item unreplied
matches message if it has not been replied to.
@item unanswered
matches message if it has not been replied to.
Same as the @code{unreplied} selector.
@item forwarded
matches message if it has been forwarded using
a variant of @code{vm-forward-message}, @code{vm-send-digest} or one
of their variants.
@item unforwarded
matches message if it has not been forwarded using
@code{vm-forward-message}, @code{vm-send-digest} or one
of their variants.
@item redistributed
matches message if it has been redistributed using
@code{vm-resend-message}.
@item unredistributed
matches message if it has not been redistributed using
@code{vm-resend-message}.
@item marked
matches message if it is marked, as with
@code{vm-mark-message}.
@end table

@unnumberedsubsec Selectors based on analyzing the text

@table @code
@vindex vm-vs-attachment-regexp
@item attachment
matches if a message contains an attachment, i.e., its text matches
@code{vm-vs-attachment-regexp}.
@item less-chars-than
matches message if message has less than @var{ARG}
characters.  @var{ARG} should be a number.
@item less-lines-than
matches message if message has less than @var{ARG}
lines.  @var{ARG} should be a number.
@item more-chars-than
matches message if message has more than @var{ARG}
characters.  @var{ARG} should be a number.
@item more-lines-than
matches message if message has more than @var{ARG}
lines.  @var{ARG} should be a number.
@end table

@unnumberedsubsec Complex selector operations

@table @code
@item sexp
matches message if the argument ``s-expression'' yields @code{t}.  For
example, to find all the messages from @samp{Jenny} with attachments, you
can type @kbd{V C sexp @key{RET} (and (author "Jenny") attachment) @key{RET}}.

(This selector is available for creating interactive virtual folders.  The
argument ``s-expression'' can involve selectors combined using the logical
connectives listed below.  There would be no need to use the @code{sexp}
selector in defining predefined virtual folders because those definitions
can directly use ``s-expressions''.)

@item eval
matches message if evaluating the Lisp expression @var{ARG} yields @code{t}.
The Lisp expression can refer to the message by the name
@code{vm-virtual-message}.  This is more flexible than the @code{sexp}
selector because it allows arbitrary Lisp expressions, not only the built-in
selectors.  However, you would need some knowledge of the Lisp functions
that manipulate VM messages to use this selector.

@item and
matches the message if all its argument
selectors match the message.  Example:
@example
(and (author "Derek McGinty") (new))
@end example
@noindent matches all new messages from Derek McGinty.
@code{and} takes any number of arguments.

@item not
matches message only if its selector argument
does NOT match the message.  Example:
@example
(not (deleted))
@end example
@noindent matches messages that are not deleted.

@item or
matches the message if any of its argument
selectors match the message.  Example:
@example
(or (author "Dave Weckl") (subject "drum"))
@end example
@noindent matches messages from Dave Weckl or messages
with the string ``drum'' in their Subject header.
@code{or} takes any number of arguments.

@item thread
matches a message thread if any message in the thread matches the argument
selector.  Example:
@example
(thread (outgoing))
@end example
@noindent matches all threads that have an outgoing message, i.e., a message
authored by you.

@item thread-all
matches a message thread if all messages in the thread match the argument
selector.  Example:
@example
(thread (less-chars-than 1000))
@end example
@noindent matches threads if all their messages contain fewer than 1000
characters. 
@end table

@unnumberedsubsec Selectors based on context

@table @code
@item folder-name
matches message if it is from a folder matching @code{ARG}
@item virtual-folder-member
matches message if the message is already a
member of some virtual folder currently
being visited.
@item vm-mode
matches the message if the current-buffer is in vm-mode and one of its
argument selectors matches the message.
@item mail-mode
matches the message if the current-buffer is in mail-mode and one of
its argument selectors matches the message.
@end table

@node Working with Virtual Folders, vm-avirtual, Virtual Selectors, Virtual Folders
@section Working with Virtual Folders

@findex vm-get-new-mail
@findex vm-save-folder
Once you've
visited a virtual folder most VM commands work as they do in a
normal folder.  There are exceptions.  If you use @kbd{S}
(@code{vm-save-folder}), the folder save command will be invoked
on each real folder in turn.  Similarly if you use @kbd{g}
(@code{vm-get-new-mail}) in a virtual folder, mail is retrieved
from the spool files associated with each of the real folders.
If any of the retrieved messages are matched by the virtual
folder's selectors, they will be added to the virtual folder.

These commands will signal an error when invoked in a virtual folder:

@display
    vm-save-buffer
    vm-write-file
    vm-change-folder-type
    vm-expunge-imap-messages
    vm-expunge-pop-messages
@end display

Normally messages in a virtual folder share attributes with the
underlying real messages.  For example, if you delete a message
in a virtual folder, it is also flagged as deleted in the real
folder.  If you then run @code{vm-expunge-folder} in the virtual folder,
the deleted message is expunged from the virtual folder as well as
the real folder.  Labels are shared between virtual and real
messages.  However virtual folders have their own set of message
marks.

To make virtual folders not share message attributes with real
folders by default, set the variable @code{vm-virtual-mirror} to nil.
This should be done in your VM init file and you should use
@code{setq-default}, as this variable is automatically local to all
buffers.

@example
(setq-default vm-virtual-mirror nil)
@end example

@findex vm-toggle-virtual-mirror
@kindex V M
@noindent If you want to change virtual mirror status of a particular
virtual folder, use the command @code{vm-toggle-virtual-mirror} (bound
to @kbd{V M}).  If the virtual folder is currently sharing attributes
with real folders, it will no longer be.  If it is not sharing
attributes with the underlying folders then it will be.

@node vm-avirtual,, Working with Virtual Folders, Virtual Folders
@section vm-avirtual Package

@cindex vm-avirtual
The @samp{vm-avirtual} add-on package created by Robert Widhopf-Fenk provides
various automatic operations based on virtual selectors.  These
facilities are only partially documented.

@kindex V O
@findex vm-virtual-omit-message
@kindex V U
@findex vm-virtual-update-folders
The command @code{M-x vm-virtual-omit-message} (bound to @kbd{V O} in
version 8) will omit a message from a virtual folder, irrespective of
whether it satisfies the definition of the virtual folder.  The command
@code{M-x vm-virtual-update-folders} (bound to @kbd{V U} in version 8) will
add the current message to all visited virtual folders that it logically
belongs to.  This is useful for adding newly arrived messages or newly
marked messages to virtual folders.

@findex vm-virtual-check-selector-interactive
The command @kbd{M-x vm-virtual-check-selector-interactive} (bound to @kbd{V
?} in version 8) allows you to test a selector, i.e., a virtual folder
definition, interactively by applying it to the current message.  With a
prefix argument, it will print diagnostic information in a separate buffer.
This feature is useful because virtual folder selectors can get quite
complicated and it is important to make sure that they work correctly.

The vm-avirtual packages allows you to use virtual selectors to carry out
automatic deletion of messages (e.g., for spam) and for automatic saving of
messages to folders.

@unnumberedsubsec Automatic deletion

@findex vm-virtual-auto-delete-message
@vindex vm-virtual-auto-delete-message-selector
Automatic deletion of messages based on the virtual folder facility can be
achieved with the command @code{vm-virtual-auto-delete-message} (bound to
@kbd{V D} in version 8).  First, set the variable
@code{vm-virtual-auto-delete-message-selector} to the name of a virtual
folder whose members should be normally deleted.  Then invoking the command
on the current message (or a COUNT number of messages with a prefix
argument) deletes all those messages among them that belong to the virtual
folder @code{vm-virtual-auto-delete-message-selector}.  There is no need to
separately view the virtual folder before deleting such messages.

@findex vm-virtual-auto-delete-messages
@vindex vm-arrived-messages-hook
The function @code{vm-virtual-auto-delete-messages} can be added to the VM
hook @code{vm-arrived-messages-hook}.  This causes all the messages matching
the @code{vm-virtual-auto-delete-message-selector} in the incoming mail
to be automatically deleted before you view them.

@unnumberedsubsec Automatic saving
@anchor{vm-virtual-auto-folder-alist}

@findex vm-virtual-save-message
@findex vm-virtual-auto-archive-messages
@vindex vm-virtual-auto-folder-alist
The commands @kbd{M-x vm-virtual-save-message} and
@kbd{M-x vm-virtual-auto-archive-messages} provide variants of
@code{vm-save-message} and @code{vm-auto-archive-messages} based on the
virtual folder facility.  To use them, you must first set the variable
@code{vm-virtual-auto-folder-alist} to an association-list of the form

@example
((@var{VIRTUAL-FOLDER-NAME} . @var{FOLDER})
 ... )
@end example

@noindent where @var{VIRTUAL-FOLDER-NAME} is a string and @var{FOLDER} is
either a string or an expression that evaluates to a string.  If the message
being saved is a member of @var{VIRTUAL-FOLDER-NAME}, as per its definition
in @code{vm-virtual-folder-alist}, then @var{FOLDER} is regarded as the
place where it should be saved.  The command @code{vm-virtual-save-message}
suggests this folder as the default location for saving.  The command
@code{vm-virtual-auto-archive-messages} archives all matching messages in
the corresponding @var{FOLDER}s, as suggested by
@code{vm-virtual-auto-folder-alist}.

@node @acronym{IMAP} Server Folders, Frames and Windows, Virtual Folders, Top
@chapter @acronym{IMAP} Server Folders

This chapter covers the additional features of @acronym{IMAP} server
folders, i.e., folders on an @acronym{IMAP} server that you access using VM.
@xref{@acronym{IMAP} Folders}.  Do not use these features if you just
download mail from IMAP mail boxes into local folders.

@findex vm-imap-synchronize
The command @code{vm-imap-synchronize} can be used to perform full
synchronization between a VM folder and the corresponding folder on the IMAP
server.  (Recall that @code{vm-get-new-mail} and @code{vm-save-folder} do
half-synchronization in one direction each.)

@vindex vm-imap-connection-mode
The variable @code{vm-imap-connection-mode} allows you to work while
disconnected from the network.  If it is set to @code{online}, which is the
default, VM communicates with the server during @code{vm-get-new-mail},
@code{vm-save-folder} and @code{vm-imap-synchronize} operations.  In order
to work while disconnected from the network, set the variable to
@code{offline}.  In this mode, @code{vm-save-folder} writes any changes
made to the folder to the local copy on disk (the ``cache'' folder);
@code{vm-visit-imap-folder} likewise visits the cache folder.

You can set @code{vm-imap-connection-mode} to @code{autoconnect} if you have
intermittent problems with the network.  In this mode, doing
@code{vm-get-new-mail} attempts to connect to the network.  If it succeeds
then @code{vm-imap-connection-mode} turns into @code{online}.

When the @acronym{IMAP} server is connected again, you should run @kbd{C-u
M-x vm-imap-synchronize}, i.e., call it with a @emph{prefix argument}.  This
causes @emph{all} the message attributes and labels to be written to the
server, since it may not be known which of them have actually changed during
the offline operation.  Similarly, @emph{all} the messages that may have
been expunged in the cache folder are expunged on the server.

@anchor{@acronym{UIDVALIDITY}}
@unnumberedsec @acronym{UIDVALIDITY}

@cindex @acronym{UIDVALIDITY}
Messages on an @acronym{IMAP} server have unique id numbers called UID's.
In addition, a second id number called @dfn{@acronym{UIDVALIDITY}} allows
the server to renumber messages when the id numbers within a particular
@acronym{UIDVALIDITY} are exhausted.  All the messages on the server at any
given time have the same @acronym{UIDVALIDITY} value.  When the server needs
to renumber the messages, it changes the @acronym{UIDVALIDITY} value and
issues new @acronym{UID} numbers for all the messages with new
@acronym{UIDVALIDITY}.  This happens but rarely because there are over two
billion UID's within each @acronym{UIDVALIDITY}.

When the @acronym{UIDVALIDITY} changes on the @acronym{IMAP} server, VM has
no easy way to identify the new UID's for the messages in its cache.  So, it
marks all the messages in the cache as invalid and refreshes the cache with
new copies of messages from the server.  This is a time-consuming operation
but it happens only rarely.  VM warns you before it refreshes the cache and
asks for confirmation.  You can abort the operation if you cannot spare the
time, but note that it is not possible to perform any changes to the
@acronym{IMAP} folder until the cache is refreshed.  You might consider
setting the @code{vm-enable-external-messages} flag to @code{(imap)} before
you refresh the cache so that it will be quicker. @pxref{External Messages}.

@unnumberedsec Operations for the IMAP server

@cindex vm-list-imap-folders
The command @code{vm-list-imap-folders} lists the folders available on the
@acronym{IMAP} server, along with the total number of messages and recent
(new) messages in each of them.  If you run it with a prefix argument, it
lists only those folders that have new messages.

@cindex vm-create-imap-folder
@cindex vm-delete-imap-folder
@cindex vm-rename-imap-folder
Use the command @code{vm-create-imap-folder} for creating a new folder on
the @acronym{IMAP} server and @code{vm-delete-imap-folder} for deleting an
existing folder.  You can rename a folder using
@code{vm-rename-imap-folder}.

@node Frames and Windows, Toolbar, @acronym{IMAP} Server Folders, Top
@chapter Frames and Windows

VM uses Emacs frames and windows to display messages and summaries
and to provide a place for you to compose messages.  Using VM's
frame configuration facilities you can control when VM creates new
frames and the size and attributes associated with new frames.
Inside each frame you can associate different window setups with
commands and classes of commands by using VM's window configuration
facilities.

@vindex vm-mutable-frame-configuration
@vindex vm-mutable-frames
To use VM's frame configuration features, the variable
@code{vm-mutable-frame-configuration} must be set non-@code{nil}.  This is
the default.  If @code{vm-mutable-frame-configuration} is set to @code{nil}
VM will only use the current frame, and VM will not create, delete or resize
frames.  (This variable was called @code{vm-mutable-frames} in versions
prior to 8.2.)

@vindex vm-mutable-window-configuration
@vindex vm-mutable-windows
To use window configurations, the variable
@code{vm-mutable-window-configuration} must be set non-@code{nil}.  If
@code{vm-mutable-window-configuration} is set to @code{nil}, VM will only
use the selected window, and will not create, delete or resize windows.
(This variable was called @code{vm-mutable-windows} in versions
prior to 8.2.)

@menu
* Frame Configuration::         How to configure frame use and appearance.
* Window Configuration::        How to configure window use and appearance.
@end menu

@node Frame Configuration, Window Configuration, Frames and Windows, Frames and Windows
@section Frame Configuration

VM has a set of variables that let you specify when VM creates
frames and what attributes the new frames will have.

@vindex vm-frame-per-folder
If @code{vm-frame-per-folder} is set non-@code{nil}, when you visit a folder,
VM will create a new frame and display that folder in the new
frame.  When you quit the folder, VM will delete the frame.

@vindex vm-frame-per-summary
If @code{vm-frame-per-summary} is set non-@code{nil}, the @code{vm-summarize}
command will create a new frame in which to display a folder's summary
buffer.  This works best if a full-screen window configuration has
been assigned to the @code{vm-summarize} command.  When you quit the folder
or kill the summary, VM will delete the frame.

@vindex vm-frame-per-composition
Setting @code{vm-frame-per-composition} non-@code{nil} causes VM to create a
new frame for the composition buffer when you run any of VM's message
composition commands.  E.g. @code{vm-reply-include-text},
@code{vm-mail-from-folder}, @code{vm-mail}, @code{vm-forward-message}.  When
you finish editing the composition and send it, or when you kill the
composition buffer, the frame will be deleted.

@vindex vm-frame-per-edit
The variable @code{vm-frame-per-edit}, if non-@code{nil}, tells VM to create a
new frame when the vm-edit-message command is run.  When you
finish editing the message, or abort the edit, the frame will be
deleted.

@vindex vm-frame-per-help
If @code{vm-frame-per-help} is set non-@code{nil}, VM will create a new frame
to display any help buffer produced by the vm-help command.

@vindex vm-frame-per-completion
If @code{vm-frame-per-completion} is set non-@code{nil}, VM will create a new
frame on mouse initiated completing reads.  A mouse initiated
completing read occurs when you invoke a VM command using the
mouse, either with a menu or a toolbar button.  That command
must then prompt you for information, and there must be a
limited set of valid responses.  If these conditions are met
and @code{vm-frame-per-completion}'s value is non-@code{nil}, VM will
create a new frame containing a list of responses that you can
select with the mouse.

@vindex vm-search-other-frames
When VM is deciding whether to create a new frame, it checks
other existing frames to see if a buffer that it wants to display in a
frame is already being displayed somewhere.  If so, then VM will
not create a new frame.  If you don't want VM to search other
frames, set the variable @code{vm-search-other-frames} to @code{nil}.  VM will 
still search the currently selected frame and will not create a
new frame if the buffer that it wants to display is visible there.

@vindex vm-frame-parameter-alist
The variable @code{vm-frame-parameter-alist} allows you to specify the
frame parameters for newly created frames.

The value of @code{vm-frame-parameter-alist} should be of this form

@example
((@var{SYMBOL} @var{PARAMLIST}) (@var{SYMBOL2} @var{PARAMLIST2}) ...)
@end example

@var{SYMBOL} must be one of ``completion'', ``composition'', ``edit'',
``folder'', ``primary-folder'' or ``summary''.  It specifies the type
of frame that the following @var{PARAMLIST} applies to.

@table @code
@item completion
specifies parameters for frames that display lists of
choices generated by a mouse-initiated completing read.
(See @code{vm-frame-per-completion}.)
@item composition
specifies parameters for mail composition frames.
@item edit
specifies parameters for message edit frames
(e.g. created by @code{vm-edit-message-other-frame})
@item folder
specifies parameters for frames created by `vm' and the
@code{vm-visit-} commands.
@item primary-folder
specifies parameters for the frame created by running
@code{vm} without any arguments.
@item summary
specifies parameters for frames that display a summary buffer
(e.g. created by @code{vm-summarize-other-frame})
@end table
@var{PARAMLIST} is a list of pairs as described in the documentation for
the function @code{make-frame}.

@node Window Configuration,, Frame Configuration, Frames and Windows
@section Window Configuration

@findex vm-save-window-configuration
@kindex W S
Window configurations allow you to specify how the windows within
a frame should look for a particular command or class of
commands.  Each command can have a configuration associated with
it and you can also associate a configuration with command
classes like ``reading-message'' or ``composing-message''.  To
setup a window configuration, first use Emacs' window management
commands (@code{split-window}, @code{enlarge-window}, etc.)  to make the
windows in the frame look the way you want.  Then use the
switch-to-buffer command to put the buffers you want to see into
the windows.  Next type @kbd{W S}, which invokes the
@code{vm-save-window-configuration} command.  Type the name of the
command or class of commands to which you want the configuration
to apply.  Nearly all VM commands can be entered here.  Valid
classes are:

@display
    default
    startup
    quitting
    reading-message
    composing-message
    marking-message
    searching-message
@end display

When a VM command is executed, window configurations are searched 
for as follows.  First, a command specific configuration is
searched for.  If one is found, it is used.  Next a class
configuration is searched for.  Not all commands are in command
classes.  Message composition commands are in the
``composing-message'' class.  All the @code{vm-quit*} commands are in the
``quitting'' class.  All the VM commands that set and clear
message marks are in the ``marking-message'' class, and so on.
If such a class configuration is found it is used.  If no
matching class configuration is found, the ``default'' class
configuration is used, if it is defined.

Note that when a window configuration is saved the selected
window at that time will be the selected window when that window
configuration is used.  So if you prefer for the cursor to be in
a particular window, make sure you invoke
@code{vm-save-window-configuration} window from that window.  Remember
that you can invoke the command with @kbd{M-x} if VM's normal
key map is not in effect.

@kindex W D
@findex vm-delete-window-configuration
To delete a window configuration, use @kbd{W D} which is bound to
@code{vm-delete-window-configuration}.  You will be prompted for the
name of the configuration to delete.

@kindex W W
@findex vm-apply-window-configuration
To see what an existing configuration looks like, type @kbd{W W}
which invokes @code{vm-apply-window-configuration}.

@vindex vm-window-configuration-file
@cindex .vm.windows
VM saves information about your window configurations in the file
named by the variable @code{vm-window-configuration-file}.  The default
location of the configuration file is @file{"~/.vm.windows"}.
Do not make @code{vm-window-configuration-file} point to the same
location as @code{vm-init-file}, as the window configuration save
commands will then overwrite the content of your init file.

@node Toolbar, Menus, Frames and Windows, Top
@chapter Toolbar

VM can display a toolbar that allows you to run VM commands with
a single mouse click.  By default the toolbar is displayed on the
left of the Emacs frame and is only visible if you're running
under a window system like X Windows or Microsoft Windows.

@vindex vm-use-toolbar
To make VM not display the toolbar, set @code{vm-use-toolbar} to nil.
To configure what buttons are displayed on the toolbar, you must
change the value of @code{vm-use-toolbar}.  If non-@code{nil}, the value of
@code{vm-use-toolbar} should be a list of symbols and integers, which
specify which buttons appear on the toolbar and the layout of the
buttons.  These are the allowed symbols along with the buttons
they represent.

@table @code
@item autofile
The AutoFile button.  Clicking on this button runs the command
@code{vm-toolbar-autofile-message}.  This command will save the current
message into the folder matched by @code{vm-auto-folder-alist}, if there
is a match.
@item compose
The Compose button.  Clicking on this button runs the command
@code{vm-toolbar-compose-command}.  This command is normally just an
alias for the @code{vm-mail} command.  If you want the Compose button to 
do something else, redefine @code{vm-toolbar-compose-command} using
either @code{fset} or @code{defun}.
@item delete/undelete
The Delete/Undelete button.  If the current message is marked for 
deletion, this button displays as an Undelete button.  Otherwise
it displays as a Delete button.
@item file
The File button.  Clicking on this button runs the command
@code{vm-toolbar-file-command}.  This command is normally just an
alias for the @code{vm-mail} command.  If you want the File button to 
do something else, redefine @code{vm-toolbar-file-command} using
either @code{fset} or @code{defun}.
@item getmail
The Get Mail button.  Clicking on this button runs the command
@code{vm-toolbar-getmail-command}.  This command is normally just an
alias for the @code{vm-get-new-mail} command.  If you want the
Get Mail button to 
do something else, redefine @code{vm-toolbar-getmail-command} using
either @code{fset} or @code{defun}.
@item help
The Helper button.  Clicking on this button runs the command
@code{vm-toolbar-helper-command}.  This command normally just runs
@code{vm-help}, but it also does context specific things under certain
conditions.  If the current message is a @acronym{MIME} message that needs
decoding, the Helper button becomes the Decode @acronym{MIME} button.  If the 
current folder has an auto-save file that appears to be the result 
of an Emacs or system crash, the Helper button becomes the Recover 
button.  Clicking on the Recover button runs @code{vm-recover-folder}, 
so you can recover your folder from an existing auto-save file.
@item mime
The Decode @acronym{MIME} button.  Clicking on this button runs the command
@code{vm-toolbar-mime-command}.  This command is normally just an
alias for the @code{vm-decode-mime-message} command.
@item next
The Next button.  Clicking on this button runs the command
@code{vm-toolbar-next-command}.  This command is normally just an
alias for the @code{vm-next-message} command.  If you want the Next button to 
do something else, redefine @code{vm-toolbar-next-command} using
either @code{fset} or @code{defun}.
@item previous
The Previous button.  Clicking on this button runs the command
@code{vm-toolbar-previous-command}.  This command is normally just an
alias for the @code{vm-previous-message} command.  If you want the Previous button to 
do something else, redefine @code{vm-toolbar-previous-command} using
either @code{fset} or @code{defun}.
@item print
The Print button.  Clicking on this button runs the command
@code{vm-toolbar-print-command}.  This command is normally just an
alias for the @code{vm-print-message} command.  If you want the
Print button to 
do something else, redefine @code{vm-toolbar-print-command} using
either @code{fset} or @code{defun}.
@item quit
The Quit button.  Clicking on this button runs the command
@code{vm-toolbar-quit-command}.  This command is normally just an
alias for the @code{vm-quit} command.  If you want the Quit button to 
do something else, redefine @code{vm-toolbar-quit-command} using
either @code{fset} or @code{defun}.
@item reply
The Reply button.  Clicking on this button runs the command
@code{vm-toolbar-reply-command}.  This command is normally just an
alias for the @code{vm-reply-include-text} command.  If you want
the Reply button to
do something else, redefine @code{vm-toolbar-reply-command} using
either @code{fset} or @code{defun}.
@item visit
The Visit button.  Clicking on this button runs the command
@code{vm-toolbar-visit-command}.  This command is normally just an
alias for the @code{vm-visit-folder} command.  If you want the Visit button to 
do something else, redefine @code{vm-toolbar-visit-command} using
either @code{fset} or @code{defun}.
@item nil
If nil appears in the list, it must appear exactly once.  The
buttons associated with symbols that appear after nil in the
list will be display flushright for top and bottom toolbars, and
flushbottom for left and right toolbars.
@end table

If an positive integer appears in the @code{vm-use-toolbar} list, it
specifies the number of pixels of blank space to display between
the button that comes before and the button that comes after the
integer.

@vindex vm-toolbar-orientation
The variable @code{vm-toolbar-orientation} controls on which side of the 
frame the toolbar is displayed.  E.g.

@example
(setq vm-toolbar-orientation 'top)
@end example

@noindent causes the toolbar to be displayed at the top of the frame.  The
@code{top} in the example can be replaced with @code{bottom},
@code{right} and @code{left} to make the toolbar appear in those
places instead.

@vindex vm-toolbar-pixmap-directory
VM finds the images for the toolbar in the directory specified by
@code{vm-toolbar-pixmap-directory}.  This variable should already be set
properly by whoever installed VM on your system, so you should
not need to set it.

@node Menus, Faces, Toolbar, Top
@chapter Menus

@vindex vm-popup-menu-on-mouse-3
@cindex menu bar
@cindex menus, pop-up
VM uses Emacs' menu bar and pop-up menus whenever they are available
using which you can readily access VM's commands.  By default, VM puts
a context-sensitive pop-up menu on mouse button 3 (usually the
rightmost mouse button).  If you don't want this menu, set the
variable @code{vm-popup-menu-on-mouse-3} to nil.

@vindex vm-use-menus
If you set @code{vm-use-menus} to nil, VM will not generate a menu bar
for VM folder buffers and VM won't use pop-up menus either.  If you
set @code{vm-use-menus} to @samp{1}, VM will add a single @samp{VM}
menu to the existing menu bar and provide various submenus under it
for the VM operations.

By default, @code{vm-use-menus} is set to a list of symbols indicating
which menus should appear in the menu bar.  These menus will replace
the standard Emacs menus whenever VM folder are being viewed.  You can
switch to the Emacs menu bar when necessary by clicking on the menu
labelled @code{[Emacs]} (on some systems, there will be a drop-down
menu labelled @code{Emacs}).  From the Emacs menu bar, you can return
to the VM menu bar by clicking on the menu labelled @code{[VM]} (or
under the drop-down menu labelled @code{VM}).

@cindex graphics toolkit
On some graphics toolkits, menu bar cannot have ``buttons'' that
invoke immediate actions (such as @code{[Emacs]}).  VM knows about
some of those toolkits and automatically uses drop-down menus instead
of buttons.  If your system shows buttons but they are not
operational, then you should set @code{vm-use-menubar-buttons} to nil
in your init file.  That will cause VM use to drop-down menus instead
of buttons on the menu bar.

The available menus for the VM menubar are the following:

@table @code
@item dispose
This is menu of commands that are commonly used to dispose of a
message.  E.g. reply, print, save, delete.
@item emacs
This provides a menu button labelled @code{[Emacs]} that causes the
menu bar to change to the global Emacs menu bar.  On that menu bar you
will find a @code{[VM]} button that can return you to the VM menu
bar.  
@item folder
This is a menu of folder related commands.  You can visit a
folder, save a folder, quit a folder and so on.
@item help
This is a menu of commands that provide information for you if
you don't know what to do next.
@item label
This is a menu of commands that let you add and remove message
labels from messages.
@item mark
This is a menu of commands that you can use to mark and unmark
messages based on various criteria.  @xref{Selecting Messages}.
@item motion
This is a menu of commands to move around inside messages and
inside folders.
@item send
This is a menu of commands you use to compose and send messages.
@item sort
This is a menu of commands to sort a folder by various criteria.
@item undo
This provides a menu button that invokes the @code{vm-undo} command.
@item virtual
This is a menu of commands that let you visit and create virtual
folders.
@item nil
If nil appears in the list, it should appear exactly once.  All
menus after nil in the list will be displayed flushright in
the menu bar.
@end table

@node Faces, Using the Mouse, Menus, Top
@chapter Faces
VM uses Emacs faces to emphasize text in the folder and summary
buffers.  In addition to using the predefined faces of Emacs, VM also
defines several faces of its own.  You can do @code{M-x list-faces}
inside Emacs to see what faces have been defined.  You can also define
your own faces using Emacs primitives for doing so.
@xref{Faces,,,emacs, the GNU Emacs Manual}.

@vindex vm-highlighted-header-regexp
@vindex vm-highlighted-header-face
In the folder or presentation buffer, the header contents of headers
matched by the @code{vm-highlighted-header-regexp} variable are
displayed using the face named by @code{vm-highlighted-header-face}.
This variable is ignored under XEmacs if
@code{vm-use-lucid-highlighting} is non-@code{nil}.  The XEmacs
@code{highlight-headers} package is used instead.  See the
documentation for the function @code{highlight-headers} to find out
how to customize header highlighting using this package.

@cindex @acronym{URL}
@vindex vm-highlight-url-face
@vindex vm-url-search-limit
URL's that occur in message bodies are displayed using the face
named by @code{vm-highlight-url-face}.  Typing Return on such URL's or
clicking button-2 has the effect of sending the @acronym{URL} to an external web
browser.  @xref{Using the Mouse}.  Searching for @acronym{URL}s in a
large message can take a long time.  Since @acronym{URL}s often occur near
the beginning and near the end of messages, VM offers a way to
search just those parts of a message for @acronym{URL}s.  The variable
@code{vm-url-search-limit} specifies how much of a message to search.
If @code{vm-url-search-limit} has a positive numeric value @var{N}, VM 
will search the first @math{@var{N} / 2} characters and the last
@math{@var{N} / 2} characters in the message for @acronym{URL}s.

@vindex vm-mime-button-face
The face named by @code{vm-mime-button-face} is used to display the
textual buttons that trigger the display of @acronym{MIME} objects.

@xref{Summary Faces}, for the faces support in the Summary buffer.

@node Using the Mouse, Hooks, Faces, Top
@chapter Using the Mouse

VM uses the following layout for the mouse buttons in the folder
and summary buffers.

@table @asis
@item button-1 (left button usually)
Unchanged.
@cindex @acronym{URL}
@vindex vm-url-browser
@item button-2 (middle button usually)
Activate.  If you click on a summary entry, that message will be
selected and become the current message.  If you click on a
highlighted @acronym{URL} in the body of a message, that @acronym{URL} will
be sent 
to the browser specified by @code{vm-url-browser}.
@item button-3 (right button usually)
Context Menu.  If the mouse pointer is over the contents of the
From header, button-3 pops up a menu of actions that can be taken 
using the author of the message as a parameter.  For instance,
you may want to create a virtual folder containing all the
messages in the current folder written by this author.  If the
mouse pointer is over the contents of the Subject header, a menu
of actions to be performed on the current message's subject is
produced.  If button-3 is clicked over a highlighted @acronym{URL}, a menu
of Web browsers is produced.  Otherwise the normal VM mode
specific menu is produced.
@end table

@cindex Emacs-w3m
@cindex @acronym{HTML}
@vindex w3m-goto-article-function
These button assignments work only in plain text messages.  For @acronym{HTML}
messages, you might use an internal web browser such as Emacs-w3m to display
the content, which will have its own button assignments.  For instance,
Emacs-w3m binds button-2 to the browser function specified by the variable
@code{w3m-goto-article-function}.  You will need to set that variable to
the desired browser function to get button-2 to work in @acronym{HTML} messages.

In mail composition buffers only mouse button-3 is affected.
Context sensitive menus are produced when that button is clicked.

@findex vm-mouse-send-url-to-netscape
@findex vm-mouse-send-url-to-xxx
@findex vm-mouse-send-url-to-xxx-new-window
@findex browse-url
@cindex browse-url
@cindex web browser
VM provides a number of browser functions that you can set as the value of
@code{vm-url-browser}.  An example is the function
@code{vm-mouse-send-url-to-netscape}, which sends the @acronym{URL} at mouse
to the Netscape browser.  Other browsers supported in this way include
@code{mosaic}, @code{mmosaic}, @code{opera}, @code{mozilla}, @code{firefox},
and @code{konqueror}, all of which have functions of the form
@code{vm-mouse-send-url-to-xxx} and
@code{vm-mouse-send-url-to-xxx-new-window}.  You can also set
@code{vm-url-browser} to the Emacs function @code{browse-url}, and use the
facilities defined in the @samp{browse-url} library to send URL's to
external browsers.

@node Hooks, Configuration, Using the Mouse, Top
@chapter Hooks

VM has many hook variables that allow you to run functions when
certain events occur.  Here is a list of the hooks and when they
are run.  (If you don't write Emacs-Lisp programs you 
can skip this chapter.)

@table @code
@vindex vm-select-new-message-hook
@item vm-select-new-message-hook
List of hook functions called every time a message with the ``new''
attribute is made to be the current message.  When the hooks are run, the
current buffer will be the folder containing the message and the
start and end of the message will be bracketed by (point-min) and
(point-max).

@item vm-select-unread-message-hook
@vindex vm-select-unread-message-hook
List of hook functions called every time a message with the ``unread''
attribute is made to be the current message.  When the hooks are run, the
current buffer will be the folder containing the message and the
start and end of the message will be bracketed by (point-min) and
(point-max).

@item vm-select-message-hook
@vindex vm-select-message-hook
List of hook functions called every time a message
is made to be the current message.  When the hooks are run, the
current buffer will be the folder containing the message and the
start and end of the message will be bracketed by (point-min) and
(point-max).

@item vm-save-message-hook
@vindex vm-save-message-hook
List of hook functions called every time a message is saved to a folder.
When the hooks are called, the current buffer will be the folder containing
the message and the start and end of the message will be bracketed by
(point-min) and (point-max).  The hooks are called with one argument, a
string denoting the folder where the message was saved.  The folder could be
a file name or the maildrop specification of an @acronym{IMAP} mailbox.

@item vm-arrived-message-hook
@vindex vm-arrived-message-hook
List of hook functions called once for each message gathered from the
system mail spool, or from another folder with @code{vm-get-new-mail},
or from a digest with @code{vm-burst-digest}.  When the hooks are run,
the current buffer will be the folder containing the message and the
start and end of the message will be bracketed by (point-min) and
(point-max).

@item vm-spooled-mail-waiting-hook
@vindex vm-spooled-mail-waiting-hook
List of functions called when VM first notices mail is spooled
for a folder.  The folder buffer will be current when the hooks are
run.

@item vm-arrived-messages-hook
@findex vm-get-new-mail
@vindex vm-arrived-messages-hook
List of hook functions called after VM has gathered a group
of messages from the system mail spool, or from another
folder with @code{vm-get-new-mail}, or from a digest with
@code{vm-burst-digest}.  When the hooks are run, the new
messages will have already been added to the message list
but may not yet appear in the summary.  When the hooks are
run the current buffer will be the folder containing the
messages.

@item vm-reply-hook
@vindex vm-reply-hook
List of hook functions to be run after a Mail mode composition
buffer has been created for a reply.  VM runs this hook and then
runs @code{vm-mail-mode-hook} before leaving you in the Mail
mode buffer.

@item vm-forward-message-hook
@vindex vm-forward-message-hook
List of hook functions to be run after a Mail mode
composition buffer has been created to forward a message.  VM
runs this hook and then runs @code{vm-mail-mode-hook} before leaving the
user in the Mail mode buffer.

@item vm-resend-bounced-message-hook
@vindex vm-resend-bounced-message-hook
List of hook functions to be run after a Mail mode
composition buffer has been created to resend a bounced message.
VM runs this hook and then runs @code{vm-mail-mode-hook} before leaving
you in the Mail mode buffer.

@item vm-resend-message-hook
@vindex vm-resend-message-hook
List of hook functions to be run after a Mail mode composition
buffer has been created to resend a message.  VM runs this hook
and then runs @code{vm-mail-mode-hook} before leaving you in
the Mail mode buffer.

@item vm-send-digest-hook
@vindex vm-send-digest-hook
List of hook functions to be run after a Mail mode composition
buffer has been created to send a digest.  VM runs this hook and
then runs @code{m-mail-mode-hook} before leaving you in the Mail
mode buffer.

@item vm-mail-hook
@vindex vm-mail-hook
List of hook functions to be run after a Mail mode
composition buffer has been created to send a non specialized
message, i.e. a message that is not a reply, forward, digest,
etc.  VM runs this hook and then runs @code{vm-mail-mode-hook} before
leaving you in the Mail mode buffer.

@item vm-summary-update-hook
@vindex vm-summary-update-hook
List of hook functions called just after VM updates an existing
entry in a folder summary buffer.

@item vm-summary-redo-hook
@vindex vm-summary-redo-hook
List of hook functions called just after VM adds or deletes
entries from a folder summary buffer.

@item vm-visit-folder-hook
@vindex vm-visit-folder-hook
List of hook functions called just after VM visits a folder.
It doesn't matter if the folder buffer already exists, this hook
is run each time @code{vm} or @code{vm-visit-folder} is called interactively.
It is @emph{not} run after @code{vm-mode} is called.

@item vm-retrieved-spooled-mail-hook
@vindex vm-retrieved-spooled-mail-hook
List of hook functions called just after VM has retrieved
a group of messages from your system mailbox(es).  When these
hooks are run, the messages have been added to the folder buffer
but not the message list or summary.  When the hooks are run, the
current buffer will be the folder where the messages were
incorporated.

@item vm-edit-message-hook
@vindex vm-edit-message-hook
List of hook functions to be run just before a message is edited.
This is the last thing @code{vm-edit-message} does before leaving you
in the edit buffer.

@item vm-mail-mode-hook
@vindex vm-mail-mode-hook
List of hook functions to be run after a Mail mode
composition buffer has been created.  This is the last thing VM
does before leaving you in the Mail mode buffer.

@item vm-mode-hook
@vindex vm-mode-hook
List of hook functions to run when a buffer enters @code{vm-mode}.
These hook functions should generally be used to set key bindings
and local variables.

@item vm-mode-hooks
@vindex vm-mode-hooks
Old name for @code{vm-mode-hook}.
Supported for backward compatibility.
You should use the new name.

@item vm-summary-mode-hook
@vindex vm-summary-mode-hook
List of hook functions to run when a VM summary buffer is created.
The current buffer will be that buffer when the hooks are run.

@item vm-summary-mode-hooks
@vindex vm-summary-mode-hooks
Old name for @code{vm-summary-mode-hook}.
Supported for backward compatibility.
You should use the new name.

@item vm-virtual-mode-hook
@vindex vm-virtual-mode-hook
List of hook functions to run when a VM virtual folder buffer is created.
The current buffer will be that buffer when the hooks are run.

@item vm-presentation-mode-hook
@vindex vm-presentation-mode-hook
List of hook functions to run when a VM presentation buffer is
created.  The current buffer will be the new presentation buffer
when the hooks are run.  Presentation buffers are used to display
messages when some type of decoding must be done to the message
to make it presentable.  E.g. @acronym{MIME} decoding.

@item vm-quit-hook
@vindex vm-quit-hook
List of hook functions to run when you quit VM.
This applies to all VM quit commands, including @code{vm-quit-no-change}.
So you should not include in this hook any functions that alter the folder.
For automatically expunging deleted messages, set the variable
@code{vm-expunge-before-quit}. 

@item vm-summary-pointer-update-hook
@vindex vm-summary-pointer-update-hook
List of hook functions to run when the VM summary pointer is updated.
When the hooks are run, the current buffer will be the summary buffer.

@item vm-display-buffer-hook
@vindex vm-display-buffer-hook
List of hook functions that are run every time VM wants to
display a buffer.  When the hooks are run, the current buffer will
be the buffer that VM wants to display.  The hooks are expected
to select a window and VM will display the buffer in that
window.

If you use display hooks, you should not use VM's built-in window
configuration system as the result is likely to be confusing.

@item vm-undisplay-buffer-hook
@vindex vm-undisplay-buffer-hook
List of hook functions that are run every time VM wants to
remove a buffer from the display.  When the hooks are run, the
current buffer will be the buffer that VM wants to disappear.
The hooks are expected to do the work of removing the buffer from
the display.  The hook functions should not kill the buffer.

If you use undisplay hooks, you should not use VM's built-in
window configuration system as the result is likely to be
confusing.

@item vm-iconify-frame-hook
@vindex vm-iconify-frame-hook
List of hook functions that are run whenever VM iconifies a frame.

@item vm-menu-setup-hook
@vindex vm-menu-setup-hook
List of hook functions that are run just after all menus are initialized.

@item vm-mime-display-function
@vindex vm-mime-display-function
If non-@code{nil}, this should name a function to be called inside 
@code{vm-decode-mime-message} to do the @acronym{MIME} display of the current
message.  The function is called with no arguments, and at the
time of the call the current buffer will be the @dfn{presentation
buffer} for the folder, which is a temporary buffer that VM uses
for the display of @acronym{MIME} messages.  A copy of the current message
will be in the presentation buffer at that time.  The normal work
that @code{vm-decode-mime-message} would do is not done, because this
function is expected to subsume all of it.

@item vm-mail-send-hook
@vindex vm-mail-send-hook
List of hook functions to call just before sending a message.
The hooks are run after confirming that you want to send the
message (see @code{vm-confirm-mail-send}) but before @acronym{MIME} encoding
and FCC processing.

@item mail-yank-hooks
@vindex mail-yank-hooks
Hooks called after a message is yanked into a mail composition buffer.

(This hook is deprecated, you should use mail-citation-hook instead.)

The value of this hook is a list of functions to be run.  Each
hook function can find the newly yanked message between point
and mark.  Each hook function should return with point and mark
around the yanked message.

See the documentation for @code{vm-yank-message} to see when VM will run
these hooks.

@item mail-citation-hook
@vindex mail-citation-hook
Hook for modifying a citation just inserted in the mail buffer.
Each hook function can find the citation between (point) and (mark t).
And each hook function should leave point and mark around the citation
text as modified.

If this hook is entirely empty, i.e. @code{nil}, a default action is taken
instead of no action.
@end table

@node Configuration, Preface to Add-ons, Hooks, Top
@section Configuration of VM

@unnumberedsubsec Hints on email environment configuration

When VM was first written, the majority of users received their email and
replied to them on Unix systems.  These systems either ran permanent services
for receiving and sending email, or they shared their file systems with
other servers which provided such services.  The local system administrators
took care of all the configuration.

Today, the majority of users receive their email and reply to them on remote
servers across th Internet.  A variety of protocols are used to download,
share and transmit email, which the users need to know about.  In addition,
the email messages sent across the network are open to probes that violate
our privacy and security.  To address the problem, additional security
protocols are used to protect privacy.  Finally, VM runs inside the Emacs
environment and depends on it for the implementation of various protocols,
and Emacs in turn depends on other Gnu tools for other implementations of
protocols.  This section is an attempt to bring together all the information
you would be potentially required to master in order to configure VM through
all these protocols and services.  It is only expected to be introductory.
You may need to consult additional documentation of other protocols and
programs in order to fully understand how to configure your email
environment.

@unnumberedsubsubsec Configuration for email reception

If you receive email on a remote server, that email will be made available
via a mail reception protocol.  The two commonly used protocols are:

@itemize
@item @acronym{POP} (Post office protocol)
@item @acronym{IMAP} (Internet message access protocol)
@end itemize

@noindent @acronym{POP} was designed to receive and store your email in a
``post office'' until you are ready to download it to your own computer.
Once you download it, the email gets deleted from the server's ``post
office.''  However, today, most @acronym{POP} servers also provide the
ability to retain the email in the post office even after you downloaded it.

@acronym{IMAP} was designed to receive and store your email essentially
permanently.  However, the @acronym{IMAP} service providers are likely to
give you a limit on how much disk space your account will be allowed to use.
As long as you are within those limits, you can organize your email on the
server as if it is your own computer, and create multiple folders etc.

VM provides two ways of working with mail servers:

@itemize
@item
You can store your email in local folders and download new mail from the
mail servers.  @xref{Local Folders}, especially the subsections on
``@acronym{POP} Spool Files'' and ``@acronym{IMAP} Spool Files.''  Even
though the local folders method is provided for both @acronym{POP} and
@acronym{IMAP} servers, it is really appropriate only for @acronym{POP}
servers.
@item
You can store your email on the mail server and process it in VM via cache
folders stored on your file system.  @xref{@acronym{POP} and @acronym{IMAP}
Folders}.  Even though the method of server folders is provided for both
@acronym{POP} and @acronym{IMAP} servers, it is really appropriate only for
@acronym{IMAP} servers.
@end itemize

@unnumberedsubsubsec Configuration for secure email reception

To ensure privacy on the open Internet while you download email from mail
servers, some servers provide an additional secure communication layer.
Some servers insist that you can only use secure communication, and
refuse to provide an insecure channel.  For your own security, you should
attempt to use the secure communication layer whenever it is available.  You
can specify the secure mail servers using tags @code{pop-ssl} or
@code{imap-ssl} in defining maildrop specifications.  Please make sure that
you specify an appropriate port number, as required by the documentation of
your mail server.  (Normally port 995 is used for @code{pop-ssl} and
port 993 is used for @code{imap-ssl}.)

Secure channels are provided using a protocol called @acronym{SSL} (Secure
Sockets Layer).  A later version of the protocol is called @acronym{TLS}
(Transport Layer Security), which is backward compatible with @acronym{SSL}.

Gnu Emacs version 24 has a built-in implementation of @acronym{TLS} (which
also includes @acronym{SSL}).  Prior versions of Gnu Emacs do not have it.
Other versions of Emacs may or may not have any implementation of
@acronym{SSL} or @acronym{TLS}.

If the Emacs version does not have SSL/TLS support, you can use an external
@code{stunnel} program to establish a secure ``tunnel''.  You can download
the @code{stunnel} program from the @code{stunnel.org} web site, and install
it somewhere on the @code{exec-path}.  VM is preconigured to use the
@code{stunnel} program for talking to the mail servers that require SSL,
i.e., the value of the variable @code{vm-stunnel-program} is set to
@code{stunnel}.  VM automatically generates a configuration file that the
@code{stunnel} program requires, starts the program, and communicates
through it to the mail server.  You can look at the generated configuration
file by running:

@example
M-: (find-file (vm-stunnel-configuration-file))
@end example

@noindent Depending on what is required by your mail server, you may need to
specify additional configuration options for @code{stunnel}.  In that case,
you should create the required configuration file and set the variable
@code{vm-stunnel-program-additional-configuration-file} to its path name.

If your Emacs version has a built-in implementation of @acronym{TLS} and you
wish to use it, you should set the variable @code{vm-stunnel-program} to
@code{nil}.

@unnumberedsubsubsec Configuration for email sending

Configuration for sending email can be more complicated, partly because you
are dependent on Emacs for the mail sending libraries.  VM does not have its
own mail sending functionality.

The original Emacs mail-sending library is called @code{sendmail.el} (also
referred to @code{mail-mode} because of its user interface for mail
composition).  This library essentially assumes that the local machine has
mail sending capabilities.

When using remote servers for mail sending, the servers runs a protocol
called @acronym{SMTP} (Simple mail transfer protocol).  A separate Emacs
library @code{smtpmail.el} has been written to intervene in the operation of
@code{sendmail.el} and hand the mail to the remote @acronym{SMTP} server
instead.  @xref{top,, Emacs SMTP Library, smtpmail, Emacs SMTP Library}.
This library has traditionally had limited functionality, and various other
packages have been contributed to enhance the functionality.

On the server side, there are actually two versions of the @acronym{SMTP}
that are run by servers.  The so-called ``Mail Transfer Agents'' use port 25
for plain connections and port 465 for secure @acronym{SSL} connections.
Mail Submission Agents use port 587 for both secure and insecure
communication.  These complexities, coupled with the limited functionality
of @code{smtpmail.el} library, have made the life difficult to many users.

@vindex smtpmail-stream-type
@vindex smtpmail-smtp-service
The @code{smtpmail.el} library included with Gnu Emacs version 24 has
@acronym{SSL}/@acronym{TLS} functionality.  Follow these guidelines for
configuring the uptodate @code{smtpmail} library depending on the type of
the @acronym{SMTP} server.

@itemize
@item The @acronym{SMTP} server does not use a secure protocol.

In this case, the server expects connections on port 25.  You should set the
variable @code{smtpmail-stream-type} to @code{nil} and
@code{smtpmail-smtp-service} to 25.

@item The @acronym{SMTP} server supports @acronym{SSL}.

In this case, you should set the variable @code{smtpmail-stream-type} to
@code{ssl} to use it with the mail server. The port number to use (usually
465) is specified in the variable @code{smtpmail-smtp-service}.

@item The @acronym{SMTP} server is a Mail Submission Agent.

This is the more complicated case.  The @acronym{SMTP} server expects a ``mail
submission'' connection on port 587, and it may require a @acronym{STARTTLS}
protocol to engage in secure communication.  This means that your mail
program first communicates insecurely, the server informs it that it
requires the @acronym{STARTTLS} protocol, and the mail program must then
initiate a negotiation to establish a secure channel.

In Gnu Emacs 24, due to the integration of the @acronym{TLS} protocol, Emacs
is able to use an external @acronym{GnuTLS} library, which can execute a
@acronym{STARTTLS} protocol.  However, you must obtain and install the
binary executables of the @acronym{GnuTLS} library on your system in order
to obtain this functionality.  Having done this, you should set the variable
@code{smtpmail-stream-type} to @code{starttls} to request Emacs to use
the @code{STARTTLS} protocol.  Emacs 24 tries both an external
@acronym{GnuTLS} library and its own internal @code{starttls.el} library, to
achieve the @code{STARTTLS} negotiation.

If you set @code{smtpmail-stream-type} to @code{nil} (which is also the
default value), then Emacs tries a plain text communication initially and
upgrades it to @acronym{TLS} if the server requires @acronym{STARTTLS}.
@end itemize

Prior to Gnu Emacs 24, Emacs did not have built-in support for @acronym{SSL}
or @acronym{TLS} protocols.  However, a contributed Emacs package called
@code{starttls.el} was available to make use of an external @acronym{GnuTLS}
library which was not integrated with Emacs.  The @code{smtpmail.el} library
did not have the @code{smtpmail-stream-type} setting.  The default behaviour
depended on the @code{smtpmail-smtp-service}, with the possible values of
25, 465 or 587, as explained above.  It did the job adequately for many
users.  But it did not work properly on the Windows platform, because
Windows did not respect the signal requests needed for @acronym{STARTTLS}
negotiation.

@node Preface to Add-ons, Customizations, Configuration, Top
@unnumbered What are Add-ons?

Over the years, a number of users have contributed various functions
and packages adding features and customizations to VM.  Many of them
have been collected and included in the standard VM distribution.

This part of the manual provides documentation for these features.

The add-ons are classified into:

@itemize
@item Customizations.
Small functions or settings that can be tagged on top of VM to make it
easier to use, either in general or in particular environments.
@item Add-ons.
More elaborate features.
@item Packages.
Full-blown packages that add new functionality or interface to other
packages in your environment.
@end itemize

@node Customizations, History and Administration, Preface to Add-ons, Top
@chapter Customizations
Useful ways to customize VM.
@section Reading messages

@unnumberedsubsec Shrunken headers

@cindex headers, shrunken
@vindex vm-enable-addons
Some messages come with huge lists of recipients and one has to page
through them before getting to the actual content of the message.  The
@dfn{shrunken headers} feature, included in @code{vm-rfaddons},
addresses this problem.  To use the feature, you must add
@code{shrunken-headers} to the variable @code{vm-enable-addons} in
your VM init file:

@example
(setq vm-enable-addons (cons 'shrunken-headers vm-enable-addons))
@end example

@noindent The add-on abbreviates all the message headers to
single lines, and adds a button at the end.  You can click
the button to expand the header to its full length.  The function
@code{vm-shrunken-headers-toggle} can be used to expand or collapse
all the headers of a message.  You might bind this to a key, if you
use it often.

(This add-on was provided by Robert Fenk.)

@unnumberedsubsubsec @acronym{MIME} alternatives
@cindex @acronym{MIME} alternatives
The default setting of VM for handling @acronym{MIME} alternatives is
@code{best-internal}, which means the best alternative that can be
displayed internally in VM is chosen.  Many users have environments
where only @code{text/plain} parts can be displayed internally.
However, some messages come with @code{text/html} parts that are
expected to be more faithful to the sender's composition.  On
occasion, you might wish to see the @code{text/html} part even if it
has to be viewed externally.

@cindex @acronym{MIME} alternative, best
@cindex @acronym{MIME} alternative, best-internal
@findex vm-toggle-best-mime
The function @code{vm-toggle-best-mime} function, included in
@code{vm-rfaddons}, allows you to change VM's selection method to
@code{best} temporarily so that you can view the @code{text/html}
part.  You can use the same function to change the method back to
@code{best-internal}.

(Thanks to Alley Stoughton for this contribution.)

@section Saving messages and attachments

@unnumberedsubsec Auto saving attachments

Messages with attachments get bulky and increase the size of VM
folders, slowing down VM.  The functions
@code{vm-save-all-attachments} and @code{vm-save-attachments} provide
ways to save attachments of messages on the file system and deleting
them from the mail folders.

@findex vm-mime-auto-save-all-attachments
@vindex vm-mime-auto-save-all-attachments-subdir
The function @code{vm-mime-auto-save-all-attachments}, included in
@code{vm-rfaddons}, provides enhanced functionality for saving
attachments.  It saves the attachments in a sub-directory of
@code{vm-mime-save-attachment-save-directory}, whose name is obtained
by concatenating the ``from'', ``subject'' and ``date'' headers of the
message.  This can be customized via the variable
@code{vm-mime-auto-save-all-attachments-subdir}. 

You can save the attachments of all new messages automatically by
putting @code{vm-mime-auto-save-all-attachments} in
@code{vm-select-new-message-hook}.

(This add-on was provided by Robert Fenk.)

@node History and Administration, Highlights, Customizations, Top
@chapter History and Administration

@cindex Kyle Jones
VM was developed by Kyle Jones, starting in early 1989.  The first
public release of VM was version 4.10, released in June of that year.
The original development environment was GNU Emacs 18.52.  

@cindex Wonderworks
The copyright for the code was retained by Kyle Jones.  Hence, the
package was never included in GNU releases, which only contain code
copyrighted by the Free Software Foundation.  However, Lucid/XEmacs
shipped VM starting with version 19.9.  The other users obtained VM from
the Wonderworks web site, which hosted Kyle Jones's work.  The home page
of VM at this site is @uref{http://www.wonderworks.com/vm}.

The last version released by Kyle Jones was 7.19, in September 2004,
which can be found on the Wonderworks web site and its mirror sites.

@cindex Robert Widhopf-Fenk
After this release, Robert Widhopf-Fenk picked up the maintenance of
VM, by releasing a series of patches under a separate distribution.  He
also acquired a number of add-on's contributed by various developers,
including himself, and included them in his distribution.  Kyle Jones
agreed to hand over the maintenance of VM to Robert Fenk in February,
2007.  Further releases were made by Robert Fenk under the @code{8.0.x}
series. 

@cindex Savannah
All these releases are available from the new project page of VM hosted
by Savannah, at the @acronym{URL}
@uref{http://savannah.nongnu.org/projects/viewmail/}. 
According to the project page, ``this site exists to continue VM development
after version 7.19 as a community project.''

@cindex Ulrich M�ller
@cindex Uday S Reddy
VM wwas  maintained by a ``VM Development Team,'' consisting of
Robert Widhopf-Fenk, Ulrich M�ller and Uday S Reddy.  Other potential members
are warmly welcomed.  Robert Fenk has been inactive since November, 2008
but he continues to be an official member of the team.  The new
releases made by the team are numbered @code{8.1.0} and up.

@cindex GitLab
In 2024, the project code development was moved to GitLab
@uref{https://gitlab.com/emacs-vm/vm/} by a small team of
new developers.

@unnumberedsec Savannah project site

The changes made in each of the releases is described in the @samp{NEWS}
file, which can be found in the source code repository.  The changes made
in versions up to 7.19 are described in the @samp{CHANGES} file.

The @code{Download} link on the Savannah project page, takes you to the
downloads area where all the recent releases are available.  Under the
@code{Source Code} menu, the @code{Browse Sources Repository} takes you
to the source files, which include, among others, the @samp{NEWS} and
@samp{CHANGES} files mentioned above.

If you have obtained VM through a secondary distribution that does not
include all the sources, you can browse and download the sources from
the @code{Source Code} menu.  The @code{Use Bazaar} entry in the menu
takes you to a page that lists various version of VM source code, and
gives instructions for downloading it via @samp{Bazaar} (@code{bzr}).

@unnumberedsec Technical support

VM has a dedicated usenet newsgroup @code{gnu.emacs.vm.info} and a
gmane newsgroup @code{gmane.emacs.viewmail}, in which the developers
and the active users participate.  This is the first port of call for
getting help with VM.  The archives of the newsgroup dating back to
the very beginning can be found at the Google Groups site
@uref{http://groups.google.com/group/gnu.emacs.vm.info/topics}.  The
discussions can also be accessed by email via a mailing list
@uref{viewmail-info}.  Please go to the Savannah home page to
subscribe to it.

The easiest way to report bugs that need fixing is to use the command
@code{M-x vm-submit-bug-report} within VM.  This prepares an email
message by including a state of your VM program which will allow the
developers to reproduce your problem.  (Potentially sensitive information
such as passwords are not included in this state.)  Please include a
detailed description of the problem and how it arose.  The developers
may need to ask you for further information or ask you to try
alternative approaches to narrow down the problem.

The best way to report bugs at GitLab site:
@uref{https://gitlab.com/emacs-vm/vm/-/issues}.

@unnumberedsec Get Involved

VM is now supported and maintained by the user community.  So, as an
active user, your participation is key to keep the project going.

@unnumberedsubsec Contributors

Contributions to the code from the following members of the VM community
are gratefully acknowledged:

@itemize
@item Aidan Kehoe
@item Glenn <unknown last name>
@item Jens Gustedt
@item John J Foerch
@item Kevin Rogers
@item Rob Hodges
@item Robert Marshall
@item Robert P. Goldman
@item Katsumi Yamaoka
@item Julian Bradfield
@item Samuel Bronson
@item Brent Goodrick
@item Tim Cross
@item Arik Mitschang
@item Anthony Mallet
@item Noah Friedman
@item JJK ``Blueman''
@item Eric Schulte
@end itemize

Please let us know if any contributors have been missed out.

@unnumberedsubsec Selected Releases of Kyle Jones
@itemize
@item Version 4.10, released in 1989.
@item Version 5.00, released in 1990.
@item Version 6.00, released 6 January, 1997.
@item Version 7.00, released 2 December, 2001.
@item Version 7.10, released 5 March, 2003.
@item Version 7.15, released 3 May, 2003.
@item Version 7.16, released 26 May, 2003.
@item Version 7.17, released 6 July, 2003.
@item Version 7.18, released 2 November, 2003.
@item Version 7.19, released 29 September, 2004.
@end itemize


@unnumberedsubsec Releases of Robert Widhopf-Fenk
@itemize
@item Version 8.0.0, released 31 May, 2007.
@item Version 8.0.1, released 29 June, 2007.
@item Version 8.0.2, released 25 July, 2007.
@item Version 8.0.3, released 15 August, 2007.
@item Version 8.0.4, released 2 November, 2007.
@item Version 8.0.5, released 3 November, 2007.
@item Version 8.0.6, released 2 January, 2008.
@item Version 8.0.7, released 5 January, 2008.
@item Version 8.0.8, released 11 February, 2008.
@item Version 8.0.9, released 20 February, 2008.
@item Version 8.0.10, released 22 June, 2008.
@item Version 8.0.11, released 11 August, 2008.
@item Version 8.0.12, released 5 November, 2008.
@item Version 8.0.13, released 29 November, 2009.
@item Version 8.0.14, released 16 December, 2009.
@end itemize


@unnumberedsubsec Releases of VM development team
@itemize
@item Version 8.1.0, released 21 March, 2010.
@item Version 8.1.1, released 25 April, 2010.
@item Version 8.1.2, released 5 March, 2012.
@item Version 8.2.0, planned for release in March, 2013.
@item Version 8.3.0, released 22 December 2025
@item Version 8.3.1, released 27 December 2025
@item Version 8.3.2, released 29 December 2025
@item Version 8.3.3snapshot, from git
@end itemize





@node Highlights, Future Plans, History and Administration, Top
@chapter Highlights

Here are some of the VM features that its users find most valuable:

@cindex @acronym{BBDB}
@cindex @acronym{IMAP}
@cindex @acronym{HTML}
@cindex @acronym{MIME}
@cindex virtual folders
@itemize
@item
VM's reliability and stability.
@item
Integration within Emacs, providing ease of editing and familiar key
bindings. 
@item
Speed of usage facilitated by keyboard commands.
@item
Integration with @acronym{BBDB} for maintaining contacts and email addresses.
@item
VM-Pcrisis for managing multiple mail identities.
@item 
Integration with emacs-w3m for viewing @acronym{HTML} email.
@item
Comprehensive @acronym{MIME} support.
@item
Ability to operate on all attachments of a message, such as saving or
deleting. 
@item
Interactive virtual folders (created by @code{V C}).
@item
Support for @acronym{IMAP} folders.
@item
Ability to delete duplicate copies of messages.
@end itemize


@node Future Plans, Bugs, Highlights, Top
@chapter Future Plans

Some of the ideas being worked on for future extensions of VM are the
following:

@itemize
@item 
Ability to compose rich text email messages (in 'text/enriched' and
'text/html' modes).
@item
Incremental search in virtual folders.
@item
Downloading @acronym{IMAP} messages without attachments.
@item
Support for maildir folders.
@item
A message migration/expiration facility.
@end itemize


@node Bugs, Internals, Future Plans, Top
@chapter Reporting Bugs
@cindex bug reports

VM has a sophisticated bug reporting system in order to provide the
VM maintainers with adequate information about the state of VM when the
error situation occurred.  However, it is still important for the
users to give as full an explanation of the problem as possible.
@xref{Bugs,,,emacs, the GNU Emacs Manual}.


@findex vm-submit-bug-report
The command @code{M-x vm-submit-bug-report} should be invoked from the
VM folder buffer in which a problem is encountered.  This creates a
mail buffer with information about the state of VM pre-filled.  Insert
suitable text to explain the problem and send the bug-report message.

@findex vm-pop-start-bug-report
@findex vm-pop-submit-bug-report
@findex vm-imap-start-bug-report
@findex vm-imap-submit-bug-report
For mail server-associated problems dealing with @acronym{POP}/@acronym{IMAP} spool files
or @acronym{POP}/@acronym{IMAP} folders, the cause of the problem might be in the
interaction with the mail server.  To identify the cause, it may be
necessary for the VM maintainer to look at the server interactions
during the problem occurrence.  To capture the server interactions,
run @code{vm-pop-start-bug-report}/@code{vm-imap-start-bug-report}
before the problem occurrence and @code{vm-pop-submit-bug-report}
/@code{vm-imap-submit-bug-report} after the problem occurrence.  All
the server interactions during the interval are captured and
automatically included in the bug-report.

@node Internals, Concept Index, Bugs, Top
@chapter VM Internals

This section gives a sketchy overview of the VM internals for the
developers/programmers. 

@menu
* Folder Internals::      Structure of the folders
* Message Internals::     Structure of the message data structure
* Summary Internals::     Details of summary generation
* Threading Internals::   Details of message threads handling
* Sorting Internals::     Details of how messages are sorted
* IMAP Server Interaction:: Handling interaction with IMAP servers
* User Interaction::      Handling of the user interaction
* Coding Systems::        How VM handles character coding
* Message Display::       How VM displays messages
* @acronym{MIME} Display::          How VM displays @acronym{MIME} messages
* @acronym{MIME} Composition::	  How @acronym{MIME} messages are composed
* Virtual Folder Internals:: Details of virtual folders and selectors
* Extents and Overlays::  How VM deals with XEmacs and GNU Emacs differences
* Timers and Concurrency:: How VM runs asynchronous timers
@end menu

@node Folder Internals, Message Internals , , Internals
@section Folder Internals

@cindex mbox
@inindex mbox
VM stores mail folders in the Unix @samp{mbox} format (in all its variants).
Internal to Emacs, the mbox is loaded into a text buffer (the @dfn{Folder}
buffer) and individual messages are identified by remembering markers into
the text buffer.  @xref{Message Internals}.

The Unix @dfn{mbox} format is described in the RFC 4155 specification of the
Internet Engineering Task Force.  The mail folder is a text file consisting
of a sequence of messages, with each message consisting of a series of
headers followed by a message body.  The beginning of each message is
delineated by a separator line starting with the string ``From '' and the
end of the message by a blank line.  The leading separator line in VM folder
is of the form ``From VM ...'' where the ``...''  records the time at which
VM first saw the message.  The format of the individual messages is as per
the RFC 2822 specification, except that Line-Feed characters may be used to
delineate the end of lines in the "Unix" format.

@vindex vm-folder-type
@cindex From_ folder type
@cindex BellFrom_ folder type
@cindex From_with-Content-Length folder type
@cindex System V
@inindex vm-folder-type
@inindex From_ folder type
@inindex BellFrom_ folder type
@inindex From_with-Content-Length folder type
@inindex System V
Three variants of the @code{mbox} format are recognized by VM, called
@code{From_}, @code{BellFrom_} and @code{From_with-Content-Length}.
In a @code{From_} type mbox, every message has a leading and trailing
separator line, as indicated above.  In a @code{BellFrom_} type mbox,
the trailing separator line can be missing.  (This is so that the 
mbox's from the old System V format can be handled.)  In a
@code{From_with-Content-Length} type mbox, the @code{From} separator
line stores the length of the message.  So, no trailing separator line
is required.

@cindex @acronym{MMDF} format
@cindex Babyl format
@inindex @acronym{MMDF} format
@inindex Babyl format
In addition to these mbox formats, VM also handles the @acronym{MMDF} format and
the Emacs Rmail's Babyl format.  The variable @code{vm-folder-type}
stores the type of the folder being used.

@inindex X-VM-v5-Data header
To every message, VM adds a header with the field name
``X-VM-v5-Data:'' and stores in it the information about the message it
wishes to remember between sessions.

The first message of the VM folder file contains additional headers used
by VM for remembering information between sessions.

@itemize
@inindex X-VM-Bookmark
@item
X-VM-Bookmark. This header stores the position of the cursor, as a
message number, in effect when VM saved the folder.  Upon revisiting the
folder, VM attempts to put the cursor back at this position.
@item
@inindex X-VM-Last-Modified
X-VM-Last-Modified.  The date and time at which the folder was last
modified. 
@item
@inindex X-VM-Message-order
X-VM-Message-Order.  This header lists the order in which the messages
should be listed.
@item
@inindex X-VM-Labels
X-VM-Labels. This header lists the message labels that have been used in
the folder.  
@item
@inindex X-VM-VHeader
X-VM-VHeader. This header lists the values of @code{vm-visible-headers}
and @code{vm-invisible-header-regexp} that were in effect when the
folder was saved.  The messages in the folder would have their headers
arranged according to these variables.
@item
@inindex X-VM-Summary-Format
X-VM-Summary-Format.  This header stores the format string for the
summary lines.
@item
@inindex X-VM-@acronym{POP}-Retrieved
X-VM-@acronym{POP}-Retrieved. This header lists all the messages that have
been retrieved from @acronym{POP} servers together with the identifying
information for the @acronym{POP} servers.  VM refrains from retrieving these
messages again in future in order to avoid duplication.
@item
@inindex X-VM-@acronym{IMAP}-Retrieved
X-VM-@acronym{IMAP}-Retrieved. This header lists messages that have been
retrieved from @acronym{IMAP} servers together with their identifying
information on the @acronym{IMAP} servers (@acronym{UID} and
@acronym{UIDVALIDITY}).  VM refrains from retrieving these messages again in
future in order to avoid duplication.  (For local folders, this lists all
the retrieved messages except those known to be expunged on the server.  For
@acronym{IMAP} folders, it does not list all the retrieved messages because
they are normally the same as those on the server.  Only the messages
locally expunged in the cache folder but not known to be expunged on the
server are listed.  In the normal cases, the variable is just nil in
@acronym{IMAP} folders.)
@end itemize

@unnumberedsubsec Folder variables

Internal to Emacs, VM stores the folder as simply a text buffer.  However, it
remembers a variety of data about the message contents in the buffer
through internal variables.

@itemize
@item
@inindex vm-message-list
@code{vm-message-list}.  A list of message data structures for all the
messages in the buffer.
@item
@inindex vm-folder-type
@code{vm-folder-type}.  The type of the current folder indicating how
the messages are stored: one of 'babyl, 'From_, 'BellFrom_,
'From_-with-Content-Length and 'mmdf.
@item
@inindex vm-folder-access-method
@code{vm-folder-access-method}.  The method for accessing the server
message store: 'pop for pop-folders and 'imap for imap-folders, and nil
for all other folders. 
@item
@inindex vm-folder-access-data
@code{vm-folder-access-data}.  A vector of data for accessing the server
message store.  The first two elements of the vector are the maildrop
specification for the mail server and a reference to the process
connecting to the mail server.  For the 'pop access method, that is all
there is.  But, for the 'imap access method, the vector has 9 other
entries detailing various pieces of data about the @acronym{IMAP} server.
@item
@inindex vm-folder-read-only
@code{vm-folder-read-only}.  A boolean flag indicating whether the
folder is read-only.  If so, no modifications are allowed, including
attribute changes.  However, messages can be fetched from external
storage for viewing.
@item
@inindex vm-virtual-folder-definition
@code{vm-virtual-folder-definition}.  If the current folder is virtual,
then this variable holds the data constituting its definition.
@item
@inindex vm-real-buffers
@code{vm-real-buffers}.  If the current folder is virtual, then this
variable is a list of all the real folder buffers involved in
constructing it.
@item
@inindex vm-virtual-buffers
@code{vm-virtual-buffers}.  A list of all the virtual folder buffers
that the current buffer is involved in.
@item
@inindex vm-component-buffers
@code{vm-component-buffers}.  An a-list containing all the folder
buffers (real or virtual) that make up the components of the current
virtual folder, and a flag indicating whether those folders were
visited as part of visiting the virtual folder.  When the virtual
folder is closed, all the folders purposely visited will also be closed..
@item
@inindex vm-summary-buffer
@code{vm-summary-buffer}.  The Summary buffer of the folder.  (If the
Summary buffer gets killed for any reason, the value of this variable
becomes <killed buffer>, which is unfortunate.  Therefore, most
interactive commands of VM check for killed Summary buffer and reset
this variable to nil in such a case.  So, in the middle of code, this
variable can be regarded as a valid buffer pointer.)
@item
@inindex vm-presentation-buffer-handle
@code{vm-presentation-buffer-handle}. The message Presentation buffer of the
folder.  (Same proviso applies as for @code{vm-summary-buffer}.)
@item
@inindex vm-presentation-buffer
@code{vm-presentation-buffer}. This seems to be a copy of the
@code{vm-presentation-buffer-handle}.  Its purpose is unknown.
@end itemize

The running state of the folder buffer is represented in a number of
buffer-local variables:

@itemize
@item
@inindex vm-message-pointer
@code{vm-message-pointer}.  A sublist of vm-message-list starting from
the current message that the cursor is on.  So, the first element of
vm-message-pointer is the current message.
@item
@inindex vm-last-message-pointer
@code{vm-last-message-pointer}.  Whenever the cursor is moved, the
previous value of vm-message-pointer is remembered in this variable.
@item
@inindex vm-summary-pointer
@code{vm-summary-pointer}.  The message struct of the message which
has the summary pointer in the Summary buffer.
@item
@inindex vm-fetched-messages
@code{vm-fetched-messages}.  List of external messages whose
bodies were fetched for viewing or other operations.
@item
@inindex vm-fetched-message-count
@inindex vm-fetched-messages
@code{vm-fetched-message-count}.  The number of messages in
@code{vm-fetched-messages}.  An attempt is made to keep this below the
@code{vm-external-fetched-message-limit}. 
@item
@inindex vm-mime-decoded
@inindex @acronym{MIME}
@code{vm-mime-decoded}.  The @acronym{MIME} decoding state of the current
message display: @code{nil} if the message is shown in undecoded plain
text form, @code{decoded} if the message is shown decoded, and
@code{buttons} if the message is shown as a series of buttons for all its
@acronym{MIME} components.  The @kbd{D} command cycles through these states.
@item
@inindex vm-system-state
@code{vm-system-state}.  The state of VM in a Folder buffer or
Presentation buffer: 

@itemize
@item 
@inindex previewing
@code{previewing}.
if a message is being previewed.
@item 
@inindex showing
@code{showing}.
if a full message is being shown.
@item 
@inindex reading
@code{reading}.
if message reading is in progress.
@end itemize

@inindex editing
A message edit buffer is in state @code{editing}.

A message composition buffer may be in one of these states:

@itemize
@item 
@inindex forwarding
@code{forwarding}.
if a message is being forwarded.
@item 
@inindex replying
@code{replying}.
if a message is being replied to.
@item 
@inindex redistributing
@code{redistributing}.
if a message is being redistributed.
@end itemize

@item
@inindex vm-spooled-mail-waiting
@code{vm-spooled-mail-waiting}.  VM periodically checks if there is new
mail in the spool files of the current folder and set this flag to t if
there is new mail.
@item
@inindex vm-undo-record-list
@code{vm-undo-record-list}.  A list of undo records describing the
actions to be performed if an undo operation is invoked.  Each undo
record has an action, the message, if any, to which the action
applies, and any arguments needed for the action.
@item
@inindex vm-undo-record-pointer
@code{vm-undo-record-pointer}.  A pointer into the
@code{vm-undo-record-list} indicating the current position of the
undoing cycle.
@item
@inindex vm-label-obarray
@code{vm-label-obarray}.  An obarray storing all the labels that are
registered to be used in the current folder.
@inindex vm-folder-garbage-alist
@code{vm-folder-garbage-alist}.  An alist with items that constitute the
temporary storage used in displaying the folder and functions to
dispose them.  These garbage items are disposed when the folder is quit.
@inindex vm-message-garbage-alist
@code{vm-message-garbage-alist}. An alist with items that constitute the
temporary storage used in displaying the current message and functions to
dispose them.  These garbage items are disposed whenever a new message is
selected or if the folder is quit.
@end itemize

@unnumberedsubsubsec vm-folder-access-data

The variable @code{vm-folder-access-data} is a vector storing data about the
state of the mail server (for @acronym{POP} and @acronym{IMAP} servers).  It
contains the following items:

@itemize
@item
@code{pop-maildrop-spec} or @code{imap-maildrop-spec}.
MAILDROP specification of the server folder.
@item
@code{pop-process} or @code{imap-process}.
The Emacs process being used to communicate with the server for this
folder.  (Each folder uses a separate process to avoid unwanted
interference.) 
@item
@code{imap-uid-validity}.
The @acronym{UIDVALIDITY} value of the @acronym{IMAP} folder.
@item
@code{imap-read-write}.
A boolean flag indicating whether the folder is writable.
@item
@code{imap-can-delete}.
A boolean flag indicating whether the folder allows deletions.
@item
@code{imap-body-peek}.
A boolean flag indicating whether the folder allows the @code{BODYPEEK}
command of @acronym{IMAP}.
@item
@code{imap-permanent-flags}.
The list of permanent flags that have been stored in the folder.
@item
@code{imap-mailbox-count}.
The number of messages in the folder.
@item
@code{imap-recent-count}.
The number of messages in the folder that are considered ``recent'' by the
server.
@item
@code{imap-retrieved-count}.
The number of messages present in the folder when messages were last
retrieved.  This would have been the value of @code{imap-mailbox-count} at
that time.
@item
@code{imap-uid-list}.
The list of UID's and flags of the messages in the folder,
using cons cells of the form (msg-num . uid . size . flags list).  The cons
cells (size . flags list) are shared with @code{imap-flags-obarray} below.
@item
@code{imap-uid-obarray}.
An obarray that binds all the UID's of messages in the folder to their
message sequence numbers.
@item
@code{imap-flags-obarray}.  An obarray that binds all the UID's of messages
in the folder to cons cells of the form (size . flags list).  These cons
cells are the same as those occurring in the @code{imap-uid-list} field.
So, any updates will be shared through both the views.  The two obarrays,
@code{imap-uid-obarray} and @code{imap-flags-obarray}, bind exactly the same
set of UID's.  Jointly, they are referred to as @code{uid-and-flags-data}.
The reason for their separation is historical.
@end itemize

@node Message Internals, Summary Internals, Folder Internals, Internals
@section Message Internals

The format of the mail messages is as described in RFC 822. The message
bodies can be in the MIME format, as described in RFC 2045, 2046 and
2047. See @xref{Message Internals, RFC compliance}.

The message data structure is a vector containing various pieces of
data about the message, some of which is permanent and some that is
calculated during a VM session.  The data is organized into four
sub-vectors:

@itemize
@item
Location data (0).  This data about the location of the various parts of the
message in the Folder buffer is calculated after a folder is loaded and
parsed.
@item
Soft data (1).  This vector contains other calculated data about the
message that is specific to a VM session.
@item
Attributes (2).  All the hard-wired message attributes are stored in this
vector.
@item
Cached Data (3).  Calculated data that is cached for each message.
@item
Mirror Data (4).  Extra data shared by virtual messages if vm-virtual-mirror
is non-nil.
@end itemize

@inindex X-VM-v5-Data
The attributes vector and cached data vector are stored in the
folder on disk as the @code{X-VM-v5-Data} header of the first message.

@subsubheading Location data
@anchor{Location data vector}

This vector holds the data about the location of the various parts of
the message in the folder buffer.  Every folder buffer or folder-like
buffer (such as a Presentation buffer) has variables that contain
message data structures.  The location data is normally expected to
refer to locations in that very buffer.  However, this condition is
not actually required.  (See below.)

@inindex start
@itemize
@item
@code{start} (0).  Marker for the starting position of the message, at which a
leading separator line begins.
@inindex headers
@item
@code{headers} (1). Marker for the position in the buffer where the headers
of the message start.
@inindex vheaders
@item
@code{vheaders} (2).  Marker for the position in the buffer where the
visible headers of the message start.  (The headers are rearranged in
such a way that all the visible headers are towards the end of the
headers region.)
@inindex text
@item
@code{text} (3). Marker for the position in the buffer where the text of the
message starts.
@inindex text-end
@item
@code{text-end} (4). Marker for the position in the buffer where the text of
the message ends.
@inindex end
@item
@code{end} (5). Marker for the position in the buffer where the message
ends.
@end itemize

Unfortunately, in the current versions of VM, the folder buffer to
which the location data point is not itself part of this vector.  This
information is inferred from the context (which makes the code
brittle).  The Folder buffer of the message can be obtained from the
soft data vector but the location data could also point to a
Presentation buffer.


@subsubheading Soft data
@anchor{Soft data vector}
This vector contains other calculated data about the message that is
specific to a VM session.

@inindex number
@itemize
@item
@code{number} (0). The message number as an integer.
@inindex padded-number
@item
@code{padded-number} (1). The message number as a padded string.
@inindex mark
@item
@code{mark} (2). Flag that indicates if the message has been marked (via
@code{vm-mark-message}).
@inindex su-start
@item
@code{su-start} (3). The position in the Summary buffer where the summary
line of the message starts.
@inindex su-end
@item
@code{su-end} (4).  The position in the Summary buffer where the summary line of
the message ends.
@inindex real-message-sym
@item
@code{real-message-sym} (5).  If the message is in a virtual folder, then its
corresponding ``real message'' is the underlying message in another
folder which is described by a message data structure similar to the
current one.  The real message data structures are represented by
uninterned symbols written as ``<<>>''.  This field stores the symbol
representing the real message of the current message.  If the current
message is a real message then this field contains its own symbol.
The use of symbols for this purpose avoids the possibility of circular
data structures.
@inindex mirrored-message-sym
@item
@code{mirrored-message-sym} (21).  This is similar to the
@code{real-message-sym}, except that it points to the message that this
message directly mirrors (as a virtual message).  If we follow the
``mirrored-message'' links in succession we should eventually reach the
``real-message''.
@inindex reverse-link-sym
@item
@code{reverse-link-sym} (6).  Reference to the previous message in the
message list, also represented by an uninterned symbol written as ``<--''.
@inindex message-type
@item
@code{message-type} (7).  A symbol indicating the type of the message
according to its folder type, one of @code{BellFrom_}, @code{From_} and
@code{From_-with-Content-Length}.
@inindex message-id-number
@item
@code{message-id-number} (8).  A number that uniquely identifies the message 
within a VM session.
@inindex buffer
@item
@code{buffer} (9). The Folder buffer of the message.  (Messages in Presentation
buffers also have this field set to the corresponding Folder buffer.)
@inindex thread-indentation
@item
@code{thread-indentation} (10). Indentation level of the message in its message
thread.
@inindex thread-indentation-offset
@item
@code{thread-indentation-offset} (22). Indentation added by the user for the
message, which is used in addition to the @code{thread-indentation}.  This
is not ``cached'' data and should not be discarded.
@inindex thread-list
@item
@code{thread-list} (11).  List of symbols from @code{vm-thread-obarray} that
give this message's lineage.
@inindex thread-subtree
@item
@code{thread-subtree} (20).  List of messages that form the subtree under
this message in a threaded summary display.
@inindex babyl-frob-flag
@item
@code{babyl-frob-flag} (12).
@inindex saved-virtual-attributes
@item
@code{saved-virtual-attributes} (13).  Saved attributes if the message
switched from unmirrored to mirrored.
@inindex saved-virtual-mirror-data
@item
@code{saved-virtual-mirror-data} (14).  Saved mirror data, if the message was
switched from unmirrored to mirrored.
@inindex virtual-summary
@item
@code{virtual-summary} (15).  Summary for unmirrored virtual message.
@inindex mime-layout
@item
@code{mime-layout} (16).  @acronym{MIME} layout information; types, ids,
positions, etc of all @acronym{MIME} entities.  (See below.)
@inindex mime-encoded-header-flag
@item
@code{mime-encoded-header-flag} (17). Flag that indicates if the headers of
the message are @acronym{MIME} encoded.
@inindex su-summary-mouse-track-overlay
@item
@code{su-summary-mouse-track-overlay} (18).  The overlay on the summary of
this message used for selection by mouse.
@inindex message-access-method
@item
@code{message-access-method} (19).  The access-method to be used for the
message, inherited from its real folder.
@end itemize


@subsubheading Attributes
@anchor{Attributes vector}
All the hard-wired message attributes are stored in this
vector.  They also get saved as part of the @code{X-VM-v5-Data} header
field when the folder is saved to disk.

@inindex new-flag
@itemize
@item
@code{new-flag} (0).  Flag to indicate if the message is ``new''.
@inindex unread-flag
@item
@code{unread-flag} (1).  Flag to indicate if the message is unread.
@inindex deleted-flag
@item
@code{deleted-flag} (2).  Flag to indicate if the message has been deleted.
@inindex filed-flag
@item
@code{filed-flag} (3).  Flag to indicate if the message has been filed.
@inindex replied-flag
@item
@code{replied-flag} (4).  Flag to indicate if the message has been replied to.
@inindex written-flag
@item
@code{written-flag} (5).  Flag to indicate if the message has been saved.
@inindex forwarded-flag
@item
@code{forwarded-flag} (6).  Flag to indicate if the message has been forwarded.
@inindex edited-flag
@item
@code{edited-flag} (7).  Flag to indicate if the message has been edited.
@inindex redistributed-flag
@item
@code{redistributed-flag} (8).  Flag to indicate if the message has been
redistributed. 
@item
@code{flagged-flag} (9). Flag to indicate if the message has been
``flagged'' as important.
@item
@code{folded-flag} (10). Flag to indicate whether the summary of the
subthread rooted at this message has been ``folded'', i.e., hidden from
view.
@item
@code{watched-flag} (11). Flag that says that the user wants to ``watch''
this thread.  There are no functions that use this at present.
@item
@code{ignored-flag} (12).  Flag that says that the user wants to ignore this
thread.  There are no functions that use this at present.
@item
@code{read-receipt-flag} (13).  Flag that says that the sender of this
message wishes to receive a read-receipt.  There are no functions that use
this at present. 
@item
@code{read-receipt-sent-flag} (14).  Flag that says that a read-receipt has
been sent for this message.  There are no functions that use this at present.
@item
@code{attachments-flag} (15).  Flag that says that this message has
attachments.  There are no functions that use this at present.
@item
@code{thread-root-flag} (16). Flag that says that this message should be
regarded as the root of a message thread, even if its ``parent'' and
``references'' headers say otherwise.  This field is not used at present.

@end itemize

@subsubheading Cached Data
@anchor{Cached data vector}

@cindex cached data
@inindex X-VM-v5-Data header
The vector is meant for data that is cached for each message and stored on
the disk as part of the @code{X-VM-v5-Data} header field.  Cached data is
present in other parts of the message or its headers and, so can be freely
discarded and recalculated.  That is history.

Over the years, this vector has also accumulated a number of fields that are
not ``cached'' data in this sense.  Some fields contain hard data that is
not available elsewhere, such as the ID's of external messages on mail
servers.  It also contains data provided by the user which should be
preserved across VM sessions.

Some fields contain information from message headers.  The header fields can
have @acronym{MIME}-encoded words in them.  The strings stored in the
cached-data vector, however, are @acronym{MIME}-decoded versions of the
header fields.  So, when they are written to disk, they should be re-encoded
because only @acronym{MIME}-encoded text can appear in mail folders.  To
facilitate this, they are given text properties that store the names of the
original character sets used in the header fields.  This allows the strings
to be quickly re-encoded for storage on disk.

@inindex byte-count
@itemize
@item
@code{byte-count} (0).  The size of the message in bytes.
@item
@code{weekday}, @code{monthday}, @code{month}, @code{year}, @code{hour},
@code{zone} (1-6).  Data indicating the date of 
the message.
@inindex decoded-full-name
@item 
@code{decoded-full-name} (7).  The full name of the author of the message.
This is a @acronym{MIME}-decoded string with text properties.
@inindex decoded-from
@item
@code{decoded-from} (8).  The email address of the author of the message.
This is a @acronym{MIME}-decoded string with text properties.
@inindex message-id
@item
@code{message-id} (9).  The unique id of the message.
@inindex line-count
@item
@code{line-count} (10). The number of lines in the message.
@inindex decoded-subject
@item
@code{decoded-subject} (11).  The subject string of the message.  This is a
@acronym{MIME}-decoded string with text properties.
@inindex vheaders-regexp
@item
@code{vheaders-regexp} (12).  A regular expression that can be used to find
the start of the visible headers.  The headers must have been already
ordered so that the visible headers are at the bottom of the headers
section.
@inindex decoded-to
@item
@code{decoded-to} (13).  The email addresses of the addressees of the message
(listed in the ``To'' header) in a comma separated string.  This is a
@acronym{MIME}-decoded string with text properties.
@inindex to-names
@item
@code{decoded-to-names} (14). The full names of the addressees in a comma
separated string.  Addresses are used if full names are not available.  This
is a @acronym{MIME}-decoded string with text properties.
@inindex month-number
@item
@code{month-number} (15).  Numeric month of the sent date.
@inindex sortable-datestring
@item
@code{sortable-datestring} (16).  The date string of the ``date'' of the
message for sorting purposes (either the sent date or the delivery date,
depending on the value of @code{vm-sort-messages-by-delivery-date}).
@inindex decoded-sortable-subject
@item
@code{decoded-sortable-subject} (17).  The subject string of the message for
sorting purposes.  (Prefixes such as ``re:'' are removed and subject tags of
mailing lists might also be removed.)  This is a @acronym{MIME}-decoded
string with text properties.
@inindex summary
@item
@code{decoded-tokenized-summary} (18).  A tokenized summary for the message,
from which the actual summary line can be quickly calculated.  This is a
list containing tokens, such as @code{number} and @code{thread-indent}, as
well as @acronym{MIME}-decoded strings with text properties.
@inindex parent
@item
@code{parent} (19).  The message ID of the parent of the message in its
thread.
@inindex references
@item
@code{references} (20).  Message IDs listed in the References header of the
message. 
@inindex body-to-be-retrieved
@item
@code{body-to-be-retrieved} (22).  Flag that indicates whether the body of the
message has not been retrieved from the mail server.
@item
@inindex body-to-be-discarded
@code{body-to-be-discarded} (21).  Flag that indicates whether they body of
the message should be discarded before the folder is saved.  (This is used
in conjunction with the @code{body-to-be-retrieved} above.)
@inindex pop-uidl
@item
@code{pop-uidl} (23).  The @acronym{UIDL} id of the message on the
@acronym{POP} server.
@inindex imap-uid
@item
@code{imap-uid} (23).  The @acronym{UID} of the message on the
@acronym{IMAP} server.
@inindex imap-uid-validity
@item
@code{imap-uid-validity} (24).  The @acronym{UIDVALIDITY} value of the
message on the @acronym{IMAP} server.
@inindex spam-score
@item
@code{spam-score} (25).  The spam score of the message.
@inindex headers-to-be-retrieved
@item
@code{headers-to-be-retrieved} (26).  Flag that indicates whether the
headers of the message have not been retrieved from the mail server (for
external messages).  This is not ``cached'' data and should not be
discarded.   This field is unused at present.
@inindex headers-to-be-discarded
@item
@code{headers-to-be-discarded} (27).  Flag that indicates whether the
headers of the message should be discarded before the folder is saved (for
external messages).  This is not ``cached'' data and should not be
discarded.  This field is unused at present.
@inindex decoded-summary-subject
@item
@code{decoded-summary-subject} (28).  Subject of the message as it appears
in the summary line of the message.  (This optionally omits the subject tags
added by mailing lists.)
@inindex declared-parent
@item
@code{declared-parent} (29).  The message ID of the parent of the message,
as declared by the user.  This may not be present in the headers of the
message.  So, it is not ``cached'' data and should not be discarded.  This
field is not used at present. 
@inindex declared-duplicates
@item
@code{declared-duplicates} (30).  List of message ID's that the user
declared as being duplicates of this message.  The duplicate copies may not
be present in the folder, but they should be taken into account in
calculating threads.  This is not ``cached'' data and should not be
discarded.  This field is not used at present.
@item
@code{d-weekday}, @code{d-monthday}, @code{d-month}, @code{d-year},
@code{d-hour}, @code{d-zone} (31-36).  Data indicating the delivery date of
the message.   These fields are not used at present.
@inindex decoded-reply-to-name
@inindex decoded-reply-to
@item
@code{decoded-reply-to-name}, @code{decoded-reply-to} (37-38).  The full
name and the email address in the @samp{Reply-To} header of the message
(called the ``principal'' of the message.)
@inindex decoded-to-cc
@inindex decoded-to-cc-name
@item
@code{decoded-to-cc-name}, @code{decoded-to-cc} (39-40).  The full names and
the email addresses in the @samp{To} and @samp{Cc} headers of the message
(called the ``recipients'' of the message.)
@end itemize

@subsubheading Mirror Data
@anchor{Mirror data vector}
Extra data shared by virtual messages if vm-virtual-mirror
is non-nil.

@inindex edit-buffer
@itemize
@item 
@code{edit-buffer} (0).  If the message is being edited, this is the buffer
being used.
@inindex virtual-messages-sym
@item
@code{virtual-messages-sym} (1).  List of virtual messages mirroring the
current real message, represented by an uninterned symbol written as
``<v>''.
@inindex stuff-flag
@item
@code{stuff-flag} (2).  Flag to indicates if the attribute changes have been
``stuffed'' into the folder buffer.
@inindex labels
@item
@code{labels} (3).  List of labels attached to the message.
@inindex label-string
@item
@code{label-string} (4).  The string of labels attached to the message.
@inindex attribute-modflag
@item
@code{attribute-modflag} (5).  Flag to indicate if the attributes of the
message have been modified since the last save.
@end itemize

@unnumberedsubsec @acronym{MIME} layout
@anchor{@acronym{MIME} layout}

The @acronym{MIME} layout of a message, stored in the soft data of the
message, is in turn a vector containing various pieces of data.  Such a
vector is used not only for the overall message, but for all its
@acronym{MIME} parts and subparts as well.

@inindex type
@inindex Content-Type
@itemize
@item @code{type} (0).
A list of strings consisting of the @acronym{MIME} type of the part along
with its attributes.  This comes from ``Content-Type'' header.  The type
could be of the form `type/subtype'.  Quotation marks are stripped from
attribute values.  An example is 
@code{("multipart/mixed" "boundary=----_=_NextPart_001_01AFE588.63E23840")}.
@inindex qtype
@item
@code{qtype} (1).  Like type, but the quotation marks are not stripped.
@inindex encoding
@inindex Content-Transfer-Encoding
@item
@code{encoding} (2).  The @acronym{MIME} encoding used for the part.  It comes
from the ``Content-Transfer-Encoding'' header.
@inindex id
@inindex Content-ID
@item
@code{id} (3). The id obtained from the ``Content-ID'' header of the part.
@inindex description
@inindex Content-Description
@item
@code{description} (4).  A description string obtained from the
``Content-Description'' header of the part.
@inindex disposition
@inindex Content-Disposition
@item
@code{disposition} (5).  A list of strings obtained from the
``Content-Disposition'' header of the part.  Quotation marks are
stripped from attribute values.  (An example is @code{(``attachment'',
``filename=mydocument.doc'')}.)
@inindex qdisposition
@item
@code{qdisposition} (6).  Like disposition, but the quotation marks are not
stripped. 
@inindex header-start
@item
@code{header-start} (7), @code{header-end} (8), @code{body-start} (9) and
@code{body-end} (10).  Markers into the content buffer delineating the
headers/body of the @acronym{MIME} part.
@inindex parts
@item
@code{parts} (11). A list of @acronym{MIME} layouts for the individual subparts
of this part.
@inindex cache
@item
@code{cache} (12). A symbol that is unique to this @acronym{MIME} part.  Other
data is stored as properties of this symbol:
@itemize
@inindex vm-mime-display-external-generic
@item
@code{vm-mime-display-external-generic}.
This property stores the id of the process used to externally display
the @acronym{MIME} part as well as the name of the temporary file used. 
@inindex vm-mime-display-internal-image-xxxx
@item
@code{vm-mime-display-internal-image-xxxx}.
This property stores the name of the temporary file where the image is
stored.  
@comment For an image represented as image strips, it actually stores
@comment a list with a number of other data items.
@inindex vm-image-modified
@item
@code{vm-image-modified}.
This property stores a boolean flag indicating that the image has been
modified. 
@inindex vm-mime-display-internal-audio/basic
@item
@code{vm-mime-display-internal-audio/basic}.
This property stores the name of the temporary file where the audio
clip is stored.
@inindex vm-message-garbage
@item
@code{vm-message-garbage}.  This property is a boolean flag indicating
whether the files used in this layout have been registered as message
garbage.  (This feature is currently not in use.)
@end itemize
@inindex message-symbol
@item
@code{message-symbol} (13).  A reference to the message that contains the
@acronym{MIME} part.  Represented as a symbol (that is, an interned key into
a hash table).  This is a different symbol from the real-message-sym of the
message.
@inindex display-error
@item
@code{display-error} (14).  If the display of a @acronym{MIME} part fails, its
error string is stored here.
@inindex layout-is-converted
@item
@code{layout-is-converted} (15).  Flag indicating that @acronym{MIME} type
conversion has been performed on this part.  @pxref{@acronym{MIME} type
conversion}.
@inindex unconverted-layout
@item
@code{unconverted-layout} (16).  If the @acronym{MIME} type conversion has been
performed on this part, then this holds the original unconverted layout.
@end itemize

@unnumberedsubsec Cross-buffer sharing of data

@inindex vm-message-list
@inindex vm-message-pointer
Every Folder buffer has a @code{vm-message-list} and a
@code{vm-message-pointer} list containing message data vectors.  

Every Presentation buffer also uses a @code{vm-message-pointer} list
with a single message (the one being presented).  The message data
vector in the Presentation buffer has its own location data, but
@i{shares} all other components with the message in the Folder buffer.
This allows the Presentation buffer to, for example, change the
attributes of the message without having to switch context to the
Folder buffer.

Virtual folders, which contain only references to messages in other
folders, store just a single message body in the Folder buffer.
However, they have message descriptors for all the messages in
@code{vm-message-list}.  All the message descriptors use the same
location data vector, because only one message body can be stored in
the Folder buffer, but have separate Soft data vectors.  (This allows,
for instance, virtual folders to have their own threads, which could
in general be different from the threads in the underlying folders.)  
The other sub-vectors are shared with the underlying real folders.  (In
particular, the tokenized summary line is the same in the virtual
folders and their underlying folders.)

@subsection RFC compliance
The format of the mail messages is as described in RFC 822.  
@itemize
@item
RFC 822. Standard for the format of ARPA Internet text messages. August 1982.
@item
RFC 2822. Internet Message Format (proposed). April 2001.
@item
RFC 5322. Internet Message Format (standard). October 2008.
@end itemize
@noindent It is not known whether the updates of RFC 5322 have been
incorporated in VM. 

The message bodies can be in the MIME format, as described in RFC 2045, 2046
and 2047.
@itemize
@item 
RFC 2045. Format of Internet Message Bodies. November 1996.
@item 
RFC 2046. Media Types. November 1996.
@item 
RFC 2047. Message Header Extensions for NON-ASCII
Text. November 1996.
@item
RFC 2048. Registration Procedures. November 1996.
@item
RFC 2049. Conformance Criteria and Examples. November 1996.
@end itemize
@noindent The following updates that have been made to the original MIME
standards have not been implemented in VM.
@itemize
@item
RFC 2231. MIME Parameter Value and Encoded Word Extensions. November 1997.
@item
RFC 5335. Internationalized Email Headers (Experimental). September 2008.
@item
RFC 6532. Internationalized Email Headers (Proposed). February 2012.
@end itemize


@node Summary Internals, Threading Internals, Message Internals, Internals
@section Summary Internals

@inindex vm-summary-line-format
@inindex summary line, tokenized
@inindex tokenized summary line
Generating a summary is quite a time-consuming operation.  VM uses a
variety of tricks to speed up the generation of summaries.  

The format of the summary lines is specified in the variable
@code{vm-summary-line-format}.  The information that needs to go into
the summary lines is divided into two classes:

@itemize
@item
Information that is fixed for each message.  Examples include the
subject, author and other header information.
@item
Information that is variable during a VM session.  Examples include
the message number and thread indentation.
@end itemize

A @emph{tokenized summary line} is a list whose elements can be
strings, representing fixed information in a message, and tokens,
representing variable information.  VM calculates a tokenized summary
line for each message and caches it in the cached-data vector.
The following forms of tokens are used in tokenized summary lines:

@itemize
@item 
@code{number}.
Stands for the message number in the linear order of the summary.
@item
@code{mark}.
Stands for an indicator of message mark (whether the message is marked
at present).
@item 
@code{thread-indent}.
Stands for the indentation to be used for the message's summary
depending on its position in the message thread.
@item 
@code{group-begin}, @code{group-end}.
Brackets used to denote groups of items that might have particular
formatting constraints.
@end itemize

The function @code{vm-tokenized-summary-insert} converts a tokenized
summary line into a string and inserts it in the summary buffer.  The
minibuffer message ``Generating summary...'' is used to show the
progress of generating summary lines from tokenized summaries.

Buffer local variables in each Folder buffer responsible for
maintaining summary information:

@itemize
@item
@inindex vm-summary-pointer
@code{vm-summary-pointer}.  The message selected by the cursor in the
Summary window.
@item
@inindex vm-summary-redo-start-point
@code{vm-summary-redo-start-point}.  A pointer into the
@inindex vm-message-list
@code{vm-message-list} indicating the first message for which the
summary line must be redisplayed.  All the messages from here on are
assumed to require a summary redisplay.  The assumption is usually valid
because the message numbers of all the succeeding messages might have
changed.  But, if message numbers are not included in the summary lines,
then this results in unnecessary work.
@item
@inindex vm-messages-needing-summary-update
@code{vm-messages-needing-summary-update}.  The list of messages for
which summary lines must be redisplayed.  Messages are included in this
list by calling the function @code{vm-mark-for-summary-update}.
@item
@inindex vm-numbering-redo-start-point
@code{vm-numbering-redo-start-point}.  A pointer into
@inindex vm-message-list
@code{vm-message-list} indicating the first message whose message number
needs to be recalculated.
@inindex vm-numbering-redo-end-point
@code{vm-numbering-redo-end-point}.  A pointer into
@code{vm-message-list} indicating the last message whose message number
needs to be recalculated.
@end itemize

The beginning and the ending positions of each message summary line are
stored in the message's soft data vector. @pxref{Message Internals}.
The positions within the summary line have text-properties set, which
give the data about the message:

@itemize
@item
@inindex vm-message
@code{vm-message}.  The message struct for which this line is a summary.
@end itemize

@node Threading Internals, Sorting Internals, Summary Internals, Internals
@section Threading Internals

@inindex vm-thread-obarray
@inindex vm-thread-subject-obarray
@inindex In-Reply-To header
@inindex References header
Message threads required for threaded summaries are calculated using
message ID's, which are unique when the message was originally
composed.  However, VM may need to deal with multiple copies of the
same message received via possibly different routes.  So, message ID's are
not unique for messages inside VM.  

Messages composed as replies generally have an ``In-Reply-To'' header.
The message mentioned in this header is referred to as the parent of
the message.  In addition, messages also arrive with a ``References''
header which lists all the ancestors of the message, with the oldest
message being listed first.  The last message listed in the
``References'' header is the direct parent of message.  It is
important to keep in mind that all the messages listed in the
``References'' header may not be present in the VM folder.

Thread trees are constructed using the ``In-Reply-To'' headers and
``References'' headers.  Jamie Zawinski has done a good analysis of
the information contained in these headers which can be found on the
web.  VM's threading algorithm is currently based on these ideas.
These trees are called reference-based threads.

@inindex vm-thread-using-subject
In addition, VM also allows threads to be built using the subject
headers via the option @code{vm-thread-using-subject}.  Subject-based
threading is used in addition to reference-based threading.  So, in a
subject-based thread, the root message would be the oldest message
with that subject and, below it, would be reference-based threads all
of which share the same subject.  The roots of these reference-based
threads are referred to as the ``members'' of the subject thread.
Subject threading is only one level deep, whereas reference threading
can be arbitrarily deep.

Threads are built using two hash tables @code{vm-thread-obarray} and
@code{vm-thread-subject-obarray}.  The former keeps track of the thread
obtained by following parent and reference chains.  The latter keeps track
of messages with the ``same subject''.  To prevent messages from jumping
from one thread to another within the same VM session, the subject used is
not the message's own subject, but rather the subject of the oldest message
in the thread.  This subject is retained even if the oldest message is
expunged.

The message ID's are interned in @code{vm-thread-obarray} and the
following information is stored for each message ID:

@itemize
@item messages:
The list of messages that carry this message ID in the folder.  There
could be none, if we only know this message from its appearance in
other ``References'' headers.
@item message:
The ``canonical'' message with this message ID.  It is typically the
first message encountered by VM with this message ID.  If there are no
messages with this ID, then the field is @code{nil}.
@item date:
The date of the message.
@item parent:
The interned message ID of the parent of this message.  (The folder
may or may not contain a message with this ID.)  If there is no
parent, then this is @code{nil}
@item children:
The interned message ID's of all the children of this message.  (The
folder may or may not contain messages with these ID's.)
@item youngest-date:
The date of the youngest message in the thread, among all the messages
present in the folder.
@item oldest-date:
The date of the oldest message in the thread, among the messages
present in the folder.
@item oldest-subject:
The subject of the oldest message in the thread, among the messages present
in the folder.
@end itemize

The @code{vm-thread-subject-obarray} interns each subject string found
in the folder and maps it to a vector containing the following elements:

@itemize
@item id-sym:
The interned message ID of what is likely to be the root of the
thread, which is, at any rate, the oldest message with this subject.
@item date:
The date of the root message.
@item members:
A list of interned message ID's for the ``members'' of the subject
thread, which are messages without any reference-based ancestors.  The
root message represented by @code{id-sym} is not included as a member.
@item messages:
The list of all the messages in the folder that have this subject.
@end itemize

@inindex threads, building
@b{Building threads} involves calculating all the data stored with the
@code{vm-thread-obarray} and @code{vm-thread-subject-obarray}.  These two
collections of data are calculated in sequence, because the subject
threads are based on the reference threads.  

@inindex thread-subtree
@inindex thread-list
@inindex thread-indentation
After the threads are built, the @code{thread-list},
@code{thread-indentation} and the @code{thread-subtree} fields of the
Soft data vector are calculated as needed on demand and cached.
(@xref{Soft data vector}.)  These fields cannot be calculated without
building threads first.

When new messages are assimilated, they are added to the threads that
might have been already built, and the thread-related fields in the
Soft data vector are erased so that they will be recalculated.  The
@code{thread-subtree} field is erased for all the ancestors of the
assimilated message.  The @code{thread-list} and
@code{thread-indentation} fields are erased for all the descendants of
the assimilated message.

@inindex unthread
Before messages in the folder are expunged, they are @b{unthreaded}.
This involves removing them from their respective thread trees.  It
also involves the erasure of the @code{thread-subtree} field of all
their ancestors and the @code{thread-list} and
@code{thread-indentation} fields of the descendants.

@unnumberedsubsec Error handling

The code for threading has to be robust in the presence of erroneous
information in the message headers.  We have no control over the mail
clients that produce those messages and faulty information should not
lead to VM hanging or producing errors.  It should just do the best
job it can in the presence of imperfect information.

It is possible that the information in the headers give rise to cycles
in the thread trees.  Kyle Jones's original implementation allowed
these cycles to exist, but all functions that traversed the thread
trees were protected to detect cycles.  However, since thread trees
are updated when new messages are received or existing messages are
expunged, this led to unstable results.

Following Jamie Zawinski's recommendation, VM now avoids cycles in
thread trees.  Loop detection is still carried out during traversal as
a double safeguard.

VM gives priority to the parent information contained in the
``In-Reply-To'' headers in preference to the information in the
``References'' headers.  However, if an ``In-Reply-To'' header gives
rise to a cycle, it is ignored, and then ``References'' headers might
be used to fill in the missing information.




@node Sorting Internals, IMAP Server Interaction, Threading Internals, Internals
@section Sorting Internals

@inindex vm-key-functions
Sorting of messages in VM is carried out using the Emacs built-in
sorting function, which is generic in the comparison
operation to be used for sorting.  The required comparison operation
is expressed as a sequence of basic comparison operations such as
comparison by date, by author, by subject etc.  The dynamic
variable @code{vm-key-functions} is bound to a list of comparison
functions before calling the Emacs sort function.

@inindex vm-sort-compare-xxxxxx
The function @code{vm-sort-compare-xxxxxx} uses the functions listed
in @code{vm-key-functions} to do the overall comparison.  It compares
the given messages using the key functions in sequence.  If the first
key function decides one of the messages to precede the other, then
the comparison is over.  If the messages are found to be equivalent
according to the first key function then the second key function is
tried and, if they are still equivalent, then the next key
function is tried and so on.  This is called the lexicographic
combination of the given key functions.

@inindex vm-sort-compare-thread
Sorting by threads is special.  When messages are to be sorted by
threads, all the messages belonging to a thread should appear
together.  The required effect is achieved by using
@code{vm-sort-compare-thread} as the first key function in the
sequence.  This function checks to see if the two messages belonging
to the same thread.  If they do then the farthest ancestors of the two
messages that share the same parent are returned so that the remaining
comparison operations can be applied to these ancestors.  The
rationale is that these ancestors are the roots of the thread subtrees
that the two messages belong to.  So, the relative ordering of the
messages should be the same as the relative ordering of these
ancestors.  If the two messages belong to different threads then the
thread roots of the two messages are returned, again with the same
rationale.

Threaded summaries can be sorted by any key, e.g., by author
(full-name).  It is most common to sort them by ``activity,'' i.e.,
the order of the most recent message in the thread or subthread.
Sorting them by ``date'' means using the date of the root message of
the thread or subthread.

@node IMAP Server Interaction, User Interaction, Sorting Internals, Internals
@section IMAP Server Interaction

When IMAP servers are used as mail spools (or ``drop boxes'') for local
folders, VM opens a session with the IMAP server each time it is asked to
get new mail.  These sessions are closed immediately after the downloading
is completed.

When VM is used to handle IMAP folders, sessions are created with the server
each time a synchronization is performed (for reading as well as saving).
A separate session is created for each IMAP folder visited in VM.
If, in addition, the IMAP folders have external messages, VM keeps an active
session with the server (separately for each IMAP folder), which is used to
fetch messages on demand.

When an IMAP session is inactive for a certain period, IMAP server is likely
to forcibly close it.  To ensure that an IMAP session is active when VM
tries to talk to the server, it first checks that the session is active.
(This can be disabled by setting @code{vm-imap-ensure-active-sessions}.)  If
the server has forcibly closed the connection, it would not respond, and
Emacs networking code times out after a certain period.  During this
process, VM will appear to ``hang.''  In reality, it is waiting for the
Emacs networking code to come back with a response.

@node User Interaction, Coding Systems, IMAP Server Interaction, Internals
@section User Interaction

@inindex vm-mail-buffer
@inindex vm-select-folder-buffer-and-validate
@inindex vm-user-interaction-buffer
For each mail folder, VM creates three kinds of buffers in Emacs: the
Folder buffer, the Presentation buffer and the Summary buffer.  All
three types of buffers have the same user interface as far as
possible: the same key bindings, menu bars, tool bars and also the
same @i{commands}.  The  functions implementing the commands must
therefore work irrespective which of the three buffers they are
invoked in.  This makes VM quite different from most Emacs modes.

@inindex vm-mail-buffer
@inindex vm-summary-buffer
@inindex vm-presentation-buffer
VM stores the identity of the Folder buffer in a buffer-local variable
@code{vm-mail-buffer} in each of the other types of buffers.
Conversely, each Folder buffer uses buffer-local variables
@code{vm-summary-buffer} and @code{vm-presentation-buffer} to store
the identity of the other buffers.

@inindex vm-user-interaction-buffer
@inindex vm-select-folder-buffer-and-validate
Whenever a VM command is invoked by the user, VM calls a function
called @code{vm-select-folder-buffer-and-validate}, which sets the
current-buffer to the Folder buffer.  It also stores the identity of
the buffer with the user's focus in a global variable called
@code{vm-user-interaction-buffer}.  Thus, at every point during the
command execution, VM has knowledge of all the buffers involved as
well as the buffer in which the command execution was initiated.

[More to be filled in on @code{vm-display} etc.]

@unnumberedsubsec Menus
@inindex vm-mode-menu-map
The default menu bar of VM contains VM-specific menus, replacing the
standard Emacs menus.  This is achieved by setting the buffer-specific
menu bar to one in which the Emacs menus are @code{undefined} (at
least in Gnu Emacs).  

VM computes its standard menu bar and stores it internally:

@itemize
@item 
In Gnu Emacs, this is stored in the keymap @code{vm-mode-menu-map}. 
@item
In XEmacs ...
@end itemize

@noindent
The menu bar also has a menu, or a menu item, to switch back to the
standard Emacs menu bar.
@inindex vm-use-menus
The computed menu bar is then installed depending on the setting of
@code{vm-use-menus}.
If the user selects the action to revert to the standard Emacs menu
bar, the installation is easily reverted.  

@itemize
@item
In Gnu Emacs, the installation involves inserting a key binding for
@code{menu-bar}. 
@item
In XEmacs, ...
@end itemize

@inindex vm-menu-toggle-menubar
@noindent When the user picks a menu item to revert to the
Emacs menu bar, the function @code{vm-menu-toggle-menubar} is invoked,
which installs a fresh menu bar retaining the standard Emacs menus.
The same function is used to reinstall the dedicated VM menu bar when
needed. 

@node Coding Systems, Message Display, User Interaction, Internals
@section Coding Systems

@inindex coding system
A Coding System is a way of encoding characters as bit patterns.
@pxref{Coding System Basics,, Coding System Basics, elisp, Emacs Lisp
manual}.  US-ASCII is a coding system for English.  Other coding systems are
used to encode the various languages of the world, e.g., @samp{iso-latin-1}
(also called @samp{iso-8859-1} or simply @samp{latin-1}) for Western
European languages, and @code{hebrew-iso-8bit} (also called
@samp{iso-8858-8}) for Hebrew.  In addition to these standard coding
systems, Emacs uses its own internal coding system for characters, which can
encode all character sets currently in existence.  But the internal coding
system can vary between different versions of Emacs.

@inindex Content-Type
@inindex decode-coding-region
@inindex encode-coding-region
@inindex mime-charset
@inindex coding-system-get
@inindex charset
@inindex vm-mime-mule-coding-to-charset-alist
@inindex vm-mime-mule-charset-to-coding-alist
@acronym{MIME} messages specify the @dfn{character set} that their content
is in, in the @samp{Content-Type} header.  In reality, the ``character set''
is a reference to a coding system, which has been used to encode the
characters in the particular character set as bit patterns.  However, the
name that Emacs uses to refer to a coding system is often different from the
MIME character set name.  The correspondence between the two is defined via
a property called @code{mime-charset} for each implemented coding system
inside Emacs.  For example, the @code{mime-charset} property of
@samp{iso-latin-1} is @samp{iso-8859-1}, that of @samp{hebrew-iso-8bit} is
@samp{iso-8859-8}.  The Emacs function @code{coding-system-get} can be used
to extract the @code{mime-charset} property of an Emacs coding system.  VM
stores all the known coding systems and the corresponding @acronym{MIME}
charsets in its internal variables
@code{vm-mime-mule-coding-to-charset-alist} and
@code{vm-mime-mule-charset-to-coding-alist}.

VM uses this information to decode the content
to the Emacs internal coding system.  This is done using the function
@code{decode-coding-region}.  Conversely, VM encodes the outgoing messages
into the default or chosen @acronym{MIME} character set using the function
@code{encode-coding-region}.

@inindex decode-coding-string
@inindex encode-coding-string
@inindex base 64
@inindex quoted printable
The headers of email messages can only be in US-ASCII.  So header fields
in other character sets are encoded using either base-64 or
quoted-printable encoding (which yield ASCII strings) and annotated
with the name of the original character set.  Such annotations look
like @code{=?charset?B?}.  They can apply
to individual words or sequences of words appearing the in the
headers.  Note that the annotation @code{?B?} signifies a base-64
encoding of the byte stream.  Similarly the annotation @code{?Q?} is
be used to denote the quoted-printable encoding.
VM decodes such strings using the function @code{decode-coding-string}.
Conversely, the headers of outgoing messages are encoded using
@code{encode-coding-string}.

When header lines are MIME-decoded from the original character set into the
Emacs internal coding, the original character set is still remembered as a
text property of the strings.  The strings in the @code{X-VM-v5-Data} header
have these text properties and, when the header is written to the disk,
these strings are converted back into their original MIME encodings.

@node Message Display, @acronym{MIME} Display, Coding Systems, Internals
@section Message Display

VM displays messages in a ``Presentation buffer'' separate from the Folder
buffer.  This is done in two stages: @i{Preview} and @i{Show}.  

The previewing is done by a function called
@code{vm-present-current-message}.  It creates a Presentation buffer if it
is not present already, makes a copy of the message text in the Presentation
buffer and carries out any @acronym{MIME} decoding that may be necessary.
And, then, depending on the value of @code{vm-preview-lines}, it narrows the
buffer to show a selected portion of the message.

The full message display is done by @code{vm-show-current-message}.  It does
nothing more than removing the narrowing done by
@code{vm-present-current-message}.

Prior to version 8.2.0, it was possible to see plain text messages directly
in the Folder buffer.  That mode of operation is now obsolete.  For
uniformity, VM assumes that the Presentation buffer is always used for
displaying the message content.

@node @acronym{MIME} Display, @acronym{MIME} Composition, Message Display, Internals
@section @acronym{MIME} Display

@inindex vm-decode-mime-layout
The @acronym{MIME} layout of a message is stored in the @code{mime-layout}
field of the Soft data vector of the message.  (@xref{@acronym{MIME}
layout}.)  The @acronym{MIME} layout is in general a tree structure of
``@acronym{MIME} parts''.  The function @code{vm-decode-mime-layout} is
responsible for traversing the tree structure at each @acronym{MIME} part
and displaying it appropriately.

The function @code{vm-decode-mime-layout} goes through the following
sequence of decisions: 

@enumerate
@item
If the @acronym{MIME} part is a @code{multipart} type, then the subparts are
displayed as needed.  If it is a single part, it proceeds as follows.
@item 
If the @acronym{MIME} part should not be displayed automatically, it is
displayed as a button.  (An automatically displayed @acronym{MIME} type is one
listed in @code{vm-mime-auto-displayed-content-types}
but not listed in the corresponding exceptions.)
@item
If the @acronym{MIME} part should be displayed internally and VM is able to do
so, then it is displayed internally.  (An internally displayed @acronym{MIME}
type is one listed in @code{vm-mime-internal-content-types} but not
listed in the corresponding exceptions.)
@item
Otherwise, the @acronym{MIME} part is displayed externally.  An external viewer
is found from
@code{vm-mime-external-content-types-alist} and it is invoked to
display the @acronym{MIME} part.
@end enumerate

@inindex message/external-body
@acronym{MIME} parts of type @samp{message/external-body} need special
treatment.  If they are not asked to be auto-displayed, then they are
displayed as buttons, but the button caption may use information from the
child part (the actual object that is in the external-body) such as its type
and description.  If a @code{message/external-body} part is asked to be
auto-displayed, then the child part is fetched from the external source and
stored in an internal buffer.  It may be auto-displayed if it is appropriate
to do so, or shown in turn as a button.

@inindex @acronym{MIME} button
@acronym{MIME} buttons are displayed as regions of text displaying button
labels.  In addition, they have an overlay/extent placed on them,
which has a number of properties associated with it:

@itemize
@item @code{vm-button}.
Always @code{t}.
@item @code{vm-mime-layout}.  
Gives the layout of the @acronym{MIME} part.
@item @code{vm-mime-function}.
The function that carries out the action represented by pressing the
button.
@item @code{vm-mime-disposable}.
Set to true if the button should be removed when it is replaced by the
@acronym{MIME} object.
@inindex vm-mime-button-face
@item @code{face}.
Set to the value of @code{vm-mime-button-face}.
@item @code{local-map} (FSF Emacs) or @code{keymap} (XEmacs).
Set to a keymap that includes @code{vm-mime-reader-map}, binding the
@kbd{$} keys.
@end itemize


@node @acronym{MIME} Composition, Virtual Folder Internals, @acronym{MIME} Display, Internals
@section @acronym{MIME} Composition

@inindex attachment button
A @acronym{MIME} message is composed just like a normal message.  When objects
are attached using commands like @code{vm-attach-file},
@b{attachment buttons} are created in the message composition buffer.  An
attachment button is a region of text that looks like:

@example
[Attachment mary.jpeg, image/jpeg]
@end example

@noindent Various text properties are associated with an attachment
button, allowing it to be turned into an actual attachment when the
message is sent.

The representation of the attachment buttons differs in GNU Emacs and
XEmacs.  In GNU Emacs, the region of text is given @i{text properties}
that represent the metadata about the object.  In XEmacs, the region
of text is given an @i{extent}, which is then given properties
representing the metadata.  The reason for the  different
representations is that in GNU Emacs, only text properties are
preserved under killing and yanking.

The following properties are defined for attachment buttons:

@itemize
@item @code{vm-mime-object}.
The object denoting the @acronym{MIME} attachment.  It is either 

@itemize
@item 
a string denoting a file name, 
@item
a buffer containing the file to be attached, 
@item
a list of the form (buffer, start, end, filename) indicating a region in a
buffer, typically the Folder buffer, or 
@item
@code{t} indicating that the attachment is another @acronym{MIME}
object in a VM folder.  
@end itemize

@noindent 
In the last case, the @code{vm-mime-layout}
property describes the rest of the metadata.
@item @code{vm-mime-type}.
A string denoting the @acronym{MIME} type of the object.  (Note that it is a
single string, unlike the @code{type} component of a @acronym{MIME} layout.)
@item @code{vm-mime-parameters}.
A list of strings denoting the parameters of the @acronym{MIME} type.
@item @code{vm-mime-description}.
A string for the @acronym{MIME} description of the object.
@item @code{vm-mime-disposition}.
A list describing the @acronym{MIME} disposition.
@item @code{vm-mime-encoded}.
A boolean indicating whether the object has @acronym{MIME} headers.
@item @code{vm-mime-encoding}.
The @acronym{MIME} encoding used, if it is already encoded.
@item @code{vm-mime-forward-local-refs}.
Whether or not references to local external-body objects should be
forwarded as is.
@item @code{fontified}.
Standard text property.
@item @code{duplicable}.
Set to @code{t} in XEmacs allowing the extent to be
preserved under killing and yanking.
@item @code{front-nonsticky} and @code{rear-nonsticky}.  
Standard stickiness of text properties in GNU Emacs.
@end itemize

@inindex vm-mime-fake-attachment-overlays
When a composed message is sent, the attachment buttons are replaced
by actual attachment objects.  In FSF Emacs, the attachment buttons
are first converted into ``fake'' overlays before @acronym{MIME} encoding, in a
function called @code{vm-mime-fake-attachment-overlays}.  This allows
the next stage to treat both FSF Emacs and XEmacs using the same
logic.

The function @code{vm-mime-encode-composition} then encodes the composition
buffer, by selecting each attachment button and replacing it with the
corresponding object.  The bodies of @samp{external-body} objects are also
retrieved at this stage.  Unless the objects were already
@acronym{MIME}-encoded, they are @acronym{MIME}-encoded and made into
@acronym{MIME} parts by adding suitable headers.  The message itself is
given @acronym{MIME} headers describing its content and then handed to Emacs
message-sending functions.

@unnumberedsubsec Yanking or Forwarding @acronym{MIME} Messages
@inindex yank
@inindex include
@inindex vm-include-mime-attachments
When another message is yanked or ``included'' in a message composition,
the handling of attachments depends on the variable
@code{vm-include-mime-attachments}.  If the variable is @code{nil}, then
the attachments are displayed as token buttons in @i{plain text} that
appear similar to:

@example
[DELETED ATTACHMENT mary.jpg, image/jpeg]
@end example

@noindent The function @code{vm-decode-mime-layout} is employed to
generate the yanked text along with such token buttons.

If @code{vm-include-mime-attachments} is @code{t}, then first the
@code{vm-decode-mime-layout} function is employed to generate proper
@acronym{MIME} buttons for all the attachments.  In a second step, the
@acronym{MIME} buttons are replaced by attachment buttons using a function
called @code{vm-mime-convert-to-attachment-buttons}.  These attachment
buttons are then handled as described above.



@node Virtual Folder Internals, Extents and Overlays, @acronym{MIME} Composition, Internals
@section Virtual Folder Internals

@inindex virtual-folder-definition
@inindex vm-virtual-folder-alist
A virtual folder is characterized by its definition, which is stored in the
buffer-local variable @code{virtual-folder-definition}.  The form of the
definition is as given in @code{vm-virtual-folder-alist}.  @xref{Defined
Folders, vm-virtual-folder-alist}.  It is a collection of clauses, with each
clause listing a collection of folders and a collection of virtual
selectors.

Each virtual selector @var{X} has a corresponding Lisp function
@samp{vm-vs-@var{X}}, whose purpose is to check whether a given message
matches the selector.  The arguments for @samp{vm-vs-@var{X}} are a message
data structure @code{m} and all the arguments for the virtual selector
@var{X}.

For example, the virtual selector @code{author} has a string argument,
representing the author name.  The corresponding Lisp function is defined
as: 

@example
(defun vm-vs-author (m author-name)
  (or (string-match author-name (vm-su-full-name m))
      (string-match author-name (vm-su-from m))))
@end example

@noindent The definition checks to see if the given @code{author-name}
pattern occurs in the full name of the author (@code{vm-su-full-name}) or
the email address of the author (@code{vm-su-from}).

The @code{author} selector is then registered in four places:

@itemize
@inindex vm-virtual-selector-function-alist
@item 
The variable @code{vm-virtual-selector-function-alist}, which contains pairs
of the form @samp{(@var{SELECTOR} . @var{FUNCTION})}.  For the @code{author}
selector, the pair is @code{(author . vm-vs-author)}.

@inindex vm-virtual-selector-arg-type
@item
The selector symbol @code{author} is given a property
@code{vm-virtual-selector-arg-type} indicating the type of argument it
requires:

@example
(put 'author 'vm-virtual-selector-arg-type 'string)
@end example

@inindex vm-supported-interactive-virtual-selectors
@item
The variable @code{vm-supported-interactive-virtual-selectors}, which
contains lists of strings, each string being the name of a virtual
selector.  For the @code{author} selector, the list is @code{("author")}.
Including the selector in this variable allows it to be used in creating
interactive virtual folders (search folders).

@inindex vm-virtual-selector-clause
@item
The selector symbol @code{author} is given a property
@code{vm-virtual-selector-clause} indicating the prompt string for
interactive use:

@example
(put 'author 'vm-virtual-selector-clause "with author matching")
@end example
@end itemize

@noindent Evidently, the last two registrations are only needed for interactive
selectors that can be used with the @kbd{V C} command.


@node Extents and Overlays, Timers and Concurrency, Virtual Folder Internals, Internals
@section Extents and Overlays

@inindex extents
@inindex overlays
XEmacs and GNU Emacs differ in how they represent non-textual
properties in buffers.  The web page on ``XEmacs vs GNU Emacs''
describes the situation as follows:

@quotation
XEmacs uses "extents" to represent all non-textual aspects of buffers;
GNU Emacs 19 uses two distinct objects, "text properties" and
"overlays", which divide up the functionality between them. Extents
are a superset of the union of the functionality of the two GNU Emacs
data types. The full GNU Emacs 19 interface to text properties and
overlays is supported in XEmacs (with extents being the underlying
representation). 

Extents can be made to be copied into strings, and then restored, by
kill and yank. Thus, one can specify this behavior on either "extents"
or "text properties", whereas in GNU Emacs 19 text properties always
have this behavior and overlays never do. 
@end quotation

While extents and overlays look similar on the surface, they differ
fundamentally in that extents are attached to text and, so, can be
killed and yanked, whereas overlays are not attached to text.  XEmacs
has implemented GNU-like text properties on top of extents.  So, text
properties may work more uniformly in both the Emacsen, but VM was
developed in the early days of the forking and does not use these
common features.

The file @code{vm-misc.el} contains definitions whereby both extents
and overlays can be treated as a single type of ``VM extents''.
Wherever such VM extents can be used, there is some uniformity in the
code but, in other places, there is not.  (Independently, the XEmacs
team has developed the @code{fsf-compat} package by which FSF-style
overlays are implemented on top of extents.  This package is not
compatible with the way VM deals with the two types.)

Another major differences between extents and overlays is that the
beginning and ending of overlays are markers.  This has some
advantages.  However, if a buffer has many overlays, normal editing
operations must update all the overlay markers, which can be
time-consuming.  

The major applications of extents and overlays in VM are the following:

@enumerate
@item
Summary buffers use extents/overlays for each summary line.  These are
implemented uniformly but, to avoid the performance problem in GNU
Emacs, all the markers are reset to nil before a summary is
regenerated and then set to their correct positions afterwards.  Not
doing this correctly can seriously degrade the performance of summary
generation.
@item
Presentation buffers use extents/overlays for @acronym{MIME} buttons.  These
are implemented uniformly.
@item
The message composition buffers have attachment buttons.  These are
implemented using text properties in GNU Emacs and extents in
overlays.  The difference is necessary because VM allows the
attachment buttons to be killed and yanked.  It is not possible to
implement this functionality using overlays.
@end enumerate

@node Timers and Concurrency,, Extents and Overlays, Internals
@section Timers and Concurrency

@inindex timers
@inindex concurrency
VM has been designed as mainly a sequential program.  However, there
are three timer tasks that get scheduled to occur at regular intervals: 

@table @code
@inindex vm-flush-itimer-function
@item vm-flush-itimer-function
Stores any needed message attributes in folder buffers so that they will be
saved when an autosave is done.  This is controlled by the variable
@code{vm-flush-interval}.  

This timer task switches to the folder buffers and
inserts text in message headers.  So, it moves the point and mark and
invalidates any cached
positions in the folder buffer.
@inindex vm-get-mail-itimer-function
@inindex vm-message-list
@item vm-get-mail-itimer-function
Moves any new mail from maildrops into the folder buffers.  This is
controlled by the variable @code{vm-auto-get-new-mail}.

This timer task switches to the folder buffers and appends text at the end.
It would extend the @code{vm-message-list} variables in these buffers.
It might also do various wholesale modifications such as sorting messages,
modifying the threads database, updating the summary and modeline etc.  If
there are POP or IMAP folders, it would execute server commands in the
corresponding process buffers.
@inindex vm-check-mail-itimer-function
@item vm-check-mail-itimer-function
Checks the maildrops for any new mail.  This is controlled by the
variable @code{vm-mail-check-interval}.

This timer task does not make any modifications to the folder buffers.
However, it executes server command in the process buffers of POP or IMAP
folders. 
@end table

@noindent These timer tasks are scheduled using the @code{itimer} package in
XEmacs and the @code{timer} package in Gnu Emacs.

@inindex vm-global-block-new-mail
The basic synchronization mechanism is a global variable
@code{vm-global-block-new-mail}.  If set, it prohibits the
@code{vm-get-mail-itimer-function} and @code{vm-check-mail-itimer-function}
from running.  All invocations of @code{get-new-mail} and
@code{check-for-new-mail} functions set this variable during their activity.


@node Concept Index, Key Index, Internals, Top
@unnumbered Concept Index
@printindex cp

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

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

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

@node Internals Index, License, Variable Index, Top
@unnumbered Internals Index
@printindex in

@node License,, Internals Index, Top
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifnottex
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifnottex

@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The ``Program'', below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term ``modification''.)  Each licensee is addressed as ``you''.

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

@item
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifnottex
@center NO WARRANTY
@end ifnottex

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifnottex
@center END OF TERMS AND CONDITIONS
@end ifnottex

@page
@unnumberedsec How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
@group
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end smallexample

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

@summarycontents
@contents
@bye
