\input texinfo @c -*-texinfo-*-
@comment $Id: imail.texinfo,v 1.39 2004/10/17 03:07:06 cph Exp $
@comment %**start of header
@setfilename mit-scheme-imail
@set EDITION 1.8
@set VERSION 1.19
@set UPDATED 2004-10-16
@settitle IMAIL @value{VERSION}
@comment %**end of header
@setchapternewpage on
@finalout

@syncodeindex pg cp
@syncodeindex tp cp

@copying
This manual documents @acronym{IMAIL} @value{VERSION}.

Copyright @copyright{} 2000,2001,2002,2003 Massachusetts Institute of Technology@*
Copyright @copyright{} 2004 Massachusetts Institute of Technology

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying

@dircategory Programming Languages
@direntry
* IMAIL: (mit-scheme-imail).		IMAP/MIME mail reader for MIT/GNU Scheme
@end direntry

@titlepage
@title{IMAIL User's Manual}
@subtitle Edition @value{EDITION} for IMAIL @value{VERSION}
@subtitle @value{UPDATED}
@author by Chris Hanson
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@headings double
@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top IMAIL

@insertcopying
@end ifnottex

@menu
* Introduction::                
* Getting Started::             
* Concepts::                    
* Commands::                    
* GNU Free Documentation License::  
* Key Index::                   
* Command Index::               
* Variable Index::              
* Concept Index::               
@end menu

@node Introduction, Getting Started, Top, Top
@chapter Introduction

@cindex Internet Message Access Protocol
@cindex IMAP
@cindex RFC 2060
@acronym{IMAIL} is a program for reading electronic mail.  It uses the
@dfn{Internet Message Access Protocol} (@acronym{IMAP},
@uref{http://www.ietf.org/rfc/rfc2060.txt, , @acronym{RFC} 2060}) to
access mail that is stored on a server, from which @acronym{IMAIL}
fetches individual messages on demand.  The server may have many
different @dfn{folders} in which messages are stored, arranged in a
hierarchical structure like that of a file system.  Messages are easily
moved or copied from one folder to another.

@cindex Multipurpose Internet Mail Extensions
@cindex MIME
@cindex RFC 2045
@acronym{IMAP} also supports the @dfn{Multipurpose Internet Mail
Extensions} (@acronym{MIME}, @uref{http://www.ietf.org/rfc/rfc2045.txt,
, @acronym{RFC} 2045}), which facilitate the sending and receiving of
@dfn{attachments}.  The @acronym{IMAP} protocol supports this by
allowing you to fetch some parts of a mail message while leaving others
on the server.  So, for example, if you receive a message containing a
large attachment, it is possible to view the text of the message without
waiting for the attachment to be fetched from the server; the attachment
is fetched only if you want to view or save it.  If you aren't
interested in the attachment, you can delete the message without ever
fetching it from the server.

@cindex Rmail
In addition to these features, @acronym{IMAIL} provides a user interface
very similar to that of the Emacs Rmail mail reader (@pxref{Rmail,
Rmail, Rmail, emacs-e20, the GNU Emacs Manual}).  @acronym{IMAIL}
supports most of the same commands and has most of the same key bindings
as Rmail.  @acronym{IMAIL} is primarily intended to be an Rmail
replacement for people who wish to read their mail using an
@acronym{IMAP} server.  @acronym{IMAIL} can also read and write Rmail
files and unix mail (mbox) files, and provides the ability to copy
messages from such a file to an @acronym{IMAP} folder, or vice versa;
this greatly simplifies the transition from Rmail to @acronym{IMAIL} for
those of us who have large amounts of mail stored in files.

@node Getting Started, Concepts, Introduction, Top
@chapter Getting Started

@cindex RFC 2095
At present, @acronym{IMAIL} has only a very simple mechanism for
connecting to an @acronym{IMAP} server: it makes an unencrypted
connection to the server, and logs in with a user name and a password.
In the near future, we will implement @acronym{CRAM-MD5} authentication
(defined in @uref{http://www.ietf.org/rfc/rfc2095.txt, , @acronym{RFC}
2095}).  However, we have no plans to implement data-stream encryption
for the connection.@footnote{Here at MIT, we connect to our server using
@uref{http://www.stunnel.org/, @command{stunnel}} to provide end-to-end
encryption.  This provides connection security without the need to
integrate the encryption into the client or the server.}

To use @acronym{IMAIL}, you must create an Edwin init file, called
@file{~/.edwin} on unix machines or @file{edwin.ini} on Windows or OS/2
machines.  This file contains arbitrary Scheme expressions that are
evaluated in the Edwin environment when Edwin is started.  In addition
to any other customizations you put in this file, you must include the
following expression:

@example
(load-option 'imail)
@end example

@noindent
Next, you must tell Edwin where to find your @acronym{IMAP} server, by
setting some variables; the expression to do this must follow the call
to @code{load-option}.  Here is an example:

@example
@group
(load-option 'imail)
(set-variable! imail-default-imap-server "imap.foo.org")
@end group
@end example

@noindent
Note that this is syntactically similar to Scheme's @code{set!} special
form, but that it modifies the value of an Edwin editor variable rather
than a Scheme variable.  There are several other variables that control
how @acronym{IMAIL} connects to the server.  @xref{Multiple Folders},
for a complete list.  By default, @acronym{IMAIL} tries to connect to
@samp{localhost} using port @code{143}, and to log in using the user
name that you are logged in as.  This is the right default if you are
using stunnel on the client.

After you are finished creating the init file, you can either restart
Edwin, or you can load the file using @kbd{M-x load-file}.  At this
point, you are ready to run @acronym{IMAIL}.  To start @acronym{IMAIL}
and read the mail in the @samp{inbox} folder on your @acronym{IMAP}
server, type @kbd{M-x imail}.

@node Concepts, Commands, Getting Started, Top
@chapter Concepts

To use @acronym{IMAIL} effectively, it is helpful to know the
terminology and understand the concepts underlying @acronym{IMAIL}'s
design.  Here we will introduce you to messages, folders,
@acronym{URL}s, and server connections.

@menu
* Messages::                    
* Folders::                     
* Containers::                  
* URLs::                        
* Server Connections::          
@end menu

@node Messages, Folders, Concepts, Concepts
@section Messages

@cindex message
@cindex email message
@cindex RFC 821
@cindex RFC 822
@cindex SMTP
A @dfn{message}, or @dfn{email message}, is the basic unit of electronic
mail.  The format of a message is defined by
@uref{http://www.ietf.org/rfc/rfc0822.txt, , @acronym{RFC} 822}.  Nearly
all email messages are transmitted over the internet, which means that
the contents of such messages are further constrained by the
@acronym{SMTP} protocol that is used for internet message transmission,
as defined in @uref{http://www.ietf.org/rfc/rfc0821.txt, , @acronym{RFC}
821}.

@cindex Multipurpose Internet Mail Extensions
@cindex MIME
@cindex RFC 2045
In brief, the primary constraints on an email message is that it may
contain only printable @acronym{US-ASCII} characters, and that lines of
text in the message may not exceed 1000 characters, @emph{including} the
carriage-return/linefeed pair at the end of each line.  These
constraints are fairly strict, and do not permit messages to contain
text in languages other than English, or to contain non-textual data
such as images.  The @dfn{Multipurpose Internet Mail Extensions}
(@acronym{MIME}, @uref{http://www.ietf.org/rfc/rfc2045.txt, ,
@acronym{RFC} 2045}) provide a way to encode other kinds of text and
data so that they can be carried in an email message.  Most modern email
software supports the @acronym{MIME} standard; one notable exception is
Emacs Rmail.

@node Folders, Containers, Messages, Concepts
@section Folders

@cindex folder
Another important concept is a means for grouping messages together.
All email software provides some means for doing this, and
@acronym{IMAIL} is no exception.  @acronym{IMAIL} provides objects
called @dfn{folders}.  A folder is just an object that holds an
arbitrary number of email messages.  Messages can be added to a folder,
deleted from a folder, and moved or copied from one folder to another.

@cindex Rmail file
@cindex BABYL file
@cindex unix mailbox file
@cindex mbox file
@cindex IMAP mailbox, as folder
@cindex type of folder
In @acronym{IMAIL}, the concept of the folder is used to embrace
different grouping mechanisms.  This is because @acronym{IMAIL} provides
a uniform means for accessing different kinds of email systems.  In
particular, @acronym{IMAIL} supports access to Emacs Rmail files (also
known as BABYL files, for historical reasons), to unix mailbox files
(sometimes called @dfn{mbox} files), and to @acronym{IMAP} mailboxes.
Each of these grouping mechanisms, although implemented very
differently, is viewed as a folder by @acronym{IMAIL}.  With some
exceptions, each of these different @dfn{types} of folder are treated
exactly the same by @acronym{IMAIL}.  Finally, because @acronym{IMAIL}
is extensible, other types of folders may be supported in the future.

@node Containers, URLs, Folders, Concepts
@section Containers

@cindex container
@cindex type of container
@cindex directory, as container
Folders can themselves be grouped together inside objects called
@dfn{containers}.  A container is an object that holds folders, much in
the same way that a folder holds messages.  As for folders, the concept
of a container is a generalization of the different kinds of mechanisms
used by the underlying mail technology.  So, for example, the container
of a file folder is the directory holding that file.

@cindex IMAP mailbox, as container
@acronym{IMAP} containers are a little different: each @acronym{IMAP}
mailbox is capable of holding other mailboxes.  What this means is that,
from @acronym{IMAIL}'s point of view, an @acronym{IMAP} mailbox is both
a folder object and a container object at the same time.  However, when
@acronym{IMAIL} views an @acronym{IMAP} mailbox as a container, it is
treated differently than when it is viewed as a folder, and consequently
different notation is used in each case.

@node URLs, Server Connections, Containers, Concepts
@section URLs

@cindex Uniform Resource Locator
@cindex URL
@cindex RFC 1738
@cindex RFC 2396
In email software like Rmail, where mail is stored in files, filenames
are used to refer to groups of messages.  Since @acronym{IMAIL} folders
often aren't files, it is necessary to use a more general kind of
reference for folders.  To this end, @acronym{IMAIL} uses @dfn{Uniform
Resource Locators} (@acronym{URL}s) to refer to
folders.@footnote{@acronym{URL}s are defined in
@uref{http://www.ietf.org/rfc/rfc1738.txt, , @acronym{RFC} 1738} and
@uref{http://www.ietf.org/rfc/rfc2396.txt, , @acronym{RFC} 2396}.}
@acronym{IMAIL} currently supports two kinds of @acronym{URL}s:
@acronym{IMAP} @acronym{URL}s and file @acronym{URL}s.

@menu
* IMAP URLs::                   
* File URLs::                   
* Container URLs::              
@end menu

@node IMAP URLs, File URLs, URLs, URLs
@subsection IMAP URLs

@cindex IMAP URL
@cindex URL, IMAP
The first kind of @acronym{URL} is an @acronym{IMAP}
@acronym{URL},@footnote{The syntax for @acronym{IMAP} @acronym{URL}s is
defined by @uref{http://www.ietf.org/rfc/rfc2192.txt, , @acronym{RFC}
2192}, except that @acronym{IMAIL} uses only a subset of the defined
syntax.} which looks like this:

@example
imap://@var{uname}@@@var{hostname}:@var{port}/@var{mailbox}
@end example

@noindent
In this syntax, the parts @samp{@var{uname}@@} and @samp{:@var{port}}
are optional.  @var{Hostname} is the internet host name or @acronym{IP}
address of the @acronym{IMAP} server.  @var{Uname} is the user name that
identifies the account to be accessed on the server; this defaults to
your user name.  @var{Port} is the server's @acronym{IP} port; this
defaults to @code{143} and is normally not specified.

@cindex hierarchical mailbox
@var{Mailbox} specifies the @acronym{IMAP} mailbox (or folder, in
@acronym{IMAIL}'s terminology) that is being referred to.  Since most
@acronym{IMAP} servers support hierarchical mailboxes, @var{mailbox} is
a structured component indicating the location of the folder in the
hierarchy, much like filenames or @acronym{HTTP} @acronym{URL}s.  Here
are some examples of @acronym{IMAP} @acronym{URL}s showing different
mailbox paths:

@example
imap://localhost/inbox
imap://localhost/inbox/sysadmin
imap://localhost/inbox/sysadmin/equipment
@end example

@noindent
@cindex inbox
@cindex primary IMAP mailbox
Here you see several interesting properties of @acronym{IMAP} mailboxes.
The first @acronym{URL} refers to the primary @acronym{IMAP} mailbox for
this account, called the @dfn{inbox}.  All @acronym{IMAP} servers must
support this mailbox, which is always called @samp{inbox}; the name is
not case sensitive and may be typed in any combination of upper or lower
case letters.  However, case sensitivity for names other than
@samp{inbox} is undefined by @acronym{IMAP}, so @acronym{IMAIL} treats
all other names as if they were case sensitive.

@cindex heirarchical IMAP mailbox
The second and third @acronym{URL}s show how hierarchically-nested
mailboxes are referred to: by writing the components of the path,
separated by slashes.  Note that @acronym{IMAP} does not require
particular path-separator characters for hierarchical names, and in fact
different @acronym{IMAP} servers use different separators.  However,
@acronym{IMAIL} @emph{always} uses the forward-slash character as a
separator, and translates to the server's character as
needed.@footnote{This is in opposition to
@uref{http://www.ietf.org/rfc/rfc2192.txt, , @acronym{RFC} 2192}, which
specifies use of the server-specific separator.
@uref{http://www.ietf.org/rfc/rfc2396.txt, , @acronym{RFC} 2396} and
@uref{http://www.ietf.org/rfc/rfc2718.txt, , @acronym{RFC} 2718} provide
compelling arguments against this design.}

@cindex Cyrus
Another thing to note about these examples is that @acronym{IMAP},
unlike most file systems, allows a folder to contain messages @emph{and}
to have subfolders.  This includes the @samp{inbox} folder, as shown
here.  At least one server (@uref{http://asg.web.cmu.edu/cyrus/, ,
Cyrus}) puts @emph{all} subfolders for a user account under
@samp{inbox}, but this is not required by @acronym{IMAP} and is not
generally true.

@node File URLs, Container URLs, IMAP URLs, URLs
@subsection File URLs

@cindex file URL
@cindex URL, file
There is one other @acronym{URL} type supported by @acronym{IMAIL}: file
@acronym{URL}s.  This uses the @samp{file:} @acronym{URL}
syntax,@footnote{File @acronym{URL}s are defined in
@uref{http://www.ietf.org/rfc/rfc1738.txt, , @acronym{RFC} 1738}.} as
follows:

@example
@group
file://@var{hostname}/@var{pathname}
@end group
@end example

@noindent
Here @var{hostname} refers to the host on which the file (folder)
resides.  Since @acronym{IMAIL} supports only files on the local file
system, @var{hostname} must be @samp{localhost}; it may also be omitted,
as in

@example
file:///@var{pathname}
@end example

@noindent
@acronym{IMAIL} also supports a non-standard abbreviation:

@example
file:/@var{pathname}
@end example

As specified by the @acronym{URL} standard, @var{pathname} is a
slash-separated sequence of path components, where unusual characters
appearing in the components, such as the space character, are specially
encoded.  However, @acronym{IMAIL} will accept nearly any character in a
component, and encode it if required; with few exceptions you can type
any pathname without encoding.  @acronym{IMAIL} always displays
@acronym{URL}s with proper encoding.

In practice, this means that most unix filenames are written verbatim,
with exceptions for special characters, and with the leading slash
omitted.  However, @acronym{DOS}-style filenames, as used by Windows and
OS/2, must be specially rewritten to conform to this style.

The rewriting rules for @acronym{DOS} file @acronym{URL}s are not
specified by the standard, so consequently @acronym{IMAIL} defines its
own rules for this encoding, as follows.  A @acronym{DOS} filename is
encoded by replacing all of the backslash characters with forward-slash
characters, and by encoding unusual characters in the path components.
Finally, the drive letter is prefixed to the path with an additional
forward-slash separator.  So for, example, the filename

@example
C:\My Documents\Mail\My Mail.rmail
@end example

@noindent
becomes the @acronym{URL}

@example
file://localhost/C:/My%20Documents/Mail/My%20Mail.rmail
@end example

@node Container URLs,  , File URLs, URLs
@subsection Container URLs

@cindex container URL
@cindex URL, container
@acronym{IMAIL} also uses @acronym{URL}s to refer to containers.  The
notation used for a container is what you would expect: take a folder
@acronym{URL} and drop everything after the rightmost slash.  For
example, the folder @acronym{URL}

@example
imap://localhost/inbox/sysadmin/equipment
@end example

@noindent
has the corresponding container @acronym{URL}

@example
imap://localhost/inbox/sysadmin/
@end example

@noindent
Note that this is different from the @acronym{URL} for the
@code{sysadmin} folder:

@example
imap://localhost/inbox/sysadmin
@end example


@c **** Other stuff to consider documenting. ****
@ifset dontsetme
@itemize @bullet
@item
@acronym{MIME} entity

@item
@acronym{IMAP} extensions: UIDPLUS, NAMESPACE

@item
differences between Rmail and @acronym{IMAIL}: narrowed buffer versus
individual messages; no editing commands, flags vs. labels.
@end itemize
@end ifset

@node Server Connections,  , URLs, Concepts
@section Server Connections

@cindex connection state
Unlike a file folder, in which the folder's contents are always
available, access to an @acronym{IMAP} folder requires an active network
connection to the @acronym{IMAP} server.  This adds an additional layer
of complexity to the mail-reading process, which is reflected in the
@dfn{connection state} of an @acronym{IMAP} folder.

@cindex online state
@cindex offline state
@cindex online mode
@cindex offline mode
@cindex disconnected mode
An @acronym{IMAP} folder can be in one of two states: @dfn{online},
meaning that there is an established network connection between
@acronym{IMAIL} and the @acronym{IMAP} server, and @dfn{offline} when
there is not.  @acronym{IMAIL} is, at present, a very simple
@acronym{IMAP} mail reader: it must be online to read and manipulate
mail messages.  Mail readers that have this property are said to operate
in @dfn{online mode}.@footnote{@acronym{IMAP} also supports two other
modes of operation, called @dfn{offline mode} and @dfn{disconnected
mode}; at present @acronym{IMAIL} can not operate in these alternate
modes.} Do not confuse the online @emph{state} with online @emph{mode}.
When we refer to online or offline in this document, it always means the
corresponding @emph{state}.

When an @acronym{IMAP} folder is selected in an @acronym{IMAIL} buffer,
the modeline for that buffer shows either @samp{online} or
@samp{offline} to indicate the folder's connection state.  Normally, an
@acronym{IMAP} folder goes online when it is first selected, and stays
online indefinitely until it is explicitly
disconnected.@footnote{Although @acronym{IMAP} servers are allowed to
disconnect mail readers that are inactive for long periods of time,
@acronym{IMAIL} silently keeps the connection open by periodically
transmitting commands to the server.} Commands that break the connection
are explicitly pointed out in their descriptions below; most other
commands will force an @acronym{IMAP} folder into the online state if it
is offline.

@node Commands, GNU Free Documentation License, Concepts, Top
@chapter Commands

@acronym{IMAIL} provides a rich set of commands for manipulating
messages.  Like Rmail, most of these commands are bound to letter keys.

@findex imail
The most important command is @kbd{M-x imail}, which is used to start
@acronym{IMAIL}.  With no arguments, @kbd{M-x imail} reads the primary
folder, selects the first unseen message in the folder, then selects the
folder's buffer.  If the primary folder is an @acronym{IMAP} folder,
@kbd{M-x imail} will connect to the server and check for new mail.  If
@kbd{M-x imail} is given a prefix argument, it will prompt for the
@acronym{URL} of a folder rather than reading the primary folder.

The @acronym{IMAIL} message buffer is put in @code{IMAIL} mode, a
special mode in which most letter commands are defined to have special
meanings.  Where possible, the letters chosen for these commands are the
same as those for the corresponding Rmail commands.  The command keys
specified in this chapter are for @code{IMAIL} mode, unless otherwise
specified.

@menu
* Navigation::                  
* Deleting Messages::           
* Multiple Folders::            
* MIME Support::                
* Flags::                       
* Sending Replies::             
* Message Display::             
* Summaries::                   
* Sorting Messages::            
* Other Commands::              
@end menu

@node Navigation, Deleting Messages, Commands, Commands
@section Navigation

The most basic thing to do with a message is to read it.  The way to do
this in @acronym{IMAIL} is to @dfn{select} the message.  The usual
practice is to move sequentially through the folder, since this is the
order of receipt of messages.  When you enter @acronym{IMAIL}, you are
positioned at the first message that you have not yet seen (that is, the
first one that has the @samp{unseen} flag; @pxref{Flags}).  Move forward
to see the other new messages; move backward to reexamine old messages.

@table @kbd
@item n
Move to the next nondeleted message, skipping any intervening deleted
messages (@code{imail-next-undeleted-message}).
@item p
Move to the previous nondeleted message
(@code{imail-previous-undeleted-message}).
@item M-n
Move to the next message, including deleted messages
(@code{imail-next-message}).
@item M-p
Move to the previous message, including deleted messages
(@code{imail-previous-message}).
@item j
Move to the first message.  With argument @var{n}, move to
message number @var{n} (@code{imail-select-message}).
@item >
Move to the last message (@code{imail-last-message}).
@item <
Move to the first message (@code{imail-first-message}).
@item M-u
Move to the first unseen message (@code{imail-first-unseen-message}).
@item M-s @var{string} @key{RET}
Move to the next message containing a match for @var{string}
(@code{imail-search}).
@item M-- M-s @var{string} @key{RET}
Move to the previous message containing a match for @var{string}.
@item C-c C-n
Move to the next message with the same subject
(@code{imail-next-same-subject}).
@item C-c C-p
Move to the previous message with the same subject
(@code{imail-previous-same-subject}).
@end table

@kindex n
@findex imail-next-undeleted-message
@kindex p
@findex imail-previous-undeleted-message
@kindex M-n
@findex imail-next-message
@kindex M-p
@findex imail-previous-message
@kbd{n} and @kbd{p} are the usual way of moving among messages in
@acronym{IMAIL}.  They move through the messages sequentially, but skip
over deleted messages, which is usually what you want to do.  Their
command definitions are named @code{imail-next-undeleted-message} and
@code{imail-previous-undeleted-message}.  If you do not want to skip
deleted messages---for example, if you want to move to a message to
undelete it---use the variants @kbd{M-n} and @kbd{M-p}
(@code{imail-next-message} and @code{imail-previous-message}).  A
numeric argument to any of these commands serves as a repeat count.

In @acronym{IMAIL}, you can specify a numeric argument by typing just
the digits.  You don't need to type @kbd{C-u} first.

@kindex M-s
@findex imail-search
@cindex searching in IMAIL
The @kbd{M-s} (@code{imail-search}) command is @acronym{IMAIL}'s version
of search.  The usual incremental search command @kbd{C-s} works in
@acronym{IMAIL}, but it searches only within the current message.  The
purpose of @kbd{M-s} is to search for another message.  It reads a
string nonincrementally, then searches starting at the beginning of the
following message for a match.  It then selects that message.  If
@var{string} is empty, @kbd{M-s} reuses the string used the previous
time.

To search backward in the folder for another message, give @kbd{M-s} a
negative argument.  In @acronym{IMAIL} you can do this with @kbd{- M-s}.

It is also possible to search for a message based on flags.
@xref{Flags}.

@kindex C-c C-n
@findex imail-next-same-subject
@kindex C-c C-p
@findex imail-previous-same-subject
To find the next message with the same subject as the current message,
use @kbd{C-c C-n} (@code{imail-next-same-subject}).  This is useful for
following the thread of an email conversation.  @kbd{C-c C-p}
(@code{imail-previous-same-subject}) finds the previous message with the
same subject.

@kindex j
@findex imail-select-message
@kindex >
@findex imail-last-message
@kindex <
@findex imail-first-message
@kindex M-u
@findex imail-first-unseen-message
To move to a message specified by absolute message number, use @kbd{j}
(@code{imail-select-message}) with the message number as argument.  With
no argument, @kbd{j} selects the first message.  @kbd{<}
(@code{imail-first-message}) also selects the first message.  @kbd{>}
(@code{imail-last-message}) selects the last message.  @kbd{M-u} selects
the first unseen message (@code{imail-first-unseen-message}).

@node Deleting Messages, Multiple Folders, Navigation, Commands
@section Deleting Messages

@cindex deletion
When you no longer need to keep a message, you can @dfn{delete} it.
This flags it as ignorable, and some @acronym{IMAIL} commands pretend it
is no longer present; but it still has its place in the @acronym{IMAIL}
folder, and still has its message number.

@cindex expunging
@dfn{Expunging} the @acronym{IMAIL} folder actually removes the deleted
messages.  The remaining messages are renumbered consecutively.
Expunging is the only action that changes the message number of any
message.

@table @kbd
@item d
Delete the current message, and move to the next nondeleted message
(@code{imail-delete-forward}).
@item C-d
Delete the current message, and move to the previous nondeleted
message (@code{imail-delete-backward}).
@item u
Undelete the current message, or move back to a deleted message and
undelete it (@code{imail-undelete-previous-message}).
@item x
Expunge the @acronym{IMAIL} folder (@code{imail-expunge}).
@end table

@kindex d
@findex imail-delete-forward
@kindex C-d
@findex imail-delete-backward
There are two @acronym{IMAIL} commands for deleting messages.  Both
delete the current message and select another message.  @kbd{d}
(@code{imail-delete-forward}) moves to the following message, skipping
messages already deleted, while @kbd{C-d} (@code{imail-delete-backward})
moves to the previous nondeleted message.  If there is no nondeleted
message to move to in the specified direction, the message that was just
deleted remains current.  A numeric argument to either command reverses
the direction of motion after deletion.

@cindex undeletion
@kindex x
@findex imail-expunge
@kindex u
@findex imail-undelete-previous-message
To make all the deleted messages finally vanish from the @acronym{IMAIL}
folder, type @kbd{x} (@code{imail-expunge}).  Until you do this, you can
still @dfn{undelete} the deleted messages.  The undeletion command,
@kbd{u} (@code{imail-undelete-previous-message}), is designed to cancel
the effect of a @kbd{d} command in most cases.  It undeletes the current
message if the current message is deleted.  Otherwise it moves backward
to previous messages until a deleted message is found, and undeletes
that message.

@vindex imail-expunge-confirmation
Because @code{imail-expunge} irreversibly deletes mail, @acronym{IMAIL}
normally requires confirmation before it performs the expunge.  This
confirmation is controlled by the value of the variable
@code{imail-expunge-confirmation}, which is a list of symbols.  There
are two independent behaviors controlled by this: whether to prompt, and
whether to show the messages being expunged.  If the list contains the
symbol @code{verbose} (the default), the user is prompted for a
yes-or-no style confirmation; if the list contains the symbol
@code{brief}, the user is prompted for a y-or-n style confirmation; if
neither of these symbols is present, no confirmation is done.  If the
list contains the symbol @code{show-messages}, a window is popped up
showing the messages to be expunged; otherwise the list is not shown.

You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves
back to and undeletes the message that the @kbd{d} deleted.  But this
does not work when the @kbd{d} skips a few already-deleted messages that
follow the message being deleted; then the @kbd{u} command undeletes the
last of the messages that were skipped.  There is no clean way to avoid
this problem.  However, by repeating the @kbd{u} command, you can
eventually get back to the message that you intend to undelete.  You can
also select a particular deleted message with the @kbd{M-p} command,
then type @kbd{u} to undelete it.

A deleted message has the @samp{deleted} flag, and as a result
@samp{deleted} appears in the mode line when the current message is
deleted.  In fact, deleting or undeleting a message is nothing more than
adding or removing this flag.  @xref{Flags}.

@node Multiple Folders, MIME Support, Deleting Messages, Commands
@section Multiple Folders

@cindex primary folder
@cindex folder, primary
@acronym{IMAIL} operates by default on your @dfn{primary folder}, which
is the folder named @samp{inbox} on your @acronym{IMAP} server.  Your
incoming mail is placed in that folder by your system's mail-delivery
software.  Whenever it has an open connection to the server,
@acronym{IMAIL} notices new mail and brings it to your attention by
modifying the Edwin mode line.

@vindex imail-primary-folder
@vindex imail-default-user-id
@vindex imail-default-imap-server
@vindex imail-default-imap-mailbox
You can specify a different folder to be your primary folder by
modifying one or more of @acronym{IMAIL}'s variables.  The simplest way
to do this is to change the variable @code{imail-primary-folder} to
contain the @acronym{URL} of the folder that you wish to be your primary
folder.  Normally @code{imail-primary-folder} is @code{#f}, in which
case the primary folder has the form

@example
imap://@var{user-id}@@@var{server}/@var{mailbox}
@end example

@noindent
where @var{user-id} is the value of the variable
@code{imail-default-user-id}, @var{server} is the value of
@code{imail-default-imap-server}, and @var{mailbox} is the value of
@code{imail-default-imap-mailbox}.  @code{imail-default-user-id} may be
@code{#f} meaning to use the value of @samp{(current-user-name)}.

In addition to the primary folder, you can also have other folders and
edit them with @acronym{IMAIL}.  You can move messages into them with
explicit @acronym{IMAIL} commands.@footnote{While Emacs Rmail
additionally supports the ability to retrieve mail from ``system
inboxes'' on your local computer (usually
@file{/var/spool/mail/@var{USER}} on unix systems), @acronym{IMAIL} does
not.  @acronym{IMAIL} only supports incoming mail when it is delivered
to an @acronym{IMAP} server.  This Rmail feature can easily be
implemented if desired, but there has been no call for it.}

One major difference between a file-based mail reader like Rmail and an
@acronym{IMAP} mail reader like @acronym{IMAIL} is that file-based mail
readers do not need to provide commands to manipulate mail files (as
opposed to mail messages).  This is because ordinary file-system
commands already provide the ability to copy, delete, and rename such
files.  This isn't the case for @acronym{IMAP} mail readers.
Consequently @acronym{IMAIL} provides a basic set of commands for
manipulating folders, as well as a Dired-like folder browser.

@menu
* Simple Folder Commands::      
* Folder Browser::              
@end menu

@node Simple Folder Commands, Folder Browser, Multiple Folders, Multiple Folders
@subsection Simple Folder Commands

Within a folder's buffer, @acronym{IMAIL} provides a number of simple
commands that can be used to interact with other folders.

@table @kbd
@item i @var{URL} @key{RET}
Read the folder named @var{URL} and run @acronym{IMAIL} on it
(@code{imail-input}).

@item g
Get new mail for the current folder (@code{imail-get-new-mail}).

@item C-u g @var{URL} @key{RET}
Read the folder named @var{URL} and append all of its messages to the
current folder (@code{imail-input-from-folder}).

@item o @var{URL} @key{RET}
Copy the current message into the folder named @var{URL}
(@code{imail-output}).

@item M-o @var{filename} @key{RET}
Append the current message, in human-readable form, to the file named
@var{filename} (@code{imail-file-message}).

@item C @var{URL1} @key{RET} @var{URL2} @key{RET}
Copy the folder named @var{URL1} to @var{URL2}
(@code{imail-copy-folder}).

@item D @var{URL} @key{RET}
Delete the folder named @var{URL} (@code{imail-delete-folder}).

@item R @var{URL1} @key{RET} @var{URL2} @key{RET}
Rename the folder named @var{URL1} to be @var{URL2}
(@code{imail-rename-folder}).

@item + @var{URL} @key{RET}
Create a folder named @var{URL} (@code{imail-create-folder}).
@end table

@kindex i
@findex imail-input
To run @acronym{IMAIL} on a folder other than your primary folder, you
may use the @kbd{i} (@code{imail-input}) command in @acronym{IMAIL}.
This visits the folder in @acronym{IMAIL} mode.  You can use @kbd{M-x
imail-input} even when not in @acronym{IMAIL}.

@kindex g
@findex imail-get-new-mail
The @kbd{g} (@code{imail-get-new-mail}) command gets new mail for the
current @acronym{IMAIL} folder, and if there is new mail, moves to the
first unseen message.  This command works only on @acronym{IMAP}
folders; it does nothing on file-based folders.  Normally this command
isn't needed since @acronym{IMAIL} periodically checks for new mail in
all @acronym{IMAP} folders, but it is occasionally useful to force
@acronym{IMAIL} to get new mail immediately rather than waiting for the
next periodic mail check.  The command @kbd{M-x imail} has the same
effect as @code{imail-get-new-mail} if the primary folder is already
open in a buffer.

@vindex imail-update-interval
@vindex imail-global-mail-notification
@acronym{IMAIL} normally checks for new mail in @acronym{IMAP} folders
according to the value of the variable @code{imail-update-interval}.
This variable specifies the time between checks in seconds.  It may also
be set to @code{#f}, which disables automatic mail checking.  When
@acronym{IMAIL} detects new mail in the primary folder, it normally
modifies the mode line of all buffers to contain the string @samp{[New
Mail]}.  This can be disabled by setting the variable
@code{imail-global-mail-notification} to @code{#f}.

@kindex C-u g
@findex imail-input-from-folder
To copy messages from another folder into the current folder, give the
@kbd{g} key a numeric argument, as in @kbd{C-u g}.  This runs the
command @code{imail-input-from-folder}, which reads a @acronym{URL} and
copies all the messages from the specified folder into the current one.
The messages are appended to the current folder, in the same order that
they appear in the specified folder.

@kindex o
@findex imail-output
@vindex imail-delete-after-output
@vindex imail-output-default
The @kbd{o} (@code{imail-output}) command copies the current message
into a folder that you specify as a @acronym{URL}.  The folder initially
defaults to the current folder, unless you have set the variable
@code{imail-output-default} to a different default; after the first
message is output, the default folder becomes the one to which you last
output a message.  If the target folder doesn't exist, it is created
first; in any case, the copied message is appended to the end of the
folder.  The current message is flagged as @samp{filed}.  If the
variable @code{imail-delete-after-output} is true, the message is also
marked as deleted.

@kindex M-o
@findex imail-file-message
The @kbd{M-o} (@code{imail-file-message}) command appends the current
message to a file that you specify.  The message is written to the
file in the same format in which it appears in the @acronym{IMAIL}
buffer, preceded by a separator line if there is other text in the
file.  This simplifies the task of collecting messages into a plain
text file for future reference.  Note that attachments appear in the
output only as markers; their contents are not included in the file.

@kindex C
@findex imail-copy-folder
The @kbd{C} (@code{imail-copy-folder}) command copies an entire folder
from one place to another.  You specify two @acronym{URL}s, the source
and the target, and all of the messages from the source folder are
copied verbatim to the target folder.  The source folder is not changed.
The target folder is created if it doesn't exist.  If the target folder
does exist, the source folder's messages are appended to it.

Note that all of the commands that copy messages between folders will
work whether the folders are the same type or not.  In particular,
messages in @acronym{IMAP} folders can be copied to file folders, and
vice versa.  You can copy messages between two file folders in different
formats, or between two different @acronym{IMAP} servers.
@acronym{IMAIL} doesn't care; it translates as needed.

@kindex D
@findex imail-delete-folder
The @kbd{D} (@code{imail-delete-folder}) command deletes a specified
folder.  All of the messages in the folder, and the folder itself, are
deleted.  You will be prompted to confirm before any deletion is done.

@kindex R
@findex imail-rename-folder
The @kbd{R} (@code{imail-rename-folder}) command renames a specified
folder.  You are prompted for two @acronym{URL}s, the old name and the
new one.  At present, this command only works in limited circumstances,
specifically, when moving a folder from one place to another on a single
@acronym{IMAP} server, or when moving a file folder from one place to
another within the same file system.  The rename operation fails if the
new name is already in use.

@kindex +
@findex imail-create-folder
The @kbd{+} (@code{imail-create-folder}) command creates a new, empty
folder.  It prompts for a @acronym{URL}, and signals an error if the
name is already in use.  This command is rarely used since the
message-copying commands automatically create folders as needed.

@node Folder Browser,  , Simple Folder Commands, Multiple Folders
@subsection The Folder Browser

In addition to the simple commands just described, @acronym{IMAIL} also
provides a Dired-like browser for viewing and manipulating folders.  The
browser is generic, meaning that it will view collections of both
@acronym{IMAP} folders and file folders, although it works better and is
more useful in conjunction with @acronym{IMAP} folders.

@kindex ^
@findex imail-browser-view-container
The @code{imail-browser-view-container} command is used to enter the
folder browser.  In an @acronym{IMAIL} folder buffer, this command is
bound to the @kbd{^} key, and will bring up a folder browser that is
viewing the container of the current folder.  With a prefix argument,
you will be asked for the URL of a container to browse.

An @acronym{IMAIL} browser buffer is arranged so that each line in the
browser represents a folder or a container (or both, in the case of
@acronym{IMAP} containers).  Here is an example:

@example
@group
imap://localhost/inbox/
-----------------------
  + debian/
  + family
  + gnu/
  + ham/
  + hp-laptops/
  + linux/
  + misc/
  + mit/
  + music/
  + purchases
  + scheme/
  + software/
  + sysadmin
  + vendors/
  + vlsi
@end group
@end example

@noindent
There are several interesting features of this buffer.  The first two
lines of the buffer are a title, telling you the URL of the container
that this buffer is browsing.  Each of the remaining lines shows the
name of a folder (or container) that is inside the container.  You can
perform various operations on one of these folders by moving point
to the folder's line and invoking commands.

Each line uses special characters to give you cues about the object
being described.  If the object is a container, there is a @samp{+}
character at the beginning of the line.  Because our example is showing
an @acronym{IMAP} container, and virtually all @acronym{IMAP} folders
are also containers, every line in the example starts with @samp{+}.
Additionally, if the object is @emph{only} a container, then the
object's name ends in the character @samp{/}; if the object is only a
folder, or if it is both a folder and a container, then there is no
trailing @samp{/}.

The following commands are available in an @acronym{IMAIL} browser
buffer.

@table @kbd
@item f
View the folder on the current line in an @acronym{IMAIL} buffer
(@code{imail-browser-view-selected-folder}).

@item t
If the object on the current line is a container, toggle whether its
contents are shown (@code{imail-browser-toggle-container}).

@item c
Browse the container on the current line
(@code{imail-browser-view-selected-container}).

@item ^
Browse the container of the this buffer's container
(@code{imail-browser-view-container}).

@item d
Mark the object on the current line for subsequent deletion
(@code{imail-browser-flag-folder-deletion}).

@item m
Mark the object on the current line for subsequent operations
(@code{imail-browser-mark}).

@item u
Remove any mark from the current line and move to the next line
(@code{imail-browser-unmark}).

@item @key{DEL}
Move to the previous line and remove any mark there
(@code{imail-browser-unmark-backward}).

@item M-@key{DEL} @var{char}
Remove marks from all folders (@code{imail-browser-unmark-all-folders}).

@item C @var{URL} @key{RET}
Copy the folder on the current line to the folder named @var{URL},
creating it if needed (@code{imail-browser-do-copy}).

@item R @var{URL} @key{RET}
Rename the object on the current line to be @var{URL}
(@code{imail-browser-do-rename}).

@item D
Delete the object on the current line (@code{imail-browser-do-delete}).
Prompts for confirmation before performing the deletion.

@item x
Delete all objects that have been marked for deletion
(@code{imail-browser-do-flagged-delete}).  Prompts for confirmation
before any deletion is performed.

@item + @var{URL} @key{RET}
Create a folder named @var{URL} (@code{imail-create-folder}).

@item g
Recompute the buffer's contents by querying the server or file system
(@code{imail-browser-revert}).

@item q
Kill the current buffer (@code{imail-browser-quit}).
@end table

@kindex f
@findex imail-browser-view-selected-folder
If point is on a line describing a folder, use the @kbd{f}
(@code{imail-browser-view-selected-folder}) command to view the contents
of that folder.  This selects an @acronym{IMAIL} folder buffer for that
folder.

@kindex t
@findex imail-browser-toggle-container
If point is on a line describing a container, use the @kbd{t}
(@code{imail-browser-toggle-container}) command to show the contents of
the container in the current buffer.  This causes the @samp{+} on this
line to change to a @samp{-}, and new lines describing the contents are
inserted into the buffer following the current line.  The new lines are
slightly indented to indicate the container relationship.  For example:

@example
@group
imap://localhost/inbox/
-----------------------
  - debian/
      + bugs
      + maintainer
      + misc
  + family
  + gnu/
  + ham/
  + hp-laptops/
  + linux/
  + misc/
  + mit/
  + music/
  + purchases
  + scheme/
  + software/
  + sysadmin
  + vendors/
  + vlsi
@end group
@end example

@noindent
@findex imail-browser-mouse-toggle-container
To hide the container's content lines, use the @kbd{t} command again.
Another way to open and close containers is to click the left mouse
button on the @samp{+} or @samp{-} character for the container
(@code{imail-browser-mouse-toggle-container}).

@kindex c
@findex imail-browser-view-selected-container
@kindex ^
@findex imail-browser-view-container
If you would rather browse a container in a separate buffer, use the
@kbd{c} (@code{imail-browser-view-selected-container}) command.  To
browse the container of this buffer's container, use the @kbd{^}
(@code{imail-browser-view-container}) command.

Besides simple browsing capabilities, the @acronym{IMAIL} folder browser
also provides the ability to modify folders and containers, by copying,
renaming, and deleting them.  The commands to do this normally operate
on the object on the current line.  However, you can @dfn{mark} one or
more lines, and subsequently perform an operation on all of them at
once.

@kindex m
@findex imail-browser-mark
@kindex d
@findex imail-browser-flag-folder-deletion
There are several marking and unmarking commands.  The @kbd{m}
(@code{imail-browser-mark}) command marks the current line and moves
down to the next line.  The mark is visible as an asterisk at the
beginning of the line.  A numeric argument serves as a repeat count.
The @kbd{d} (@code{imail-browser-flag-folder-deletion}) is just like
@kbd{m}, except that it marks lines with @samp{D}.  @samp{D} marks are
used to flag objects for deletion, while @samp{*} marks are used for
everything else.

@kindex u
@findex imail-browser-unmark
@kindex DEL
@findex imail-browser-unmark-backward
@kindex M-DEL
@findex imail-browser-unmark-all-folders
To unmark a line, use the @kbd{u} (@code{imail-browser-unmark}) command.
This removes any mark from the current line and moves to the next line.
Like @kbd{m}, a numeric argument serves as a repeat count.  The
@key{DEL} (@code{imail-browser-unmark-backward}) command moves upward,
removing flags; it is like @kbd{u} with argument @code{-1}.  Finally,
the @kbd{M-@key{DEL}} (@code{imail-browser-unmark-all-folders}) prompts
for a character and unmarks @emph{all} lines marked with that character;
specifying @key{RET} as the character removes all marks.

The next three commands perform the copy, rename, and delete operations.
These commands all operate on one or more folders, which you specify
either by marking them, or by moving point to the corresponding lines.
The folders to be operated on are specified as follows.  If the command
is given a numeric argument @var{N}, then the next @var{N} folders are
specified.  Otherwise, any folders marked with an asterisk are
specified.  If there is no argument and no marked folders, then the
folder on the current line is specified.

@kindex C
@findex imail-browser-do-copy
The @kbd{C} (@code{imail-browser-do-copy}) command copies one or more
folders.  If one folder is specified, the command prompts for the
@acronym{URL} of another folder, and appends the messages of the first
folder to the end of the second folder.  The second folder is created if
necessary.  If more than one folder is specified, the command prompts
for the @acronym{URL} of an existing container, and copies the source
folders into the target container with the same names.

@kindex R
@findex imail-browser-do-rename
The @kbd{R} (@code{imail-browser-do-rename}) command renames one or more
folders.  If one folder is specified, the command prompts for a
@acronym{URL}, and changes the name of the folder to the @acronym{URL}.
If more than one folder is specified, the command prompts for the
@acronym{URL} of an existing container, and moves the folders into the
container.  Note that in both cases, it is an error if there is already
a folder with the new name.  Furthermore, this command only works in
limited circumstances, specifically, when moving a folder from one place
to another on a single @acronym{IMAP} server, or when moving a file
folder from one place to another within the same file system.

@kindex D
@findex imail-browser-do-delete
@kindex x
@findex imail-browser-do-flagged-delete
The @kbd{D} (@code{imail-browser-do-delete}) command deletes one or more
folders.  The command prompts for confirmation before any folders are
deleted.  The @kbd{x} (@code{imail-browser-do-flagged-delete}) command
is similar, except that the folders it deletes are those that have been
marked with @samp{D}.  (The @kbd{x} command is mostly provided for
compatibility with Dired.)

@kindex +
@findex imail-create-folder
The @kbd{+} (@code{imail-create-folder}) command creates a new, empty
folder.  It prompts for a @acronym{URL}, and signals an error if the
name is already in use.  This command is rarely used since the
message-copying commands automatically create folders as needed.

@kindex g
@findex imail-browser-revert
The @kbd{g} (@code{imail-browser-revert}) command re-reads the contents
of the browser buffer's container and uses that information to
regenerate the buffer's contents.  Any marks that you have placed in the
buffer are preserved.

@kindex q
@findex imail-browser-quit
The @kbd{q} (@code{imail-browser-quit}) command kills the current
buffer.  If you have marked some folders for later operation, the marks
are discarded and the operations are not performed.

@node MIME Support, Flags, Multiple Folders, Commands
@section MIME Support

@cindex Multipurpose Internet Mail Extensions
@cindex MIME
@cindex RFC 2045
@cindex MIME entity
@cindex entity, MIME
@cindex in-line
@cindex MIME attachment
@cindex attachment, MIME
The @dfn{Multipurpose Internet Mail Extensions} (@acronym{MIME}) define
a standard means for structuring mail messages.  @acronym{MIME} permits
a message to have multiple parts, each of which is called an
@dfn{entity}.  It also provides a way to associate type information with
each entity.  For example, an ordinary text message has type
@samp{text/plain}, @acronym{HTML} has type @samp{text/html}, and a
@acronym{JPEG} image has type @samp{image/jpeg}.  Additionally,
@acronym{MIME} entities may be annotated to indicate whether they should
be shown @dfn{in-line}, or whether they are @dfn{attachments} that
should be shown only upon further user action.

@acronym{IMAIL} provides simple support for @acronym{MIME} messages.
@acronym{MIME} attachments are shown in the @acronym{IMAIL} buffer by
special abbreviations.  You can write an attachment to a file.
Multipart @acronym{MIME} structures are recognized and displayed in a
clean format that suppresses unnecessary clutter.  And @acronym{MIME}
encodings such as @dfn{quoted-printable} and @dfn{base64} are
automatically decoded prior to displaying the message or saving the
attachment.

End-user formatting of @acronym{MIME} messages is a complex process,
partly because these messages can be arbitrarily complex in their
internal structure.  @acronym{IMAIL} provides several variables that
give you some control over the formatting prcess.

@vindex imail-mime-boundary-style
Many @acronym{MIME} messages have multiple parts; for example, a message
with an attachment normally contains at least two parts: the message
text and the attachment.  @acronym{IMAIL} separates the different parts
of a @acronym{MIME} message with specially-formatted lines.  There are
several styles of separator lines available, selected by changing the
value of the variable @code{imail-mime-boundary-style}.  The default
value of @code{simple} means to use long lines of hyphen characters as
the separator lines.  A value of @code{sgml} means use long lines of
hyphens that are wrapped with @samp{<!--} and @samp{-->}, which makes
them valid @acronym{SGML} comments.  A value of @code{original} means to
use the original @acronym{MIME} @dfn{boundaries}, which have certain
useful syntactic properties but are not as visually distinctive.

@vindex imail-mime-show-alternatives
@acronym{MIME} also specifies a particular kind of multipart message, of
type @samp{multipart/@-alternative}, in which the parts are different
representations of the same message.  A typical example of this is a
mailer that sends both plain text and @acronym{HTML} versions of the
message text.  Normally @acronym{IMAIL} shows only the simplest of these
parts (which is almost always plain text) and suppresses the
alternatives.  However, if you set the variable
@code{imail-mime-show-alternatives} to @code{#t}, @acronym{IMAIL} will
show these alternative forms as attachments.

@vindex imail-mime-collapse-digest
Another kind of multipart @acronym{MIME} message is the digest message,
which has type @samp{multipart/@-digest}.  Digest messages are normally
used by high-volume mailing lists to reduce the number of messages sent
to the end user; instead the user receives one message containing all of
the messages from that list in a particular time period, usually a day.
@acronym{IMAIL} can present @acronym{MIME} digest messages in one of two
formats.  The default format is to show all of the component messages of
the digest as attachments.  This is particularly useful for large
digests that you will only read a few messages from, since you can scan
the digest contents for interesting messages without downloading all of
the messages in the digest.  In the alternative format, selected by
setting @code{imail-mime-collapse-digest} to @code{#f}, the component
messages of a digest are all shown inline.

As a general rule, any @acronym{MIME} entity that contains non-textual
information is displayed as an attachment.  Attachments are normally
shown as specially-formatted abbreviations.  Here is an example:

@example
@group
<imail-part
    name="foo.doc"
    type="application/msword"
    length="55499"
    />
@end group
@end example

@noindent
This shows various things about the attachment, including its (optional)
name, its @acronym{MIME} type, and the length of the attachment in
bytes.  (The length is computed on the encoded form of the attachment,
and is generally slightly larger than the decoded length.)

@acronym{IMAIL} uses somewhat more complicated rules for deciding when a
@acronym{MIME} entity is displayed in this abbreviated format, and when
it is expanded in line.  In general, all non-text entities are
abbreviated.  Additionally, if a text entity is given a
@dfn{@acronym{MIME} disposition} of @samp{attachment}, if the character
set of the entity is unknown, if the encoding type is unknown, or if the
subtype is unknown, it is abbreviated.

@vindex imail-known-mime-charsets
@vindex imail-inline-mime-text-subtypes
Two variables control the abbreviation of text entities.
@code{imail-known-mime-charsets} is a list of regular expressions that
specify the known character sets; by default it specifies
@acronym{US-ASCII}, the @acronym{ISO} 8859 character sets, and some
random but commonly-seen Microsoft Windows character sets.  The variable
@code{imail-inline-mime-text-subtypes} contains a list of symbols, each
of which is the name of a text subtype that should be shown in line.
For example, if the symbol @code{html} is in this list, then
@acronym{MIME} parts of type @code{text/html} are shown in-line.  Text
subtypes not appearing in this list are abbreviated as attachments.

Here are @acronym{IMAIL}'s @acronym{MIME}-specific commands:

@table @kbd
@item C-o
Save a @acronym{MIME} attachment to a file
(@code{imail-save-attachment}).

@item w
Save an arbitrary @acronym{MIME} entity (message part) to a file
(@code{imail-save-mime-entity}).

@item C-c C-t C-e
Toggle a @acronym{MIME} entity between its formatted and raw forms
(@code{imail-toggle-mime-entity}).
@end table

@kindex C-o
@findex imail-save-attachment
The primary @acronym{MIME} command is @kbd{C-o}
(@code{imail-save-attachment}), which saves a single attachment to a
file.  If point is on an attachment, that is the attachment to be saved,
otherwise @acronym{IMAIL} prompts for an attachment by name.  If a
prefix argument is specified, prompting is performed even if point is on
an attachment.  Once the attachment is determined, @acronym{IMAIL}
prompts for the name of a file to save the attachment to.  The filename
is initialized from the name specified by the attachment, if any.  The
directory of the filename is initialized to the directory in which the
last attachment was saved, or the user's home directory if no
attachments have previously been saved.

@vindex imail-mime-attachment-directory
If you want to save attachments to a specific directory, change the
variable @code{imail-mime-attachment-directory} to contain the name of
that directory.

@kindex w
@findex imail-save-mime-entity
The command @kbd{w} (@code{imail-save-mime-entity}) is similar to
@code{imail-save-attachment} except that it will save any @acronym{MIME}
entity, not just an attachment.  For example, this allows you to save
the message text.  This command saves the entity that point is on; if
point is not on any entity, an error is signalled.  If the entity is
encoded, e.g. with quoted-printable or base64 encoding, it is decoded
before it is saved.  If the entity is text, it is written to the file in
text mode (relevant only under Windows and OS/2); otherwise it is
written in binary mode.

@findex imail-mouse-save-mime-entity
A simpler way to save a @acronym{MIME} entity is to point at the entity
with the mouse and click the right button
(@code{imail-mouse-save-mime-entity}).  This works the same way as
@code{imail-save-mime-entity} except that the entity is selected by the
mouse instead of point.

@kindex C-c C-t C-e
@findex imail-toggle-mime-entity
The command @kbd{C-c C-t C-e} (@code{imail-toggle-mime-entity}) is
similar to @code{imail-save-mime-entity}, except that instead of saving
the entity to a file, it toggles whether the entity is shown in-line or
in abbreviated form.  A common situation in which this is useful is when
the text of a message is in an unknown character set.  In this case,
@acronym{IMAIL} by default shows the text in abbreviated form; use
@kbd{C-t} to expand it in place.

@node Flags, Sending Replies, MIME Support, Commands
@section Flags

@cindex flags
Each message can have various @dfn{flags} assigned to it as a means of
classification.  Each flag has a name; different names are different
flags.  Any given flag is either present or absent on a particular
message.  A few flag names have standard meanings and are given to
messages automatically by @acronym{IMAIL} when appropriate.  All other
flags are assigned only by users.

@table @kbd
@item a @var{flag} @key{RET}
Assign the flag @var{flag} to the current message (@code{imail-add-flag}).
@item k @var{flag} @key{RET}
Remove the flag @var{flag} from the current message (@code{imail-kill-flag}).
@item C-M-n @var{flags} @key{RET}
Move to the next message that has one of the flags @var{flags}
(@code{imail-next-flagged-message}).
@item C-M-p @var{flags} @key{RET}
Move to the previous message that has one of the flags @var{flags}
(@code{imail-previous-flagged-message}).
@item C-M-l @var{flags} @key{RET}
Make a summary of all messages containing any of the flags @var{flags}
(@code{imail-summary-by-flags}).
@end table

@kindex a
@findex imail-add-flag
@kindex k
@findex imail-kill-flag
The @kbd{a} (@code{imail-add-flag}) and @kbd{k} (@code{imail-kill-flag})
commands allow you to assign or remove any flag on the current message.

Once you have given messages flags to classify them as you wish, there
are two ways to use the flags: in moving and in summaries.

@kindex C-M-n
@findex imail-next-flagged-message
@kindex C-M-p
@findex imail-previous-flagged-message
The command @kbd{C-M-n @var{flags} @key{RET}}
(@code{imail-next-flagged-message}) moves to the next message that has
one of the flags @var{flags}.  The argument @var{flags} specifies one or
more flag names, separated by commas.  @kbd{C-M-p}
(@code{imail-previous-flagged-message}) is similar, but moves backwards
to previous messages.  A numeric argument to either command serves as a
repeat count.

The command @kbd{C-M-l @var{flags} @key{RET}}
(@code{imail-summary-by-flags}) displays a summary containing only the
messages that have at least one of a specified set of flags.  The
argument @var{flags} is one or more flag names, separated by commas.
@xref{Summaries}, for information on summaries.

If the @var{flags} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l}
is empty, it means to use the last set of flags specified for any of
these commands.

Some flags such as @samp{deleted} and @samp{filed} have built-in
meanings and are assigned to or removed from messages automatically at
appropriate times.  Here is a list of built-in flags:

@table @samp
@item seen
Means the message has been selected, implying that the user has seen it.
Assigned to a message when it is selected by the user.  When you start
@acronym{IMAIL}, it initially shows the first message that lacks this
flag.

@item deleted
Means the message is deleted.  Assigned by deletion commands and removed
by undeletion commands (@pxref{Deleting Messages}).

@item filed
Means the message has been copied to another folder.  Assigned by the
message-copying commands (@pxref{Multiple Folders}).

@item answered
Means you have mailed an answer to the message.  Assigned by the @kbd{r}
command (@code{imail-reply}).  @xref{Sending Replies}.

@item forwarded
Means you have forwarded the message.  Assigned by the @kbd{f} command
(@code{imail-forward}).  @xref{Sending Replies}.

@item resent
Means you have resent the message.  Assigned by the command @kbd{C-u f}
(@code{imail-resend}).  @xref{Sending Replies}.
@end table

All other flags are assigned or removed only by the user, and have no
standard meaning.

@node Sending Replies, Message Display, Flags, Commands
@section Sending Replies

@acronym{IMAIL} has several commands that use Mail mode to send outgoing
mail.  What this section documents are the special commands of
@acronym{IMAIL} for entering Mail mode.  Note that the usual keys for
sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5 m}---are
available in @acronym{IMAIL} mode and work just as they usually do.

@table @kbd
@item m
Send a message (@code{imail-mail}).
@item c
Continue editing the already started outgoing message (@code{imail-continue}).
@item r
Send a reply to the current @acronym{IMAIL} message (@code{imail-reply}).
@item f
Forward the current message to other users (@code{imail-forward}).
@item C-u f
Resend the current message to other users (@code{imail-resend}).
@ifset dontsetme
@item M-m
Try sending a bounced message a second time (@code{imail-retry-failure}).
@end ifset
@end table

@kindex r
@findex imail-reply
@cindex reply to a message
The most common reason to send a message while in @acronym{IMAIL} is to
reply to the message you are reading.  To do this, type @kbd{r}
(@code{imail-reply}).  This displays the @samp{*mail*} buffer in another
window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
@samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
message you are replying to.  The @samp{To} field starts out as the
address of the person who sent the message you received, and the
@samp{CC} field starts out with all the other recipients of that
message.

@vindex imail-dont-reply-to-names
@vindex imail-default-dont-reply-to-names
You can exclude certain recipients from being placed automatically in
the @samp{CC}, using the variable @code{imail-dont-reply-to-names}.  Its
value should be a regular expression (as a string); any recipient that
the regular expression matches is excluded from the @samp{CC} field.
The default value matches your own name, and any name starting with
@samp{info-} (the value of the variable
@code{imail-default-dont-reply-to-names}).  (Those names are excluded
because there is a convention of using them for large mailing lists to
broadcast announcements.)

To omit the @samp{CC} field completely for a particular reply, enter
the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}.

@vindex imail-reply-with-re
By default, the @samp{Subject} field of a reply is initialized to the
contents of the @samp{Subject} field of the message being replied to.
However, if the variable @code{imail-reply-with-re} is set to @code{#t},
then the reply subject will be prefixed with @samp{Re:}.

Once the @samp{*mail*} buffer has been initialized, editing and sending
the mail goes as usual.  You can edit the presupplied header fields if
they are not right for you.  You can also use the commands of Mail mode,
including @kbd{C-c C-y} which yanks in the message that you are replying
to.  You can switch to the @acronym{IMAIL} buffer, select a different
message there, switch back, and yank the new current message.

@ifset dontsetme
@kindex M-m
@findex imail-retry-failure
@cindex retrying a failed message
@vindex imail-retry-ignored-headers
Sometimes a message does not reach its destination.  Mailers usually
send the failed message back to you, enclosed in a @dfn{failure
message}.  The @acronym{IMAIL} command @kbd{M-m} (@code{imail-retry-failure})
prepares to send the same message a second time: it sets up a
@samp{*mail*} buffer with the same text and header fields as before.  If
you type @kbd{C-c C-c} right away, you send the message again exactly
the same as the first time.  Alternatively, you can edit the text or
headers and then send it.  The variable
@code{imail-retry-ignored-headers}, in the same format as
@code{imail-ignored-headers} (@pxref{Appearance Options}), controls which
headers are stripped from the failed message when retrying it; it
defaults to @code{#f}.
@end ifset

@kindex f
@findex imail-forward
@cindex forwarding a message
Another frequent reason to send mail in @acronym{IMAIL} is to
@dfn{forward} the current message to other users.  @kbd{f}
(@code{imail-forward}) makes this easy by preinitializing the
@samp{*mail*} buffer with the current message as a @acronym{MIME}
attachment, and a subject designating a forwarded message.  All you have
to do is fill in the recipients and send.  When you forward a message,
recipients get a message which is ``from'' you, and which has the
original message in its contents.

@vindex imail-forward-using-mime
By default, forwarded messages are sent as @acronym{MIME} attachments,
which allows @acronym{MIME}-aware mail readers to recognize that the
attachment is a mail message and to specially present it.  However, this
means that such forwarded messages appear more complex when viewed in
mail readers that do not understand @acronym{MIME}.  @acronym{IMAIL}
deliberately minimizes the amount of encoding overhead used for
@acronym{MIME}-forwarded messages, but some people prefer not to use
@acronym{MIME} at all.  For that reason, @acronym{IMAIL} allows you to
turn off this feature, so that forwarded messages are included in the
main body of the message (as Rmail does).  To do this, set the variable
@code{imail-forward-using-mime} to @code{#f}.

@vindex imail-forward-all-headers
Normally, when @acronym{IMAIL} forwards a message, it sends only a few
of the message's header fields.  In particular, it sends only those
header fields that you see when viewing the message in @acronym{IMAIL}.
Sometimes it is desirable to send @emph{all} of the message's header
fields; @acronym{IMAIL} provides two ways to do this.  First, if you
want to send all of the header fields for a particular message, use
@code{imail-forward} with a negative argument, like this: @kbd{- f}.
Alternatively, you can set the variable @code{imail-forward-all-headers}
to @code{#t}, which will cause @emph{all} forwarded messages to retain
all of their header fields.

@kindex C-u f
@findex imail-resend
@dfn{Resending} is an alternative similar to forwarding; the difference
is that resending sends a message that is ``from'' the original sender,
just as it reached you---with a few added header fields
@samp{Resent-from} and @samp{Resent-to} to indicate that it came via
you.  To resend a message in @acronym{IMAIL}, use @kbd{C-u f}.  (@kbd{f}
runs @code{imail-forward}, which is programmed to invoke
@code{imail-resend} if you provide a numeric argument.)

@kindex m
@findex imail-mail
The @kbd{m} (@code{imail-mail}) command is used to start editing an
outgoing message that is not a reply.  It leaves the header fields
empty.  Its only difference from @kbd{C-x 4 m} is that it makes the
@acronym{IMAIL} buffer accessible for @kbd{C-c C-y}, just as @kbd{r}
does.  Thus, @kbd{m} can be used to reply to or forward a message.

@kindex c
@findex imail-continue
The @kbd{c} (@code{imail-continue}) command resumes editing the
@samp{*mail*} buffer, to finish editing an outgoing message you were
already composing, or to alter a message you have sent.

@node Message Display, Summaries, Sending Replies, Commands
@section Message Display

@acronym{IMAIL} provides several variables and commands to give you
control over how messages are formatted in the message buffer.

@vindex imail-auto-wrap
By default, @acronym{IMAIL} automatically wraps long lines at the right
margin.  It uses @dfn{adaptive fill}@footnote{See the online help for
the variable @code{adaptive-fill-regexp} for more information about
adaptive fill.} to do the wrapping, which means that common prefixes
such as @samp{>} and @samp{Chris>} will be automatically copied down
with the wrapped line.  Generally, this wrapping makes messages easier
to read.  Specifically, it is important for messages sent by clients
that use ``soft'' line breaks, because such clients expect the mail
reader to wrap lines.  However, if you'd rather not have @acronym{IMAIL}
do this for you, you can disable wrapping by setting the variable
@code{imail-auto-wrap} to @code{#f}.

@vindex imail-kept-headers
Another feature of @acronym{IMAIL} is that it filters message headers,
showing you only the most relevant ones.  There are two variables that
control how this is done, and a command that can override the filtering.
The variable @code{imail-kept-headers} contains a list of regular
expressions that are matched against message-header names (the name is
everything to the left of the colon, e.g. @samp{From} in @samp{From:
cph}).  If @code{imail-kept-headers} is a non-empty list, then only the
headers matching those regular expressions are shown.  Furthermore, the
shown headers will be in the same order as the regular expressions.

@vindex imail-ignored-headers
If @code{imail-kept-headers} is an empty list, then all of the message
headers are shown, except those matching the regular expression that is
the value of the variable @code{imail-ignored-headers}.  By default, the
value of @code{imail-ignored-headers} contains some common uninteresting
header names; this expression is identical to the default used by Rmail.
Note that @code{imail-ignored-headers} is a single regular expression,
while @code{imail-kept-headers} is a list of regular expressions.  This
is because @code{imail-ignored-headers} is meant to be an exact analog
of the Rmail variable @code{rmail-ignored-headers}.

@kindex t
@findex imail-toggle-header
Regardless of how the message-header filtering is done, you can toggle
between viewing the filtered headers and the unfiltered headers using
the @kbd{t} command (@code{imail-toggle-header}).  If filtered headers
are shown, this command replaces them with unfiltered headers, and vice
versa.

@kindex C-c C-t C-m
@findex imail-toggle-message
As you can see, @acronym{IMAIL} performs extensive transformation of a
mail message before presenting it to you: @acronym{MIME} formatting,
line wrapping, and header filtering.  Sometimes, it's desirable to see
the original message, exactly as it was received, without any formatting
at all.  The command @kbd{C-c C-t C-m} toggles the entire message between
a formatted view and a raw view.  This should be used with care, as a
message with a large attachment might not fit in memory in its raw form.

@node Summaries, Sorting Messages, Message Display, Commands
@section Summaries

A @dfn{summary} is a buffer containing one line per message to give you
an overview of the mail in an @acronym{IMAIL} folder.  Each line shows
the message number, the sender, the flags, and the subject.  Almost all
@acronym{IMAIL} commands are valid in the summary buffer also; these
apply to the message described by the current line of the summary.
Moving point in the summary buffer selects messages as you move to their
summary lines.

A summary buffer applies to a single @acronym{IMAIL} folder only; if you
are editing multiple @acronym{IMAIL} folders, each one can have its own
summary buffer.  The summary buffer name is made by appending
@samp{-summary} to the @acronym{IMAIL} buffer's name.  Normally only one
summary buffer is displayed at a time.

@menu
* Making Summaries::            
* Editing in Summaries::        
@end menu

@node Making Summaries, Editing in Summaries, Summaries, Summaries
@subsection Making Summaries

Here are the commands to create a summary for the current
@acronym{IMAIL} folder.  Once the @acronym{IMAIL} folder has a summary
buffer, changes in the @acronym{IMAIL} folder (such as deleting or
expunging messages, and getting new mail) automatically update the
summary.

@table @kbd
@item h
@itemx C-M-h
Summarize all messages (@code{imail-summary}).
@item l @var{flags} @key{RET}
@itemx C-M-l @var{flags} @key{RET}
Summarize messages that have one or more of the specified flags
(@code{imail-summary-by-flags}).
@item C-M-r @var{rcpts} @key{RET}
Summarize messages that have one or more of the specified recipients
(@code{imail-summary-by-recipients}).
@item C-M-t @var{topic} @key{RET}
Summarize messages that have a match for the specified regexp
@var{topic} in their subjects (@code{imail-summary-by-topic}).
@item C-M-s @var{regexp} @key{RET}
Summarize messages that have a match for the specified regexp
anywhere in their header (@code{imail-summary-by-regexp}).
@end table

@kindex h
@findex imail-summary
The @kbd{h} or @kbd{C-M-h} (@code{imail-summary}) command fills the
summary buffer for the current @acronym{IMAIL} folder with a summary of
all the messages in the folder.  It then displays and selects the
summary buffer in another window.

@kindex l
@kindex C-M-l
@findex imail-summary-by-flags
@kbd{C-M-l @var{flags} @key{RET}} (@code{imail-summary-by-flags}) makes
a partial summary mentioning only the messages that have one or more of
the flags @var{flags}.  @var{flags} should contain flag names separated
by commas.

@kindex C-M-r
@findex imail-summary-by-recipients
@kbd{C-M-r @var{rcpts} @key{RET}} (@code{imail-summary-by-recipients})
makes a partial summary mentioning only the messages that have one or
more of the recipients @var{rcpts}.  @var{rcpts} should contain mailing
addresses separated by commas.

@kindex C-M-t
@findex imail-summary-by-topic
@kbd{C-M-t @var{topic} @key{RET}} (@code{imail-summary-by-topic}) makes
a partial summary mentioning only the messages whose subjects have a
match for the regular expression @var{topic}.

@kindex C-M-s
@findex imail-summary-by-regexp
@kbd{C-M-s @var{regexp} @key{RET}} (@code{imail-summary-by-regexp})
makes a partial summary mentioning only the messages whose headers
contain a match for the regular expression @var{regexp}.  This match
includes all lines in the header, including for example the date and
from lines.

Note that there is only one summary buffer for any @acronym{IMAIL}
folder; making one kind of summary discards any previously made summary.

@vindex imail-summary-height
There are several variables that affect how summaries are displayed.
@code{imail-summary-height} controls the height of the summary window.
If it is an exact positive integer, the summary window is that many
lines high.  Alternatively, if it is a real number between 0 and 1
exclusive, the height of the summary window is computed by multiplying
the number of lines in the message window by @code{imail-summary-height}
and rounding to the nearest integer.

@vindex imail-summary-fixed-layout
If the variable @code{imail-summary-fixed-layout} is set to @code{#t},
then an @acronym{IMAIL} message buffer and its associated summary buffer
are always shown in a fixed window layout (provided the summary buffer
exists).  Selecting either buffer causes all other windows in the
current editor frame to be deleted, then splits the frame into two
windows showing the summary buffer and message buffer.  Selecting any
other buffer when this layout is displayed causes both windows to be
deleted, and the other buffer displayed in a single window filling the
editor frame.  Basically, this causes the message and summary buffers to
be treated as a unit most of the time.  Currently, the default for
@code{imail-summary-fixed-layout} is @code{#f}, but the feature has been
very popular and the default may be changed to @code{#t} in a future
release.

@vindex imail-summary-pop-up-message
When fixed layout is not used, the variable
@code{imail-summary-pop-up-message} provides a different kind of window
splitting for message and summary buffers.  If this is set to @code{#t}
(the default), then selecting a new message in the summary buffer causes
the message buffer to be popped up in a new window if it isn't already
visible.

@vindex imail-summary-highlight-message
If the variable @code{imail-summary-highlight-message} is @code{#t}, the
message currently selected in the message buffer is highlighted in the
summary buffer.  This aids navigation in the summary buffer and is thus
the default.  Set it to @code{#f} if you don't like the highlighting.

@vindex imail-summary-show-date
By default, the summary buffer has five columns: flags, message number,
message length, subject, and author.  If @code{imail-summary-show-date}
is set to @code{#t}, a sixth column containing an abbreviated date
appears between the message number and the subject.

@vindex imail-summary-subject-width
The width of the subject column is specified by the value of
@code{imail-summary-subject-width}; subject fields longer than this
number of characters are truncated.

@node Editing in Summaries,  , Making Summaries, Summaries
@subsection Editing in Summaries

You can use the @acronym{IMAIL} summary buffer to do almost anything you
can do in the @acronym{IMAIL} buffer itself.  In fact, once you have a
summary buffer, there's no need to switch back to the @acronym{IMAIL}
buffer.

You can select and display various messages in the @acronym{IMAIL}
buffer, from the summary buffer, just by moving point in the summary
buffer to different lines.  It doesn't matter what Emacs command you use
to move point; whichever line point is on at the end of the command,
that message is selected in the @acronym{IMAIL} buffer.

Almost all @acronym{IMAIL} commands work in the summary buffer as well
as in the @acronym{IMAIL} buffer.  Thus, @kbd{d} in the summary buffer
deletes the current message, @kbd{u} undeletes, and @kbd{x} expunges.
@kbd{o} outputs the current message to a folder; @kbd{C-o} saves an
attachment from the current message; @kbd{r} starts a reply to it.  You
can scroll the current message while remaining in the summary buffer
using @key{SPC} and @key{DEL}.

@kindex e
@findex imail-summary-select-message
The @acronym{IMAIL} commands to move between messages also work in the
summary buffer, but with a twist: they move through the set of messages
included in the summary.  They also ensure the @acronym{IMAIL} buffer
appears on the screen (unlike cursor motion commands, which update the
contents of the @acronym{IMAIL} buffer but don't display it in a window
unless it already appears).  You can always display the message indicated
by point using the @key{e} command (@code{imail-summary-select-message}).

When you are finished using the summary, type @kbd{C-x k @key{RET}} to
delete the summary buffer's window.

@node Sorting Messages, Other Commands, Summaries, Commands
@section Sorting Messages

@acronym{IMAIL} provides several commands that change the order of
messages within a folder.  These commands are closely modelled on
those of Rmail.  Note that these commands don't modify the folder
itself; they only modify the way that the folder behaves.  This means
that if a folder buffer is deleted, the sort order associated with
that buffer is deleted too.

@table @kbd
@item C-c C-s C-v
@kindex C-c C-s C-v
@findex imail-sort-by-arrival
Sort messages of current @acronym{IMAIL} folder by arrival time
(@code{imail-sort-by-arrival}).  This is the default; this sort undoes
any other sorting on the folder.

@item C-c C-s C-d
@kindex C-c C-s C-d
@findex imail-sort-by-date
Sort messages of current @acronym{IMAIL} folder by date
(@code{imail-sort-by-date}).

@item C-c C-s C-s
@kindex C-c C-s C-s
@findex imail-sort-by-subject
Sort messages of current @acronym{IMAIL} folder by subject
(@code{imail-sort-by-subject}).

@item C-c C-s C-a
@kindex C-c C-s C-a
@findex imail-sort-by-author
Sort messages of current @acronym{IMAIL} folder by author's name
(@code{imail-sort-by-author}).

@item C-c C-s C-r
@kindex C-c C-s C-r
@findex imail-sort-by-recipient
Sort messages of current @acronym{IMAIL} folder by recipient's names
(@code{imail-sort-by-recipient}).

@item C-c C-s C-c
@kindex C-c C-s C-c
@findex imail-sort-by-correspondent
Sort messages of current @acronym{IMAIL} folder by the name of the
other correspondent (@code{imail-sort-by-correspondent}).
@end table

The @acronym{IMAIL} sort commands perform a @emph{stable sort}: if
there is no reason to prefer either one of two messages, their order
remains unchanged.  You can use this to sort by more than one
criterion.  For example, if you use @code{imail-sort-by-date} and then
@code{imail-sort-by-author}, messages from the same author appear in
order by date.

With a numeric argument, all these commands reverse the order of
comparison.  This means they sort messages from newest to oldest, from
biggest to smallest, or in reverse alphabetical order.

@node Other Commands,  , Sorting Messages, Commands
@section Other Commands

This section documents a handful of commands and variables that don't
fit into any of the other documentation categories.

@table @kbd
@item q
Quit out of @acronym{IMAIL} (@code{imail-quit}).  This closes all open
@acronym{IMAP} connections and buries all @acronym{IMAIL} buffers.  With
prefix argument, only affects the current @acronym{IMAIL} buffer,
leaving any other @acronym{IMAIL} buffers alone.

@item M-d
Disconnect from the @acronym{IMAP} server (@code{imail-disconnect}).

@item b
Bury the @acronym{IMAIL} buffer (@code{imail-bury}).

@item s
Save changes in the current folder to disk (@code{imail-save-folder}).
@end table

@kindex q
@findex imail-quit
@cindex close folder
@cindex folder, close
When you are finished reading mail in a folder, use the @kbd{q} command
(@code{imail-quit}).  This command @dfn{closes} the folder, then buries
the buffer.  Closing a folder has different effects, depending on the
type of folder.  Closing an @acronym{IMAP} folder causes @acronym{IMAIL}
to disconnect from the @acronym{IMAP} server (go offline).  Closing a
file folder saves any changes out to the corresponding file.  In both
cases, internal data structures may be dropped, requiring them to be
rebuilt, should the folder later be re-opened.  In no case are any
changes made to the folder's contents; in particular, deleted messages
are @emph{not} expunged.

On @acronym{IMAP} folders, the @kbd{q} command is equivalent to @kbd{M-d
b}.  On file folders, the @kbd{q} command is equivalent to @kbd{s b}.

@kindex M-d
@findex imail-disconnect
The @kbd{M-d} command (@code{imail-disconnect}) disconnects
@acronym{IMAIL} from the @acronym{IMAP} server (goes offline).  This has
no effect on file folders.

@kindex b
@findex imail-bury
The @kbd{b} command (@code{imail-bury}) buries the selected
@acronym{IMAIL} buffer.  @dfn{Burying} a buffer means moving it to the
bottom of the buffer list and selecting another buffer from the top of
the list.  This is similar to the command @code{bury-buffer}, except
that any summary buffer associated with this buffer is also buried, and
if a window was created to hold the summary buffer, it is deleted.

@kindex s
@findex imail-save-folder
The @kbd{s} command (@code{imail-save-folder}) saves out any changes to
the selected @acronym{IMAIL} folder.  For file folders, this means
writing the folder back out to its file.  For @acronym{IMAP} folders,
this no effect.  In no case are any changes made to the folder's
contents; in particular, deleted messages are @emph{not} expunged.

@vindex imail-body-cache-limit
@acronym{IMAIL} normally caches @acronym{IMAP} message bodies in memory
in order to increase performance.  The variable
@code{imail-body-cache-limit} gives you some control over how this
caching is done.  @code{imail-body-cache-limit} is normally set to a
positive integer, meaning that any message body or in-line
@acronym{MIME} entity whose size in bytes is less than this number is
cached.  However, caching can be entirely disabled by setting
@code{imail-body-cache-limit} to @code{#f}, or made unconditional by
setting it to @code{#t}.

@vindex imail-pass-phrase-retention-time
Another thing that @acronym{IMAIL} caches is @acronym{IMAP} passwords.
This is done so that you don't have to keep typing your password
whenever you connect to a new @acronym{IMAP} folder.  However, this is
also a security risk, because the password is kept in Scheme's memory.
The variable @code{imail-pass-phrase-retention-time} says how long
passwords are cached, in minutes.  Normally this is set to 30 minutes,
but if you are paranoid you can set it to zero to disable password
caching altogether.  Scheme keeps track of the use of each password,
and deletes its copy of the password when it has expired.  Additionally,
Scheme stores passwords in an obscured form, to prevent them being seen
during casual browsing through memory structures, but this does
@emph{not} provide any protection against a deliberate attempt to find
the password.

@node GNU Free Documentation License, Key Index, Commands, Top
@appendix GNU Free Documentation License

@cindex FDL, GNU Free Documentation License
@center Version 1.2, November 2002

@display
Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@enumerate 0
@item
PREAMBLE

The purpose of this License is to make a manual, textbook, or other
functional and useful document @dfn{free} in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.

This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

@item
APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The ``Document'', below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as ``you''.  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.

A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A ``Secondary Section'' is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject.  (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.

The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.

A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not ``Transparent'' is called ``Opaque''.

Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
PostScript or @acronym{PDF} designed for human modification.  Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
@acronym{JPG}.  Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
PostScript or @acronym{PDF} produced by some word processors for
output purposes only.

The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements'',
``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.

The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.

@item
VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

@item
COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.

@item
MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document).  You may use the same title as a previous version
if the original publisher of that version gives permission.

@item
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.

@item
State on the Title page the name of the publisher of the
Modified Version, as the publisher.

@item
Preserve all the copyright notices of the Document.

@item
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.

@item
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.

@item
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.

@item
Include an unaltered copy of this License.

@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page.  If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.

@item
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on.  These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.

@item
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.

@item
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles.  Section numbers
or the equivalent are not considered part of the section titles.

@item
Delete any section Entitled ``Endorsements''.  Such a section
may not be included in the Modified Version.

@item
Do not retitle any existing section to be Entitled ``Endorsements'' or
to conflict in title with any Invariant Section.

@item
Preserve any Warranty Disclaimers.
@end enumerate

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section Entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

@item
COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
and any sections Entitled ``Dedications''.  You must delete all
sections Entitled ``Endorsements.''

@item
COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.

@item
AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.

@item
TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warrany Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.

If a section in the Document is Entitled ``Acknowledgements'',
``Dedications'', or ``History'', the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.

@item
TERMINATION

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation 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.  See
@uref{http://www.gnu.org/copyleft/}.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate

@page
@appendixsec ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:

@smallexample
@group
  Copyright (C)  @var{year}  @var{your name}.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.2
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.
@end group
@end smallexample

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with...Texts.'' line with this:

@smallexample
@group
    with the Invariant Sections being @var{list their titles}, with
    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
    being @var{list}.
@end group
@end smallexample

If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.

@node Key Index, Command Index, GNU Free Documentation License, Top
@appendix Key Index
@printindex ky

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

@node Variable Index, Concept Index, Command Index, Top
@appendix Variable Index
@printindex vr

@node Concept Index,  , Variable Index, Top
@appendix Concept Index
@printindex cp

@bye
