   This file documents the use of MIT Scheme.

   Copyright (C) 2000, 2001 Massachusetts Institute of Technology

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

IMAIL
*****

   IMAIL is an email-reading program for MIT Scheme.  This manual
describes how to use IMAIL, what features it provides for viewing and
editing email, and how to customize its optional behavior.

Introduction
************

   IMAIL is a program for reading electronic mail.  It uses the
"Internet Message Access Protocol" (IMAP, RFC 2060) to access mail that
is stored on a server, from which IMAIL fetches individual messages on
demand.  The server may have many different "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.

   IMAP also supports the "Multipurpose Internet Mail Extensions"
(MIME, RFC 2045), which facilitate the sending and receiving of
"attachments".  The 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.

   In addition to these features, IMAIL provides a user interface very
similar to that of the Emacs Rmail mail reader (see Rmail (emacs-e20)).
IMAIL supports most of the same commands and has
most of the same key bindings as Rmail.  IMAIL is primarily intended to
be an Rmail replacement for people who wish to read their mail using an
IMAP server.  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 IMAP folder, or vice versa; this greatly simplifies the
transition from Rmail to IMAIL for those of us who have large amounts
of mail stored in files.

Getting Started
***************

   At present, IMAIL has only a very simple mechanism for connecting to
an 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 CRAM-MD5 authentication (defined in RFC 2095).  However, we
have no plans to implement data-stream encryption for the connection.(1)

   To use IMAIL, you must create an Edwin init file, called `~/.edwin'
on unix machines or `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:

     (load-option 'imail)

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

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

Note that this is syntactically similar to Scheme's `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 IMAIL connects to the server.  See Multiple Folders, for a
complete list.  By default, IMAIL tries to connect to `localhost' using
port `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 `M-x load-file'.  At this point,
you are ready to run IMAIL.  To start IMAIL and read the mail in the
`inbox' folder on your IMAP server, type `M-x imail'.

   ---------- Footnotes ----------

   (1) Here at MIT, we connect to our server using `stunnel'
(http://www.stunnel.org/) to provide end-to-end encryption.  This
provides connection security without the need to integrate the
encryption into the client or the server.

Concepts
********

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

Messages
========

   A "message", or "email message", is the basic unit of electronic
mail.  The format of a message is defined by RFC 822.  Nearly all email
messages are transmitted over the internet, which means that the
contents of such messages are further constrained by the SMTP protocol
that is used for internet message transmission, as defined in RFC 821.

   In brief, the primary constraints on an email message is that it may
contain only printable US-ASCII characters, and that lines of text in
the message may not exceed 1000 characters, _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 "Multipurpose Internet Mail Extensions" (MIME, 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 MIME standard; one notable exception is Emacs Rmail.

Folders
=======

   Another important concept is a means for grouping messages together.
All email software provides some means for doing this, and IMAIL is no
exception.  IMAIL provides objects called "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.

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

Containers
==========

   Folders can themselves be grouped together inside objects called
"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.

   IMAP containers are a little different: each IMAP mailbox is capable
of holding other mailboxes.  What this means is that, from IMAIL's
point of view, an IMAP mailbox is both a folder object and a container
object at the same time.  However, when IMAIL views an 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.

URLs
====

   In email software like Rmail, where mail is stored in files,
filenames are used to refer to groups of messages.  Since IMAIL folders
often aren't files, it is necessary to use a more general kind of
reference for folders.  To this end, IMAIL uses "Uniform Resource
Locators" (URLs) to refer to folders.(1) IMAIL currently supports two
kinds of URLs: IMAP URLs and file URLs.

   ---------- Footnotes ----------

   (1) URLs are defined in RFC 1738 and RFC 2396.

IMAP URLs
---------

   The first kind of URL is an IMAP URL,(1) which looks like this:

     imap://UNAME@HOSTNAME:PORT/MAILBOX

In this syntax, the parts `UNAME@' and `:PORT' are optional.  HOSTNAME
is the internet host name or IP address of the IMAP server.  UNAME is
the user name that identifies the account to be accessed on the server;
this defaults to your user name.  PORT is the server's IP port; this
defaults to `143' and is normally not specified.

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

     imap://localhost/inbox
     imap://localhost/inbox/sysadmin
     imap://localhost/inbox/sysadmin/equipment

Here you see several interesting properties of IMAP mailboxes.  The
first URL refers to the primary IMAP mailbox for this account, called
the "inbox".  All IMAP servers must support this mailbox, which is
always called `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 `inbox' is undefined by IMAP, so IMAIL
treats all other names as if they were case sensitive.

   The second and third URLs show how hierarchically-nested mailboxes
are referred to: by writing the components of the path, separated by
slashes.  Note that IMAP does not require particular path-separator
characters for hierarchical names, and in fact different IMAP servers
use different separators.  However, IMAIL _always_ uses the
forward-slash character as a separator, and translates to the server's
character as needed.(2)

   Another thing to note about these examples is that IMAP, unlike most
file systems, allows a folder to contain messages _and_ to have
subfolders.  This includes the `inbox' folder, as shown here.  At least
one server (Cyrus) puts _all_ subfolders for a user account under
`inbox', but this is not required by IMAP and is not generally true.

   ---------- Footnotes ----------

   (1) The syntax for IMAP URLs is defined by RFC 2192, except that
IMAIL uses only a subset of the defined syntax.

   (2) This is in opposition to RFC 2192, which specifies use of the
server-specific separator.  RFC 2396 and RFC 2718 provide compelling
arguments against this design.

File URLs
---------

   There is one other URL type supported by IMAIL: file URLs.  This
uses the `file:' URL syntax,(1) as follows:

     file://HOSTNAME/PATHNAME

Here HOSTNAME refers to the host on which the file (folder) resides.
Since IMAIL supports only files on the local file system, HOSTNAME must
be `localhost'; it may also be omitted, as in

     file:///PATHNAME

IMAIL also supports a non-standard abbreviation:

     file:/PATHNAME

   As specified by the URL standard, 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, IMAIL will accept nearly any character in a component, and
encode it if required; with few exceptions you can type any pathname
without encoding.  IMAIL always displays URLs 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, DOS-style filenames, as used by Windows and
OS/2, must be specially rewritten to conform to this style.

   The rewriting rules for DOS file URLs are not specified by the
standard, so consequently IMAIL defines its own rules for this
encoding, as follows.  A 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

     C:\My Documents\Mail\My Mail.rmail

becomes the URL

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

   ---------- Footnotes ----------

   (1) File URLs are defined in RFC 1738.

Container URLs
--------------

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

     imap://localhost/inbox/sysadmin/equipment

has the corresponding container URL

     imap://localhost/inbox/sysadmin/

Note that this is different from the URL for the `sysadmin' folder:

     imap://localhost/inbox/sysadmin

Server Connections
==================

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

   An IMAP folder can be in one of two states: "online", meaning that
there is an established network connection between IMAIL and the IMAP
server, and "offline" when there is not.  IMAIL is, at present, a very
simple IMAP mail reader: it must be online to read and manipulate mail
messages.  Mail readers that have this property are said to operate in
"online mode".(1) Do not confuse the online _state_ with online _mode_.
When we refer to online or offline in this document, it always means the
corresponding _state_.

   When an IMAP folder is selected in an IMAIL buffer, the modeline for
that buffer shows either `online' or `offline' to indicate the folder's
connection state.  Normally, an IMAP folder goes online when it is
first selected, and stays online indefinitely until it is explicitly
disconnected.(2) Commands that break the connection are explicitly
pointed out in their descriptions below; most other commands will force
an IMAP folder into the online state if it is offline.

   ---------- Footnotes ----------

   (1) IMAP also supports two other modes of operation, called "offline
mode" and "disconnected mode"; at present IMAIL can not operate in
these alternate modes.

   (2) Although IMAP servers are allowed to disconnect mail readers
that are inactive for long periods of time, IMAIL silently keeps the
connection open by periodically transmitting commands to the server.

Commands
********

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

   The most important command is `M-x imail', which is used to start
IMAIL.  With no arguments, `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 IMAP folder, `M-x imail'
will connect to the server and check for new mail.  If `M-x imail' is
given a prefix argument, it will prompt for the URL of a folder rather
than reading the primary folder.

   The IMAIL message buffer is put in `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 `IMAIL' mode, unless otherwise specified.

Navigation
==========

   The most basic thing to do with a message is to read it.  The way to
do this in IMAIL is to "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 IMAIL, you are positioned at the
first message that you have not yet seen (that is, the first one that
has the `unseen' flag; see Flags).  Move forward to see the other
new messages; move backward to reexamine old messages.

`n'
     Move to the next nondeleted message, skipping any intervening
     deleted messages (`imail-next-undeleted-message').

`p'
     Move to the previous nondeleted message
     (`imail-previous-undeleted-message').

`M-n'
     Move to the next message, including deleted messages
     (`imail-next-message').

`M-p'
     Move to the previous message, including deleted messages
     (`imail-previous-message').

`j'
     Move to the first message.  With argument N, move to message
     number N (`imail-select-message').

`>'
     Move to the last message (`imail-last-message').

`<'
     Move to the first message (`imail-first-message').

`M-u'
     Move to the first unseen message (`imail-first-unseen-message').

`M-s STRING <RET>'
     Move to the next message containing a match for STRING
     (`imail-search').

`M-- M-s STRING <RET>'
     Move to the previous message containing a match for STRING.

`C-c C-n'
     Move to the next message with the same subject
     (`imail-next-same-subject').

`C-c C-p'
     Move to the previous message with the same subject
     (`imail-previous-same-subject').

   `n' and `p' are the usual way of moving among messages in 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 `imail-next-undeleted-message' and
`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 `M-n' and `M-p' (`imail-next-message' and
`imail-previous-message').  A numeric argument to any of these commands
serves as a repeat count.

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

   The `M-s' (`imail-search') command is IMAIL's version of search.
The usual incremental search command `C-s' works in IMAIL, but it
searches only within the current message.  The purpose of `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 STRING is empty, `M-s' reuses
the string used the previous time.

   To search backward in the folder for another message, give `M-s' a
negative argument.  In IMAIL you can do this with `- M-s'.

   It is also possible to search for a message based on flags.  See
Flags.

   To find the next message with the same subject as the current
message, use `C-c C-n' (`imail-next-same-subject').  This is useful for
following the thread of an email conversation.  `C-c C-p'
(`imail-previous-same-subject') finds the previous message with the
same subject.

   To move to a message specified by absolute message number, use `j'
(`imail-select-message') with the message number as argument.  With no
argument, `j' selects the first message.  `<' (`imail-first-message')
also selects the first message.  `>' (`imail-last-message') selects the
last message.  `M-u' selects the first unseen message
(`imail-first-unseen-message').

Deleting Messages
=================

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

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

`d'
     Delete the current message, and move to the next nondeleted message
     (`imail-delete-forward').

`C-d'
     Delete the current message, and move to the previous nondeleted
     message (`imail-delete-backward').

`u'
     Undelete the current message, or move back to a deleted message and
     undelete it (`imail-undelete-previous-message').

`x'
     Expunge the IMAIL folder (`imail-expunge').

   There are two IMAIL commands for deleting messages.  Both delete the
current message and select another message.  `d'
(`imail-delete-forward') moves to the following message, skipping
messages already deleted, while `C-d' (`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.

   To make all the deleted messages finally vanish from the IMAIL
folder, type `x' (`imail-expunge').  Until you do this, you can still
"undelete" the deleted messages.  The undeletion command, `u'
(`imail-undelete-previous-message'), is designed to cancel the effect
of a `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.

   Because `imail-expunge' irreversibly deletes mail, IMAIL normally
requires confirmation before it performs the expunge.  This
confirmation is controlled by the value of the variable
`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 `verbose' (the default), the user is prompted for a yes-or-no
style confirmation; if the list contains the symbol `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 `show-messages', a window is popped up showing the messages to
be expunged; otherwise the list is not shown.

   You can usually undo a `d' with a `u' because the `u' moves back to
and undeletes the message that the `d' deleted.  But this does not work
when the `d' skips a few already-deleted messages that follow the
message being deleted; then the `u' command undeletes the last of the
messages that were skipped.  There is no clean way to avoid this
problem.  However, by repeating the `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 `M-p' command, then type `u' to
undelete it.

   A deleted message has the `deleted' flag, and as a result `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.  See Flags.

Multiple Folders
================

   IMAIL operates by default on your "primary folder", which is the
folder named `inbox' on your 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, IMAIL notices new mail and brings
it to your attention by modifying the Edwin mode line.

   You can specify a different folder to be your primary folder by
modifying one or more of IMAIL's variables.  The simplest way to do
this is to change the variable `imail-primary-folder' to contain the
URL of the folder that you wish to be your primary folder.  Normally
`imail-primary-folder' is `#f', in which case the primary folder has
the form

     imap://USER-ID@SERVER/MAILBOX

where USER-ID is the value of the variable `imail-default-user-id',
SERVER is the value of `imail-default-imap-server', and MAILBOX is the
value of `imail-default-imap-mailbox'.  `imail-default-user-id' may be
`#f' meaning to use the value of `(current-user-name)'.

   In addition to the primary folder, you can also have other folders
and edit them with IMAIL.  You can move messages into them with
explicit IMAIL commands.(1)

   One major difference between a file-based mail reader like Rmail and
an IMAP mail reader like 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 IMAP mail readers.  Consequently IMAIL provides a basic
set of commands for manipulating folders, as well as a Dired-like
folder browser.

   ---------- Footnotes ----------

   (1) While Emacs Rmail additionally supports the ability to retrieve
mail from "system inboxes" on your local computer (usually
`/var/spool/mail/USER' on unix systems), IMAIL does not.  IMAIL only
supports incoming mail when it is delivered to an IMAP server.  This
Rmail feature can easily be implemented if desired, but there has been
no call for it.

Simple Folder Commands
----------------------

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

`i URL <RET>'
     Read the folder named URL and run IMAIL on it (`imail-input').

`g'
     Get new mail for the current folder (`imail-get-new-mail').

`C-u g URL <RET>'
     Read the folder named URL and append all of its messages to the
     current folder (`imail-input-from-folder').

`o URL <RET>'
     Copy the current message into the folder named URL
     (`imail-output').

`M-o FILENAME <RET>'
     Append the current message, in human-readable form, to the file
     named FILENAME (`imail-file-message').

`C URL1 <RET> URL2 <RET>'
     Copy the folder named URL1 to URL2 (`imail-copy-folder').

`D URL <RET>'
     Delete the folder named URL (`imail-delete-folder').

`R URL1 <RET> URL2 <RET>'
     Rename the folder named URL1 to be URL2 (`imail-rename-folder').

`+ URL <RET>'
     Create a folder named URL (`imail-create-folder').

   To run IMAIL on a folder other than your primary folder, you may use
the `i' (`imail-input') command in IMAIL.  This visits the folder in
IMAIL mode.  You can use `M-x imail-input' even when not in IMAIL.

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

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

   To copy messages from another folder into the current folder, give
the `g' key a numeric argument, as in `C-u g'.  This runs the command
`imail-input-from-folder', which reads a 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.

   The `o' (`imail-output') command copies the current message into a
folder that you specify as a URL.  The folder initially defaults to the
current folder, unless you have set the variable `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 `filed'.  If the variable
`imail-delete-after-output' is true, the message is also marked as
deleted.

   The `M-o' (`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 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.

   The `C' (`imail-copy-folder') command copies an entire folder from
one place to another.  You specify two URLs, 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 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 IMAP servers.  IMAIL doesn't care; it
translates as needed.

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

   The `R' (`imail-rename-folder') command renames a specified folder.
You are prompted for two URLs, 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
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.

   The `+' (`imail-create-folder') command creates a new, empty folder.
It prompts for a 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.

The Folder Browser
------------------

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

   The `imail-browser-view-container' command is used to enter the
folder browser.  In an IMAIL folder buffer, this command is bound to
the `^' 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 IMAIL browser buffer is arranged so that each line in the browser
represents a folder or a container (or both, in the case of IMAP
containers).  Here is an example:

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

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 `+'
character at the beginning of the line.  Because our example is showing
an IMAP container, and virtually all IMAP folders are also containers,
every line in the example starts with `+'.  Additionally, if the object
is _only_ a container, then the object's name ends in the character
`/'; if the object is only a folder, or if it is both a folder and a
container, then there is no trailing `/'.

   The following commands are available in an IMAIL browser buffer.

`f'
     View the folder on the current line in an IMAIL buffer
     (`imail-browser-view-selected-folder').

`t'
     If the object on the current line is a container, toggle whether
     its contents are shown (`imail-browser-toggle-container').

`c'
     Browse the container on the current line
     (`imail-browser-view-selected-container').

`^'
     Browse the container of the this buffer's container
     (`imail-browser-view-container').

`d'
     Mark the object on the current line for subsequent deletion
     (`imail-browser-flag-folder-deletion').

`m'
     Mark the object on the current line for subsequent operations
     (`imail-browser-mark').

`u'
     Remove any mark from the current line and move to the next line
     (`imail-browser-unmark').

`<DEL>'
     Move to the previous line and remove any mark there
     (`imail-browser-unmark-backward').

`M-<DEL> CHAR'
     Remove marks from all folders (`imail-browser-unmark-all-folders').

`C URL <RET>'
     Copy the folder on the current line to the folder named URL,
     creating it if needed (`imail-browser-do-copy').

`R URL <RET>'
     Rename the object on the current line to be URL
     (`imail-browser-do-rename').

`D'
     Delete the object on the current line (`imail-browser-do-delete').
     Prompts for confirmation before performing the deletion.

`x'
     Delete all objects that have been marked for deletion
     (`imail-browser-do-flagged-delete').  Prompts for confirmation
     before any deletion is performed.

`+ URL <RET>'
     Create a folder named URL (`imail-create-folder').

`g'
     Recompute the buffer's contents by querying the server or file
     system (`imail-browser-revert').

`q'
     Kill the current buffer (`imail-browser-quit').

   If point is on a line describing a folder, use the `f'
(`imail-browser-view-selected-folder') command to view the contents of
that folder.  This selects an IMAIL folder buffer for that folder.

   If point is on a line describing a container, use the `t'
(`imail-browser-toggle-container') command to show the contents of the
container in the current buffer.  This causes the `+' on this line to
change to a `-', 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:

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

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

   If you would rather browse a container in a separate buffer, use the
`c' (`imail-browser-view-selected-container') command.  To browse the
container of this buffer's container, use the `^'
(`imail-browser-view-container') command.

   Besides simple browsing capabilities, the 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 "mark" one or more
lines, and subsequently perform an operation on all of them at once.

   There are several marking and unmarking commands.  The `m'
(`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 `d'
(`imail-browser-flag-folder-deletion') is just like `m', except that it
marks lines with `D'.  `D' marks are used to flag objects for deletion,
while `*' marks are used for everything else.

   To unmark a line, use the `u' (`imail-browser-unmark') command.
This removes any mark from the current line and moves to the next line.
Like `m', a numeric argument serves as a repeat count.  The <DEL>
(`imail-browser-unmark-backward') command moves upward, removing flags;
it is like `u' with argument `-1'.  Finally, the `M-<DEL>'
(`imail-browser-unmark-all-folders') prompts for a character and
unmarks _all_ lines marked with that character; specifying <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 N, then the next 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.

   The `C' (`imail-browser-do-copy') command copies one or more
folders.  If one folder is specified, the command prompts for the 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 URL
of an existing container, and copies the source folders into the target
container with the same names.

   The `R' (`imail-browser-do-rename') command renames one or more
folders.  If one folder is specified, the command prompts for a URL,
and changes the name of the folder to the URL.  If more than one folder
is specified, the command prompts for the 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 IMAP server, or when moving a file folder from one place to
another within the same file system.

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

   The `+' (`imail-create-folder') command creates a new, empty folder.
It prompts for a 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.

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

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

MIME Support
============

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

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

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

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

   MIME also specifies a particular kind of multipart message, of type
`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 HTML versions of the message
text.  Normally IMAIL shows only the simplest of these parts (which is
almost always plain text) and suppresses the alternatives.  However, if
you set the variable `imail-mime-show-alternatives' to `#t', IMAIL will
show these alternative forms as attachments.

   Another kind of multipart MIME message is the digest message, which
has type `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.
IMAIL can present 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
`imail-mime-collapse-digest' to `#f', the component messages of a
digest are all shown inline.

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

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

This shows various things about the attachment, including its (optional)
name, its 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.)

   IMAIL uses somewhat more complicated rules for deciding when a 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 "MIME disposition" of
`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.

   Two variables control the abbreviation of text entities.
`imail-known-mime-charsets' is a list of regular expressions that
specify the known character sets; by default it specifies US-ASCII, the
ISO 8859 character sets, and some random but commonly-seen Microsoft
Windows character sets.  The variable `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 `html' is in
this list, then MIME parts of type `text/html' are shown in-line.  Text
subtypes not appearing in this list are abbreviated as attachments.

   Here are IMAIL's MIME-specific commands:

`C-o'
     Save a MIME attachment to a file (`imail-save-attachment').

`w'
     Save an arbitrary MIME entity (message part) to a file
     (`imail-save-mime-entity').

`C-c C-t C-e'
     Toggle a MIME entity between its formatted and raw forms
     (`imail-toggle-mime-entity').

   The primary MIME command is `C-o' (`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 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, 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.

   If you want to save attachments to a specific directory, change the
variable `imail-mime-attachment-directory' to contain the name of that
directory.

   The command `w' (`imail-save-mime-entity') is similar to
`imail-save-attachment' except that it will save any 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.

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

   The command `C-c C-t C-e' (`imail-toggle-mime-entity') is similar to
`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, IMAIL by default
shows the text in abbreviated form; use `C-t' to expand it in place.