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 not 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.  If
`vm-save-message' is given a prefix argument N, the current message
plus the next N-1 message are saved.  If N is negative, the current
message and the previous N-1 messages are saved.  Messages saved with
`vm-save-message' are flagged "filed".

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

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

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

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

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

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

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

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

VM can save messages to a folder in two distinct ways.  The message
can be appended directly to the folder on disk, or the folder can be
visited as Emacs would visit any other file and the message be
appended to that buffer.  In the latter method you must save the
buffer yourself to change the on-disk copy of the folder.  The
variable `vm-visit-when-saving' controls which method is used.  A
value of `t' 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' or `A' commands (see
below).  The variable `vm-delete-after-archiving' works like
`vm-delete-after-saving' but applies to the `A'
(`vm-auto-archive-messages') command instead.

Other commands:

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

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

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