This is vm.info, produced by makeinfo version 7.1.1 from vm.texinfo.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* VM: (vm).                             A mail reader.
END-INFO-DIR-ENTRY

This file documents the VM mail reader.
Copyright © 1989, 1991, 1999 Kyle E. Jones
Copyright © 2003 - 2008 Robert Widhopf-Fenk
Copyright © 2008 - 2012 Uday S. Reddy
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.


File: vm.info,  Node: Top,  Next: Preface,  Up: (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 8.3.3snapshot.

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



File: vm.info,  Node: Preface,  Next: Introduction,  Prev: Top,  Up: Top

What is VM?
***********

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.

   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 MIME.  VM can interface to other packages available in
Emacs, for remote file access, BBDB address book, 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.

   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
POP and IMAP protocols.  The local folders are stored in a Unix-standard
'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 'Babyl' format used by Emacs Rmail.  So, it is also possible to
inter-operate with Rmail if you have archived mail in that format.

   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 RSS feeds.  It does not have its own mail filtering
tools.  It does not have support for the Secure MIME (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


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

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
'mail-user-agent' to 'vm-user-agent', e.g.  by 'M-x'
'customize-variable' <RET> 'mail-user-agent' <RET>.

   To invoke VM, type 'M-x vm'.  VM gathers any mail that has arrived in
your system mailbox and appends it to a mail folder known as your
"primary inbox", and visits that folder for reading.  *Note 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 '?' in a VM folder buffer you will get some help, i.e.
'vm-help' is called.

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

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

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

   Messages are deleted by typing 'd' ('vm-delete-message') while
previewing or reading them.  The message is not 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 'u'
('vm-undelete-message'), and the message will be undeleted.  *Note
Deleting Messages::.  The actual removal of deleted messages from the
current folder is called "expunging" or "compacting", and it is
accomplished by typing '###' ('vm-expunge-folder', 'vm-compact-folder').
The deleted messages are still present in the on-disk version of the
folder until the folder is saved.

   Typing 'h' ('vm-summarize', '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 '->' appears to the left of the line summarizing the current
message.  The summary format is user configurable, *note Summaries::.

   When you are finished reading mail the current folder must be saved,
so that the next time the folder is visited VM will know which messages
have been already read, replied to and so on.  Typing 'S'
('vm-save-folder') saves the folder.  The default behavior is that
deleted messages are _not_ expunged automatically when you save a
folder.  The next time you visit the folder any deleted messages will
still be flagged for deletion.  *note Deleting Messages::.

   When a folder is first visited, the value of the variable
'vm-folder-file-precious-flag' is used to initialize a buffer-local
instance of '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.

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

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

   If the variable 'vm-confirm-quit' is set to 't' VM will always ask
for confirmation before ending a VM visit of a folder.  A 'nil' value
means VM will ask only when messages will be lost unwittingly by
quitting, i.e.  not removed by intentional delete and expunge.  A value
that is neither 'nil' nor 't' causes VM to ask only when there are
unsaved changes to message attributes or when messages will be lost.

   You do not have to quit a folder to continue using Emacs for other
purposes.  '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 'M-x vm-switch-to-folder'.  Or, you can
locate the folder's buffers again by using 'list-buffers', which is
normally bound to 'C-x C-b'.

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

   At any time while reading mail in any folder you can type 'g'
('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 '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.

   By default your primary inbox has your system mailbox associated with
it, e.g.  '/var/spool/mail/kyle', and so typing 'g' will retrieve mail
from this file.  Your system mailbox is one example of a "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 'vm-spool-files'.  *Note Spool
Files::.


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

1 Starting Up
*************

The first time VM is started in an Emacs session, it attempts to load
the file specified by the variable 'vm-init-file', normally '~/.vm'.  If
present this file should contain Lisp code, much like the '.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 'M-x vm-load-init-file' from within VM.

   In addition, VM also attempts to load a file specified by the
variable 'vm-preferences-file', normally '~/.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 '~/.vm.preferences' can considerably
reduce clutter in the '.vm' file.

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

   'M-x vm' causes VM to visit a folder known as your "primary inbox",
specified by the variable 'vm-primary-inbox'.  If the variable
'vm-auto-get-new-mail' is set non-'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 '~/Mail/inbox', but a
variety of other options are available.

   VM can work with mail folders saved on the local file system.  *Note
Local Folders::.  It can also work with mail folders stored on remote
mail servers, such as POP and IMAP servers.  *Note POP and 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.

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

   With a prefix argument '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 'vm-preserve-read-only-folders-on-disk' should be set to
'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.

   '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
'auto-mode-alist' to automatically start VM on a file based on a
particular filename suffix.  'vm-mode' skips some of VM's start-up
procedures (e.g.  starting up a summary) to make non-interactive use
easier.

   The variable 'vm-startup-with-summary' controls whether VM
automatically displays a summary of the folder's contents at startup.  A
value of 'nil' gives no summary; a value of 't' always gives a summary.
A value that is a positive integer N means that VM should generate a
summary if there are N or more messages in the folder.  A negative value
-N means generate a summary only if there are N or fewer messages.  The
default value of 'vm-startup-with-summary' is 't'.

* Menu:

* Local Folders::       Working with folders on the local file system
* POP and 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.


File: vm.info,  Node: Local Folders,  Next: POP and IMAP Folders,  Prev: Starting Up,  Up: Starting Up

1.1 Local Folders
=================

A local mail folder is simply a file that can be stored on the local
file system.  VM works with the Unix "mbox" format to store messages in
folders.  It can also work with the "Babyl" format used by the Emacs
Rmail package.  The subtypes of mboxes handled by VM are listed under
Folder types below.

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

   A "spool file" is a file where the mail transport system delivers
messages intended for you.  On Unix systems, a program called
'/bin/mail' or '/bin/mail.local' does this delivery.  It is also
possible for agents such as 'procmail', 'filter' and 'slocal' to be
invoked from a user's '~/.forward' or '~/.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 POP and 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.

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

   VM transfers the mail from a spool file to a folder via a temporary
file known as the "crash box".  The variable 'vm-crash-box' names the
crash box file for the primary inbox.  Or a crash-box name may be
created from 'vm-crash-box-suffix' described below.  (*note 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 '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
* POP Spool Files::     How to use a POP mailbox as a spool file
* IMAP Spool Files::    How to use an 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


File: vm.info,  Node: Spool Files,  Next: POP Spool Files,  Prev: Local Folders,  Up: Local Folders

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 'vm-spool-files'.

   If you only want to associate spool files with your primary inbox,
you can set '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 'vm-spool-files' like this:

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

With this setting, VM will retrieve mail for the primary inbox from
first '/var/spool/mail/kyle' and then '~/Mailbox'.

   If the value of 'vm-spool-files' is 'nil', a default value for
'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
'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 '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 '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 'vm-spool-files' like this

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

The folder '~/INBOX' has two spool files associated with it in this
example, '/var/spool/mail/kyle' and '~/Mailbox'.  Another folder,
'"~/Mail/bugs"' has one spool file '/var/spool/mail/answerman'
associated with it.  Note that both of the '~/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.

   An alternate way of specifying folder/spool file associations is to
use the variables 'vm-spool-file-suffixes' and 'vm-crash-box-suffix'.

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

     (setq vm-spool-file-suffixes '(".spool" "-"))

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

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

   The idea behind 'vm-spool-file-suffixes' and '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
'vm-spool-files'.  If you need even more control of spool file and crash
box names, use 'vm-make-spool-file-name' and '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 POP and IMAP protocols.


File: vm.info,  Node: POP Spool Files,  Next: IMAP Spool Files,  Prev: Spool Files,  Up: Local Folders

POP Spool Files
---------------

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

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

   The variable 'vm-pop-messages-per-session' controls how many messages
VM will retrieve from a POP mailbox before returning control to you.
Similarly, the variable 'vm-pop-bytes-per-session' limits the number of
bytes VM will retrieve from a 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 POP mailbox regardless of how many
messages there are and how large the mailbox is.

   Another way to reduce the amount of wait is to control how the large
messages should be handled.  If you set '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
'vm-get-new-mail' interactively, then VM will ask whether it should
retrieve the large message.  If VM is retrieving messages automatically
(e.g.  'vm-auto-get-new-mail' is set non-'nil') then VM will skip the
large messages and you can retrieve them later.

   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 'vm-expunge-pop-messages'; only
those messages that VM has retrieved into the current folder will be
expunged.

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

     ((MAILDROP . VAL) (MAILDROP . VAL) ...)

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

   VAL should be 'nil' if retrieved messages should be left in the
corresponding POP mailbox, 't' if retrieved messages should be removed
from the mailbox immediately after retrieval.

   Here is an 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
         )
     )


File: vm.info,  Node: IMAP Spool Files,  Next: Index Files,  Prev: POP Spool Files,  Up: Local Folders

IMAP Spool Files
----------------

VM can also use "IMAP" ("Internet Message Access Protocol") to retrieve
mail from a mail server.  As with POP, instead of specifying a local
file name in the 'vm-spool-files' definition, you would give an IMAP
maildrop specification (*note maildrop specification::, *note POP and
IMAP Folders::).  Once this is done, VM will retrieve new mail from the
IMAP mailbox in the same way as it retrieves it from system mailbox.
The retrieved messages can be automatically removed from the IMAP
mailbox or retained until a later expunge operation.

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

   The variable 'vm-imap-messages-per-session' controls how many
messages VM will retrieve from an IMAP mailbox before returning control
to you.  Similarly, the variable 'vm-imap-bytes-per-session' limits the
number of bytes VM will retrieve from an 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 IMAP mailbox regardless of
how many messages there are and how large the mailbox is.

   Another way to reduce the amount of wait is to control how the large
messages should be handled.  If you set '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
'vm-get-new-mail' interactively, then VM will ask whether it should
retrieve the large message.  If VM is retrieving messages automatically
(e.g.  'vm-auto-get-new-mail' is set non-'nil') then VM will skip the
large messages and you can retrieve them later.

   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 'vm-expunge-imap-messages'; only
those messages that VM has retrieved into the current folder will be
expunged.

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

     ((MAILDROP . VAL) (MAILDROP . VAL) ...)

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

   VAL should be 'nil' if retrieved messages should be left in the
corresponding IMAP mailbox, 't' if retrieved messages should be removed
from the mailbox immediately after retrieval.

   Here is an 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)
         )
     )

Multiple access to IMAP spool files
...................................

A principal idea behind the 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 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 IMAP mailboxes from multiple locations is to
use the facility of IMAP folders.  (*Note POP and 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 'vm-expunge-imap-messages' if you are careful to remember which site
should expunge messages and which site should retain them.

   VM remembers the messages you have downloaded from an 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
'X-VM-IMAP-Retrieved' in your mail folder.  When you expunge 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 '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.

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


File: vm.info,  Node: Index Files,  Next: Folder types,  Prev: IMAP Spool Files,  Up: Local Folders

Index Files
-----------

VM can create an "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.

   To use this feature, set the variable 'vm-index-file-suffix' to a
file name extension, e.g.,

     (setq vm-index-file-suffix "idx")


File: vm.info,  Node: Folder types,  Prev: Index Files,  Up: Local Folders

Folder types
------------

VM can handle a variety of formats for mail folders, which differ in
details.  The variable '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.)

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

   The system default format on most flavors of Unix (except Solaris,
AIX and System V) is referred to as '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.

   A variant of this format is referred to as '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
'From_' or 'BellFrom_', you must tell VM which one your system uses by
setting the variable 'vm-default-From_-folder-type'.  Some of the old
folders created by VM prior to 2000 were in the 'BellFrom_' format.  If
you will be using both 'From_' and 'BellFrom_' style folders, it is not
possible to choose an appropriate setting for this variable.  It is
recommended that you convert all the old 'BellFrom_' folders to the
'From_' format using the command 'vm-change-folder-type'.

   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 'From_-with-Content-Length'.  Since
the content lengths may be unreliable, you must also set the variable
'vm-trust-From_-with-Content-Length' to a non-Nil value in order to
convince VM that you really want to use this format.

   Two additional formats are 'mmdf' used by MMDF systems and 'babyl'
used by the Emacs Rmail mode.  These formats are recognized
automatically when read from the file system.


File: vm.info,  Node: POP and IMAP Folders,  Next: Thunderbird Folders,  Prev: Local Folders,  Up: Starting Up

1.2 POP and IMAP Folders
========================

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

     ``pop:HOST:PORT:AUTH:USER:PASSWORD''
     ``imap:HOST:PORT:MAILBOX:AUTH:USER:PASSWORD''

Remote mailboxes accessed by VM in this fashion are referred to as
"server folders" (and "POP folders" or "IMAP folders", more
specifically).

   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
"cache folders".  However, the _only_ permanent copies of the folders
are on the mail server.  This should be contrasted with using server
mailboxes as spool files (*note POP Spool Files:: and *note IMAP Spool
Files::), where the permanent folders are on the _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.

Maildrop specification
----------------------

The format of a POP or IMAP maildrop specification is as follows:

     ``pop:HOST:PORT:AUTH:USER:PASSWORD''
     ``imap:HOST:PORT:MAILBOX:AUTH:USER:PASSWORD''

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

   "SSL" refers to a protocol called "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 "TLS"
("transport layer security").  We refer to both of them as "SSL" in this
manual.

   For SSL, you must either be using a version of Emacs that has SSL
capability or have the 'stunnel' program installed and the variable
'vm-stunnel-program' naming it.  The default value of this variable,
'"stunnel"', which will work if an 'stunnel' program is installed in
your normal command search path.  In order to use the built-in SSL
capability of your Emacs, set 'vm-stunnel-program' to 'nil'.  Depending
on the version of 'stunnel' program you are using, you may need to
define a configuration file for 'stunnel'.  If you need it, you should
set the variable '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 'stunnel' program to find out what to put
in the configuration file.)

   For SSH, you must have the 'ssh' program installed and the variable
'vm-ssh-program' must name it in order for POP/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
POP/IMAP connection to be established.  By default that command is
'"echo ready; sleep 10"', but you can specify another command by setting
'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.)

   HOST is the host name of the mail server.

   PORT is the TCP port number to connect to.  The normal port numbers
are:
110            for POP
995            for POP over SSL
143            for IMAP
993            for IMAP over SSL

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

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

   Acceptable values of AUTH for IMAP are '"preauth"', '"cram-md5"', and
'"login"'.  '"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 'vm-imap-session-preauth-hook' is run,
and it is expected to return a process connected to an authenticated
IMAP session.  '"cram-md5' tells VM to use the CRAM-MD5 authentication
method as specified in RFC 2195.  The advantage of this method over the
'"login"' method is that it avoids sending your password over the net
unencrypted.  Not all IMAP servers support '"cram-md5"'; if you're not
sure, ask your mail administrator or just try it.  The other value,
'"login"', tells VM to use the IMAP LOGIN command for authentication,
which sends your user name and password in clear text to the server.

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

   PASSWORD is the secret shared by you and the server for
authentication purposes.  How it is used depends on the value of the
AUTH parameter.  If the PASSWORD is '*', 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.

   If your environment has the "EasyPG" utility and your version of
Emacs supports it, i.e., has the 'epa-file' and 'auth-source' libraries,
then you can store password information in a file such as
'.authinfo.gpg'.  The '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 '.authinfo.gpg' file should be of the form

     machine HOST login USER password PASSWORD port PORT

where HOST, USER, PASSWORD and PORT are as detailed above.  Ensure that
the variable 'auth-sources' is customized to refer to your authinfo
file.  *Note Help for users: (auth)Help for users.  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 'vm-pop-folder-alist' and
'vm-imap-account-alist', described below.

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.

   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 POP session" or "trace of 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 'stunnel' program.

   The variables 'vm-pop-keep-trace-buffer' and
'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:

* POP Folders::         How to use mailboxes on POP servers
* IMAP Folders::        How to use mail folders on IMAP servers


File: vm.info,  Node: POP Folders,  Next: IMAP Folders,  Prev: POP and IMAP Folders,  Up: POP and IMAP Folders

POP Folders
-----------

The command 'vm-visit-pop-folder' allows you to visit a POP mailbox as a
folder.  When you visit a 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
'vm-pop-folder-cache-directory' (or 'vm-folder-directory' if the former
is not defined).  If you delete and expunge messages in the folder, the
corresponding messages on the POP server will be removed when you save
the changes with 'vm-save-folder'.

   "Message attributes" (new, replied, filed, etc.)  and labels cannot
be stored on the POP server but they will be maintained in the cache
folder.  This means that if you access the same 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 IMAP folders (*note IMAP Folders::)
resident on an IMAP server.

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

      ((POPDROP NAME) ...)

   POPDROP is a POP maildrop specification (*note maildrop
specification::).

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

   For example:

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

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


File: vm.info,  Node: IMAP Folders,  Prev: POP Folders,  Up: POP and IMAP Folders

IMAP Folders
------------

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

   When you visit an 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
'vm-imap-folder-cache-directory' (or 'vm-folder-directory' if the former
is not defined).  If you delete and expunge messages, these changes are
made to both the cache folder and the folder on the IMAP server when
saved with 'vm-save-folder'.

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

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

      ((IMAPDROP NAME) ...)

   IMAPDROP is an IMAP maildrop specification (*note maildrop
specification::).

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

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

The mailbox and password fields ('*' in the example) are ignored.  When
'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 IMAP server can be specified.  For example, 'becky:inbox' or
'crickle:drafts'.

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

   The customization variable 'vm-imap-server-list', used in older
versions of VM, is deprecated.  Please use 'vm-imap-account-alist'
instead.

IMAP Synchronization
--------------------

The cache folder and the folder on the IMAP server are partially
synchronized every time '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.
The variable 'vm-imap-sync-on-get' specifies whether such
synchronization should be done as part of 'vm-get-new-mail'.  If the
variable is set to nil then 'vm-get-new-mail' simply retrieves any new
messages.

   The cache folder and the folder on the IMAP server are also
synchronized every time '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.

   The command 'vm-imap-synchronize' can always be used to perform full
synchronization with the server.


File: vm.info,  Node: Thunderbird Folders,  Next: External Messages,  Prev: POP and IMAP Folders,  Up: Starting Up

1.3 Thunderbird Folders
=======================

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.

   Alternatively, you can set the variable
'vm-thunderbird-folder-directory' to the directory where Thunderbird
stores its folders, and use the command 'M-x
vm-visit-thunderbird-folder' to visit its folders.  This works the same
way as 'vm-visit-folder' except that the default directory for visiting
folders as well as saving messages will be the value of
'vm-thunderbird-folder-directory'.  On the other hand, the folders
visited using 'vm-visit-folder' will continue to be in
'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
'vm-folder-directory' to that place and leave
'vm-thunderbird-folder-directory' with its default value of 'nil'.

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 'vm-summary-faces-hide' command.  *Note Hiding summary
lines::.

How the inter-operation works
-----------------------------

Thunderbird stores the folders in the 'From_' folder type.  *Note 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 'X-Mozilla-Status' and
'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 '.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 '.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.

   The variable 'vm-sync-thunderbird-status' controls how VM deals with
Thunderbird folders.  The default value 't' gives the behavior described
above.  You can also set it to ''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
'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 expunge (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 'vm-sync-thunderbird-status' is a buffer-local variable.
You may set its default value in your '.vm' file.  To change it in a
running Emacs session, you must use 'setq-default'.  *Note Local
Variables: (emacs)Locals.


File: vm.info,  Node: External Messages,  Next: Getting New Mail,  Prev: Thunderbird Folders,  Up: Starting Up

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

   To enable external messages, set the variable
'vm-enable-external-messages' to a list of contexts in which external
messages may be maintained by VM.

   As of version 8.2.0, the only context in which external messages are
implemented is that of IMAP folders.  Setting
'vm-enable-external-messages' to '(imap)' enables IMAP messages to be
maintained externally.  When new messages are retrieved, this causes all
messages with size below '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 'vm-imap-max-message-size' to 0.

   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
'vm-external-fetch-message-for-presentation' to 'nil'.  In that case,
the messages are displayed with an empty message body.  You can load the
missing message body using the 'o' command described below.

   After fetching the bodies of external messages, VM stores them in the
Folder buffer temporarily, so that repeated fetching is avoided.  The
variable '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 'nil', signifying that there is no limit.  All the
fetched message bodies are removed from the folders before they are
saved to disk.

   You can manually load message bodies into the Folder using the
command 'o' ('vm-load-message').  The command 'O' ('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
'vm-refresh-message' reloads an already loaded message with a fresh copy
retrieved from the server.


File: vm.info,  Node: Getting New Mail,  Next: Crash Recovery,  Prev: External Messages,  Up: Starting Up

1.5 Getting New Mail
====================

Pressing 'g' runs 'vm-get-new-mail', which will retrieve mail from all
the spool files associated with the current folder.  *Note Local
Folders::.  For POP and IMAP folders, any newly arrived messages at the
mail server will be incorporated into the local copy of the folders.

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

   If the value of the variable 'vm-mail-check-interval' is a positive
integer N, VM will check for new mail every 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
'vm-mail-check-always'.


File: vm.info,  Node: Crash Recovery,  Prev: Getting New Mail,  Up: Starting Up

1.6 Crash Recovery
==================

When Emacs crashes, its last action before dying is to try to write out
an "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, "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 _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.

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 _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 MIME decoding to
help catch your attention.

   If you want to recover the lost changes, run 'M-x vm-recover-folder'
or use the Recover Folder entry in Folder menu.  At the 'Recover File:'
prompt press <RET>.  Emacs's built-in 'recover-file' command is _not
recommended_ for this purpose because VM is unable to obtain reliable
data regarding mail folders from Emacs.

   In response to '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 'S' to save it to disk.  After you do this, VM will allow you to
use '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
'C-x C-q', which is bound to '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 POP or 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 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
('C-x C-q') is a better option in the case of server folders.

Recovering Message Compositions
-------------------------------

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
'vm-mail-auto-save-directory', if you have set that variable, or
'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 'M-x
mail-mode'.  VM's mail-mode command keys are not available in this mode.
The best option is to run 'M-x vm-postpone-message' to save the
unfinished message composition and then continue it using
'vm-continue-postponed-message'.  *Note Postponing Messages::.

Recovering Sessions
-------------------

Emacs also provides a way to recover the entire Emacs session after a
crash.  *Note (emacs)Recover::.  However, the Emacs '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 'vm-recover-folder' command instead.  So, when Emacs
'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 '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 '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.

Reverting a Folder
------------------

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 'vm-revert-folder' or the "Revert Folder" entry in the Folder
menu.  (Emacs's built-in 'revert-file' is not recommended.)


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

2 Navigating
************

In order to read, delete, or do anything to a message, you need to
select it.  In other words, make the message the "current message".

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

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

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

   A value of 't' causes all VM commands to consider folders circular.
A value of 'nil' causes all 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 'nil' or 't' causes only VM's movement commands to consider
folders circular.  Saves, deletes and undeletes will behave as if the
value is 'nil'.  The default value of 'vm-circular-folders' is 'nil'.

   You can also select messages by using the summary window.  *Note
Summaries::.  Move the cursor to the summary line for the message you
want to select and press <RET>.  VM will select this message.  Instead
of pressing <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 'd', VM will select the message under the cursor
and then delete it.  Note that this occurs _only_ when you execute a
command when the cursor is in the summary buffer window and only if the
variable 'vm-follow-summary-cursor' is non-'nil'.

   When a folder is visited or when you type '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 'vm-jump-to-new-messages' to 'nil', VM will favor old, unread
messages over new messages if the old, unread message appears earlier in
the folder.  If you set 'vm-jump-to-unread-messages' to 'nil' also, VM
will not search for new or unread messages.

   Other commands to select messages:

'<RET> (vm-goto-message)'
     Go to message number N.  N is the prefix argument, if provided,
     otherwise it is prompted for in the minibuffer.
'TAB (vm-goto-message-last-seen)'
     Go to message last previewed or read.
'N (vm-next-message-no-skip)'
'P (vm-previous-message-no-skip)'
     Go to the next (previous) message, ignoring the settings of the
     skip control variables.
'M-n (vm-next-unread-message)'
'M-p (vm-previous-unread-message)'
     Move forward (backward) to the nearest new or unread message.
'M-s (vm-isearch-forward)'
'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
     'vm-search-using-regexps' is non-'nil', a regular expression may be
     used instead of a fixed string for the search pattern; VM defaults
     to the fixed string search.  If a prefix argument is given, the
     value of 'vm-search-using-regexps' is temporarily reversed for the
     search.  *Note (emacs)Incremental Search::.


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

3 Reading Messages
******************

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

* Menu:

* Previewing::                  Customizing message previews.
* Paging::                      Viewing the current message.
* MIME Messages::     Using VM's MIME display features.


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

3.1 Previewing
==============

"Previewing" means showing you a small portion of a message and allowing
you to decide whether you want to read it.  Typing <SPC> exposes the
body of the message, and from there you can repeatedly type <SPC> to
page through the message.

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

   If the value of '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 'vm-preview-lines' is 'nil', then previewing
is not done at all; when a message is first presented it is immediately
exposed in its entirety and is flagged as read.  If 'vm-preview-lines'
is 't', the message body is displayed fully but the message is not
flagged as read until you type <SPC>.

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

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

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

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

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

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


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

3.2 Paging
==========

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

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

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

   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 '!'
('vm-toggle-flag-message').  You can also turn off the flag on a flagged
message by typing '!' again.  In the Summary display, the flagged
messages are highlighted using the 'vm-summary-high-priority-face'.
(*Note predefined summary faces::.)

   Sometimes you will receive messages that contain lines that are too
long to fit on your screen without wrapping.  Setting
'vm-word-wrap-paragraphs' to t will cause VM to use the 'longlines.el'
library by Grossjohann, Schroeder and Yidong to carry out word wrapping.
You must have this library installed somewhere on your 'load-path'.
Another way to deal with the problem is to use the 'visual-line-mode' in
Emacs 23.  You can activate it automatically for viewing messages by
adding the function 'turn-on-visual-line-mode' to the
'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
'vm-fill-paragraphs-containing-long-lines' to a positive numeric value
N, VM will call 'fill-paragraph' on all paragraphs that contain lines
spanning N columns or more.  You can also set this variable to the
symbol '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 'vm-paragraph-fill-column'.  Unlike the Emacs
variable 'fill-column', this variable is not buffer-local by default.


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

3.3 Reading MIME Messages
=========================

"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 MIME encoded messages and display them as
specified by the various MIME standards specifications.  This can be
turned off by setting the variable 'vm-display-using-mime' to 'nil' and
VM will then display MIME messages as plain text messages.

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

* Menu:

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


File: vm.info,  Node: Viewing MIME,  Next: Attachments,  Up: MIME Messages

3.3.1 Viewing 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.

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

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

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

   The variable 'vm-mime-auto-displayed-content-types' specifies the
types that are displayed immediately and
'vm-mime-auto-displayed-content-type-exceptions' specifies any
exceptions to the types specified in
'vm-mime-auto-displayed-content-types'.

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

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

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.

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

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

If "text" has been included in 'vm-mime-auto-displayed-content-types'
then the effect of this setting is to allow the auto-display of all text
types except for html.

Content-Disposition (inline or attachment)
..........................................

The MIME objects in messages come with a header called
"Content-Disposition", which specifies whether the 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 "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 MIME objects to be "inline" and others
that declare all MIME objects to be "attachment".  The variable
'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 't' means that they should be always honored and a value of
'nil' means that they should be ignored.  It can also be set to the
symbol 'internal-only', which means that the Content-Disposition
suggestions should be honored for only the internally displayable types.
(*Note Internal display of MIME attachments::.)

Viewing MIME structure
......................

The MIME structure of a message can be displayed using the command
'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.


File: vm.info,  Node: Attachments,  Next: Internal display,  Prev: Viewing MIME,  Up: MIME Messages

3.3.2 Operating on MIME attachments
-----------------------------------

The commands '[' and ']' ('vm-previous-button') and 'vm-next-button',
respectively) can be used to move to attachment buttons within the
message presentation.

   To activate a button, either click mouse-2 over it, or move the
cursor to the line and press <RET>.  If you are running under a window
system, you can use mouse-3 over a MIME button to display a menu of
actions you can take on the MIME object.  If you prefer using keyboard
commands, you can save the MIME object with '$ w', print it with '$ p',
or pipe it to a shell command with '$ |'.  Use '$ 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 '$ <RET>'.  To display the object using an external viewer,
type '$ e'.

$ w            'vm-mime-reader-map-save-file'
$ s            'vm-mime-reader-map-save-message'
$ p            'vm-mime-reader-map-pipe-to-printer'
$ |            'vm-mime-reader-map-pipe-to-command'
$ <RET>        'vm-mime-reader-map-display-using-default'
$ e            'vm-mime-reader-map-display-using-external-viewer'
$ v            'vm-mime-reader-map-display-object-as-type'
$ d            'vm-delete-mime-object'
$ a            'vm-mime-reader-map-attach-to-composition'

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

   It is a good idea to use '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.

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


File: vm.info,  Node: Internal display,  Next: HTML display,  Prev: Attachments,  Up: MIME Messages

3.3.3 Internal display of MIME attachments
------------------------------------------

The variable 'vm-mime-internal-content-types' specifies which types
should be displayed internally within Emacs.  Like
'vm-mime-auto-displayed-content-types' its value should be a list of
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:

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

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.

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

   The HTML content in text/html MIME parts can be displayed in Emacs
using a variety of packages.  VM knows about:

lynx        The 'lynx' browser used externally to convert HTML to plain
            text
w3m         The 'w3m' browser used externally to convert HTML to plain
            text
emacs-w3    The 'Emacs/W3' browser used internally in Emacs
emacs-w3m   The 'Emacs-W3M' browser used internally in Emacs.
            *Note Emacs-w3m: (emacs-w3m)top.

   You can set the variable 'vm-mime-text/html-handler' to one of these
values to use the appropriate package.  A value of 'auto-select' causes
VM to select the best package available.  A value of 'nil' asks VM not
to display HTML content internally.  The default value is '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 'nil'.


File: vm.info,  Node: HTML display,  Next: External display,  Prev: Internal display,  Up: MIME Messages

3.3.4 HTML display
------------------

The preferred method of displaying HTML content in email messages is
through the Emacs-w3m browser.  *Note Emacs-w3m: (emacs-w3m)top.  VM has
special facilities for using this browser, which are described in this
section.

   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 'vm-use-presentation-minor-modes' to 't'.  The minor mode
to be used for the Emacs-w3m generated text can be set using the
variable 'vm-presentation-minor-modes'.

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

   URL's embedded in 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 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 'vm-w3m-safe-url-regexp'.  You can set it to 't',
to regard all URL's as being safe, or to a regular expression that
identifies which 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:

'w3m-force-redisplay'
     You may set this to 'nil' if you find the HTML display "jittery"
     (which is caused by Emacs-w3m redisplaying the text during
     formatting).

'w3m-pop-up-frames'
     You may set this to 't' if you find that Emacs-w3m is too liberal
     with your Emacs windows.

'w3m-goto-article-function'
     Set this to an Emacs function that opens a 'URL'.  If you have
     already set 'vm-url-browser', you may copy its value into this
     variable.


File: vm.info,  Node: External display,  Next: Displaying images,  Prev: HTML display,  Up: MIME Messages

3.3.5 External display of MIME attachments
------------------------------------------

For types that you want displayed externally, set the value of
'vm-mime-external-content-types-alist' to specify external viewers for
the types.  The value of this variable should be an associative list of
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
'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

     (TYPE FUNCTION ARG ARG ... )

or

     (TYPE PROGRAM ARG ARG ... )

or

     (TYPE COMMAND-LINE)

TYPE is a string specifying a 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, FUNCTION is a lisp function that is responsible
for displaying the attachment in an external application.  Any ARGs 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, PROGRAM is a string naming a program to run to
display an object.  Any ARGs 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 ARG string by writing
'%f' in the 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
'%f' does not appear in any of the ARG strings.

   If the 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 PROGRAM/ARGS form, the name of the temporary file
that contains the MIME object will be appended to the command line if
'%f' does not appear in the command line string.

   In either the PROGRAM/ARG or COMMAND-LINE forms, all the program and
argument strings will have any %-specifiers in them expanded as
described in the documentation for the variable
'vm-mime-button-format-alist'.  The only difference is that '%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:

     (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")
            )
     )

   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 'vm-mime-delete-viewer-processes' to a '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.

   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
'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
'vm-mime-type-converter-alist'.  You can still display such a type with
an external viewer by using '$ e'.

   When a 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 '.html'
or '.jpg'.  You can use the variable
'vm-mime-attachment-auto-suffix-alist' to map 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:

     ((TYPE . SUFFIX) ...)

   TYPE is a string specifying a 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.

   SUFFIX is a string specifying the suffix that should be used for the
accompanying type.

   Example:

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

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.


File: vm.info,  Node: Displaying images,  Next: MIME type conversion,  Prev: External display,  Up: MIME Messages

3.3.6 Displaying inline images in messages
------------------------------------------

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 'display-images-p'.  However, Emacs relies on
external libraries to create graphical images, which are specified
through the variable '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
'image-type-available-p' with an image type such as 'tiff' or 'gif' as
the argument.

   Assuming that a particular image type, say 'tiff' is available, you
can include its MIME type in 'vm-mime-internal-content-types', e.g.,
     (add-to-list 'vm-mime-internal-content-types "image/tiff")
   You can also add the MIME type to the variable
'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.

   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 'ImageMagick'
graphics manipulation software.  You can install ImageMagick on your
system and specify the location of its 'identify' and 'convert' programs
to VM via the variables 'vm-imagemagick-identify-program' and
'vm-imagemagick-convert-program'.

   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
'vm-mime-use-image-strips' controls whether VM uses strips for image
display.  It is 't' by default.

   VM also uses the ImageMagick's '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 'vm-imagemagick-convert-program' to
'nil'.


File: vm.info,  Node: MIME type conversion,  Next: Character sets,  Prev: Displaying images,  Up: MIME Messages

3.3.7 MIME type conversion
--------------------------

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 'vm-mime-type-converter-alist'.

   The alist format is

     ( (START-TYPE END-TYPE COMMAND-LINE ) ... )

   START-TYPE is a string specifying a MIME type or type/subtype pair.
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.

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

   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:

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

The first matching list element will be used.


File: vm.info,  Node: Character sets,  Next: multipart/alternative,  Prev: MIME type conversion,  Up: MIME Messages

3.3.8 MIME character sets
-------------------------

For text type messages, 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.

   The variable '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 '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 'vm-mime-default-face-charsets' must be a list of
strings specifying the character sets that your default face can
display.  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")

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

   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
'vm-mime-charset-converter-alist' is an associative list of 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:

      ( ( START-CHARSET END-CHARSET COMMAND-LINE ) ... )

   START-CHARSET is a string specifying a MIME charset.  Example
'"iso-8859-1"' or '"utf-8"'.

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

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

   Example:

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

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

   The variable '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:

   ( (CHARSET .  FONT) ...)

   CHARSET is a string naming a MIME registered character set such as
'"iso-8859-5"'.

   FONT is a string naming a font that can be used to display CHARSET.

   An example setup might be:

     (setq vm-mime-charset-font-alist
       '(
         ("iso-8859-5" . "-*-*-medium-r-normal-*-16-160-72-72-c-80-iso8859-5")
        )
     )

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


File: vm.info,  Node: multipart/alternative,  Next: multipart/related,  Prev: Character sets,  Up: MIME Messages

3.3.9 MIME multipart/alternative
--------------------------------

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 "multipart/alternative".  The idea is that the sender
might have different 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 '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.

   To control how VM displays 'multipart/alternative' messages, you must
set the variable 'vm-mime-alternative-show-method'.  Its value must be a
symbol.  A value of '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
'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
'all' asks VM to display all the alternatives.

   The value can also be a list of the form

       (favorite TYPE ...)

with the first element of the list being the symbol 'favorite'.  The
remaining elements of the list are strings specifying 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 'favorite', 'favorite-internal' is used then the first
TYPE that matches an alternative that can be displayed internally will
be chosen.

   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
'vm-nuke-alternative-text/html' command.  This operation may not always
be safe because the '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.


File: vm.info,  Node: multipart/related,  Next: Inferring MIME types,  Prev: multipart/alternative,  Up: MIME Messages

3.3.10 MIME multipart/related
-----------------------------

The content type "multipart/related" is used to add attachments that
should be displayed embedded in the message, typically a 'text/html'
message.  If you use Emacs-W3M to view 'text/html' content, then VM will
automatically ship the '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 '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
'multipart/mixed' content.

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


File: vm.info,  Node: Inferring MIME types,  Next: Reading Secure MIME,  Prev: multipart/related,  Up: MIME Messages

3.3.11 Inferring MIME types
---------------------------

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

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

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


File: vm.info,  Node: Reading Secure MIME,  Prev: Inferring MIME types,  Up: MIME Messages

3.3.12 Reading Secure MIME Messages
-----------------------------------

VM supports reading S/MIME messages if your Emacs version includes
'smime.el' package.  Typically, a secure message part (identified by
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
'"application/x-pkcs7-smime"' and '"application/pkcs7-smime"' to the
variable 'vm-auto-displayed-mime-content-types' But beware that, at
present, the '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 S/MIME-encoded message should be considered private,
auto-decrypting could compromise security.

   In order to get started reading 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:

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

This will generate an encrypted private key in 'key.pem' and certificate
in '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
'smime-keys'.  (Consult its documentation for further info.)  More
importantly, the 'cert.pem' file (second element of each association) is
expected to also have the private key within it.  Simply concatenate
'key.pem' and 'cert.pem' files and store it in a file:

     cat key.pem cert.pem > key-cert.pem

Then 'smime-keys' might be

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

Multiple addresses with different certificates are allowed.  When
reading S/MIME messages, VM will search for recipients of the message
that match email addresses in 'smime-keys' and attempt to decrypt the
message with one of those keys.  Should there be no matches in the "To:"
or "Cc:" fields, '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.

   Secure 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
'vm-mime-verify-signatures' to 't'.  It is assumed that the signer's
certificate is embedded in the message (this is typically the case when
sending 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
'smime-certificate-directory'), which is useful for automatically
choosing certificates when sending mail.  See *note Sending Secure MIME:
Sending Secure MIME. for more information.


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

4 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. *Note (emacs)Sending Mail::.  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.

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

'M-x vm-yank-message-other-folder'
     This allows one to yank a message from a different folder than the
     parent of this composition.

'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.
'C-c C-a (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 MIME encode it.  The variable
     'vm-send-using-mime' must be set non-'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 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
     <C-k>.  If you want to move the attachment to some other part of
     the message, you can kill it <C-k> and yank it back with <C-y>.

'C-c C-m (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 'vm-next-command-uses-marks' first, the marked messages in
     the selected folder will be attached as a MIME digest.
'C-c C-b (vm-attach-buffer)'
     Attaches an Emacs buffer to the composition.

'C-c C-e (vm-mime-encode-composition)'
     Encodes the composition using 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 'C-c C-c' as usual to send
     the message.  Emacs' 'undo' command can be used to undo the
     encoding, so that you can continue composing the unencoded message.

'C-c C-p (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 <q> to quit the temporary folder and resume
     composing your message.

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

   The alternative command 'vm-mail' can be invoked outside of VM by
typing 'M-x vm-mail'.  However, only ('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 'M-r'
('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 MIME Messages::  Sending a message using MIME attachments.
* Sending Secure MIME::  Sending a secure message using the 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.


File: vm.info,  Node: Sending Options,  Next: Sending MIME Messages,  Prev: Sending Messages,  Up: Sending Messages

4.1 Mail Sending Options
========================

As already mentioned, VM uses Emacs *note (emacs)Mail Mode:: for sending
email.  Therefore, Mail Mode options should be set to configure the mail
sending.  The extra options provided by VM are described below.

   The variable '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 'vm-folder-directory' is used for auto-saving.

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

   The variable 'vm-mail-use-sender-address', if set to 't', asks VM to
fill in the 'To' header from the sender's name and address of the
current message.  This has effect only when 'vm-mail-from-folder' is
invoked from a VM folder.  When 'vm-mail' is invoked, possibly from
other buffers, the 'To' headers is unfilled.  (Some people tend to use
'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 '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.

   Additional header lines are created by VM before the composed message
is sent.  The variable 'vm-mail-header-insert-date' can be set to '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 'nil' if you would like
to insert a Date header yourself.  The variable
'vm-mail-header-insert-message-id' asks VM to insert a Message-ID header
before sending the message.  The variable
'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 'vm-mail-header-order'.


File: vm.info,  Node: Sending MIME Messages,  Next: Sending Secure MIME,  Prev: Sending Options,  Up: Sending Messages

4.2 Sending MIME Messages
=========================

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

* Menu:

* MIME attachments::    Sending a message using MIME attachments.
* MIME characters::     Sending a message with MIME-encoded characters.
* MIME headers::        Sending a message with MIME-encoded headers.
* MIME preview::        Previewing a MIME message before sending.


File: vm.info,  Node: MIME attachments,  Next: MIME characters,  Prev: Sending MIME Messages,  Up: Sending MIME Messages

MIME attachments
================

To attach a file to your composition, use 'C-c C-a' ('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]

You can type text before and after this tag and it will appear before or
after the text in the final MIME message when VM encodes it.  You can
kill the tag with 'C-k' and yank it back with '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.

   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 "Content-Disposition" of a 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.  "Inline"
display usually means that the object will be displayed within or
alongside the message text, if that is possible.  "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 MIME types except 'application' and 'model' types.

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

   You can attach a message from another folder by using 'C-c C-m'
('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.

Point-to-point attachment operations
------------------------------------

A number of "point-to-point operations" allow you to attach objects from
other editing contexts to a message you are composing.

   You can visit a directory in Emacs (*note (emacs)Dired::), and run
'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 'vm-dired-do-attach-files' to attach all of them.

   You can use your Window system to drag and drop a file into a
composition buffer ('vm-dnd-attach-file').

   When you visit a folder in VM, you can attach a message from the
folder by running 'vm-attach-message-to-composition'.  When viewing a
message that has MIME attachments, you can attach any of those
attachments to your message composition by using the '$ a'
('vm-reader-map-attach-to-composition') function.  (*Note Operating on
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.


File: vm.info,  Node: MIME characters,  Next: MIME headers,  Prev: MIME attachments,  Up: Sending MIME Messages

MIME characters
===============

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
'vm-mime-7bit-composition-charset'.  The value of this variable should
be a string specifying the character set.

   If there are character codes in the composition greater than 128, the
variable 'vm-mime-8bit-composition-charset' tells VM what character set
to assume when encoding the message.  The default is '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.

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

   VM's text transfer encoding behavior is controlled by the variable
'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 'quoted-printable', means to use quoted-printable encoding.  A
value of 'base64' means to use BASE64 encoding.  A value of '8bit' means
to send the message as is.  Note that this variable usually only applies
to textual 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).


File: vm.info,  Node: MIME headers,  Next: MIME preview,  Prev: MIME characters,  Up: Sending MIME Messages

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 MIME encoded-word syntax,
which is of the form '=?charset?encoding?encoded text?='.

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

   The variables 'vm-mime-encode-words.regexp' and
'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.


File: vm.info,  Node: MIME preview,  Prev: MIME headers,  Up: Sending MIME Messages

MIME preview
============

To preview what a MIME message will look like to a recipient, use 'C-c
C-p' ('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 'q' in this folder will return you to your composition where you
can make further changes.

   To encode a MIME message without sending it, use 'C-c C-e'
('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 'undo' (normally bound to 'C-x u') command which will revert the
encoded MIME bodies back to tags and you can continue entering your
composition.


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

4.3 Sending Secure MIME Messages
================================

VM supports sending S/MIME messages utilizing the '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 ('C-c C-c'), you would use one of the
following functions

   * 'vm-smime-sign-message'
   * 'vm-smime-encrypt-message'
   * 'vm-smime-sign-encrypt-message'

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.

   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
'vm-smime-get-recipient-certificate-method'.  At present, the options
are one of 'ask or 'links.

   * 'ask

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

   * 'links

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

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

     This doesn't require prompting the user _unless_ a particular
     recipient address could not be associated with a file, in which
     case the user will be promoted to provide a replacement.

   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 _will_ be encrypted.


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

4.4 Replying
============

VM has special commands that make it easy to reply to a message.  When a
reply command is invoked, VM fills in the subject and recipient headers
for you, since it is apparent whom the message should be sent to and
what the subject should be.  There is an old convention of prepending
the string 'Re: ' to the subject of replies if the string isn't present
already.  You can customize the string to be prepended in this way by
setting the variable '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 'nil' value means don't prepend anything to the subject
(this is the default).  In any case you can edit any of the message
headers manually, if you wish.

   VM also helps you cite material from the message to which you are
replying, by providing "included text" as a feature of some of the
commands.  "Included text" is a copy of the message being replied to
with some prefix to each line so that the included text can be
distinguished from the text of the reply.  By default, the prefix string
is '> '.  This can be customized via the variable
'vm-included-text-prefix'.

   The reply commands are:

'r (vm-reply)'
     Replies to the author of the current message.
'R (vm-reply-include-text)'
     Replies to the author of the current message and provides included
     text.
'f (vm-followup)'
     Replies to the all recipients of the current message.
'F (vm-followup-include-text)'
     Replies to the all recipients of the current message and provides
     included text.
'vm-mail-to-sender'
     Writes a message to the sender of the current message.  (This is
     similar to 'vm-reply' but meant for writing a message about a new
     subject.)

   These commands all accept a numeric prefix argument N, which if
present, causes VM to reply to the next (or previous if the argument is
negative) N-1 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.  (*note Marking
Messages::.)

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

   The variable '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 'vm-included-text-attribution-format',
'vm-in-reply-to-format' should be a string similar to that of
'vm-summary-format'.  A 'nil' value causes the In-Reply-To header to be
omitted.  If the format includes elements that can contain non-ASCII
characters, then 'In-Reply-To' should be added to
'vm-mime-encode-headers-regexp'.

   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 'vm-strip-reply-headers' is non-'nil',
the recipient headers will be stripped of all information except the
actual addresses.

Included text
-------------

As mentioned above, the commands 'vm-reply-include-text' and
'vm-followup-include-text' provide "included text" from the original
message in your reply.  In addition, you can use 'C-c C-y'
('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.)

   Citing message text is a tricky business because the original message
could be a MIME message with encoded text or formatted text along with
embedded images and attachments.  By default, VM uses its 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 MIME attachments are not included by
default.  They are shown in the message composition buffer with
attachment buttons labelled similar to:

     [DELETED ATTACHMENT mary.jpg, image/jpeg]

If you set the variable '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:

     [ATTACHMENT mary.jpg, image/jpeg]

   When citing a 'multipart/alternative' MIME component, VM uses the
variable 'vm-mime-alternative-yank-method' to decide which alternative
should be cited.  It can be defined in a similar way to the variable
'vm-mime-alternative-show-method'.  (*note multipart/alternative::.)

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.

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

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

   Finally, you can fill individual paragraphs manually using 'C-c C-q'
('mail-fill-yanked-message').

Alternative methods to include text
-----------------------------------

The method of 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.

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

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

Options
-------

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

   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 'vm-included-text-headers' and
'vm-included-text-discard-header-regexp'.


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

4.5 Forwarding Messages
=======================

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

Forwarding
----------

Typing 'z' ('vm-forward-message') puts you into a VM Mail mode buffer
just like 'm', except that the current message appears as the body of
the message in the VM Mail mode buffer.

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

   If 'vm-forwarding-digest-type' is set to '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.

   The key 'Z' ('vm-forward-message-plain') allows you to use plain-text
forwarding directly, without needing to alter
'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
'vm-mime-forward-saved-attachments' to '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.)

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

   * For encapsulated forwarding, the default is to forward all the
     headers, but you can limit the forwarded headers by setting
     'vm-unforwarded-header-regexp' to a regular expression.  All the
     headers matching the regular expression will be omitted.  If this
     variable is set to 'nil', then its value is ignored and only the
     headers listed in 'vm-forwarded-headers' are forwarded.
   * For plain-text forwarding, done by the 'Z' command, the variables
     'vm-forwarded-headers-plain' and
     '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
     'vm-forwarded-headers-plain' are included.  The default settings
     forward only the headers "From", "To", "Cc", "Subject", "Date" and
     "In-Reply-To".

   The command 'vm-forward-message-all-headers' forwards the message
with all headers intact, irrespective of the values of these variables.

   If the variable 'vm-forwarding-subject-format' is non-'nil' it should
specify the format of the Subject header of the forwarded message.  A
'nil' value causes the Subject header to be left blank.  The forwarded
message is flagged "forwarded" when the message is sent.

Digests
-------

The command '@' ('vm-send-digest') works like 'z' except that a digest
of all the messages in the current folder is made and inserted into the
VM Mail mode buffer.  Also, 'vm-send-digest' can be applied to just
marked messages.  *Note Selecting Messages::.  The message encapsulation
method is specified by the variable 'vm-digest-send-type', which accepts
the same values as 'vm-forwarding-digest-type'.  All the messages
included in the digest will be flagged "forwarded" when the digest
message is sent.

   If you give 'vm-send-digest' a prefix argument, VM will insert a list
of preamble lines at the beginning of the digest, one line per
digestified message.  The variable 'vm-digest-preamble-format'
determines the format of the preamble lines.  If the value of
'vm-digest-center-preamble' is non-'nil', the preamble lines will be
centered.

Resending
---------

You can forward a message "as is", without appearing to intervene, by
"resending" it.  Use the 'B' ('vm-resend-message') command.  VM will
resend the same original message with its original headers and add a
'Resent-To' header that you should fill in with the new recipients.  Use
'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 '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.


File: vm.info,  Node: Saving copies,  Next: Personality Crisis,  Prev: Forwarding Messages,  Up: Sending Messages

4.6 Saving copies of sent mail
==============================

You can save copies of outgoing mail messages in 'sent' folders by
adding an '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 IMAP server.  If
you use IMAP folders for saving sent mail, you should also add the
function 'vm-imap-save-composition' to the mail-mode's 'mail-send-hook'
variable.

   If you have multiple IMAP accounts, you might wish to save copies of
your replies separately in each IMAP account.  This can be done by
adding an 'IMAP-FCC:' header line.  The value of the header field should
be a plain folder name on the "current" IMAP account, e.g., 'Sent'.  The
"current" IMAP account will be determined by the 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 IMAP folder or if
there is no parent folder, then the message copy will be saved in a
folder on 'vm-imap-default-account'.

   The variable 'vm-do-fcc-before-mime-encode' allows you save the fcc
copy to the sent folder 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.


File: vm.info,  Node: Personality Crisis,  Next: Postponing Messages,  Prev: Saving copies,  Up: Sending Messages

4.7 Personality Crisis: Programmable customization of message composition
=========================================================================

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
'vm-init-file':

     (require 'vm-pcrisis)

   As a quick start, you can add a line to define your email identities:

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

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.

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

     (set-variable 'vmpc-conditions
                   '(("condition-name1" CONDITION)
                     ("condition-name2" CONDITION)
                     ...))
     (set-variable 'vmpc-actions
                   '(("action-name1" ACTION...)
                     ("action-name2" ACTION...)
                     ...))

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

     (CONDITION-NAME ACTION-NAME1 ACTION-NAME2...)
'vmpc-default-rules'
     Condition-action rules for composing messages based on a parent
     message, such as replying, forwarding, resending and mailing (*note
     vm-mail-from-folder::).

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

'vmpc-newmail-rules'
     Condition-action rules for new message compositions with no parent
     message.  (*note vm-mail::).

'vmpc-automorph-rules'
     Condition-action rules for message compositions based on their own
     content (called "automorphing").

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

'vmpc-header-match'
     This condition checks if a header field of the message matches a
     regular expression pattern.  For example, the condition

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

     checks if either the "To" or "Cc" header contains the pattern
     'me@myisp.net'.

'vmpc-only-from-match'
     This is similar to '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

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

     if every email address in the "To" and "Cc" headers is at
     'mycompany.com'.

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

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

'vmpc-folder-account-match'
     This condition checks if the POP/IMAP account of the folder
     contains the given regular expression pattern.

'vmpc-check-virtual-selector'
     (This function is provided by the 'vm-avirtual' package.)  This
     condition checks if the message matches a given virtual selector.

'vmpc-other-cond'
     This condition returns true if another named condition (defined
     earlier in 'vmpc-conditions') evaluated to true.  This allows
     building complex conditions from simpler ones.

'vmpc-none-true-yet'
     This condition returns true if none of the conditions that came
     before it in 'vmpc-conditions' have returned true.  This is useful
     as a fallback to prompt for a profile when no other conditions
     match.

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

   The actions are typically executed in the mail composition buffer for
the message you are composing.

'vmpc-substitute-header'
     This action substitutes a specified header field of the outgoing
     message with a given string.  For example, the action

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

     sets the "From" header of the outgoing message to 'me@myisp.net'.

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

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

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

'vmpc-signature'

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

'vmpc-pre-signature'
     This action is similar to 'vmpc-signature', but inserts the new
     signature at the top, above the message body.

'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:

          (vmpc-substitute-replied-header "To" "From")

     copies the "From" header of the original message to the "To" header
     of the reply.

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

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

'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:

          (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

4.7.1 Automorph
---------------

The '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 'vm-mail-mode-map':

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

Or attach it to moving between headers:

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

4.7.2 Debugging Personality Crisis
----------------------------------

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

   * 'vmpc-true-conditions' -- the list of conditions that evaluated to
     true
   * 'vmpc-actions-to-run' -- the list of actions that will be executed

   You can also call 'vmpc-build-true-conditions-list' interactively to
test your conditions.


File: vm.info,  Node: Postponing Messages,  Prev: Personality Crisis,  Up: Sending Messages

4.8 Postponing Messages
=======================

Sometimes, you might want to interrupt the composing of a message and
continue it later.  This is called "postponing".

   In a message composition buffer, the command <C-c C-d>
('vm-postpone-message') postpones the current composition.  The
postponed message is stored in the folder specified in
'vm-postponed-folder'.  (The default is a folder called "postponed").
When called with a prefix argument, '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.

   You can continue composing the postponed messages by visiting
'vm-postponed-folder', selecting a message and running '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 MIME buttons into attachment buttons, which will be
encoded as valid 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.

   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 'vm-auto-expunge-postponed-folder' to 't'
in your VM configuration file.


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

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

   All VM operations take a prefix argument, which may be a positive
integer, negative integer or 0.  If it is a positive integer N, then the
current message and the next N-1 are selected for the operation.  If it
is a negative integer -N, then the current message and the previous N-1
are selected.  If it is 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.  *Note 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.


File: vm.info,  Node: Marking Messages,  Prev: Selecting Messages,  Up: Selecting Messages

5.1 Marking Messages
====================

VM provides a way to "mark" selected messages so that subsequent
operations can be applied to them.  This is similar to marking in other
parts of Emacs, e.g., *note Dired Marks: (emacs)Marks vs Flags, 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.

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

   To remove a mark from the current message, use 'M U'
('vm-unmark-message').  Prefix arguments work as with 'vm-mark-message'.

   Use 'M m' to mark all messages in the current folder; 'M u' removes
marks from all messages.

   Other marking commands:

'M C (vm-mark-messages-by-selector)'
     Mark all messages matching a virtual selector.  *Note Virtual
     Folders::.
'M c (vm-unmark-messages-by-selector)'
     Unmark all messages matching a virtual selector.
'M X (vm-mark-messages-by-virtual-folder)'
     Mark all messages matching the selectors of a virtual folder.
     *Note Virtual Folders::.
'M x (vm-unmark-messages-by-virtual-folder)'
     Unmark all messages matching the selectors of a virtual folder.
'M T (vm-mark-thread-subtree)'
     Mark all messages in the thread tree rooted at current message.
     *Note Threading::.
'M t (vm-unmark-thread-subtree)'
     Unmark all messages in the thread tree rooted at current message.
'M S (vm-mark-same-subject)'
     Mark messages with the same subject as the current message.
'M s (vm-unmark-same-subject)'
     Unmark messages with the same subject as the current message.
'M A (vm-mark-same-author)'
     Mark messages with the same author as the current message.
'M a (vm-unmark-same-author)'
     Unmark messages with the same author as the current message.

   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.

'M R (vm-mark-summary-region)'
     Mark all messages in the current region in a Summary buffer
'M r (vm-unmark-summary-region)'
     Unmark all messages in the current region in a Summary buffer

   To apply a VM command to all marked messages you must prefix it with
the key sequence 'M N' ('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 '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.,

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

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:

     MuMTMNsMu

saves a thread of messages.  However, there are faster methods to
operate on message threads.  *Note Thread Operations::.


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

6 Saving Messages
*****************

Mail messages are normally saved to files that contain only mail
messages.  Such files are called "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.

   The VM command to save a message to a folder is 's'
('vm-save-message'); invoking this command causes the current message to
be saved to a folder whose name you specify in the minibuffer.  It can
be given a prefix argument N to indicate how many messages should be
saved.  Messages saved with 'vm-save-message' are flagged "filed".

   Messages can be saved to folders on the local file system or to
folders on an IMAP server.  If 'vm-folder-directory' is set,
'vm-save-message' will insert this directory name into the minibuffer
before prompting you for a folder name; this will save you some typing.
If 'vm-thunderbird-folder-directory' is set and you enter a Thunderbird
folder using 'vm-visit-thunderbird-folder', then that directory will be
the default place for saving messages.

   Another aid to selecting folders in which to save mail is the
variable '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.

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

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

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

   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
'vm-visit-when-saving' controls which method is used.  A value of 't'
causes VM to always visit a folder before saving message to it.  A 'nil'
value causes VM to always append directly to the folder file.  In this
case VM will not save messages to the disk copy of a folder that is
being visited.  This restriction is necessary to insure that the buffer
and on-disk copies of the folder are consistent.  If the value of
'vm-visit-when-saving' is not 'nil' and not 't' (e.g.  0, the default),
VM will append to the folder's buffer if the buffer is currently being
visited, otherwise VM will append to the file itself.

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

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

   The variable '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.  *Note vm-virtual-auto-folder-alist::.  The suggestion of
save folders via both the methods can be turned on or off using the
variable 'vm-save-using-auto-folders'.  (Its default value is 't'.)

   The value of 'vm-auto-folder-alist' should be a list of the form:

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

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

   * the absolute path name of a local folder,
   * a relative path name - relative to 'vm-folder-directory' or the
     'default-directory' of the currently visited folder, whichever is
     non-nil, or
   * the maildrop specification of an IMAP folder.

   If any part of the contents of the message header named by
HEADER-NAME is matched by the regular expression REGEXP, VM will
evaluate the corresponding FOLDER-NAME and use the result as the default
when prompting for a folder to save the message in.

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

   Whether matching is case-sensitive depends on the value of the
variable 'vm-auto-folder-case-fold-search'.  A non-'nil' value makes
matching case-insensitive.  The default value is 't', which means
matching is case-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.

Other commands
==============

'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 'vm-save-message'
     does.  Messages saved this way are flagged "written".
'A (vm-auto-archive-messages)'
     Save all unfiled messages that auto-match a folder via
     'vm-auto-folder-alist' to their appropriate folders.  Messages that
     are flagged for deletion are not saved by this command.  This
     command asks for confirmation before archiving because it is a
     wholesale operation that cannot be easy reversed.  (Set
     'vm-confirm-for-auto-archive' to 'nil' to override the confirmation
     dialogue.)  If the command is invoked with a prefix argument,
     confirmation will be requested for each save.
'|| (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 C-u the text portion of the message is used.
     If invoked with two C-u's the header portion of the message is
     used.
     In invoked with three 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
     '*Shell Command Output*' buffer.  The message itself is not
     altered.
'|d (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.
'|s (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
     'vm-pipe-message-to-command', the leading and trailing separator
     lines are included.  This behaviour can be altered using the
     variables 'vm-pipe-messages-to-command-start' and
     'vm-pipe-messages-to-command-end'.
'|n (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.

   A non-'nil' value of 'vm-berkeley-mail-compatibility' means to read
and write BSD Mail(1) style Status: headers.  This makes sense if you
plan to use VM to read mail archives created by Mail.


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

7 Deleting Messages
*******************

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

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

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

   Normally, deleted messages are preserved in folders until an explicit
'vm-expunge-folder' ('vm-compact-folder') operation is done.  This
default behavior can be altered by setting the variables
'vm-expunge-before-save' and 'vm-expunge-before-quit'.  If
'vm-expunge-before-save' is set to non-'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 'vm-expunge-before-quit' can be similarly set to non-'nil'
to cause VM to expunge deleted messages whenever you quit the folder.

   The commands 'vm-save-folder-no-expunge' and '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
'vm-quit' command has the same effect as 'vm-quit-no-expunge'.

   The function '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
'vm-delete-duplicate-messages' automatically.  For instance, the
customization in your VM init file can have:

     (add-hook 'vm-arrived-messages-hook 'vm-delete-duplicate-messages)

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.  (*Note Hooks::.)


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

8 Editing Messages
******************

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

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

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

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


File: vm.info,  Node: Message Attributes,  Next: Sorting Messages,  Prev: Editing Messages,  Up: Top

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

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

   You can set and unset these attributes directly by using '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 'M N'.

   VM provides a special form of undo which allows changes to message
attributes to be undone.  Typing 'C-x u' or <C-_> ('vm-undo') undoes the
last attribute change.  Consecutive 'vm-undo''s undo further and further
back.  Any intervening command breaks the undo chain, after which the
undo's themselves become undoable by subsequent invocations of
'vm-undo'.

   Note that expunges, saves and message edits are _not_ undoable.

   "Labels" are user-defined message attributes.  They can have any name
and be assigned any meaning by you.  Labels are added with 'l a'
('vm-add-message-labels' and 'l e' ('vm-add-existing-message-labels',
and are removed by 'l d' ('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.

   To completely remove a label from a folder, use '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
'vm-undo'.

   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
'vm-flush-interval' controls how often that is done.  A value of 't'
means write the new attributes to the folder buffer whenever a change
occurs.  A value of '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.  *Note
Crash Recovery::.  A positive integer value N instructs VM to write out
attribute changes every N seconds.  The default value of this variable
is 't'.


File: vm.info,  Node: Sorting Messages,  Next: Digests,  Prev: Message Attributes,  Up: Top

10 Sorting Messages
*******************

In order to make numerous related messages easier to cope with, VM
provides the command 'G' ('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 'vm-sort-messages'
with a prefix argument, or you can set 'vm-move-messages-physically'
non-'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.

   Valid sort keys are:
date                      reversed-date
activity                  reversed-activity
author                    reversed-author
subject                   reversed-subject
recipients                reversed-recipients
line-count                reversed-line-count
byte-count                reversed-byte-count
physical-order            reversed-physical-order
spam-score                reversed-spam-score

   The sort key '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
'vm-sort-messages-by-delivery-date' to '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
'Delivery-Date' header.  If no such header is present, then VM uses the
sent date.)

   The sort key 'activity' represents the date of the most recent
activity.  This is the default sort order used with threads.  *Note
Threading::.  It allows even old threads that have recent messages to be
brought to the front.

   When sorting by subject (or threading using subjects, or killing
messages by subject) the subject of the message is "normalized" before
comparisons are done.  A "normalized" subject has uninteresting prefixes
and suffixes stripped off, and multiple consecutive white space
characters are collapsed to a single space.  The variable
'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 'nil' value means VM
should not ignore any prefixes.  The analogous variable for subject
suffixes is 'vm-subject-ignored-suffix'.  By default,
'vm-subject-ignored-prefix' is set to remove the prefix "Re:", which is
often added in replying to messages.  The default value of
'vm-subject-ignored-suffix' is set to remove the suffix "(fwd)", which
is sometimes added when messages are forwarded.

   In addition to these uninteresting prefixes/suffixes, you also have
the option of removing "subject tags" that are added by mailing lists
when forwarding messages to members.  For example, the '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
'vm-subject-tag-prefix' to a regular expression that matches all subject
tags you want removed.  For example, the setting

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

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

   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 'vm-summary-strip-subject-tags' should be set to a non-nil
value to achieve this effect.

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

   The sorting by '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 '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:

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

This triple causes VM to extract a spam-score from '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
'string-to-number' function.  The order in which the headers are listed
in '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 'C-M-n'
('vm-move-message-forward') and 'C-M-p' ('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 N can specify a longer
move.  The value of 'vm-move-messages-physically' applies to these
commands.

* Menu:

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


File: vm.info,  Node: Threading,  Prev: Sorting Messages,  Up: Sorting Messages

10.1 Threading
==============

A "thread" is a group of messages that are either related by subject or
that have a common ancestor.  "Threading" is the process of determining
the relationship between such messages and displaying them so that those
relationships are evident.

   To enable and disable threading, type 'C-t'
('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.

   Message relationships are discovered by examining the 'References',
'In-Reply-To', and 'Subject' headers.  The first two headers are more
reliable sources of information but not all mailers provide them.
Therefore, all messages with similar 'Subject' headers are also grouped
into threads.  If you don't want VM to use Subject headers for
threading, set the variable 'vm-thread-using-subject' to '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.

   Normally, thread-based grouping applies to entire threads as well as
all their subthreads.  You can block subthread grouping by setting the
variable 'vm-sort-subthreads' to '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 'vm-move-messages-physically' applies to
threading just as it applies to sorting.


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

11 Digests
**********

A "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.

   The command ('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.


File: vm.info,  Node: Summaries,  Next: Virtual Folders,  Prev: Digests,  Up: Top

12 Summaries
************

Typing 'h' ('vm-summarize', '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 '->' appears to the left of the line summarizing the
current message.  The variable 'vm-auto-center-summary' controls whether
VM will keep the summary arrow vertically centered within the summary
window.  A value of 't' causes VM to always keep the arrow centered.  A
value of 'nil' (the default) means VM will never bother centering the
arrow.  A value that is not 'nil' and not 't' causes VM to center the
arrow only if the summary window is not the only existing window.  You
can change what the summary arrow looks like by setting
'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 'vm-startup-with-summary' non-nil.  *Note Starting
Up::.

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

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

* 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


File: vm.info,  Node: Summary Format,  Next: Threaded Summaries,  Prev: Summaries,  Up: Summaries

12.1 Summary Format
===================

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

   Recognized specifiers are:

'a'
     attribute indicators (always four characters wide)
     The first char is 'D', 'N', 'U' or '!'  for deleted, new, unread
     and 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.

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

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

'*'
     message mark, '*' if the message is marked, ' ' otherwise

'p'
     indicator for a postponed message: 'P' or the string customized by
     'vm-summary-postponed-indicator'

'P'
     indicator for a message with attachments: '$' or the string
     customized via 'vm-summary-attachment-indicator'

'I'
     thread indentation

'n'
     message number

'i'
     message ID

'c'
     number of characters in message (ignoring headers)

'S'
     human readable size of the message

'l'
     number of lines in message (ignoring headers)

'd'
     numeric day of month message sent

'w'
     day of the week message sent

'm'
     month message sent

'M'
     numeric month message sent (January = 1)

'y'
     year message sent

'h'
     hour:min:sec message sent

'H'
     hour:min message sent

'z'
     timezone of date when the message was sent

'f'
     author's address

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

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

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

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

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

's'
     message subject

'L'
     labels (as a comma list)

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

'('
     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.

')'
     ends a group.

   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.

   If you save copies of all your outbound messages in a folder and
later visit that folder, the '%F' format specifier will normally display
your own name.  If you would rather see the recipient addresses in this
case, set the variable 'vm-summary-uninteresting-senders'.  This
variable's value, if non-'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 '%F' or
'%f' summary format specifiers VM will substitute the value of
'vm-summary-recipient-marker' (default "To: ") followed by what would be
shown by the '%T' and '%t' specifiers respectively.

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

   (For compatibility with older versions, the variable
'vm-summary-recipient-marker' is also referred to by its old name,
'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.

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

   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
'vm-restore-saved-summary-format' to t to achieve this effect.


File: vm.info,  Node: Threaded Summaries,  Next: Thread Folding,  Prev: Summary Format,  Up: Summaries

12.2 Threaded Summaries
=======================

When message threading is enabled (*note 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
'vm-summary-thread-indent-level'.  The default is two spaces.  The
variable 'vm-summary-maximum-thread-indentation' says how many levels
should be displayed via indentation.  The default is 20.

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

     (setq-default vm-summary-show-threads t)

Do not use '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 'C-t' to control the thread
display.  *Note Threading::.

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.

   The command '<' ('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.

   The command '>' ('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.


File: vm.info,  Node: Thread Folding,  Next: Thread Operations,  Prev: Threaded Summaries,  Up: Summaries

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

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

   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
'vm-summary-visible', whose value must be a list of VM selectors in the
same format as those in 'vm-virtual-folder-alist'.  *Note Virtual
Folders::.

   The variable '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 'N' and 'P'
('vm-next-message-no-skip' and 'vm-previous-message-no-skip') cause the
threads to be expanded or collapsed as needed when you move into or out
of threads.

   The variable '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 'N+C' where 'N' is
the message number and '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.

   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 'E' ('vm-expand-all-threads').  The command 'C'
('vm-collapse-all-threads') does the reverse.


File: vm.info,  Node: Thread Operations,  Next: Summary Faces,  Prev: Thread Folding,  Up: Summaries

12.4 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 'vm-enable-thread-operations' to a
non-'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 'vm-toggle-thread-operations' in a running VM session to
enable or disable thread operations.

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

     MuMTMNsMu

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.


File: vm.info,  Node: Summary Faces,  Prev: Thread Operations,  Up: Summaries

12.5 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 'vm-summary-highlight-face', which is set to the standard Emacs
'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.

   You can turn on more elaborate faces support, suitable for color
graphics terminals, by setting the variable 'vm-summary-enable-faces' to
t in your vm-init-file.  You can also run '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.  *Note (emacs)Faces::, 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.

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

     ( ((SELECTOR [ARG ...])    VM-SUMMARY-FACE)
       ... )

   The first element of each pair is a VM selector in the same format as
used for 'vm-virtual-folder-alist'.  *Note Virtual Folders::.  The
second element is a face name of the form 'vm-summary-FACE' where '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 'vm-summary-selected', 'vm-summary-collapsed' and
'vm-summary-expanded' are special.  They are added to the face specified
by '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.

   The variable '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 'highlight' face.

Hiding summary lines
....................

The command '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 'deleted' face type.  By invoking it with a prefix argument,
you can specify other face types that you might like to hide.  (Note
that 'deleted' face type does not necessarily mean deleted messages.
Whatever messages satisfy the condition associated with the
'vm-summary-deleted-face' in 'vm-summary-faces-alist' will be hidden.)

Predefined summary faces
........................

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


File: vm.info,  Node: Virtual Folders,  Next: IMAP Server Folders,  Prev: Summaries,  Up: Top

13 Virtual Folders
******************

A "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.

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

   A second way of using virtual folders is to define them through the
variable 'vm-virtual-folder-alist'.  You can visit such virtual folders
by typing 'V V' ('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 "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


File: vm.info,  Node: Search Folders,  Next: Defined Folders,  Prev: Virtual Folders,  Up: Virtual Folders

13.1 Search Folders
===================

The command 'vm-create-search-folder' (bound to '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
'V C header <RET> greeting', VM will create a folder containing only
those messages that contain the string 'greeting' in one of its headers.
*Note Virtual Selectors::, for virtual selectors you can use for this
purpose.  The variants 'vm-create-search-folder-other-frame' and
'vm-create-search-folder-other-window' provide similar functionality.

   The command 'vm-create-search-folder-of-threads' (bound to '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 'V T author <RET> Peter' then all threads
containing a message authored by 'Peter' will be included in the virtual
folder.

   The command 'vm-apply-virtual-folder' (bound to '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.

   The commands 'vm-create-virtual-folder-same-subject' (bound to 'V
S'), 'vm-create-virtual-folder-same-author' (bound to 'V A') and
'vm-create-virtual-folder-same-recipient' (bound to '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:

'V a (vm-create-author-virtual-folder)'
'V r (vm-create-author-or-recipient-virtual-folder)'
'V s (vm-create-subject-virtual-folder)'
'V t (vm-create-text-virtual-folder)'
'V d (vm-create-date-virtual-folder)'
'V l (vm-create-label-virtual-folder)'
'V ! (vm-create-flagged-virtual-folder)'
'V n (vm-create-new-virtual-folder)'
'V u (vm-create-unseen-virtual-folder)'

   When you run '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 'greeting' had a hotel offer and you wanted to
find it, you can first create a search folder of messages with subject
'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
'vm-goto-mesasge-last-seen'.  To inhibit changing the current message in
the original message entirely, quit the search folder using
'vm-quit-no-change'.)

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


File: vm.info,  Node: Defined Folders,  Next: Virtual Selectors,  Prev: Search Folders,  Up: Virtual Folders

13.2 Defined Virtual Folders
============================

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

   Each virtual folder definition should have the following form:

     (VIRTUAL-FOLDER-NAME
       ( (FOLDER ...)
         (SELECTOR [ARG ...]) ... )
       ... )

   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.

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

   The 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 SELECTORs require an
argument ARG; unless otherwise noted, ARG may be omitted.  When several
selectors are listed, messages matching any one of them are included.

   The 'text' selector provides a particularly effective way to search
for strings in messages.  It is better than the
'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.

     (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
        )
     )

   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.


File: vm.info,  Node: Virtual Selectors,  Next: Working with Virtual Folders,  Prev: Defined Folders,  Up: Virtual Folders

13.3 Virtual Selectors
======================

Generic selectors
-----------------

'any'
     matches any message.
'header'
     matches message if ARG matches any part of the header portion of
     the message; ARG should be a regular expression.
'text'
     matches message if ARG matches any part of the text portion of the
     message; ARG should be a regular expression.
'header-or-text'
     matches message if ARG matches any part of the headers or the text
     portion of the message; ARG should be a regular expression.
'header-field'
     matches messages if the header field named ARG1 has text matching
     ARG2.

Selectors based on message headers
----------------------------------

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

          (in-bbdb authors)
          (in-bbdb recipients t)
'subject'
     matches message if ARG matches any part of the message's subject;
     ARG should be a regular expression.
'sent-after'
     matches message if it was sent after the date ARG.  A fully
     specified date looks like this:
          ``31 Dec 1999 23:59:59 GMT''
     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.
'sent-before'
     matches message if it was sent before the date ARG.  A fully
     specified date looks like this:
          ``31 Dec 1999 23:59:59 GMT''
     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.
'older-than'
     matches message if it is more than ARG days old (today = 0)
'newer-than'
     matches message if it is at most ARG days old (today = 0)
'message-id'
     matches message if its Message ID has a string matching ARG
'uid'
     matches message if its IMAP UID is ARG (for IMAP folders)
'uidl'
     matches message if its POP UIDL is ARG (for POP folders)
'spam-score'
     matches message if its spam score is at least ARG.  See
     'vm-spam-score-headers' for configuration.

Selectors based on message attributes
-------------------------------------

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

Selectors based on analyzing the text
-------------------------------------

'attachment'
     matches if a message contains an attachment, i.e., its text matches
     'vm-vs-attachment-regexp'.
'less-chars-than'
     matches message if message has less than ARG characters.  ARG
     should be a number.
'less-lines-than'
     matches message if message has less than ARG lines.  ARG should be
     a number.
'more-chars-than'
     matches message if message has more than ARG characters.  ARG
     should be a number.
'more-lines-than'
     matches message if message has more than ARG lines.  ARG should be
     a number.

Complex selector operations
---------------------------

'sexp'
     matches message if the argument "s-expression" yields 't'.  For
     example, to find all the messages from 'Jenny' with attachments,
     you can type 'V C sexp <RET> (and (author "Jenny") attachment)
     <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 'sexp' selector in defining predefined
     virtual folders because those definitions can directly use
     "s-expressions".)

'eval'
     matches message if evaluating the Lisp expression ARG yields 't'.
     The Lisp expression can refer to the message by the name
     'vm-virtual-message'.  This is more flexible than the '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.

'and'
     matches the message if all its argument selectors match the
     message.  Example:
          (and (author "Derek McGinty") (new))
     matches all new messages from Derek McGinty.  'and' takes any
     number of arguments.

'not'
     matches message only if its selector argument does NOT match the
     message.  Example:
          (not (deleted))
     matches messages that are not deleted.

'or'
     matches the message if any of its argument selectors match the
     message.  Example:
          (or (author "Dave Weckl") (subject "drum"))
     matches messages from Dave Weckl or messages with the string "drum"
     in their Subject header.  'or' takes any number of arguments.

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

'thread-all'
     matches a message thread if all messages in the thread match the
     argument selector.  Example:
          (thread (less-chars-than 1000))
     matches threads if all their messages contain fewer than 1000
     characters.

Selectors based on context
--------------------------

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


File: vm.info,  Node: Working with Virtual Folders,  Next: vm-avirtual,  Prev: Virtual Selectors,  Up: Virtual Folders

13.4 Working with Virtual Folders
=================================

Once you've visited a virtual folder most VM commands work as they do in
a normal folder.  There are exceptions.  If you use 'S'
('vm-save-folder'), the folder save command will be invoked on each real
folder in turn.  Similarly if you use 'g' ('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:

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

   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 '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 'vm-virtual-mirror' to nil.  This
should be done in your VM init file and you should use 'setq-default',
as this variable is automatically local to all buffers.

     (setq-default vm-virtual-mirror nil)

If you want to change virtual mirror status of a particular virtual
folder, use the command 'vm-toggle-virtual-mirror' (bound to '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.


File: vm.info,  Node: vm-avirtual,  Prev: Working with Virtual Folders,  Up: Virtual Folders

13.5 vm-avirtual Package
========================

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

   The command 'M-x vm-virtual-omit-message' (bound to '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 'M-x
vm-virtual-update-folders' (bound to '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.

   The command 'M-x vm-virtual-check-selector-interactive' (bound to '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.

Automatic deletion
------------------

Automatic deletion of messages based on the virtual folder facility can
be achieved with the command 'vm-virtual-auto-delete-message' (bound to
'V D' in version 8).  First, set the variable
'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 'vm-virtual-auto-delete-message-selector'.  There is
no need to separately view the virtual folder before deleting such
messages.

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

Automatic saving
----------------

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

     ((VIRTUAL-FOLDER-NAME . FOLDER)
      ... )

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


File: vm.info,  Node: IMAP Server Folders,  Next: Frames and Windows,  Prev: Virtual Folders,  Up: Top

14 IMAP Server Folders
**********************

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

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

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

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

   When the IMAP server is connected again, you should run 'C-u M-x
vm-imap-synchronize', i.e., call it with a _prefix argument_.  This
causes _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, _all_ the messages that may
have been expunged in the cache folder are expunged on the server.

UIDVALIDITY
===========

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

   When the UIDVALIDITY changes on the 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 IMAP folder until the cache is refreshed.  You might
consider setting the 'vm-enable-external-messages' flag to '(imap)'
before you refresh the cache so that it will be quicker.  *note External
Messages::.

Operations for the IMAP server
==============================

The command 'vm-list-imap-folders' lists the folders available on the
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.

   Use the command 'vm-create-imap-folder' for creating a new folder on
the IMAP server and 'vm-delete-imap-folder' for deleting an existing
folder.  You can rename a folder using 'vm-rename-imap-folder'.


File: vm.info,  Node: Frames and Windows,  Next: Toolbar,  Prev: IMAP Server Folders,  Up: Top

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

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

   To use window configurations, the variable
'vm-mutable-window-configuration' must be set non-'nil'.  If
'vm-mutable-window-configuration' is set to 'nil', VM will only use the
selected window, and will not create, delete or resize windows.  (This
variable was called '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.


File: vm.info,  Node: Frame Configuration,  Next: Window Configuration,  Prev: Frames and Windows,  Up: Frames and Windows

15.1 Frame Configuration
========================

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

   If 'vm-frame-per-folder' is set non-'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.

   If 'vm-frame-per-summary' is set non-'nil', the '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 'vm-summarize' command.  When you quit the folder or
kill the summary, VM will delete the frame.

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

   The variable 'vm-frame-per-edit', if non-'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.

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

   If 'vm-frame-per-completion' is set non-'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 'vm-frame-per-completion''s value is
non-'nil', VM will create a new frame containing a list of responses
that you can select with the mouse.

   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 'vm-search-other-frames' to '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.

   The variable 'vm-frame-parameter-alist' allows you to specify the
frame parameters for newly created frames.

   The value of 'vm-frame-parameter-alist' should be of this form

     ((SYMBOL PARAMLIST) (SYMBOL2 PARAMLIST2) ...)

   SYMBOL must be one of "completion", "composition", "edit", "folder",
"primary-folder" or "summary".  It specifies the type of frame that the
following PARAMLIST applies to.

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


File: vm.info,  Node: Window Configuration,  Prev: Frame Configuration,  Up: Frames and Windows

15.2 Window Configuration
=========================

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 ('split-window', '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 'W S', which invokes the
'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:

         default
         startup
         quitting
         reading-message
         composing-message
         marking-message
         searching-message

   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 '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 'vm-save-window-configuration' window from that
window.  Remember that you can invoke the command with 'M-x' if VM's
normal key map is not in effect.

   To delete a window configuration, use 'W D' which is bound to
'vm-delete-window-configuration'.  You will be prompted for the name of
the configuration to delete.

   To see what an existing configuration looks like, type 'W W' which
invokes 'vm-apply-window-configuration'.

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


File: vm.info,  Node: Toolbar,  Next: Menus,  Prev: Frames and Windows,  Up: Top

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

   To make VM not display the toolbar, set 'vm-use-toolbar' to nil.  To
configure what buttons are displayed on the toolbar, you must change the
value of 'vm-use-toolbar'.  If non-'nil', the value of '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.

'autofile'
     The AutoFile button.  Clicking on this button runs the command
     'vm-toolbar-autofile-message'.  This command will save the current
     message into the folder matched by 'vm-auto-folder-alist', if there
     is a match.
'compose'
     The Compose button.  Clicking on this button runs the command
     'vm-toolbar-compose-command'.  This command is normally just an
     alias for the 'vm-mail' command.  If you want the Compose button to
     do something else, redefine 'vm-toolbar-compose-command' using
     either 'fset' or 'defun'.
'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.
'file'
     The File button.  Clicking on this button runs the command
     'vm-toolbar-file-command'.  This command is normally just an alias
     for the 'vm-mail' command.  If you want the File button to do
     something else, redefine 'vm-toolbar-file-command' using either
     'fset' or 'defun'.
'getmail'
     The Get Mail button.  Clicking on this button runs the command
     'vm-toolbar-getmail-command'.  This command is normally just an
     alias for the 'vm-get-new-mail' command.  If you want the Get Mail
     button to do something else, redefine 'vm-toolbar-getmail-command'
     using either 'fset' or 'defun'.
'help'
     The Helper button.  Clicking on this button runs the command
     'vm-toolbar-helper-command'.  This command normally just runs
     'vm-help', but it also does context specific things under certain
     conditions.  If the current message is a MIME message that needs
     decoding, the Helper button becomes the Decode 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 'vm-recover-folder',
     so you can recover your folder from an existing auto-save file.
'mime'
     The Decode MIME button.  Clicking on this button runs the command
     'vm-toolbar-mime-command'.  This command is normally just an alias
     for the 'vm-decode-mime-message' command.
'next'
     The Next button.  Clicking on this button runs the command
     'vm-toolbar-next-command'.  This command is normally just an alias
     for the 'vm-next-message' command.  If you want the Next button to
     do something else, redefine 'vm-toolbar-next-command' using either
     'fset' or 'defun'.
'previous'
     The Previous button.  Clicking on this button runs the command
     'vm-toolbar-previous-command'.  This command is normally just an
     alias for the 'vm-previous-message' command.  If you want the
     Previous button to do something else, redefine
     'vm-toolbar-previous-command' using either 'fset' or 'defun'.
'print'
     The Print button.  Clicking on this button runs the command
     'vm-toolbar-print-command'.  This command is normally just an alias
     for the 'vm-print-message' command.  If you want the Print button
     to do something else, redefine 'vm-toolbar-print-command' using
     either 'fset' or 'defun'.
'quit'
     The Quit button.  Clicking on this button runs the command
     'vm-toolbar-quit-command'.  This command is normally just an alias
     for the 'vm-quit' command.  If you want the Quit button to do
     something else, redefine 'vm-toolbar-quit-command' using either
     'fset' or 'defun'.
'reply'
     The Reply button.  Clicking on this button runs the command
     'vm-toolbar-reply-command'.  This command is normally just an alias
     for the 'vm-reply-include-text' command.  If you want the Reply
     button to do something else, redefine 'vm-toolbar-reply-command'
     using either 'fset' or 'defun'.
'visit'
     The Visit button.  Clicking on this button runs the command
     'vm-toolbar-visit-command'.  This command is normally just an alias
     for the 'vm-visit-folder' command.  If you want the Visit button to
     do something else, redefine 'vm-toolbar-visit-command' using either
     'fset' or 'defun'.
'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.

   If an positive integer appears in the '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.

   The variable 'vm-toolbar-orientation' controls on which side of the
frame the toolbar is displayed.  E.g.

     (setq vm-toolbar-orientation 'top)

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

   VM finds the images for the toolbar in the directory specified by
'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.


File: vm.info,  Node: Menus,  Next: Faces,  Prev: Toolbar,  Up: Top

17 Menus
********

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
'vm-popup-menu-on-mouse-3' to nil.

   If you set '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
'vm-use-menus' to '1', VM will add a single 'VM' menu to the existing
menu bar and provide various submenus under it for the VM operations.

   By default, '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 '[Emacs]' (on some systems, there will be a drop-down menu
labelled 'Emacs').  From the Emacs menu bar, you can return to the VM
menu bar by clicking on the menu labelled '[VM]' (or under the drop-down
menu labelled 'VM').

   On some graphics toolkits, menu bar cannot have "buttons" that invoke
immediate actions (such as '[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 '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:

'dispose'
     This is menu of commands that are commonly used to dispose of a
     message.  E.g.  reply, print, save, delete.
'emacs'
     This provides a menu button labelled '[Emacs]' that causes the menu
     bar to change to the global Emacs menu bar.  On that menu bar you
     will find a '[VM]' button that can return you to the VM menu bar.
'folder'
     This is a menu of folder related commands.  You can visit a folder,
     save a folder, quit a folder and so on.
'help'
     This is a menu of commands that provide information for you if you
     don't know what to do next.
'label'
     This is a menu of commands that let you add and remove message
     labels from messages.
'mark'
     This is a menu of commands that you can use to mark and unmark
     messages based on various criteria.  *Note Selecting Messages::.
'motion'
     This is a menu of commands to move around inside messages and
     inside folders.
'send'
     This is a menu of commands you use to compose and send messages.
'sort'
     This is a menu of commands to sort a folder by various criteria.
'undo'
     This provides a menu button that invokes the 'vm-undo' command.
'virtual'
     This is a menu of commands that let you visit and create virtual
     folders.
'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.


File: vm.info,  Node: Faces,  Next: Using the Mouse,  Prev: Menus,  Up: Top

18 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 '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.  *Note (emacs)Faces::.

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

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

   The face named by 'vm-mime-button-face' is used to display the
textual buttons that trigger the display of MIME objects.

   *Note Summary Faces::, for the faces support in the Summary buffer.


File: vm.info,  Node: Using the Mouse,  Next: Hooks,  Prev: Faces,  Up: Top

19 Using the Mouse
******************

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

button-1 (left button usually)
     Unchanged.
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 URL in the body of a message, that URL will be sent to
     the browser specified by 'vm-url-browser'.
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 URL, a menu of Web browsers
     is produced.  Otherwise the normal VM mode specific menu is
     produced.

   These button assignments work only in plain text messages.  For 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 'w3m-goto-article-function'.  You will need to set that
variable to the desired browser function to get button-2 to work in HTML
messages.

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

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


File: vm.info,  Node: Hooks,  Next: Configuration,  Prev: Using the Mouse,  Up: Top

20 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.)

'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).

'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).

'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).

'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 IMAP mailbox.

'vm-arrived-message-hook'
     List of hook functions called once for each message gathered from
     the system mail spool, or from another folder with
     'vm-get-new-mail', or from a digest with '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).

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

'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
     'vm-get-new-mail', or from a digest with '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.

'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 'vm-mail-mode-hook' before leaving you in the Mail mode
     buffer.

'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 'vm-mail-mode-hook' before leaving the user in the
     Mail mode buffer.

'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 'vm-mail-mode-hook' before leaving you in the
     Mail mode buffer.

'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 'vm-mail-mode-hook' before leaving you in the Mail mode
     buffer.

'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 'm-mail-mode-hook' before leaving you in the Mail mode
     buffer.

'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 'vm-mail-mode-hook' before leaving you in the
     Mail mode buffer.

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

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

'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 'vm' or 'vm-visit-folder' is called interactively.
     It is _not_ run after 'vm-mode' is called.

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

'vm-edit-message-hook'
     List of hook functions to be run just before a message is edited.
     This is the last thing 'vm-edit-message' does before leaving you in
     the edit buffer.

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

'vm-mode-hook'
     List of hook functions to run when a buffer enters 'vm-mode'.
     These hook functions should generally be used to set key bindings
     and local variables.

'vm-mode-hooks'
     Old name for 'vm-mode-hook'.  Supported for backward compatibility.
     You should use the new name.

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

'vm-summary-mode-hooks'
     Old name for 'vm-summary-mode-hook'.  Supported for backward
     compatibility.  You should use the new name.

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

'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.  MIME decoding.

'vm-quit-hook'
     List of hook functions to run when you quit VM. This applies to all
     VM quit commands, including '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
     'vm-expunge-before-quit'.

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

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

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

'vm-iconify-frame-hook'
     List of hook functions that are run whenever VM iconifies a frame.

'vm-menu-setup-hook'
     List of hook functions that are run just after all menus are
     initialized.

'vm-mime-display-function'
     If non-'nil', this should name a function to be called inside
     'vm-decode-mime-message' to do the 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 "presentation buffer"
     for the folder, which is a temporary buffer that VM uses for the
     display of MIME messages.  A copy of the current message will be in
     the presentation buffer at that time.  The normal work that
     'vm-decode-mime-message' would do is not done, because this
     function is expected to subsume all of it.

'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 'vm-confirm-mail-send') but before MIME encoding and FCC
     processing.

'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 'vm-yank-message' to see when VM will run
     these hooks.

'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.  'nil', a default action is
     taken instead of no action.


File: vm.info,  Node: Configuration,  Next: Preface to Add-ons,  Prev: Hooks,  Up: Top

20.1 Configuration of VM
========================

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.

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:

   * POP (Post office protocol)
   * IMAP (Internet message access protocol)

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 POP servers also provide the ability to retain the
email in the post office even after you downloaded it.

   IMAP was designed to receive and store your email essentially
permanently.  However, the 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:

   * You can store your email in local folders and download new mail
     from the mail servers.  *Note Local Folders::, especially the
     subsections on "POP Spool Files" and "IMAP Spool Files."  Even
     though the local folders method is provided for both POP and IMAP
     servers, it is really appropriate only for POP servers.
   * You can store your email on the mail server and process it in VM
     via cache folders stored on your file system.  *Note POP and IMAP
     Folders::.  Even though the method of server folders is provided
     for both POP and IMAP servers, it is really appropriate only for
     IMAP servers.

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 'pop-ssl'
or '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
'pop-ssl' and port 993 is used for 'imap-ssl'.)

   Secure channels are provided using a protocol called SSL (Secure
Sockets Layer).  A later version of the protocol is called TLS
(Transport Layer Security), which is backward compatible with SSL.

   Gnu Emacs version 24 has a built-in implementation of TLS (which also
includes SSL).  Prior versions of Gnu Emacs do not have it.  Other
versions of Emacs may or may not have any implementation of SSL or TLS.

   If the Emacs version does not have SSL/TLS support, you can use an
external 'stunnel' program to establish a secure "tunnel".  You can
download the 'stunnel' program from the 'stunnel.org' web site, and
install it somewhere on the 'exec-path'.  VM is preconigured to use the
'stunnel' program for talking to the mail servers that require SSL,
i.e., the value of the variable 'vm-stunnel-program' is set to
'stunnel'.  VM automatically generates a configuration file that the
'stunnel' program requires, starts the program, and communicates through
it to the mail server.  You can look at the generated configuration file
by running:

     M-: (find-file (vm-stunnel-configuration-file))

Depending on what is required by your mail server, you may need to
specify additional configuration options for 'stunnel'.  In that case,
you should create the required configuration file and set the variable
'vm-stunnel-program-additional-configuration-file' to its path name.

   If your Emacs version has a built-in implementation of TLS and you
wish to use it, you should set the variable 'vm-stunnel-program' to
'nil'.

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 'sendmail.el' (also
referred to '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 SMTP (Simple mail transfer protocol).  A separate Emacs
library 'smtpmail.el' has been written to intervene in the operation of
'sendmail.el' and hand the mail to the remote SMTP server instead.
*Note Emacs SMTP Library: (smtpmail)top.  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 SMTP that
are run by servers.  The so-called "Mail Transfer Agents" use port 25
for plain connections and port 465 for secure SSL connections.  Mail
Submission Agents use port 587 for both secure and insecure
communication.  These complexities, coupled with the limited
functionality of 'smtpmail.el' library, have made the life difficult to
many users.

   The 'smtpmail.el' library included with Gnu Emacs version 24 has
SSL/TLS functionality.  Follow these guidelines for configuring the
uptodate 'smtpmail' library depending on the type of the SMTP server.

   * The SMTP server does not use a secure protocol.

     In this case, the server expects connections on port 25.  You
     should set the variable 'smtpmail-stream-type' to 'nil' and
     'smtpmail-smtp-service' to 25.

   * The SMTP server supports SSL.

     In this case, you should set the variable 'smtpmail-stream-type' to
     'ssl' to use it with the mail server.  The port number to use
     (usually 465) is specified in the variable 'smtpmail-smtp-service'.

   * The SMTP server is a Mail Submission Agent.

     This is the more complicated case.  The SMTP server expects a "mail
     submission" connection on port 587, and it may require a STARTTLS
     protocol to engage in secure communication.  This means that your
     mail program first communicates insecurely, the server informs it
     that it requires the 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 TLS protocol, Emacs
     is able to use an external GnuTLS library, which can execute a
     STARTTLS protocol.  However, you must obtain and install the binary
     executables of the GnuTLS library on your system in order to obtain
     this functionality.  Having done this, you should set the variable
     'smtpmail-stream-type' to 'starttls' to request Emacs to use the
     'STARTTLS' protocol.  Emacs 24 tries both an external GnuTLS
     library and its own internal 'starttls.el' library, to achieve the
     'STARTTLS' negotiation.

     If you set 'smtpmail-stream-type' to 'nil' (which is also the
     default value), then Emacs tries a plain text communication
     initially and upgrades it to TLS if the server requires STARTTLS.

   Prior to Gnu Emacs 24, Emacs did not have built-in support for SSL or
TLS protocols.  However, a contributed Emacs package called
'starttls.el' was available to make use of an external GnuTLS library
which was not integrated with Emacs.  The 'smtpmail.el' library did not
have the 'smtpmail-stream-type' setting.  The default behaviour depended
on the '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 STARTTLS negotiation.


File: vm.info,  Node: Preface to Add-ons,  Next: Customizations,  Prev: Configuration,  Up: Top

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:

   * 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.
   * Add-ons.  More elaborate features.
   * Packages.  Full-blown packages that add new functionality or
     interface to other packages in your environment.


File: vm.info,  Node: Customizations,  Next: History and Administration,  Prev: Preface to Add-ons,  Up: Top

21 Customizations
*****************

Useful ways to customize VM.

21.1 Reading messages
=====================

Shrunken headers
----------------

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
"shrunken headers" feature, included in 'vm-rfaddons', addresses this
problem.  To use the feature, you must add 'shrunken-headers' to the
variable 'vm-enable-addons' in your VM init file:

     (setq vm-enable-addons (cons 'shrunken-headers vm-enable-addons))

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 '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.)

MIME alternatives
.................

The default setting of VM for handling MIME alternatives is
'best-internal', which means the best alternative that can be displayed
internally in VM is chosen.  Many users have environments where only
'text/plain' parts can be displayed internally.  However, some messages
come with 'text/html' parts that are expected to be more faithful to the
sender's composition.  On occasion, you might wish to see the
'text/html' part even if it has to be viewed externally.

   The function 'vm-toggle-best-mime' function, included in
'vm-rfaddons', allows you to change VM's selection method to 'best'
temporarily so that you can view the 'text/html' part.  You can use the
same function to change the method back to 'best-internal'.

   (Thanks to Alley Stoughton for this contribution.)

21.2 Saving messages and attachments
====================================

Auto saving attachments
-----------------------

Messages with attachments get bulky and increase the size of VM folders,
slowing down VM. The functions 'vm-save-all-attachments' and
'vm-save-attachments' provide ways to save attachments of messages on
the file system and deleting them from the mail folders.

   The function 'vm-mime-auto-save-all-attachments', included in
'vm-rfaddons', provides enhanced functionality for saving attachments.
It saves the attachments in a sub-directory of
'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
'vm-mime-auto-save-all-attachments-subdir'.

   You can save the attachments of all new messages automatically by
putting 'vm-mime-auto-save-all-attachments' in
'vm-select-new-message-hook'.

   (This add-on was provided by Robert Fenk.)


File: vm.info,  Node: History and Administration,  Next: Highlights,  Prev: Customizations,  Up: Top

22 History and Administration
*****************************

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.

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

   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 '8.0.x'
series.

   All these releases are available from the new project page of VM
hosted by Savannah, at the URL
<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."

   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 '8.1.0' and up.

   In 2024, the project code development was moved to GitLab
<https://gitlab.com/emacs-vm/vm/> by a small team of new developers.

Savannah project site
=====================

The changes made in each of the releases is described in the 'NEWS'
file, which can be found in the source code repository.  The changes
made in versions up to 7.19 are described in the 'CHANGES' file.

   The 'Download' link on the Savannah project page, takes you to the
downloads area where all the recent releases are available.  Under the
'Source Code' menu, the 'Browse Sources Repository' takes you to the
source files, which include, among others, the 'NEWS' and '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 'Source Code' menu.  The '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 'Bazaar' ('bzr').

Technical support
=================

VM has a dedicated usenet newsgroup 'gnu.emacs.vm.info' and a gmane
newsgroup '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
<http://groups.google.com/group/gnu.emacs.vm.info/topics>.  The
discussions can also be accessed by email via a mailing list
<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
'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:
<https://gitlab.com/emacs-vm/vm/-/issues>.

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.

Contributors
------------

Contributions to the code from the following members of the VM community
are gratefully acknowledged:

   * Aidan Kehoe
   * Glenn <unknown last name>
   * Jens Gustedt
   * John J Foerch
   * Kevin Rogers
   * Rob Hodges
   * Robert Marshall
   * Robert P. Goldman
   * Katsumi Yamaoka
   * Julian Bradfield
   * Samuel Bronson
   * Brent Goodrick
   * Tim Cross
   * Arik Mitschang
   * Anthony Mallet
   * Noah Friedman
   * JJK "Blueman"
   * Eric Schulte

   Please let us know if any contributors have been missed out.

Selected Releases of Kyle Jones
-------------------------------

   * Version 4.10, released in 1989.
   * Version 5.00, released in 1990.
   * Version 6.00, released 6 January, 1997.
   * Version 7.00, released 2 December, 2001.
   * Version 7.10, released 5 March, 2003.
   * Version 7.15, released 3 May, 2003.
   * Version 7.16, released 26 May, 2003.
   * Version 7.17, released 6 July, 2003.
   * Version 7.18, released 2 November, 2003.
   * Version 7.19, released 29 September, 2004.

Releases of Robert Widhopf-Fenk
-------------------------------

   * Version 8.0.0, released 31 May, 2007.
   * Version 8.0.1, released 29 June, 2007.
   * Version 8.0.2, released 25 July, 2007.
   * Version 8.0.3, released 15 August, 2007.
   * Version 8.0.4, released 2 November, 2007.
   * Version 8.0.5, released 3 November, 2007.
   * Version 8.0.6, released 2 January, 2008.
   * Version 8.0.7, released 5 January, 2008.
   * Version 8.0.8, released 11 February, 2008.
   * Version 8.0.9, released 20 February, 2008.
   * Version 8.0.10, released 22 June, 2008.
   * Version 8.0.11, released 11 August, 2008.
   * Version 8.0.12, released 5 November, 2008.
   * Version 8.0.13, released 29 November, 2009.
   * Version 8.0.14, released 16 December, 2009.

Releases of VM development team
-------------------------------

   * Version 8.1.0, released 21 March, 2010.
   * Version 8.1.1, released 25 April, 2010.
   * Version 8.1.2, released 5 March, 2012.
   * Version 8.2.0, planned for release in March, 2013.
   * Version 8.3.0, released 22 December 2025
   * Version 8.3.1, released 27 December 2025
   * Version 8.3.2, released 29 December 2025
   * Version 8.3.3snapshot, from git


File: vm.info,  Node: Highlights,  Next: Future Plans,  Prev: History and Administration,  Up: Top

23 Highlights
*************

Here are some of the VM features that its users find most valuable:

   * VM's reliability and stability.
   * Integration within Emacs, providing ease of editing and familiar
     key bindings.
   * Speed of usage facilitated by keyboard commands.
   * Integration with BBDB for maintaining contacts and email addresses.
   * VM-Pcrisis for managing multiple mail identities.
   * Integration with emacs-w3m for viewing HTML email.
   * Comprehensive MIME support.
   * Ability to operate on all attachments of a message, such as saving
     or deleting.
   * Interactive virtual folders (created by 'V C').
   * Support for IMAP folders.
   * Ability to delete duplicate copies of messages.


File: vm.info,  Node: Future Plans,  Next: Bugs,  Prev: Highlights,  Up: Top

24 Future Plans
***************

Some of the ideas being worked on for future extensions of VM are the
following:

   * Ability to compose rich text email messages (in 'text/enriched' and
     'text/html' modes).
   * Incremental search in virtual folders.
   * Downloading IMAP messages without attachments.
   * Support for maildir folders.
   * A message migration/expiration facility.


File: vm.info,  Node: Bugs,  Next: Internals,  Prev: Future Plans,  Up: Top

25 Reporting Bugs
*****************

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.  *Note
(emacs)Bugs::.

   The command '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.

   For mail server-associated problems dealing with POP/IMAP spool files
or POP/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
'vm-pop-start-bug-report'/'vm-imap-start-bug-report' before the problem
occurrence and 'vm-pop-submit-bug-report' /'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.


File: vm.info,  Node: Internals,  Next: Concept Index,  Prev: Bugs,  Up: Top

26 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
* MIME Display::          How VM displays MIME messages
* MIME Composition::	  How 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


File: vm.info,  Node: Folder Internals,  Next: Message Internals,  Up: Internals

26.1 Folder Internals
=====================

VM stores mail folders in the Unix 'mbox' format (in all its variants).
Internal to Emacs, the mbox is loaded into a text buffer (the "Folder"
buffer) and individual messages are identified by remembering markers
into the text buffer.  *Note Message Internals::.

   The Unix "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.

   Three variants of the 'mbox' format are recognized by VM, called
'From_', 'BellFrom_' and 'From_with-Content-Length'.  In a 'From_' type
mbox, every message has a leading and trailing separator line, as
indicated above.  In a '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 'From_with-Content-Length' type mbox, the
'From' separator line stores the length of the message.  So, no trailing
separator line is required.

   In addition to these mbox formats, VM also handles the MMDF format
and the Emacs Rmail's Babyl format.  The variable 'vm-folder-type'
stores the type of the folder being used.

   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.

   * 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.
   * X-VM-Last-Modified.  The date and time at which the folder was last
     modified.
   * X-VM-Message-Order.  This header lists the order in which the
     messages should be listed.
   * X-VM-Labels.  This header lists the message labels that have been
     used in the folder.
   * X-VM-VHeader.  This header lists the values of 'vm-visible-headers'
     and '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.
   * X-VM-Summary-Format.  This header stores the format string for the
     summary lines.
   * X-VM-POP-Retrieved.  This header lists all the messages that have
     been retrieved from POP servers together with the identifying
     information for the POP servers.  VM refrains from retrieving these
     messages again in future in order to avoid duplication.
   * X-VM-IMAP-Retrieved.  This header lists messages that have been
     retrieved from IMAP servers together with their identifying
     information on the IMAP servers (UID and 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 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 IMAP folders.)

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.

   * 'vm-message-list'.  A list of message data structures for all the
     messages in the buffer.
   * '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.
   * '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.
   * '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 IMAP
     server.
   * '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.
   * 'vm-virtual-folder-definition'.  If the current folder is virtual,
     then this variable holds the data constituting its definition.
   * '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.
   * 'vm-virtual-buffers'.  A list of all the virtual folder buffers
     that the current buffer is involved in.
   * '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..
   * '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.)
   * 'vm-presentation-buffer-handle'.  The message Presentation buffer
     of the folder.  (Same proviso applies as for 'vm-summary-buffer'.)
   * 'vm-presentation-buffer'.  This seems to be a copy of the
     'vm-presentation-buffer-handle'.  Its purpose is unknown.

   The running state of the folder buffer is represented in a number of
buffer-local variables:

   * '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.
   * 'vm-last-message-pointer'.  Whenever the cursor is moved, the
     previous value of vm-message-pointer is remembered in this
     variable.
   * 'vm-summary-pointer'.  The message struct of the message which has
     the summary pointer in the Summary buffer.
   * 'vm-fetched-messages'.  List of external messages whose bodies were
     fetched for viewing or other operations.
   * 'vm-fetched-message-count'.  The number of messages in
     'vm-fetched-messages'.  An attempt is made to keep this below the
     'vm-external-fetched-message-limit'.
   * 'vm-mime-decoded'.  The MIME decoding state of the current message
     display: 'nil' if the message is shown in undecoded plain text
     form, 'decoded' if the message is shown decoded, and 'buttons' if
     the message is shown as a series of buttons for all its MIME
     components.  The 'D' command cycles through these states.
   * 'vm-system-state'.  The state of VM in a Folder buffer or
     Presentation buffer:

        * 'previewing'.  if a message is being previewed.
        * 'showing'.  if a full message is being shown.
        * 'reading'.  if message reading is in progress.

     A message edit buffer is in state 'editing'.

     A message composition buffer may be in one of these states:

        * 'forwarding'.  if a message is being forwarded.
        * 'replying'.  if a message is being replied to.
        * 'redistributing'.  if a message is being redistributed.

   * '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.
   * '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.
   * 'vm-undo-record-pointer'.  A pointer into the 'vm-undo-record-list'
     indicating the current position of the undoing cycle.
   * 'vm-label-obarray'.  An obarray storing all the labels that are
     registered to be used in the current folder.
     '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.  '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.

vm-folder-access-data
.....................

The variable 'vm-folder-access-data' is a vector storing data about the
state of the mail server (for POP and IMAP servers).  It contains the
following items:

   * 'pop-maildrop-spec' or 'imap-maildrop-spec'.  MAILDROP
     specification of the server folder.
   * 'pop-process' or '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.)
   * 'imap-uid-validity'.  The UIDVALIDITY value of the IMAP folder.
   * 'imap-read-write'.  A boolean flag indicating whether the folder is
     writable.
   * 'imap-can-delete'.  A boolean flag indicating whether the folder
     allows deletions.
   * 'imap-body-peek'.  A boolean flag indicating whether the folder
     allows the 'BODYPEEK' command of IMAP.
   * 'imap-permanent-flags'.  The list of permanent flags that have been
     stored in the folder.
   * 'imap-mailbox-count'.  The number of messages in the folder.
   * 'imap-recent-count'.  The number of messages in the folder that are
     considered "recent" by the server.
   * 'imap-retrieved-count'.  The number of messages present in the
     folder when messages were last retrieved.  This would have been the
     value of 'imap-mailbox-count' at that time.
   * '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
     'imap-flags-obarray' below.
   * 'imap-uid-obarray'.  An obarray that binds all the UID's of
     messages in the folder to their message sequence numbers.
   * '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
     'imap-uid-list' field.  So, any updates will be shared through both
     the views.  The two obarrays, 'imap-uid-obarray' and
     'imap-flags-obarray', bind exactly the same set of UID's.  Jointly,
     they are referred to as 'uid-and-flags-data'.  The reason for their
     separation is historical.


File: vm.info,  Node: Message Internals,  Next: Summary Internals,  Prev: Folder Internals,  Up: Internals

26.2 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 *Note RFC compliance: Message Internals.

   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:

   * 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.
   * Soft data (1).  This vector contains other calculated data about
     the message that is specific to a VM session.
   * Attributes (2).  All the hard-wired message attributes are stored
     in this vector.
   * Cached Data (3).  Calculated data that is cached for each message.
   * Mirror Data (4).  Extra data shared by virtual messages if
     vm-virtual-mirror is non-nil.

   The attributes vector and cached data vector are stored in the folder
on disk as the 'X-VM-v5-Data' header of the first message.

Location data
.............

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

   * 'start' (0).  Marker for the starting position of the message, at
     which a leading separator line begins.
   * 'headers' (1).  Marker for the position in the buffer where the
     headers of the message start.
   * '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.)
   * 'text' (3).  Marker for the position in the buffer where the text
     of the message starts.
   * 'text-end' (4).  Marker for the position in the buffer where the
     text of the message ends.
   * 'end' (5).  Marker for the position in the buffer where the message
     ends.

   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.

Soft data
.........

This vector contains other calculated data about the message that is
specific to a VM session.

   * 'number' (0).  The message number as an integer.
   * 'padded-number' (1).  The message number as a padded string.
   * 'mark' (2).  Flag that indicates if the message has been marked
     (via 'vm-mark-message').
   * 'su-start' (3).  The position in the Summary buffer where the
     summary line of the message starts.
   * 'su-end' (4).  The position in the Summary buffer where the summary
     line of the message ends.
   * '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.
   * 'mirrored-message-sym' (21).  This is similar to the
     '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".
   * 'reverse-link-sym' (6).  Reference to the previous message in the
     message list, also represented by an uninterned symbol written as
     "<-".
   * 'message-type' (7).  A symbol indicating the type of the message
     according to its folder type, one of 'BellFrom_', 'From_' and
     'From_-with-Content-Length'.
   * 'message-id-number' (8).  A number that uniquely identifies the
     message within a VM session.
   * 'buffer' (9).  The Folder buffer of the message.  (Messages in
     Presentation buffers also have this field set to the corresponding
     Folder buffer.)
   * 'thread-indentation' (10).  Indentation level of the message in its
     message thread.
   * 'thread-indentation-offset' (22).  Indentation added by the user
     for the message, which is used in addition to the
     'thread-indentation'.  This is not "cached" data and should not be
     discarded.
   * 'thread-list' (11).  List of symbols from 'vm-thread-obarray' that
     give this message's lineage.
   * 'thread-subtree' (20).  List of messages that form the subtree
     under this message in a threaded summary display.
   * 'babyl-frob-flag' (12).
   * 'saved-virtual-attributes' (13).  Saved attributes if the message
     switched from unmirrored to mirrored.
   * 'saved-virtual-mirror-data' (14).  Saved mirror data, if the
     message was switched from unmirrored to mirrored.
   * 'virtual-summary' (15).  Summary for unmirrored virtual message.
   * 'mime-layout' (16).  MIME layout information; types, ids,
     positions, etc of all MIME entities.  (See below.)
   * 'mime-encoded-header-flag' (17).  Flag that indicates if the
     headers of the message are MIME encoded.
   * 'su-summary-mouse-track-overlay' (18).  The overlay on the summary
     of this message used for selection by mouse.
   * 'message-access-method' (19).  The access-method to be used for the
     message, inherited from its real folder.

Attributes
..........

All the hard-wired message attributes are stored in this vector.  They
also get saved as part of the 'X-VM-v5-Data' header field when the
folder is saved to disk.

   * 'new-flag' (0).  Flag to indicate if the message is "new".
   * 'unread-flag' (1).  Flag to indicate if the message is unread.
   * 'deleted-flag' (2).  Flag to indicate if the message has been
     deleted.
   * 'filed-flag' (3).  Flag to indicate if the message has been filed.
   * 'replied-flag' (4).  Flag to indicate if the message has been
     replied to.
   * 'written-flag' (5).  Flag to indicate if the message has been
     saved.
   * 'forwarded-flag' (6).  Flag to indicate if the message has been
     forwarded.
   * 'edited-flag' (7).  Flag to indicate if the message has been
     edited.
   * 'redistributed-flag' (8).  Flag to indicate if the message has been
     redistributed.
   * 'flagged-flag' (9).  Flag to indicate if the message has been
     "flagged" as important.
   * 'folded-flag' (10).  Flag to indicate whether the summary of the
     subthread rooted at this message has been "folded", i.e., hidden
     from view.
   * 'watched-flag' (11).  Flag that says that the user wants to "watch"
     this thread.  There are no functions that use this at present.
   * 'ignored-flag' (12).  Flag that says that the user wants to ignore
     this thread.  There are no functions that use this at present.
   * '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.
   * '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.
   * 'attachments-flag' (15).  Flag that says that this message has
     attachments.  There are no functions that use this at present.
   * '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.

Cached Data
...........

The vector is meant for data that is cached for each message and stored
on the disk as part of the '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 MIME-encoded words in them.  The strings stored in the
cached-data vector, however, are MIME-decoded versions of the header
fields.  So, when they are written to disk, they should be re-encoded
because only 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.

   * 'byte-count' (0).  The size of the message in bytes.
   * 'weekday', 'monthday', 'month', 'year', 'hour', 'zone' (1-6).  Data
     indicating the date of the message.
   * 'decoded-full-name' (7).  The full name of the author of the
     message.  This is a MIME-decoded string with text properties.
   * 'decoded-from' (8).  The email address of the author of the
     message.  This is a MIME-decoded string with text properties.
   * 'message-id' (9).  The unique id of the message.
   * 'line-count' (10).  The number of lines in the message.
   * 'decoded-subject' (11).  The subject string of the message.  This
     is a MIME-decoded string with text properties.
   * '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.
   * '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 MIME-decoded string with text properties.
   * '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 MIME-decoded string with text properties.
   * 'month-number' (15).  Numeric month of the sent date.
   * '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
     'vm-sort-messages-by-delivery-date').
   * '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
     MIME-decoded string with text properties.
   * '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 'number' and
     'thread-indent', as well as MIME-decoded strings with text
     properties.
   * 'parent' (19).  The message ID of the parent of the message in its
     thread.
   * 'references' (20).  Message IDs listed in the References header of
     the message.
   * 'body-to-be-retrieved' (22).  Flag that indicates whether the body
     of the message has not been retrieved from the mail server.
   * '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 'body-to-be-retrieved'
     above.)
   * 'pop-uidl' (23).  The UIDL id of the message on the POP server.
   * 'imap-uid' (23).  The UID of the message on the IMAP server.
   * 'imap-uid-validity' (24).  The UIDVALIDITY value of the message on
     the IMAP server.
   * 'spam-score' (25).  The spam score of the message.
   * '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.
   * '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.
   * '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.)
   * '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.
   * '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.
   * 'd-weekday', 'd-monthday', 'd-month', 'd-year', 'd-hour', 'd-zone'
     (31-36).  Data indicating the delivery date of the message.  These
     fields are not used at present.
   * 'decoded-reply-to-name', 'decoded-reply-to' (37-38).  The full name
     and the email address in the 'Reply-To' header of the message
     (called the "principal" of the message.)
   * 'decoded-to-cc-name', 'decoded-to-cc' (39-40).  The full names and
     the email addresses in the 'To' and 'Cc' headers of the message
     (called the "recipients" of the message.)

Mirror Data
...........

Extra data shared by virtual messages if vm-virtual-mirror is non-nil.

   * 'edit-buffer' (0).  If the message is being edited, this is the
     buffer being used.
   * 'virtual-messages-sym' (1).  List of virtual messages mirroring the
     current real message, represented by an uninterned symbol written
     as "<v>".
   * 'stuff-flag' (2).  Flag to indicates if the attribute changes have
     been "stuffed" into the folder buffer.
   * 'labels' (3).  List of labels attached to the message.
   * 'label-string' (4).  The string of labels attached to the message.
   * 'attribute-modflag' (5).  Flag to indicate if the attributes of the
     message have been modified since the last save.

MIME layout
-----------

The 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 MIME parts and
subparts as well.

   * 'type' (0).  A list of strings consisting of the 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
     '("multipart/mixed"
     "boundary=----_=_NextPart_001_01AFE588.63E23840")'.
   * 'qtype' (1).  Like type, but the quotation marks are not stripped.
   * 'encoding' (2).  The MIME encoding used for the part.  It comes
     from the "Content-Transfer-Encoding" header.
   * 'id' (3).  The id obtained from the "Content-ID" header of the
     part.
   * 'description' (4).  A description string obtained from the
     "Content-Description" header of the part.
   * '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 '(``attachment'',
     ``filename=mydocument.doc'')'.)
   * 'qdisposition' (6).  Like disposition, but the quotation marks are
     not stripped.
   * 'header-start' (7), 'header-end' (8), 'body-start' (9) and
     'body-end' (10).  Markers into the content buffer delineating the
     headers/body of the MIME part.
   * 'parts' (11).  A list of MIME layouts for the individual subparts
     of this part.
   * 'cache' (12).  A symbol that is unique to this MIME part.  Other
     data is stored as properties of this symbol:
        * 'vm-mime-display-external-generic'.  This property stores the
          id of the process used to externally display the MIME part as
          well as the name of the temporary file used.
        * 'vm-mime-display-internal-image-xxxx'.  This property stores
          the name of the temporary file where the image is stored.
        * 'vm-image-modified'.  This property stores a boolean flag
          indicating that the image has been modified.
        * 'vm-mime-display-internal-audio/basic'.  This property stores
          the name of the temporary file where the audio clip is stored.
        * '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.)
   * 'message-symbol' (13).  A reference to the message that contains
     the 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.
   * 'display-error' (14).  If the display of a MIME part fails, its
     error string is stored here.
   * 'layout-is-converted' (15).  Flag indicating that MIME type
     conversion has been performed on this part.  *note MIME type
     conversion::.
   * 'unconverted-layout' (16).  If the MIME type conversion has been
     performed on this part, then this holds the original unconverted
     layout.

Cross-buffer sharing of data
----------------------------

Every Folder buffer has a 'vm-message-list' and a 'vm-message-pointer'
list containing message data vectors.

   Every Presentation buffer also uses a '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 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
'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.)

26.2.1 RFC compliance
---------------------

The format of the mail messages is as described in RFC 822.
   * RFC 822.  Standard for the format of ARPA Internet text messages.
     August 1982.
   * RFC 2822.  Internet Message Format (proposed).  April 2001.
   * RFC 5322.  Internet Message Format (standard).  October 2008.
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.
   * RFC 2045.  Format of Internet Message Bodies.  November 1996.
   * RFC 2046.  Media Types.  November 1996.
   * RFC 2047.  Message Header Extensions for NON-ASCII Text.  November
     1996.
   * RFC 2048.  Registration Procedures.  November 1996.
   * RFC 2049.  Conformance Criteria and Examples.  November 1996.
The following updates that have been made to the original MIME standards
have not been implemented in VM.
   * RFC 2231.  MIME Parameter Value and Encoded Word Extensions.
     November 1997.
   * RFC 5335.  Internationalized Email Headers (Experimental).
     September 2008.
   * RFC 6532.  Internationalized Email Headers (Proposed).  February
     2012.


File: vm.info,  Node: Summary Internals,  Next: Threading Internals,  Prev: Message Internals,  Up: Internals

26.3 Summary Internals
======================

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
'vm-summary-line-format'.  The information that needs to go into the
summary lines is divided into two classes:

   * Information that is fixed for each message.  Examples include the
     subject, author and other header information.
   * Information that is variable during a VM session.  Examples include
     the message number and thread indentation.

   A _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:

   * 'number'.  Stands for the message number in the linear order of the
     summary.
   * 'mark'.  Stands for an indicator of message mark (whether the
     message is marked at present).
   * 'thread-indent'.  Stands for the indentation to be used for the
     message's summary depending on its position in the message thread.
   * 'group-begin', 'group-end'.  Brackets used to denote groups of
     items that might have particular formatting constraints.

   The function '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:

   * 'vm-summary-pointer'.  The message selected by the cursor in the
     Summary window.
   * 'vm-summary-redo-start-point'.  A pointer into the
     '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.
   * '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 'vm-mark-for-summary-update'.
   * 'vm-numbering-redo-start-point'.  A pointer into 'vm-message-list'
     indicating the first message whose message number needs to be
     recalculated.  'vm-numbering-redo-end-point'.  A pointer into
     'vm-message-list' indicating the last message whose message number
     needs to be recalculated.

   The beginning and the ending positions of each message summary line
are stored in the message's soft data vector.  *note Message
Internals::.  The positions within the summary line have text-properties
set, which give the data about the message:

   * 'vm-message'.  The message struct for which this line is a summary.


File: vm.info,  Node: Threading Internals,  Next: Sorting Internals,  Prev: Summary Internals,  Up: Internals

26.4 Threading Internals
========================

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.

   In addition, VM also allows threads to be built using the subject
headers via the option '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 'vm-thread-obarray' and
'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 'vm-thread-obarray' and the
following information is stored for each message ID:

   * 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.
   * 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 'nil'.
   * date: The date of the message.
   * 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 'nil'
   * 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.)
   * youngest-date: The date of the youngest message in the thread,
     among all the messages present in the folder.
   * oldest-date: The date of the oldest message in the thread, among
     the messages present in the folder.
   * oldest-subject: The subject of the oldest message in the thread,
     among the messages present in the folder.

   The 'vm-thread-subject-obarray' interns each subject string found in
the folder and maps it to a vector containing the following elements:

   * 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.
   * date: The date of the root message.
   * 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 'id-sym' is not
     included as a member.
   * messages: The list of all the messages in the folder that have this
     subject.

   Building threads involves calculating all the data stored with the
'vm-thread-obarray' and 'vm-thread-subject-obarray'.  These two
collections of data are calculated in sequence, because the subject
threads are based on the reference threads.

   After the threads are built, the 'thread-list', 'thread-indentation'
and the 'thread-subtree' fields of the Soft data vector are calculated
as needed on demand and cached.  (*Note 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
'thread-subtree' field is erased for all the ancestors of the
assimilated message.  The 'thread-list' and 'thread-indentation' fields
are erased for all the descendants of the assimilated message.

   Before messages in the folder are expunged, they are unthreaded.
This involves removing them from their respective thread trees.  It also
involves the erasure of the 'thread-subtree' field of all their
ancestors and the 'thread-list' and 'thread-indentation' fields of the
descendants.

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.


File: vm.info,  Node: Sorting Internals,  Next: IMAP Server Interaction,  Prev: Threading Internals,  Up: Internals

26.5 Sorting Internals
======================

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 'vm-key-functions' is
bound to a list of comparison functions before calling the Emacs sort
function.

   The function 'vm-sort-compare-xxxxxx' uses the functions listed in
'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.

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


File: vm.info,  Node: IMAP Server Interaction,  Next: User Interaction,  Prev: Sorting Internals,  Up: Internals

26.6 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
'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.


File: vm.info,  Node: User Interaction,  Next: Coding Systems,  Prev: IMAP Server Interaction,  Up: Internals

26.7 User Interaction
=====================

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

   VM stores the identity of the Folder buffer in a buffer-local
variable 'vm-mail-buffer' in each of the other types of buffers.
Conversely, each Folder buffer uses buffer-local variables
'vm-summary-buffer' and 'vm-presentation-buffer' to store the identity
of the other buffers.

   Whenever a VM command is invoked by the user, VM calls a function
called '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
'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 'vm-display' etc.]

Menus
-----

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 'undefined' (at least in
Gnu Emacs).

   VM computes its standard menu bar and stores it internally:

   * In Gnu Emacs, this is stored in the keymap 'vm-mode-menu-map'.
   * In XEmacs ...

The menu bar also has a menu, or a menu item, to switch back to the
standard Emacs menu bar.  The computed menu bar is then installed
depending on the setting of 'vm-use-menus'.  If the user selects the
action to revert to the standard Emacs menu bar, the installation is
easily reverted.

   * In Gnu Emacs, the installation involves inserting a key binding for
     'menu-bar'.
   * In XEmacs, ...

When the user picks a menu item to revert to the Emacs menu bar, the
function '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.


File: vm.info,  Node: Coding Systems,  Next: Message Display,  Prev: User Interaction,  Up: Internals

26.8 Coding Systems
===================

A Coding System is a way of encoding characters as bit patterns.  *note
Coding System Basics: (elisp)Coding System Basics.  US-ASCII is a coding
system for English.  Other coding systems are used to encode the various
languages of the world, e.g., 'iso-latin-1' (also called 'iso-8859-1' or
simply 'latin-1') for Western European languages, and 'hebrew-iso-8bit'
(also called '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.

   MIME messages specify the "character set" that their content is in,
in the '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 'mime-charset' for each implemented coding
system inside Emacs.  For example, the 'mime-charset' property of
'iso-latin-1' is 'iso-8859-1', that of 'hebrew-iso-8bit' is
'iso-8859-8'.  The Emacs function 'coding-system-get' can be used to
extract the 'mime-charset' property of an Emacs coding system.  VM
stores all the known coding systems and the corresponding MIME charsets
in its internal variables 'vm-mime-mule-coding-to-charset-alist' and
'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 'decode-coding-region'.
Conversely, VM encodes the outgoing messages into the default or chosen
MIME character set using the function 'encode-coding-region'.

   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
'=?charset?B?'.  They can apply to individual words or sequences of
words appearing the in the headers.  Note that the annotation '?B?'
signifies a base-64 encoding of the byte stream.  Similarly the
annotation '?Q?' is be used to denote the quoted-printable encoding.  VM
decodes such strings using the function 'decode-coding-string'.
Conversely, the headers of outgoing messages are encoded using
'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
'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.


File: vm.info,  Node: Message Display,  Next: MIME Display,  Prev: Coding Systems,  Up: Internals

26.9 Message Display
====================

VM displays messages in a "Presentation buffer" separate from the Folder
buffer.  This is done in two stages: Preview and Show.

   The previewing is done by a function called
'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 MIME decoding that may be
necessary.  And, then, depending on the value of 'vm-preview-lines', it
narrows the buffer to show a selected portion of the message.

   The full message display is done by 'vm-show-current-message'.  It
does nothing more than removing the narrowing done by
'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.


File: vm.info,  Node: MIME Display,  Next: MIME Composition,  Prev: Message Display,  Up: Internals

26.10 MIME Display
==================

The MIME layout of a message is stored in the 'mime-layout' field of the
Soft data vector of the message.  (*Note MIME layout::.)  The MIME
layout is in general a tree structure of "MIME parts".  The function
'vm-decode-mime-layout' is responsible for traversing the tree structure
at each MIME part and displaying it appropriately.

   The function 'vm-decode-mime-layout' goes through the following
sequence of decisions:

  1. If the MIME part is a 'multipart' type, then the subparts are
     displayed as needed.  If it is a single part, it proceeds as
     follows.
  2. If the MIME part should not be displayed automatically, it is
     displayed as a button.  (An automatically displayed MIME type is
     one listed in 'vm-mime-auto-displayed-content-types' but not listed
     in the corresponding exceptions.)
  3. If the MIME part should be displayed internally and VM is able to
     do so, then it is displayed internally.  (An internally displayed
     MIME type is one listed in 'vm-mime-internal-content-types' but not
     listed in the corresponding exceptions.)
  4. Otherwise, the MIME part is displayed externally.  An external
     viewer is found from 'vm-mime-external-content-types-alist' and it
     is invoked to display the MIME part.

   MIME parts of type '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 '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.

   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:

   * 'vm-button'.  Always 't'.
   * 'vm-mime-layout'.  Gives the layout of the MIME part.
   * 'vm-mime-function'.  The function that carries out the action
     represented by pressing the button.
   * 'vm-mime-disposable'.  Set to true if the button should be removed
     when it is replaced by the MIME object.
   * 'face'.  Set to the value of 'vm-mime-button-face'.
   * 'local-map' (FSF Emacs) or 'keymap' (XEmacs).  Set to a keymap that
     includes 'vm-mime-reader-map', binding the '$' keys.


File: vm.info,  Node: MIME Composition,  Next: Virtual Folder Internals,  Prev: MIME Display,  Up: Internals

26.11 MIME Composition
======================

A MIME message is composed just like a normal message.  When objects are
attached using commands like 'vm-attach-file', attachment buttons are
created in the message composition buffer.  An attachment button is a
region of text that looks like:

     [Attachment mary.jpeg, image/jpeg]

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 text properties that
represent the metadata about the object.  In XEmacs, the region of text
is given an 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:

   * 'vm-mime-object'.  The object denoting the MIME attachment.  It is
     either

        * a string denoting a file name,
        * a buffer containing the file to be attached,
        * a list of the form (buffer, start, end, filename) indicating a
          region in a buffer, typically the Folder buffer, or
        * 't' indicating that the attachment is another MIME object in a
          VM folder.

     In the last case, the 'vm-mime-layout' property describes the rest
     of the metadata.
   * 'vm-mime-type'.  A string denoting the MIME type of the object.
     (Note that it is a single string, unlike the 'type' component of a
     MIME layout.)
   * 'vm-mime-parameters'.  A list of strings denoting the parameters of
     the MIME type.
   * 'vm-mime-description'.  A string for the MIME description of the
     object.
   * 'vm-mime-disposition'.  A list describing the MIME disposition.
   * 'vm-mime-encoded'.  A boolean indicating whether the object has
     MIME headers.
   * 'vm-mime-encoding'.  The MIME encoding used, if it is already
     encoded.
   * 'vm-mime-forward-local-refs'.  Whether or not references to local
     external-body objects should be forwarded as is.
   * 'fontified'.  Standard text property.
   * 'duplicable'.  Set to 't' in XEmacs allowing the extent to be
     preserved under killing and yanking.
   * 'front-nonsticky' and 'rear-nonsticky'.  Standard stickiness of
     text properties in GNU Emacs.

   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 MIME encoding, in a function
called 'vm-mime-fake-attachment-overlays'.  This allows the next stage
to treat both FSF Emacs and XEmacs using the same logic.

   The function 'vm-mime-encode-composition' then encodes the
composition buffer, by selecting each attachment button and replacing it
with the corresponding object.  The bodies of 'external-body' objects
are also retrieved at this stage.  Unless the objects were already
MIME-encoded, they are MIME-encoded and made into MIME parts by adding
suitable headers.  The message itself is given MIME headers describing
its content and then handed to Emacs message-sending functions.

Yanking or Forwarding MIME Messages
-----------------------------------

When another message is yanked or "included" in a message composition,
the handling of attachments depends on the variable
'vm-include-mime-attachments'.  If the variable is 'nil', then the
attachments are displayed as token buttons in plain text that appear
similar to:

     [DELETED ATTACHMENT mary.jpg, image/jpeg]

The function 'vm-decode-mime-layout' is employed to generate the yanked
text along with such token buttons.

   If 'vm-include-mime-attachments' is 't', then first the
'vm-decode-mime-layout' function is employed to generate proper MIME
buttons for all the attachments.  In a second step, the MIME buttons are
replaced by attachment buttons using a function called
'vm-mime-convert-to-attachment-buttons'.  These attachment buttons are
then handled as described above.


File: vm.info,  Node: Virtual Folder Internals,  Next: Extents and Overlays,  Prev: MIME Composition,  Up: Internals

26.12 Virtual Folder Internals
==============================

A virtual folder is characterized by its definition, which is stored in
the buffer-local variable 'virtual-folder-definition'.  The form of the
definition is as given in 'vm-virtual-folder-alist'.  *Note
vm-virtual-folder-alist: Defined Folders.  It is a collection of
clauses, with each clause listing a collection of folders and a
collection of virtual selectors.

   Each virtual selector X has a corresponding Lisp function 'vm-vs-X',
whose purpose is to check whether a given message matches the selector.
The arguments for 'vm-vs-X' are a message data structure 'm' and all the
arguments for the virtual selector X.

   For example, the virtual selector 'author' has a string argument,
representing the author name.  The corresponding Lisp function is
defined as:

     (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))))

The definition checks to see if the given 'author-name' pattern occurs
in the full name of the author ('vm-su-full-name') or the email address
of the author ('vm-su-from').

   The 'author' selector is then registered in four places:

   * The variable 'vm-virtual-selector-function-alist', which contains
     pairs of the form '(SELECTOR . FUNCTION)'.  For the 'author'
     selector, the pair is '(author . vm-vs-author)'.

   * The selector symbol 'author' is given a property
     'vm-virtual-selector-arg-type' indicating the type of argument it
     requires:

          (put 'author 'vm-virtual-selector-arg-type 'string)

   * The variable 'vm-supported-interactive-virtual-selectors', which
     contains lists of strings, each string being the name of a virtual
     selector.  For the 'author' selector, the list is '("author")'.
     Including the selector in this variable allows it to be used in
     creating interactive virtual folders (search folders).

   * The selector symbol 'author' is given a property
     'vm-virtual-selector-clause' indicating the prompt string for
     interactive use:

          (put 'author 'vm-virtual-selector-clause "with author matching")

Evidently, the last two registrations are only needed for interactive
selectors that can be used with the 'V C' command.


File: vm.info,  Node: Extents and Overlays,  Next: Timers and Concurrency,  Prev: Virtual Folder Internals,  Up: Internals

26.13 Extents and 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:

     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.

   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 '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 '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:

  1. 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.
  2. Presentation buffers use extents/overlays for MIME buttons.  These
     are implemented uniformly.
  3. 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.


File: vm.info,  Node: Timers and Concurrency,  Prev: Extents and Overlays,  Up: Internals

26.14 Timers and Concurrency
============================

VM has been designed as mainly a sequential program.  However, there are
three timer tasks that get scheduled to occur at regular intervals:

'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 '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.
'vm-get-mail-itimer-function'
     Moves any new mail from maildrops into the folder buffers.  This is
     controlled by the variable 'vm-auto-get-new-mail'.

     This timer task switches to the folder buffers and appends text at
     the end.  It would extend the '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.
'vm-check-mail-itimer-function'
     Checks the maildrops for any new mail.  This is controlled by the
     variable '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.

These timer tasks are scheduled using the 'itimer' package in XEmacs and
the 'timer' package in Gnu Emacs.

   The basic synchronization mechanism is a global variable
'vm-global-block-new-mail'.  If set, it prohibits the
'vm-get-mail-itimer-function' and 'vm-check-mail-itimer-function' from
running.  All invocations of 'get-new-mail' and 'check-for-new-mail'
functions set this variable during their activity.


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

Concept Index
*************

[index]
* Menu:

* .vm:                                   Starting Up.         (line   6)
* .vm.preferences:                       Starting Up.         (line  15)
* .vm.windows:                           Window Configuration.
                                                              (line  52)
* address book:                          Preface.             (line  24)
* AIX:                                   Folder types.        (line  42)
* archiving:                             Preface.             (line  24)
* attachment button:                     Replying.            (line  87)
* attachments:                           Viewing MIME.        (line  65)
* attachments <1>:                       Attachments.         (line  10)
* auth-source library:                   POP and IMAP Folders.
                                                              (line 125)
* authinfo:                              POP and IMAP Folders.
                                                              (line 125)
* auto-save:                             Crash Recovery.      (line   6)
* auto-save <1>:                         Message Attributes.  (line  70)
* Babyl:                                 Local Folders.       (line   6)
* Babyl <1>:                             Folder types.        (line  49)
* Babyl format:                          Folder Internals.    (line  32)
* BBDB:                                  Preface.             (line  24)
* BBDB <1>:                              Virtual Selectors.   (line   9)
* BBDB <2>:                              Virtual Selectors.   (line  41)
* BBDB <3>:                              Highlights.          (line   8)
* BellFrom_:                             Folder types.        (line  29)
* BellFrom_ folder type:                 Folder Internals.    (line  23)
* browse-url:                            Using the Mouse.     (line  39)
* bug reports:                           Bugs.                (line   6)
* cache folders:                         POP and IMAP Folders.
                                                              (line  19)
* cached data:                           Message Internals.   (line 171)
* character sets:                        Character sets.      (line  12)
* compacting:                            Introduction.        (line  47)
* compacting <1>:                        Introduction.        (line  67)
* compacting, IMAP servers:              IMAP Spool Files.    (line  36)
* compacting, POP servers:               POP Spool Files.     (line  35)
* configuration settings:                Starting Up.         (line   6)
* Content-Disposition:                   Viewing MIME.        (line  65)
* Content-Disposition <1>:               MIME attachments.    (line  22)
* Content-Length:                        Folder types.        (line  42)
* CP1252:                                Character sets.      (line  12)
* CRAM-MD5:                              POP and IMAP Folders.
                                                              (line 102)
* crash box:                             Local Folders.       (line  36)
* crash recovery:                        Crash Recovery.      (line   6)
* defined virtual folders:               Virtual Folders.     (line  21)
* delivery date:                         Sorting Messages.    (line  30)
* drag and drop:                         Sending Messages.    (line  36)
* drag and drop <1>:                     MIME attachments.    (line  57)
* EasyPG:                                POP and IMAP Folders.
                                                              (line 125)
* Emacs:                                 Preface.             (line   6)
* Emacs-w3m:                             Internal display.    (line  28)
* Emacs-w3m <1>:                         HTML display.        (line   6)
* Emacs-w3m <2>:                         multipart/related.   (line   6)
* Emacs-w3m <3>:                         Using the Mouse.     (line  28)
* encryption:                            Preface.             (line  24)
* epa-file library:                      POP and IMAP Folders.
                                                              (line 125)
* expunging:                             Introduction.        (line  47)
* expunging <1>:                         Introduction.        (line  67)
* expunging, IMAP messages:              IMAP Spool Files.    (line  36)
* expunging, POP servers:                POP Spool Files.     (line  35)
* faces:                                 Summary Faces.       (line   6)
* FCC:                                   Saving copies.       (line   6)
* file CC:                               Saving copies.       (line   6)
* file locking:                          Local Folders.       (line  16)
* file locking <1>:                      Saving Messages.     (line   6)
* filling paragraphs:                    Paging.              (line  37)
* folder types:                          Folder types.        (line   6)
* From_:                                 Folder types.        (line  21)
* From_ folder type:                     Folder Internals.    (line  23)
* From_-with-Content-Length:             Folder types.        (line  42)
* From_with-Content-Length folder type:  Folder Internals.    (line  23)
* GB2312:                                Character sets.      (line  12)
* GitLab:                                History and Administration.
                                                              (line  40)
* Gnu Emacs:                             Preface.             (line   6)
* Gnus:                                  Preface.             (line   6)
* GPG:                                   Preface.             (line  24)
* graphics toolkit:                      Menus.               (line  26)
* header: In-Reply-To:                   Threading.           (line  16)
* header: References:                    Threading.           (line  16)
* header: Subject:                       Threading.           (line  16)
* headers, shrunken:                     Customizations.      (line  14)
* hiding summary lines:                  Summary Faces.       (line  51)
* HTML:                                  Internal display.    (line  25)
* HTML <1>:                              Using the Mouse.     (line  28)
* HTML <2>:                              Highlights.          (line   8)
* iconv:                                 Character sets.      (line  68)
* ImageMagick:                           Displaying images.   (line  27)
* images:                                Displaying images.   (line   6)
* IMAP:                                  Preface.             (line  33)
* IMAP <1>:                              IMAP Folders.        (line   6)
* IMAP <2>:                              Saving Messages.     (line  34)
* IMAP <3>:                              Highlights.          (line   8)
* IMAP spool files:                      IMAP Spool Files.    (line   6)
* IMAP-FCC:                              Saving copies.       (line  14)
* index file:                            Index Files.         (line   6)
* interactive virtual folders:           Virtual Folders.     (line  13)
* ISO-2022-JP:                           Character sets.      (line  39)
* ISO-8859-1:                            Character sets.      (line  12)
* Kyle Jones:                            History and Administration.
                                                              (line   6)
* longlines.el:                          Paging.              (line  37)
* lynx:                                  Internal display.    (line  28)
* mail servers:                          Preface.             (line  33)
* maildir:                               Preface.             (line  43)
* maildrop specification:                POP Spool Files.     (line   6)
* maildrop specification <1>:            IMAP Spool Files.    (line   6)
* maildrop specification <2>:            POP and IMAP Folders.
                                                              (line   6)
* marking:                               Marking Messages.    (line   6)
* mbox:                                  Preface.             (line  33)
* mbox <1>:                              Local Folders.       (line   6)
* mbox <2>:                              Folder Internals.    (line   6)
* menu bar:                              Menus.               (line   6)
* menus, pop-up:                         Menus.               (line   6)
* message attributes:                    POP Folders.         (line   6)
* message attributes <1>:                IMAP Folders.        (line   6)
* message attributes <2>:                Crash Recovery.      (line   6)
* message attributes <3>:                Message Attributes.  (line   6)
* message labels:                        IMAP Folders.        (line   6)
* message labels <1>:                    Crash Recovery.      (line   6)
* message labels <2>:                    Message Attributes.  (line  52)
* MIME:                                  Preface.             (line  24)
* MIME <1>:                              MIME Messages.       (line   6)
* MIME <2>:                              Highlights.          (line   8)
* MIME alternative, best:                multipart/alternative.
                                                              (line  18)
* MIME alternative, best <1>:            Customizations.      (line  41)
* MIME alternative, best-internal:       multipart/alternative.
                                                              (line  18)
* MIME alternative, best-internal <1>:   Customizations.      (line  41)
* MIME alternative, favorite:            multipart/alternative.
                                                              (line  29)
* MIME alternative, favorite-internal:   multipart/alternative.
                                                              (line  29)
* MIME alternatives:                     multipart/alternative.
                                                              (line   6)
* MIME alternatives <1>:                 Replying.            (line 104)
* MIME alternatives <2>:                 Customizations.      (line  33)
* MIME button:                           Viewing MIME.        (line  21)
* MMDF:                                  Folder types.        (line  49)
* MMDF format:                           Folder Internals.    (line  32)
* multipart types:                       Internal display.    (line  17)
* multipart/alternative:                 multipart/alternative.
                                                              (line   6)
* multipart/mixed:                       multipart/related.   (line   6)
* multipart/related:                     HTML display.        (line  18)
* multipart/related <1>:                 multipart/related.   (line   6)
* newsgroups:                            Preface.             (line  43)
* Org mode:                              Preface.             (line  24)
* passwords, storing:                    POP and IMAP Folders.
                                                              (line 125)
* Personality Crisis:                    Personality Crisis.  (line   6)
* point-to-point attachment operations:  MIME attachments.    (line  49)
* POP:                                   Preface.             (line  33)
* POP <1>:                               POP Folders.         (line   6)
* POP spool files:                       POP Spool Files.     (line   6)
* port, TCP:                             POP and IMAP Folders.
                                                              (line  78)
* postponing message composition:        Postponing Messages. (line   6)
* predefined summary faces:              Summary Faces.       (line  62)
* preferences settings:                  Starting Up.         (line  15)
* prefix argument:                       Navigating.          (line  17)
* prefix argument <1>:                   Selecting Messages.  (line  13)
* primary inbox:                         Introduction.        (line 125)
* primary inbox <1>:                     Starting Up.         (line  30)
* primary inbox <2>:                     POP and IMAP Folders.
                                                              (line   6)
* read-only folders:                     Starting Up.         (line  50)
* resending messages:                    Forwarding Messages. (line  93)
* Resent-To header:                      Forwarding Messages. (line  93)
* Rmail:                                 Preface.             (line   6)
* Rmail <1>:                             Local Folders.       (line   6)
* Rmail <2>:                             Folder types.        (line  49)
* Robert Widhopf-Fenk:                   History and Administration.
                                                              (line  20)
* RSS feeds:                             Preface.             (line  43)
* S/MIME:                                Preface.             (line  43)
* Savannah:                              History and Administration.
                                                              (line  28)
* save folders:                          Saving Messages.     (line  75)
* search folders:                        Virtual Folders.     (line  13)
* searching:                             Navigating.          (line  58)
* searching <1>:                         Marking Messages.    (line   6)
* searching <2>:                         Virtual Folders.     (line   6)
* searching <3>:                         Search Folders.      (line  45)
* searching <4>:                         Defined Folders.     (line  34)
* Solaris:                               Folder types.        (line  42)
* sorting:                               Sorting Messages.    (line   6)
* spam:                                  Sorting Messages.    (line  19)
* spam <1>:                              Sorting Messages.    (line  93)
* spool file:                            Introduction.        (line 125)
* spool file <1>:                        Local Folders.       (line  16)
* SSH:                                   POP and IMAP Folders.
                                                              (line  64)
* SSL:                                   POP and IMAP Folders.
                                                              (line  45)
* stunnel:                               POP and IMAP Folders.
                                                              (line  51)
* stunnel <1>:                           POP and IMAP Folders.
                                                              (line 153)
* subject tags:                          Sorting Messages.    (line  62)
* summary faces:                         Summary Faces.       (line   6)
* System V:                              Folder types.        (line  42)
* System V <1>:                          Folder Internals.    (line  23)
* threading:                             Threading.           (line   6)
* Thunderbird:                           Preface.             (line  33)
* Thunderbird <1>:                       Thunderbird Folders. (line   6)
* TLS:                                   POP and IMAP Folders.
                                                              (line  45)
* Uday S Reddy:                          History and Administration.
                                                              (line  34)
* UIDVALIDITY:                           IMAP Server Folders. (line  40)
* Ulrich Mï¿½ller:                       History and Administration.
                                                              (line  34)
* undo:                                  Message Attributes.  (line  43)
* Unix:                                  Folder types.        (line  21)
* URL:                                   Faces.               (line  20)
* URL <1>:                               Using the Mouse.     (line  10)
* US-ASCII:                              Character sets.      (line  12)
* UTF-8:                                 Character sets.      (line  39)
* virtual folders:                       Preface.             (line  24)
* virtual folders <1>:                   Marking Messages.    (line   6)
* virtual folders <2>:                   Virtual Folders.     (line   6)
* virtual folders <3>:                   Highlights.          (line   8)
* visual line mode:                      Paging.              (line  37)
* vm-avirtual:                           vm-avirtual.         (line   6)
* vm-create-imap-folder:                 IMAP Server Folders. (line  69)
* vm-delete-imap-folder:                 IMAP Server Folders. (line  69)
* vm-list-imap-folders:                  IMAP Server Folders. (line  64)
* vm-postpone:                           Postponing Messages. (line   6)
* vm-rename-imap-folder:                 IMAP Server Folders. (line  69)
* vm-summary-faces-hide:                 Summary Faces.       (line  51)
* vmpc:                                  Personality Crisis.  (line   6)
* w3:                                    Internal display.    (line  28)
* w3m:                                   Internal display.    (line  28)
* web browser:                           Using the Mouse.     (line  39)
* Windows-1252:                          Character sets.      (line  12)
* Wonderworks:                           History and Administration.
                                                              (line  10)
* word wrapping:                         Paging.              (line  37)
* X-VM-IMAP-Retrieved header:            IMAP Spool Files.    (line 101)
* XEmacs:                                Preface.             (line   6)


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

Key Index
*********

[index]
* Menu:

* !:                                     Paging.              (line  30)
* .:                                     Paging.              (line  23)
* [:                                     Attachments.         (line   6)
* ]:                                     Attachments.         (line   6)
* @:                                     Forwarding Messages. (line  74)
* ###:                                   Introduction.        (line  47)
* ### <1>:                               Deleting Messages.   (line  31)
* <:                                     Threaded Summaries.  (line  36)
* >:                                     Threaded Summaries.  (line  43)
* ||:                                    Saving Messages.     (line 137)
* |d:                                    Saving Messages.     (line 151)
* |n:                                    Saving Messages.     (line 161)
* |s:                                    Saving Messages.     (line 154)
* $ |:                                   Attachments.         (line  10)
* $ a:                                   MIME attachments.    (line  60)
* $ d:                                   Attachments.         (line  10)
* $ d <1>:                               Attachments.         (line  10)
* $ e:                                   Attachments.         (line  10)
* $ p:                                   Attachments.         (line  10)
* $ RET:                                 Attachments.         (line  10)
* $ s:                                   Attachments.         (line  10)
* $ w:                                   Attachments.         (line  10)
* A:                                     Saving Messages.     (line 128)
* B:                                     Forwarding Messages. (line  93)
* C:                                     Thread Folding.      (line  42)
* C-_:                                   Message Attributes.  (line  43)
* C-c C-]:                               Editing Messages.    (line  11)
* C-c C-a:                               Sending Messages.    (line  36)
* C-c C-a <1>:                           MIME attachments.    (line   6)
* C-c C-b:                               Sending Messages.    (line  66)
* C-c C-b <1>:                           MIME attachments.    (line  33)
* C-c C-c:                               Sending Messages.    (line  70)
* C-c C-c <1>:                           MIME preview.        (line  13)
* C-c C-d:                               Postponing Messages. (line   9)
* C-c C-e:                               Sending Messages.    (line  70)
* C-c C-e <1>:                           MIME preview.        (line  13)
* C-c C-e <2>:                           Editing Messages.    (line   6)
* C-c C-m:                               Sending Messages.    (line  59)
* C-c C-m <1>:                           MIME attachments.    (line  37)
* C-c C-p:                               Sending Messages.    (line  77)
* C-c C-p <1>:                           MIME preview.        (line   6)
* C-c C-v:                               Sending Messages.    (line  34)
* C-c C-y:                               Sending Messages.    (line  16)
* C-c ESC:                               Editing Messages.    (line  11)
* C-x u:                                 Message Attributes.  (line  43)
* d:                                     Introduction.        (line  47)
* D:                                     Viewing MIME.        (line  12)
* d <1>:                                 Deleting Messages.   (line  10)
* DEL:                                   Introduction.        (line  28)
* DEL <1>:                               Paging.              (line   6)
* E:                                     Thread Folding.      (line  42)
* f:                                     Replying.            (line  32)
* F:                                     Replying.            (line  34)
* g:                                     Introduction.        (line 113)
* g <1>:                                 Getting New Mail.    (line   6)
* G:                                     Sorting Messages.    (line   6)
* h:                                     Introduction.        (line  58)
* h <1>:                                 Summaries.           (line   6)
* k:                                     Deleting Messages.   (line  19)
* K:                                     Deleting Messages.   (line  22)
* l a:                                   Message Attributes.  (line  52)
* l d:                                   Message Attributes.  (line  52)
* m:                                     Sending Messages.    (line  84)
* M A:                                   Marking Messages.    (line  46)
* M a:                                   Marking Messages.    (line  48)
* M C:                                   Marking Messages.    (line  28)
* M c:                                   Marking Messages.    (line  30)
* M M:                                   Marking Messages.    (line  14)
* M m:                                   Marking Messages.    (line  23)
* M R:                                   Marking Messages.    (line  56)
* M r:                                   Marking Messages.    (line  57)
* M S:                                   Marking Messages.    (line  42)
* M s:                                   Marking Messages.    (line  44)
* M T:                                   Marking Messages.    (line  37)
* M t:                                   Marking Messages.    (line  40)
* M U:                                   Marking Messages.    (line  20)
* M u:                                   Marking Messages.    (line  23)
* M X:                                   Marking Messages.    (line  32)
* M x:                                   Marking Messages.    (line  35)
* M-n:                                   Navigating.          (line  68)
* M-p:                                   Navigating.          (line  68)
* M-s:                                   Navigating.          (line  71)
* n:                                     Introduction.        (line  39)
* n <1>:                                 Navigating.          (line   6)
* N:                                     Navigating.          (line  64)
* o:                                     External Messages.   (line  44)
* O:                                     External Messages.   (line  44)
* p:                                     Navigating.          (line   6)
* P:                                     Navigating.          (line  64)
* q:                                     Introduction.        (line  87)
* r:                                     Replying.            (line  28)
* R:                                     Replying.            (line  29)
* RET:                                   Navigating.          (line  60)
* s:                                     Introduction.        (line  43)
* S:                                     Introduction.        (line  67)
* s <1>:                                 Saving Messages.     (line  14)
* SPC:                                   Introduction.        (line  28)
* SPC <1>:                               Paging.              (line   6)
* t:                                     Previewing.          (line  59)
* T:                                     Thread Folding.      (line  11)
* TAB:                                   Navigating.          (line  62)
* u:                                     Introduction.        (line  47)
* U:                                     Paging.              (line  23)
* u <1>:                                 Deleting Messages.   (line  14)
* v:                                     Starting Up.         (line  45)
* V !:                                   Search Folders.      (line  35)
* V A:                                   Search Folders.      (line  28)
* V a:                                   Search Folders.      (line  35)
* V C:                                   Search Folders.      (line   6)
* V d:                                   Search Folders.      (line  35)
* V l:                                   Search Folders.      (line  35)
* V M:                                   Working with Virtual Folders.
                                                              (line  38)
* V n:                                   Search Folders.      (line  35)
* V O:                                   vm-avirtual.         (line  10)
* V r:                                   Search Folders.      (line  35)
* V S:                                   Search Folders.      (line  28)
* V s:                                   Search Folders.      (line  35)
* V T:                                   Search Folders.      (line  15)
* V t:                                   Search Folders.      (line  35)
* V u:                                   Search Folders.      (line  35)
* V U:                                   vm-avirtual.         (line  10)
* V V:                                   Virtual Folders.     (line  21)
* V V <1>:                               Defined Folders.     (line   6)
* V X:                                   Search Folders.      (line  23)
* W D:                                   Window Configuration.
                                                              (line  45)
* W S:                                   Window Configuration.
                                                              (line   6)
* W W:                                   Window Configuration.
                                                              (line  49)
* x:                                     Introduction.        (line  87)
* z:                                     Forwarding Messages. (line  13)
* Z:                                     Forwarding Messages. (line  27)


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

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

[index]
* Menu:

* browse-url:                            Using the Mouse.     (line  39)
* recover-file:                          Crash Recovery.      (line  38)
* revert-file:                           Crash Recovery.      (line 121)
* vm:                                    Starting Up.         (line  30)
* vm-add-message-labels:                 Message Attributes.  (line  52)
* vm-apply-virtual-folder:               Search Folders.      (line  23)
* vm-apply-window-configuration:         Window Configuration.
                                                              (line  49)
* vm-attach-buffer:                      MIME attachments.    (line  33)
* vm-attach-file:                        MIME attachments.    (line   6)
* vm-attach-message:                     MIME attachments.    (line  37)
* vm-attach-message-to-composition:      MIME attachments.    (line  60)
* vm-auto-archive-messages:              Saving Messages.     (line 128)
* vm-burst-digest:                       Digests.             (line  13)
* vm-change-folder-type:                 Folder types.        (line  16)
* vm-collapse-all-threads:               Thread Folding.      (line  11)
* vm-collapse-all-threads <1>:           Thread Folding.      (line  42)
* vm-collapse-thread:                    Thread Folding.      (line  11)
* vm-compact-folder:                     Introduction.        (line  47)
* vm-compact-folder <1>:                 Deleting Messages.   (line  31)
* vm-continue-postponed-message:         Postponing Messages. (line  17)
* vm-create-author-or-recipient-virtual-folder: Search Folders.
                                                              (line  35)
* vm-create-author-virtual-folder:       Search Folders.      (line  35)
* vm-create-date-virtual-folder:         Search Folders.      (line  35)
* vm-create-flagged-virtual-folder:      Search Folders.      (line  35)
* vm-create-label-virtual-folder:        Search Folders.      (line  35)
* vm-create-new-virtual-folder:          Search Folders.      (line  35)
* vm-create-search-folder:               Search Folders.      (line   6)
* vm-create-search-folder-of-threads:    Search Folders.      (line  15)
* vm-create-search-folder-other-frame:   Search Folders.      (line   6)
* vm-create-search-folder-other-window:  Search Folders.      (line   6)
* vm-create-subject-virtual-folder:      Search Folders.      (line  35)
* vm-create-text-virtual-folder:         Search Folders.      (line  35)
* vm-create-unseen-virtual-folder:       Search Folders.      (line  35)
* vm-create-virtual-folder:              Search Folders.      (line   6)
* vm-create-virtual-folder-of-threads:   Search Folders.      (line  15)
* vm-create-virtual-folder-same-author:  Search Folders.      (line  28)
* vm-create-virtual-folder-same-recipient: Search Folders.    (line  28)
* vm-create-virtual-folder-same-subject: Search Folders.      (line  28)
* vm-delete-all-attachments:             Attachments.         (line  51)
* vm-delete-duplicate-messages:          Deleting Messages.   (line  25)
* vm-delete-duplicate-messages <1>:      Deleting Messages.   (line  61)
* vm-delete-duplicate-messages-by-body:  Deleting Messages.   (line  28)
* vm-delete-message:                     Introduction.        (line  47)
* vm-delete-message <1>:                 Deleting Messages.   (line  10)
* vm-delete-message-labels:              Message Attributes.  (line  52)
* vm-delete-mime-object:                 Attachments.         (line  10)
* vm-delete-mime-object <1>:             Attachments.         (line  10)
* vm-delete-window-configuration:        Window Configuration.
                                                              (line  45)
* vm-demote-subthread:                   Threaded Summaries.  (line  43)
* vm-dired-attach-file:                  MIME attachments.    (line  52)
* vm-dired-do-attach-files:              MIME attachments.    (line  52)
* vm-dnd-attach-file:                    MIME attachments.    (line  57)
* vm-edit-message:                       Editing Messages.    (line   6)
* vm-edit-message-abort:                 Editing Messages.    (line  11)
* vm-edit-message-end:                   Editing Messages.    (line  11)
* vm-expand-all-threads:                 Thread Folding.      (line  11)
* vm-expand-all-threads <1>:             Thread Folding.      (line  42)
* vm-expand-thread:                      Thread Folding.      (line  11)
* vm-expose-hidden-headers:              Previewing.          (line  59)
* vm-expunge-folder:                     Introduction.        (line  47)
* vm-expunge-folder <1>:                 Deleting Messages.   (line  31)
* vm-expunge-imap-messages:              IMAP Spool Files.    (line  36)
* vm-expunge-label:                      Message Attributes.  (line  64)
* vm-expunge-pop-messages:               POP Spool Files.     (line  35)
* vm-fill-long-lines-in-reply:           Replying.            (line 129)
* vm-fix-my-summary:                     Summary Format.      (line 177)
* vm-followup:                           Replying.            (line  32)
* vm-followup-include-text:              Replying.            (line  34)
* vm-forward-message:                    Forwarding Messages. (line  13)
* vm-forward-message-all-headers:        Forwarding Messages. (line  63)
* vm-forward-message-plain:              Forwarding Messages. (line  27)
* vm-get-new-mail:                       Introduction.        (line 113)
* vm-get-new-mail <1>:                   POP Spool Files.     (line  26)
* vm-get-new-mail <2>:                   IMAP Spool Files.    (line  27)
* vm-get-new-mail <3>:                   Getting New Mail.    (line   6)
* vm-get-new-mail <4>:                   Working with Virtual Folders.
                                                              (line   6)
* vm-get-new-mail <5>:                   Hooks.               (line  53)
* vm-goto-message:                       Navigating.          (line  60)
* vm-goto-message-last-seen:             Navigating.          (line  62)
* vm-headers-summary:                    Introduction.        (line  58)
* vm-headers-summary <1>:                Summaries.           (line   6)
* vm-imap-save-composition:              Saving copies.       (line   6)
* vm-imap-start-bug-report:              Bugs.                (line  17)
* vm-imap-submit-bug-report:             Bugs.                (line  17)
* vm-imap-synchronize:                   IMAP Folders.        (line  89)
* vm-imap-synchronize <1>:               IMAP Server Folders. (line  11)
* vm-isearch-backward:                   Navigating.          (line  71)
* vm-isearch-backward <1>:               Defined Folders.     (line  34)
* vm-isearch-forward:                    Navigating.          (line  71)
* vm-isearch-forward <1>:                Defined Folders.     (line  34)
* vm-kill-subject:                       Deleting Messages.   (line  19)
* vm-kill-thread-subtree:                Deleting Messages.   (line  22)
* vm-load-init-file:                     Starting Up.         (line   6)
* vm-load-message:                       External Messages.   (line  44)
* vm-mail:                               Sending Messages.    (line  88)
* vm-mail-from-folder:                   Sending Messages.    (line  84)
* vm-mail-from-folder <1>:               Sending Options.     (line  20)
* vm-mail-to-sender:                     Replying.            (line  37)
* vm-mark-message-read:                  Paging.              (line  23)
* vm-mark-message-unread:                Paging.              (line  23)
* vm-mark-messages-by-selector:          Marking Messages.    (line  28)
* vm-mark-messages-by-virtual-folder:    Marking Messages.    (line  32)
* vm-mark-messages-same-author:          Marking Messages.    (line  46)
* vm-mark-messages-same-subject:         Marking Messages.    (line  42)
* vm-mark-summary-region:                Marking Messages.    (line  56)
* vm-mark-thread-subtree:                Marking Messages.    (line  37)
* vm-mime-auto-save-all-attachments:     Customizations.      (line  59)
* vm-mime-encode-composition:            Sending Messages.    (line  70)
* vm-mime-list-part-structure:           Viewing MIME.        (line  84)
* vm-mime-reader-map-attach-to-composition: Attachments.      (line  10)
* vm-mime-reader-map-attach-to-composition <1>: MIME attachments.
                                                              (line  60)
* vm-mime-reader-map-display-object-as-type: Attachments.     (line  10)
* vm-mime-reader-map-display-using-default: Attachments.      (line  10)
* vm-mime-reader-map-display-using-external-viewer: Attachments.
                                                              (line  10)
* vm-mime-reader-map-pipe-to-command:    Attachments.         (line  10)
* vm-mime-reader-map-pipe-to-printer:    Attachments.         (line  10)
* vm-mime-reader-map-save-file:          Attachments.         (line  10)
* vm-mime-reader-map-save-message:       Attachments.         (line  10)
* vm-mode:                               Starting Up.         (line  65)
* vm-mouse-send-url-to-netscape:         Using the Mouse.     (line  39)
* vm-mouse-send-url-to-xxx:              Using the Mouse.     (line  39)
* vm-mouse-send-url-to-xxx-new-window:   Using the Mouse.     (line  39)
* vm-next-button:                        Attachments.         (line   6)
* vm-next-message:                       Introduction.        (line  39)
* vm-next-message <1>:                   Navigating.          (line   6)
* vm-next-message-no-skip:               Navigating.          (line  64)
* vm-next-unread-message:                Navigating.          (line  68)
* vm-nuke-alternative-text/html:         multipart/alternative.
                                                              (line  41)
* vm-pipe-message-to-command:            Saving Messages.     (line 137)
* vm-pipe-message-to-command-discard-output: Saving Messages. (line 151)
* vm-pipe-messages-to-command:           Saving Messages.     (line 154)
* vm-pipe-messages-to-command-discard-output: Saving Messages.
                                                              (line 161)
* vm-pop-start-bug-report:               Bugs.                (line  17)
* vm-pop-submit-bug-report:              Bugs.                (line  17)
* vm-postpone-message:                   Crash Recovery.      (line  84)
* vm-postpone-message <1>:               Postponing Messages. (line   9)
* vm-preview-composition:                Sending Messages.    (line  77)
* vm-previous-button:                    Attachments.         (line   6)
* vm-previous-message:                   Navigating.          (line   6)
* vm-previous-message-no-skip:           Navigating.          (line  64)
* vm-previous-unread-message:            Navigating.          (line  68)
* vm-promote-subthread:                  Threaded Summaries.  (line  36)
* vm-prune-imap-retrieved-list:          IMAP Spool Files.    (line 111)
* vm-quit:                               Introduction.        (line  87)
* vm-quit-just-bury:                     Introduction.        (line 101)
* vm-quit-just-bury <1>:                 Introduction.        (line 109)
* vm-quit-just-iconify:                  Introduction.        (line 109)
* vm-quit-no-change:                     Introduction.        (line  87)
* vm-quit-no-expunge:                    Deleting Messages.   (line  56)
* vm-recover-folder:                     Crash Recovery.      (line  38)
* vm-refresh-message:                    External Messages.   (line  44)
* vm-reply:                              Replying.            (line  28)
* vm-reply-include-text:                 Replying.            (line  29)
* vm-resend-message:                     Forwarding Messages. (line  93)
* vm-revert-folder:                      Crash Recovery.      (line 121)
* vm-save-all-attachments:               Attachments.         (line  51)
* vm-save-folder:                        Introduction.        (line  67)
* vm-save-folder <1>:                    POP Folders.         (line   6)
* vm-save-folder <2>:                    IMAP Folders.        (line  12)
* vm-save-folder <3>:                    IMAP Folders.        (line  80)
* vm-save-folder <4>:                    Working with Virtual Folders.
                                                              (line   6)
* vm-save-folder-no-expunge:             Deleting Messages.   (line  56)
* vm-save-message:                       Introduction.        (line  43)
* vm-save-message <1>:                   Saving Messages.     (line  14)
* vm-save-message-sans-headers:          Saving Messages.     (line 125)
* vm-save-message-to-imap-folder:        Saving Messages.     (line  41)
* vm-save-message-to-local-folder:       Saving Messages.     (line  41)
* vm-save-window-configuration:          Window Configuration.
                                                              (line   6)
* vm-scroll-backward:                    Introduction.        (line  28)
* vm-scroll-forward:                     Introduction.        (line  28)
* vm-send-digest:                        Forwarding Messages. (line  74)
* vm-set-message-attributes:             Message Attributes.  (line  35)
* vm-sort-messages:                      Sorting Messages.    (line   6)
* vm-submit-bug-report:                  Bugs.                (line  12)
* vm-summarize:                          Introduction.        (line  58)
* vm-summarize <1>:                      Summaries.           (line   6)
* vm-summary-faces-mode:                 Summary Faces.       (line  13)
* vm-switch-to-folder:                   Introduction.        (line 101)
* vm-toggle-best-mime:                   Customizations.      (line  41)
* vm-toggle-flag-message:                Paging.              (line  30)
* vm-toggle-thread:                      Thread Folding.      (line  11)
* vm-toggle-thread-operations:           Thread Operations.   (line   6)
* vm-toggle-threads-display:             Threading.           (line  11)
* vm-toggle-threads-display <1>:         Threaded Summaries.  (line   6)
* vm-toggle-virtual-mirror:              Working with Virtual Folders.
                                                              (line  38)
* vm-undelete-message:                   Introduction.        (line  47)
* vm-undelete-message <1>:               Deleting Messages.   (line  14)
* vm-undo:                               Message Attributes.  (line  43)
* vm-unload-message:                     External Messages.   (line  44)
* vm-unmark-messages-by-selector:        Marking Messages.    (line  30)
* vm-unmark-messages-same-author:        Marking Messages.    (line  48)
* vm-unmark-messages-same-subject:       Marking Messages.    (line  44)
* vm-unmark-summary-region:              Marking Messages.    (line  57)
* vm-unmark-thread-subtree:              Marking Messages.    (line  40)
* vm-unmark-unmark-messages-by-virtual-folder: Marking Messages.
                                                              (line  35)
* vm-unread-message:                     Paging.              (line  23)
* vm-virtual-auto-archive-messages:      vm-avirtual.         (line  52)
* vm-virtual-auto-delete-message:        vm-avirtual.         (line  33)
* vm-virtual-auto-delete-messages:       vm-avirtual.         (line  44)
* vm-virtual-check-selector-interactive: vm-avirtual.         (line  18)
* vm-virtual-omit-message:               vm-avirtual.         (line  10)
* vm-virtual-save-message:               vm-avirtual.         (line  52)
* vm-virtual-update-folders:             vm-avirtual.         (line  10)
* vm-visit-folder:                       Starting Up.         (line  45)
* vm-visit-imap-folder:                  Starting Up.         (line  45)
* vm-visit-imap-folder <1>:              IMAP Folders.        (line   6)
* vm-visit-pop-folder:                   Starting Up.         (line  45)
* vm-visit-pop-folder <1>:               POP Folders.         (line   6)
* vm-visit-thunderbird-folder:           Thunderbird Folders. (line  12)
* vm-visit-virtual-folder:               Virtual Folders.     (line  21)
* vm-visit-virtual-folder <1>:           Defined Folders.     (line   6)
* vm-yank-message:                       Sending Messages.    (line  16)
* vm-yank-message-other-folder:          Sending Messages.    (line  16)
* vmpc-add-header:                       Personality Crisis.  (line 132)
* vmpc-automorph:                        Personality Crisis.  (line 187)
* vmpc-body-match:                       Personality Crisis.  (line  90)
* vmpc-check-virtual-selector:           Personality Crisis.  (line 102)
* vmpc-composition-buffer:               Personality Crisis.  (line 170)
* vmpc-delete-header:                    Personality Crisis.  (line 141)
* vmpc-folder-account-match:             Personality Crisis.  (line  98)
* vmpc-folder-match:                     Personality Crisis.  (line  94)
* vmpc-header-match:                     Personality Crisis.  (line  70)
* vmpc-insert-header:                    Personality Crisis.  (line 137)
* vmpc-my-identities:                    Personality Crisis.  (line  19)
* vmpc-none-true-yet:                    Personality Crisis.  (line 111)
* vmpc-only-from-match:                  Personality Crisis.  (line  79)
* vmpc-other-cond:                       Personality Crisis.  (line 106)
* vmpc-pre-function:                     Personality Crisis.  (line 165)
* vmpc-pre-signature:                    Personality Crisis.  (line 152)
* vmpc-prompt-for-profile:               Personality Crisis.  (line 175)
* vmpc-signature:                        Personality Crisis.  (line 146)
* vmpc-substitute-header:                Personality Crisis.  (line 124)
* vmpc-substitute-replied-header:        Personality Crisis.  (line 156)


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

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

[index]
* Menu:

* mail-citation-hook:                    Hooks.               (line 229)
* mail-yank-hooks:                       Hooks.               (line 214)
* smime-keys:                            Reading Secure MIME. (line  29)
* smtpmail-smtp-service:                 Configuration.       (line 137)
* smtpmail-stream-type:                  Configuration.       (line 137)
* vm-arrived-message-hook:               Hooks.               (line  40)
* vm-arrived-messages-hook:              vm-avirtual.         (line  44)
* vm-arrived-messages-hook <1>:          Hooks.               (line  53)
* vm-auto-center-summary:                Summaries.           (line   6)
* vm-auto-decode-mime-messages:          Viewing MIME.        (line  12)
* vm-auto-expunge-postponed-folder:      Postponing Messages. (line  27)
* vm-auto-folder-alist:                  Saving Messages.     (line  28)
* vm-auto-folder-alist <1>:              Saving Messages.     (line  79)
* vm-auto-folder-case-fold-search:       Saving Messages.     (line 115)
* vm-auto-get-new-mail:                  Starting Up.         (line  30)
* vm-auto-get-new-mail <1>:              POP Spool Files.     (line  26)
* vm-auto-get-new-mail <2>:              IMAP Spool Files.    (line  27)
* vm-auto-get-new-mail <3>:              Getting New Mail.    (line  11)
* vm-auto-next-message:                  Paging.              (line   6)
* vm-berkeley-mail-compatibility:        Saving Messages.     (line 166)
* vm-circular-folders:                   Navigating.          (line  22)
* vm-confirm-for-auto-archive:           Saving Messages.     (line 128)
* vm-confirm-new-folders:                Saving Messages.     (line  45)
* vm-confirm-quit:                       Introduction.        (line  94)
* vm-crash-box:                          Local Folders.       (line  36)
* vm-crash-box-suffix:                   Spool Files.         (line  54)
* vm-default-folder-type:                Local Folders.       (line   6)
* vm-default-folder-type <1>:            Folder types.        (line   6)
* vm-delete-after-archiving:             Saving Messages.     (line  64)
* vm-delete-after-saving:                Saving Messages.     (line  64)
* vm-delete-empty-folders:               Introduction.        (line  83)
* vm-digest-center-preamble:             Forwarding Messages. (line  83)
* vm-digest-preamble-format:             Forwarding Messages. (line  83)
* vm-digest-send-type:                   Forwarding Messages. (line  74)
* vm-display-buffer-hook:                Hooks.               (line 171)
* vm-display-using-mime:                 MIME Messages.       (line   6)
* vm-do-fcc-before-mime-encode:          Saving copies.       (line  24)
* vm-edit-message-hook:                  Hooks.               (line 120)
* vm-enable-addons:                      Customizations.      (line  14)
* vm-enable-external-messages:           External Messages.   (line  16)
* vm-enable-thread-operations:           Thread Operations.   (line   6)
* vm-expunge-before-quit:                Deleting Messages.   (line  45)
* vm-expunge-before-save:                Deleting Messages.   (line  45)
* vm-external-fetch-message-for-presentation: External Messages.
                                                              (line  29)
* vm-fetched-message-limit:              External Messages.   (line  36)
* vm-fill-long-lines-in-reply-column:    Replying.            (line 121)
* vm-fill-paragraphs-containing-long-lines: Paging.           (line  37)
* vm-fill-paragraphs-containing-long-lines-in-reply: Replying.
                                                              (line 121)
* vm-flush-interval:                     Message Attributes.  (line  70)
* vm-folder-directory:                   Local Folders.       (line  12)
* vm-folder-directory <1>:               POP Folders.         (line   6)
* vm-folder-directory <2>:               IMAP Folders.        (line  12)
* vm-folder-directory <3>:               Saving Messages.     (line  20)
* vm-folder-file-precious-flag:          Introduction.        (line  75)
* vm-folder-type:                        Folder Internals.    (line  23)
* vm-follow-summary-cursor:              Navigating.          (line  39)
* vm-follow-summary-cursor <1>:          Summaries.           (line  24)
* vm-forward-message-hook:               Hooks.               (line  68)
* vm-forwarded-headers:                  Forwarding Messages. (line  41)
* vm-forwarded-headers-plain:            Forwarding Messages. (line  41)
* vm-forwarding-digest-type:             Forwarding Messages. (line  17)
* vm-forwarding-subject-format:          Forwarding Messages. (line  66)
* vm-frame-parameter-alist:              Frame Configuration. (line  50)
* vm-frame-per-completion:               Frame Configuration. (line  33)
* vm-frame-per-composition:              Frame Configuration. (line  19)
* vm-frame-per-edit:                     Frame Configuration. (line  26)
* vm-frame-per-folder:                   Frame Configuration. (line   9)
* vm-frame-per-help:                     Frame Configuration. (line  30)
* vm-frame-per-summary:                  Frame Configuration. (line  13)
* vm-gargle-uucp:                        Summaries.           (line  31)
* vm-get-new-mail:                       IMAP Folders.        (line  69)
* vm-get-recipient-certificate-method:   Sending Secure MIME. (line   6)
* vm-highlight-url-face:                 Faces.               (line  20)
* vm-highlighted-header-face:            Previewing.          (line  47)
* vm-highlighted-header-face <1>:        Faces.               (line  12)
* vm-highlighted-header-regexp:          Previewing.          (line  47)
* vm-highlighted-header-regexp <1>:      Faces.               (line  12)
* vm-iconify-frame-hook:                 Hooks.               (line 190)
* vm-imagemagick-convert-program:        Displaying images.   (line  27)
* vm-imagemagick-identify-program:       Displaying images.   (line  27)
* vm-imap-account-alist:                 IMAP Folders.        (line  25)
* vm-imap-auto-expunge-alist:            IMAP Spool Files.    (line  42)
* vm-imap-bytes-per-session:             IMAP Spool Files.    (line  19)
* vm-imap-connection-mode:               IMAP Server Folders. (line  16)
* vm-imap-default-account:               Saving copies.       (line  14)
* vm-imap-expunge-after-retrieving:      IMAP Spool Files.    (line  42)
* vm-imap-folder-cache-directory:        IMAP Folders.        (line  12)
* vm-imap-folder-cache-directory <1>:    IMAP Folders.        (line  16)
* vm-imap-keep-trace-buffer:             POP and IMAP Folders.
                                                              (line 162)
* vm-imap-max-message-size:              IMAP Spool Files.    (line  27)
* vm-imap-max-message-size <1>:          External Messages.   (line  20)
* vm-imap-messages-per-session:          IMAP Spool Files.    (line  19)
* vm-imap-refer-to-inbox-by-account-name: IMAP Folders.       (line  51)
* vm-imap-save-to-server:                Saving Messages.     (line  34)
* vm-imap-server-list:                   IMAP Folders.        (line  62)
* vm-imap-session-preauth-hook:          POP and IMAP Folders.
                                                              (line 102)
* vm-imap-sync-on-get:                   IMAP Folders.        (line  75)
* vm-in-reply-to-format:                 Replying.            (line  59)
* vm-include-text-basic:                 Replying.            (line 146)
* vm-include-text-from-presentation:     Replying.            (line 154)
* vm-included-mime-types-list:           Replying.            (line 146)
* vm-included-text-attribution-format:   Replying.            (line 162)
* vm-included-text-discard-header-regexp: Replying.           (line 170)
* vm-included-text-headers:              Replying.            (line 170)
* vm-included-text-prefix:               Replying.            (line  18)
* vm-index-file-suffix:                  Index Files.         (line  11)
* vm-infer-mime-types:                   Inferring MIME types.
                                                              (line  13)
* vm-infer-mime-types-for-text:          Inferring MIME types.
                                                              (line  18)
* vm-init-file:                          Starting Up.         (line   6)
* vm-invisible-header-regexp:            Previewing.          (line  30)
* vm-jump-to-new-messages:               Navigating.          (line  50)
* vm-jump-to-unread-messages:            Navigating.          (line  50)
* vm-mail-auto-save-directory:           Crash Recovery.      (line  84)
* vm-mail-auto-save-directory <1>:       Sending Options.     (line  10)
* vm-mail-check-always:                  Getting New Mail.    (line  17)
* vm-mail-check-interval:                Getting New Mail.    (line  17)
* vm-mail-header-from:                   Sending Options.     (line  14)
* vm-mail-header-insert-date:            Sending Options.     (line  32)
* vm-mail-header-insert-message-id:      Sending Options.     (line  32)
* vm-mail-header-order:                  Sending Options.     (line  32)
* vm-mail-hook:                          Hooks.               (line  92)
* vm-mail-mode-hidden-headers:           Sending Options.     (line  14)
* vm-mail-mode-hook:                     Hooks.               (line 125)
* vm-mail-reorder-message-headers:       Sending Options.     (line  32)
* vm-mail-send-hook:                     Hooks.               (line 208)
* vm-mail-use-sender-address:            Sending Options.     (line  20)
* vm-make-crash-box-name:                Spool Files.         (line  78)
* vm-make-spool-file-name:               Spool Files.         (line  78)
* vm-menu-setup-hook:                    Hooks.               (line 193)
* vm-mime-7bit-composition-charset:      MIME characters.     (line   6)
* vm-mime-8bit-composition-charset:      MIME characters.     (line  14)
* vm-mime-8bit-text-transfer-encoding:   MIME characters.     (line  29)
* vm-mime-alternative-show-method:       multipart/alternative.
                                                              (line  18)
* vm-mime-alternative-yank-method:       Replying.            (line 104)
* vm-mime-attachment-auto-suffix-alist:  External display.    (line  95)
* vm-mime-attachment-save-directory:     Attachments.         (line  31)
* vm-mime-auto-displayed-content-type-exceptions: Viewing MIME.
                                                              (line  31)
* vm-mime-auto-displayed-content-type-exceptions <1>: Viewing MIME.
                                                              (line  50)
* vm-mime-auto-displayed-content-types:  Viewing MIME.        (line  31)
* vm-mime-auto-displayed-content-types <1>: Viewing MIME.     (line  37)
* vm-mime-auto-displayed-content-types <2>: Displaying images.
                                                              (line  17)
* vm-mime-auto-save-all-attachments-subdir: Customizations.   (line  59)
* vm-mime-button-face:                   Faces.               (line  31)
* vm-mime-button-format-alist:           Viewing MIME.        (line  21)
* vm-mime-charset-converter-alist:       Character sets.      (line  39)
* vm-mime-charset-font-alist:            Character sets.      (line  80)
* vm-mime-confirm-delete:                Attachments.         (line  31)
* vm-mime-decode-for-preview:            Viewing MIME.        (line  12)
* vm-mime-default-face-charsets:         Character sets.      (line  12)
* vm-mime-deletable-type-exceptions:     Attachments.         (line  51)
* vm-mime-deletable-types:               Attachments.         (line  51)
* vm-mime-delete-after-saving:           Attachments.         (line  31)
* vm-mime-display-function:              Hooks.               (line 197)
* vm-mime-encode-headers-regexp:         MIME headers.        (line  12)
* vm-mime-encode-headers-type:           MIME headers.        (line  12)
* vm-mime-encode-headers-words-regexp:   MIME headers.        (line  19)
* vm-mime-encode-words.regexp:           MIME headers.        (line  19)
* vm-mime-external-content-type-exceptions: External display. (line  84)
* vm-mime-external-content-types-alist:  External display.    (line   6)
* vm-mime-honor-content-disposition:     Viewing MIME.        (line  65)
* vm-mime-internal-content-type-exceptions: Internal display. (line  21)
* vm-mime-internal-content-types:        Internal display.    (line   6)
* vm-mime-internal-content-types <1>:    Displaying images.   (line  17)
* vm-mime-multipart/related-show-method: multipart/related.   (line  18)
* vm-mime-savable-type-exceptions:       Attachments.         (line  51)
* vm-mime-savable-types:                 Attachments.         (line  51)
* vm-mime-text/html-handler:             Internal display.    (line  25)
* vm-mime-type-converter-alist:          MIME type conversion.
                                                              (line   6)
* vm-mime-use-image-strips:              Displaying images.   (line  35)
* vm-mime-verify-signatures:             Reading Secure MIME. (line  51)
* vm-mode-hook:                          Hooks.               (line 130)
* vm-mode-hooks:                         Hooks.               (line 135)
* vm-mouse-track-summary:                Summary Faces.       (line  44)
* vm-move-after-deleting:                Deleting Messages.   (line  36)
* vm-move-after-killing:                 Deleting Messages.   (line  36)
* vm-move-after-reading:                 Paging.              (line  23)
* vm-move-after-undeleting:              Deleting Messages.   (line  36)
* vm-move-messages-physically:           Sorting Messages.    (line   6)
* vm-movemail-program:                   Local Folders.       (line  29)
* vm-movemail-program-switches:          Local Folders.       (line  29)
* vm-mutable-frame-configuration:        Frames and Windows.  (line  13)
* vm-mutable-frames:                     Frames and Windows.  (line  13)
* vm-mutable-window-configuration:       Frames and Windows.  (line  20)
* vm-mutable-windows:                    Frames and Windows.  (line  20)
* vm-paragraph-fill-column:              Paging.              (line  37)
* vm-pipe-messages-to-command-end:       Saving Messages.     (line 154)
* vm-pipe-messages-to-command-start:     Saving Messages.     (line 154)
* vm-pop-auto-expunge-alist:             POP Spool Files.     (line  41)
* vm-pop-bytes-per-session:              POP Spool Files.     (line  18)
* vm-pop-expunge-after-retrieving:       POP Spool Files.     (line  41)
* vm-pop-folder-alist:                   POP Folders.         (line  23)
* vm-pop-folder-cache-directory:         POP Folders.         (line   6)
* vm-pop-folder-cache-directory <1>:     POP Folders.         (line  11)
* vm-pop-keep-trace-buffer:              POP and IMAP Folders.
                                                              (line 162)
* vm-pop-max-message-size:               POP Spool Files.     (line  26)
* vm-pop-md5-program:                    POP and IMAP Folders.
                                                              (line  90)
* vm-pop-messages-per-session:           POP Spool Files.     (line  18)
* vm-popup-menu-on-mouse-3:              Menus.               (line   6)
* vm-postponed-folder:                   Postponing Messages. (line   9)
* vm-preferences-file:                   Starting Up.         (line  15)
* vm-presentation-minor-modes:           HTML display.        (line  11)
* vm-presentation-mode-hook:             Hooks.               (line 152)
* vm-preserve-read-only-folders-on-disk: Starting Up.         (line  50)
* vm-preview-lines:                      Previewing.          (line  17)
* vm-preview-read-messages:              Previewing.          (line  55)
* vm-primary-inbox:                      Starting Up.         (line  30)
* vm-primary-inbox <1>:                  POP and IMAP Folders.
                                                              (line   6)
* vm-quit-hook:                          Hooks.               (line 159)
* vm-reply-hook:                         Hooks.               (line  62)
* vm-reply-ignored-addresses:            Replying.            (line  51)
* vm-reply-subject-prefix:               Replying.            (line   6)
* vm-resend-bounced-message-hook:        Hooks.               (line  74)
* vm-resend-message-hook:                Hooks.               (line  80)
* vm-restore-saved-summary-format:       Summary Format.      (line 181)
* vm-retrieved-spooled-mail-hook:        Hooks.               (line 113)
* vm-save-message-hook:                  Hooks.               (line  31)
* vm-save-using-auto-folders:            Saving Messages.     (line  79)
* vm-search-other-frames:                Frame Configuration. (line  42)
* vm-search-using-regexps:               Navigating.          (line  71)
* vm-select-message-hook:                Hooks.               (line  25)
* vm-select-new-message-hook:            Hooks.               (line  10)
* vm-select-unread-message-hook:         Hooks.               (line  18)
* vm-send-digest-hook:                   Hooks.               (line  86)
* vm-send-using-mime:                    Sending Messages.    (line  36)
* vm-send-using-mime <1>:                Sending MIME Messages.
                                                              (line   6)
* vm-skip-deleted-messages:              Navigating.          (line   6)
* vm-skip-read-messages:                 Navigating.          (line   6)
* vm-smime-get-recipient-certificate-method: Sending Secure MIME.
                                                              (line  21)
* vm-sort-messages-by-delivery-date:     Sorting Messages.    (line  30)
* vm-sort-subthreads:                    Threading.           (line  33)
* vm-spam-score-headers:                 Sorting Messages.    (line  93)
* vm-spool-file-suffixes:                Spool Files.         (line  54)
* vm-spool-files:                        Spool Files.         (line   6)
* vm-spooled-mail-waiting-hook:          Hooks.               (line  48)
* vm-ssh-program:                        POP and IMAP Folders.
                                                              (line  64)
* vm-ssh-remote-command:                 POP and IMAP Folders.
                                                              (line  64)
* vm-startup-with-summary:               Starting Up.         (line  73)
* vm-strip-reply-headers:                Replying.            (line  68)
* vm-stunnel-program:                    POP and IMAP Folders.
                                                              (line  51)
* vm-stunnel-program-additional-configuration-file: POP and IMAP Folders.
                                                              (line  51)
* vm-subject-ignored-prefix:             Sorting Messages.    (line  47)
* vm-subject-ignored-suffix:             Sorting Messages.    (line  47)
* vm-subject-significant-chars:          Sorting Messages.    (line  85)
* vm-subject-tag-prefix:                 Sorting Messages.    (line  62)
* vm-subject-tag-prefix-exceptions:      Sorting Messages.    (line  62)
* vm-summary-arrow:                      Summaries.           (line   6)
* vm-summary-attachment-indicator:       Summary Format.      (line  50)
* vm-summary-enable-faces:               Summary Faces.       (line  13)
* vm-summary-enable-thread-folding:      Thread Folding.      (line  11)
* vm-summary-faces-alist:                Summary Faces.       (line  23)
* vm-summary-format:                     Summary Format.      (line   6)
* vm-summary-maximum-thread-indentation: Threading.           (line  11)
* vm-summary-maximum-thread-indentation <1>: Threaded Summaries.
                                                              (line   6)
* vm-summary-mode-hook:                  Hooks.               (line 139)
* vm-summary-mode-hooks:                 Hooks.               (line 143)
* vm-summary-pointer-update-hook:        Hooks.               (line 166)
* vm-summary-postponed-indicator:        Summary Format.      (line  46)
* vm-summary-recipient-marker:           Summary Format.      (line 153)
* vm-summary-redo-hook:                  Hooks.               (line 103)
* vm-summary-show-thread-count:          Thread Folding.      (line  34)
* vm-summary-show-threads:               Threaded Summaries.  (line  16)
* vm-summary-strip-subject-tags:         Sorting Messages.    (line  80)
* vm-summary-thread-folding-on-motion:   Thread Folding.      (line  27)
* vm-summary-thread-indent-level:        Threading.           (line  11)
* vm-summary-thread-indent-level <1>:    Threaded Summaries.  (line   6)
* vm-summary-uninteresting-senders:      Summary Format.      (line 153)
* vm-summary-uninteresting-senders <1>:  Virtual Selectors.   (line  38)
* vm-summary-uninteresting-senders-arrow: Summary Format.     (line 153)
* vm-summary-update-hook:                Hooks.               (line  99)
* vm-summary-visible:                    Thread Folding.      (line  20)
* vm-sync-thunderbird-status:            Thunderbird Folders. (line  61)
* vm-thread-using-subject:               Threading.           (line  16)
* vm-thunderbird-folder-directory:       Thunderbird Folders. (line  12)
* vm-thunderbird-folder-directory <1>:   Saving Messages.     (line  20)
* vm-toolbar-orientation:                Toolbar.             (line 105)
* vm-toolbar-pixmap-directory:           Toolbar.             (line 114)
* vm-trust-From_-with-Content-Length:    Folder types.        (line  42)
* vm-undisplay-buffer-hook:              Hooks.               (line 180)
* vm-unforwarded-header-regexp:          Forwarding Messages. (line  41)
* vm-unforwarded-header-regexp-plain:    Forwarding Messages. (line  41)
* vm-url-browser:                        Using the Mouse.     (line  10)
* vm-url-search-limit:                   Faces.               (line  20)
* vm-use-menus:                          Menus.               (line  12)
* vm-use-presentation-minor-modes:       HTML display.        (line  11)
* vm-use-toolbar:                        Toolbar.             (line  11)
* vm-virtual-auto-delete-message-selector: vm-avirtual.       (line  33)
* vm-virtual-auto-folder-alist:          vm-avirtual.         (line  52)
* vm-virtual-folder-alist:               Virtual Folders.     (line  21)
* vm-virtual-folder-alist <1>:           Defined Folders.     (line   6)
* vm-virtual-mode-hook:                  Hooks.               (line 147)
* vm-visible-headers:                    Previewing.          (line  25)
* vm-visit-folder-hook:                  Hooks.               (line 107)
* vm-visit-when-saving:                  Saving Messages.     (line  49)
* vm-vs-attachment-regexp:               Virtual Selectors.   (line 142)
* vm-w3m-display-inline-images:          HTML display.        (line  18)
* vm-w3m-safe-url-regexp:                HTML display.        (line  25)
* vm-window-configuration-file:          Window Configuration.
                                                              (line  52)
* vm-word-wrap-paragraphs:               Paging.              (line  37)
* vmpc-actions:                          Personality Crisis.  (line  28)
* vmpc-automorph-rules:                  Personality Crisis.  (line  61)
* vmpc-conditions:                       Personality Crisis.  (line  28)
* vmpc-default-rules:                    Personality Crisis.  (line  47)
* vmpc-forward-rules:                    Personality Crisis.  (line  48)
* vmpc-mail-rules:                       Personality Crisis.  (line  48)
* vmpc-newmail-rules:                    Personality Crisis.  (line  57)
* vmpc-reply-rules:                      Personality Crisis.  (line  48)
* vmpc-resend-rules:                     Personality Crisis.  (line  48)
* w3m-force-redisplay:                   HTML display.        (line  38)
* w3m-goto-article-function:             HTML display.        (line  47)
* w3m-goto-article-function <1>:         Using the Mouse.     (line  28)
* w3m-pop-up-frames:                     HTML display.        (line  43)


File: vm.info,  Node: Internals Index,  Next: License,  Prev: Variable Index,  Up: Top

Internals Index
***************

[index]
* Menu:

* attachment button:                     MIME Composition.    (line   6)
* attribute-modflag:                     Message Internals.   (line 285)
* Babyl format:                          Folder Internals.    (line  32)
* babyl-frob-flag:                       Message Internals.   (line 108)
* base 64:                               Coding Systems.      (line  37)
* BellFrom_ folder type:                 Folder Internals.    (line  23)
* body-to-be-discarded:                  Message Internals.   (line 232)
* body-to-be-retrieved:                  Message Internals.   (line 229)
* buffer:                                Message Internals.   (line  95)
* byte-count:                            Message Internals.   (line 191)
* cache:                                 Message Internals.   (line 319)
* charset:                               Coding Systems.      (line  17)
* coding system:                         Coding Systems.      (line   6)
* coding-system-get:                     Coding Systems.      (line  17)
* concurrency:                           Timers and Concurrency.
                                                              (line   6)
* Content-Description:                   Message Internals.   (line 306)
* Content-Disposition:                   Message Internals.   (line 308)
* Content-ID:                            Message Internals.   (line 304)
* Content-Transfer-Encoding:             Message Internals.   (line 303)
* Content-Type:                          Message Internals.   (line 296)
* Content-Type <1>:                      Coding Systems.      (line  17)
* declared-duplicates:                   Message Internals.   (line 255)
* declared-parent:                       Message Internals.   (line 251)
* decode-coding-region:                  Coding Systems.      (line  17)
* decode-coding-string:                  Coding Systems.      (line  37)
* decoded-from:                          Message Internals.   (line 195)
* decoded-full-name:                     Message Internals.   (line 193)
* decoded-reply-to:                      Message Internals.   (line 263)
* decoded-reply-to-name:                 Message Internals.   (line 263)
* decoded-sortable-subject:              Message Internals.   (line 216)
* decoded-subject:                       Message Internals.   (line 199)
* decoded-summary-subject:               Message Internals.   (line 248)
* decoded-to:                            Message Internals.   (line 205)
* decoded-to-cc:                         Message Internals.   (line 266)
* decoded-to-cc-name:                    Message Internals.   (line 266)
* deleted-flag:                          Message Internals.   (line 132)
* description:                           Message Internals.   (line 306)
* display-error:                         Message Internals.   (line 338)
* disposition:                           Message Internals.   (line 308)
* edit-buffer:                           Message Internals.   (line 276)
* edited-flag:                           Message Internals.   (line 141)
* editing:                               Folder Internals.    (line 153)
* encode-coding-region:                  Coding Systems.      (line  17)
* encode-coding-string:                  Coding Systems.      (line  37)
* encoding:                              Message Internals.   (line 303)
* end:                                   Message Internals.   (line  50)
* extents:                               Extents and Overlays.
                                                              (line   6)
* filed-flag:                            Message Internals.   (line 134)
* forwarded-flag:                        Message Internals.   (line 139)
* forwarding:                            Folder Internals.    (line 157)
* From_ folder type:                     Folder Internals.    (line  23)
* From_with-Content-Length folder type:  Folder Internals.    (line  23)
* header-start:                          Message Internals.   (line 314)
* headers:                               Message Internals.   (line  40)
* headers-to-be-discarded:               Message Internals.   (line 244)
* headers-to-be-retrieved:               Message Internals.   (line 240)
* id:                                    Message Internals.   (line 304)
* imap-uid:                              Message Internals.   (line 236)
* imap-uid-validity:                     Message Internals.   (line 237)
* In-Reply-To header:                    Threading Internals. (line   6)
* include:                               MIME Composition.    (line  75)
* label-string:                          Message Internals.   (line 283)
* labels:                                Message Internals.   (line 282)
* layout-is-converted:                   Message Internals.   (line 340)
* line-count:                            Message Internals.   (line 198)
* mark:                                  Message Internals.   (line  67)
* mbox:                                  Folder Internals.    (line   6)
* message-access-method:                 Message Internals.   (line 120)
* message-id:                            Message Internals.   (line 197)
* message-id-number:                     Message Internals.   (line  93)
* message-symbol:                        Message Internals.   (line 335)
* message-type:                          Message Internals.   (line  90)
* message/external-body:                 MIME Display.        (line  30)
* MIME:                                  Folder Internals.    (line 141)
* MIME button:                           MIME Display.        (line  39)
* mime-charset:                          Coding Systems.      (line  17)
* mime-encoded-header-flag:              Message Internals.   (line 116)
* mime-layout:                           Message Internals.   (line 114)
* mirrored-message-sym:                  Message Internals.   (line  82)
* MMDF format:                           Folder Internals.    (line  32)
* month-number:                          Message Internals.   (line 211)
* new-flag:                              Message Internals.   (line 131)
* number:                                Message Internals.   (line  66)
* overlays:                              Extents and Overlays.
                                                              (line   6)
* padded-number:                         Message Internals.   (line  66)
* parent:                                Message Internals.   (line 225)
* parts:                                 Message Internals.   (line 317)
* pop-uidl:                              Message Internals.   (line 235)
* previewing:                            Folder Internals.    (line 149)
* qdisposition:                          Message Internals.   (line 312)
* qtype:                                 Message Internals.   (line 301)
* quoted printable:                      Coding Systems.      (line  37)
* reading:                               Folder Internals.    (line 151)
* real-message-sym:                      Message Internals.   (line  73)
* redistributed-flag:                    Message Internals.   (line 143)
* redistributing:                        Folder Internals.    (line 159)
* references:                            Message Internals.   (line 227)
* References header:                     Threading Internals. (line   6)
* replied-flag:                          Message Internals.   (line 136)
* replying:                              Folder Internals.    (line 158)
* reverse-link-sym:                      Message Internals.   (line  87)
* saved-virtual-attributes:              Message Internals.   (line 109)
* saved-virtual-mirror-data:             Message Internals.   (line 111)
* showing:                               Folder Internals.    (line 150)
* sortable-datestring:                   Message Internals.   (line 212)
* spam-score:                            Message Internals.   (line 239)
* start:                                 Message Internals.   (line  39)
* stuff-flag:                            Message Internals.   (line 280)
* su-end:                                Message Internals.   (line  71)
* su-start:                              Message Internals.   (line  69)
* su-summary-mouse-track-overlay:        Message Internals.   (line 118)
* summary:                               Message Internals.   (line 220)
* summary line, tokenized:               Summary Internals.   (line   6)
* System V:                              Folder Internals.    (line  23)
* text:                                  Message Internals.   (line  46)
* text-end:                              Message Internals.   (line  48)
* thread-indentation:                    Message Internals.   (line  98)
* thread-indentation <1>:                Threading Internals. (line  88)
* thread-indentation-offset:             Message Internals.   (line 100)
* thread-list:                           Message Internals.   (line 104)
* thread-list <1>:                       Threading Internals. (line  88)
* thread-subtree:                        Message Internals.   (line 106)
* thread-subtree <1>:                    Threading Internals. (line  88)
* threads, building:                     Threading Internals. (line  83)
* timers:                                Timers and Concurrency.
                                                              (line   6)
* to-names:                              Message Internals.   (line 208)
* tokenized summary line:                Summary Internals.   (line   6)
* type:                                  Message Internals.   (line 296)
* unconverted-layout:                    Message Internals.   (line 343)
* unread-flag:                           Message Internals.   (line 131)
* unthread:                              Threading Internals. (line 100)
* vheaders:                              Message Internals.   (line  42)
* vheaders-regexp:                       Message Internals.   (line 201)
* virtual-folder-definition:             Virtual Folder Internals.
                                                              (line   6)
* virtual-messages-sym:                  Message Internals.   (line 277)
* virtual-summary:                       Message Internals.   (line 113)
* vm-check-mail-itimer-function:         Timers and Concurrency.
                                                              (line  27)
* vm-component-buffers:                  Folder Internals.    (line 108)
* vm-decode-mime-layout:                 MIME Display.        (line   6)
* vm-fetched-message-count:              Folder Internals.    (line 138)
* vm-fetched-messages:                   Folder Internals.    (line 136)
* vm-fetched-messages <1>:               Folder Internals.    (line 138)
* vm-flush-itimer-function:              Timers and Concurrency.
                                                              (line   9)
* vm-folder-access-data:                 Folder Internals.    (line  90)
* vm-folder-access-method:               Folder Internals.    (line  87)
* vm-folder-garbage-alist:               Folder Internals.    (line 171)
* vm-folder-read-only:                   Folder Internals.    (line  97)
* vm-folder-type:                        Folder Internals.    (line  23)
* vm-folder-type <1>:                    Folder Internals.    (line  84)
* vm-get-mail-itimer-function:           Timers and Concurrency.
                                                              (line  16)
* vm-global-block-new-mail:              Timers and Concurrency.
                                                              (line  38)
* vm-image-modified:                     Message Internals.   (line 326)
* vm-include-mime-attachments:           MIME Composition.    (line  75)
* vm-key-functions:                      Sorting Internals.   (line   6)
* vm-label-obarray:                      Folder Internals.    (line 170)
* vm-last-message-pointer:               Folder Internals.    (line 131)
* vm-mail-buffer:                        User Interaction.    (line   6)
* vm-mail-buffer <1>:                    User Interaction.    (line  14)
* vm-menu-toggle-menubar:                User Interaction.    (line  53)
* vm-message:                            Summary Internals.   (line  65)
* vm-message-garbage:                    Message Internals.   (line 331)
* vm-message-garbage-alist:              Folder Internals.    (line 175)
* vm-message-list:                       Folder Internals.    (line  82)
* vm-message-list <1>:                   Message Internals.   (line 351)
* vm-message-list <2>:                   Summary Internals.   (line  43)
* vm-message-list <3>:                   Summary Internals.   (line  54)
* vm-message-list <4>:                   Timers and Concurrency.
                                                              (line  16)
* vm-message-pointer:                    Folder Internals.    (line 128)
* vm-message-pointer <1>:                Message Internals.   (line 351)
* vm-messages-needing-summary-update:    Summary Internals.   (line  51)
* vm-mime-button-face:                   MIME Display.        (line  48)
* vm-mime-decoded:                       Folder Internals.    (line 141)
* vm-mime-display-external-generic:      Message Internals.   (line 322)
* vm-mime-display-internal-audio/basic:  Message Internals.   (line 328)
* vm-mime-display-internal-image-xxxx:   Message Internals.   (line 324)
* vm-mime-fake-attachment-overlays:      MIME Composition.    (line  58)
* vm-mime-mule-charset-to-coding-alist:  Coding Systems.      (line  17)
* vm-mime-mule-coding-to-charset-alist:  Coding Systems.      (line  17)
* vm-mode-menu-map:                      User Interaction.    (line  33)
* vm-numbering-redo-end-point:           Summary Internals.   (line  56)
* vm-numbering-redo-start-point:         Summary Internals.   (line  54)
* vm-presentation-buffer:                Folder Internals.    (line 122)
* vm-presentation-buffer <1>:            User Interaction.    (line  14)
* vm-presentation-buffer-handle:         Folder Internals.    (line 120)
* vm-real-buffers:                       Folder Internals.    (line 103)
* vm-select-folder-buffer-and-validate:  User Interaction.    (line   6)
* vm-select-folder-buffer-and-validate <1>: User Interaction. (line  20)
* vm-sort-compare-thread:                Sorting Internals.   (line  23)
* vm-sort-compare-xxxxxx:                Sorting Internals.   (line  14)
* vm-spooled-mail-waiting:               Folder Internals.    (line 161)
* vm-summary-buffer:                     Folder Internals.    (line 114)
* vm-summary-buffer <1>:                 User Interaction.    (line  14)
* vm-summary-line-format:                Summary Internals.   (line   6)
* vm-summary-pointer:                    Folder Internals.    (line 134)
* vm-summary-pointer <1>:                Summary Internals.   (line  41)
* vm-summary-redo-start-point:           Summary Internals.   (line  43)
* vm-supported-interactive-virtual-selectors: Virtual Folder Internals.
                                                              (line  42)
* vm-system-state:                       Folder Internals.    (line 146)
* vm-thread-obarray:                     Threading Internals. (line   6)
* vm-thread-subject-obarray:             Threading Internals. (line   6)
* vm-thread-using-subject:               Threading Internals. (line  27)
* vm-undo-record-list:                   Folder Internals.    (line 164)
* vm-undo-record-pointer:                Folder Internals.    (line 168)
* vm-use-menus:                          User Interaction.    (line  44)
* vm-user-interaction-buffer:            User Interaction.    (line   6)
* vm-user-interaction-buffer <1>:        User Interaction.    (line  20)
* vm-virtual-buffers:                    Folder Internals.    (line 106)
* vm-virtual-folder-alist:               Virtual Folder Internals.
                                                              (line   6)
* vm-virtual-folder-definition:          Folder Internals.    (line 101)
* vm-virtual-selector-arg-type:          Virtual Folder Internals.
                                                              (line  36)
* vm-virtual-selector-clause:            Virtual Folder Internals.
                                                              (line  48)
* vm-virtual-selector-function-alist:    Virtual Folder Internals.
                                                              (line  32)
* written-flag:                          Message Internals.   (line 137)
* X-VM-Bookmark:                         Folder Internals.    (line  43)
* X-VM-IMAP-Retrieved:                   Folder Internals.    (line  63)
* X-VM-Labels:                           Folder Internals.    (line  51)
* X-VM-Last-Modified:                    Folder Internals.    (line  47)
* X-VM-Message-order:                    Folder Internals.    (line  49)
* X-VM-POP-Retrieved:                    Folder Internals.    (line  59)
* X-VM-Summary-Format:                   Folder Internals.    (line  57)
* X-VM-v5-Data:                          Message Internals.   (line  26)
* X-VM-v5-Data header:                   Folder Internals.    (line  36)
* X-VM-v5-Data header <1>:               Message Internals.   (line 171)
* X-VM-VHeader:                          Folder Internals.    (line  53)
* yank:                                  MIME Composition.    (line  75)


File: vm.info,  Node: License,  Prev: Internals Index,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     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.

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.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

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

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

  2. 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:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

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

       c. 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.)

     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.

  3. 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:

       a. 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,

       b. 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,

       c. 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.)

     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.

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

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

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

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

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

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

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

                              NO WARRANTY

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

  12. 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 OF TERMS AND CONDITIONS

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.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  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.

   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:

     Gnomovision version 69, Copyright (C) 19YY 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.

   The hypothetical commands 'show w' and 'show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than 'show w' and '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:

     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   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.



Tag Table:
Node: Top561
Node: Preface3134
Node: Introduction6120
Node: Starting Up13039
Node: Local Folders17841
Node: Spool Files20855
Node: POP Spool Files25240
Node: IMAP Spool Files28795
Node: Index Files34713
Node: Folder types35236
Node: POP and IMAP Folders37768
Ref: maildrop specification39286
Ref: troubleshooting mail servers45188
Node: POP Folders46330
Node: IMAP Folders48294
Ref: IMAP Synchronization51272
Node: Thunderbird Folders52564
Node: External Messages56618
Node: Getting New Mail59516
Node: Crash Recovery60978
Node: Navigating67694
Node: Reading Messages72015
Node: Previewing72474
Node: Paging75572
Node: MIME Messages78839
Node: Viewing MIME80800
Node: Attachments85020
Ref: Operating on MIME attachments85196
Node: Internal display87980
Ref: Internal display of MIME attachments88170
Node: HTML display90068
Node: External display92431
Node: Displaying images97836
Node: MIME type conversion100270
Node: Character sets101727
Node: multipart/alternative106585
Node: multipart/related109169
Node: Inferring MIME types110162
Node: Reading Secure MIME111075
Node: Sending Messages114413
Ref: vm-mail-from-folder118917
Ref: vm-mail119071
Node: Sending Options120516
Node: Sending MIME Messages122703
Node: MIME attachments123436
Node: MIME characters126969
Node: MIME headers129169
Node: MIME preview130282
Node: Sending Secure MIME131410
Node: Replying133743
Node: Forwarding Messages142040
Node: Saving copies147056
Node: Personality Crisis148628
Node: Postponing Messages156908
Node: Selecting Messages158364
Node: Marking Messages159557
Node: Saving Messages163094
Node: Deleting Messages171695
Node: Editing Messages175537
Node: Message Attributes176543
Node: Sorting Messages180420
Node: Threading186824
Node: Digests188852
Node: Summaries189909
Node: Summary Format191958
Node: Threaded Summaries198101
Node: Thread Folding200667
Node: Thread Operations202999
Node: Summary Faces205092
Ref: Hiding summary lines207417
Ref: predefined summary faces207953
Node: Virtual Folders209063
Node: Search Folders210830
Node: Defined Folders214177
Node: Virtual Selectors216833
Node: Working with Virtual Folders225311
Node: vm-avirtual227294
Ref: vm-virtual-auto-folder-alist229636
Node: IMAP Server Folders230538
Ref: UIDVALIDITY232374
Node: Frames and Windows234193
Node: Frame Configuration235573
Node: Window Configuration239273
Node: Toolbar242079
Node: Menus247999
Node: Faces251094
Node: Using the Mouse252871
Node: Hooks255259
Node: Configuration265567
Node: Preface to Add-ons275006
Node: Customizations275782
Node: History and Administration278617
Node: Highlights285163
Node: Future Plans285988
Node: Bugs286458
Node: Internals287771
Node: Folder Internals288832
Node: Message Internals300768
Ref: Location data vector302057
Ref: Soft data vector303556
Ref: Attributes vector306948
Ref: Cached data vector309077
Ref: Mirror data vector315086
Ref: MIME layout315810
Node: Summary Internals321438
Node: Threading Internals324714
Node: Sorting Internals331427
Node: IMAP Server Interaction333738
Node: User Interaction335111
Node: Coding Systems337567
Node: Message Display340641
Node: MIME Display341701
Node: MIME Composition344339
Node: Virtual Folder Internals348569
Node: Extents and Overlays350992
Node: Timers and Concurrency354110
Node: Concept Index356118
Node: Key Index373897
Node: Command Index383779
Node: Variable Index401718
Node: Internals Index425982
Node: License443540

End Tag Table


Local Variables:
coding: iso-8859-1
End:
