</sect1>
-<sect1 id="pop">
-<title>POP3 Support (OPTIONAL)</title>
+<sect1 id="urlview">
+<title>Start a WWW Browser on URLs (EXTERNAL)</title>
<para>
-If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis>
-script with the <emphasis>--enable-pop</emphasis> flag), it has the ability to work
-with mailboxes located on a remote POP3 server and fetch mail for local
-browsing.
-</para>
+If a message contains URLs (<emphasis>unified resource locator</emphasis> = address in the
+WWW space like <emphasis>http://www.mutt.org/</emphasis>), it is efficient to get
+a menu with all the URLs and start a WWW browser on one of them. This
+functionality is provided by the external urlview program which can be
+retrieved at <ulink
+url="ftp://ftp.mutt.org/mutt/contrib/"
+>ftp://ftp.mutt.org/mutt/contrib/</ulink
+> and the configuration commands:
-<para>
-You can access the remote POP3 mailbox by selecting the folder
-<literal>pop://popserver/</literal>.
-</para>
+<screen>
+macro index \cb |urlview\n
+macro pager \cb |urlview\n
+</screen>
-<para>
-You can select an alternative port by specifying it with the server, ie:
-<literal>pop://popserver:port/</literal>.
</para>
-<para>
-You can also specify different username for each folder, ie:
-<literal>pop://username@popserver[:port]/</literal>.
-</para>
+</sect1>
-<para>
-Polling for new mail is more expensive over POP3 than locally. For this
-reason the frequency at which Mutt will check for mail remotely can be
-controlled by the
-<link linkend="pop-checkinterval">$pop_checkinterval</link>
-variable, which defaults to every 60 seconds.
-</para>
+</chapter>
-<para>
-If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis>
-script with the <emphasis>--with-ssl</emphasis> flag), connections to POP3 servers
-can be encrypted. This naturally requires that the server supports
-SSL encrypted connections. To access a folder with POP3/SSL, you should
-use pops: prefix, ie:
-<literal>pops://[username@]popserver[:port]/</literal>.
-</para>
+<chapter id="mimesupport">
+<title>Mutt's MIME Support</title>
<para>
-Another way to access your POP3 mail is the <emphasis>fetch-mail</emphasis> function
-(default: G). It allows to connect to <link linkend="pop-host">$pop_host</link>, fetch all your new mail and place it in the
-local <link linkend="spoolfile">$spoolfile</link>. After this
-point, Mutt runs exactly as if the mail had always been local.
+Quite a bit of effort has been made to make Mutt the premier text-mode
+MIME MUA. Every effort has been made to provide the functionality that
+the discerning MIME user requires, and the conformance to the standards
+wherever possible. When configuring Mutt for MIME, there are two extra
+types of configuration files which Mutt uses. One is the
+<literal>mime.types</literal> file, which contains the mapping of file extensions to
+IANA MIME types. The other is the <literal>mailcap</literal> file, which specifies
+the external commands to use for handling specific MIME types.
</para>
+<sect1 id="using-mime">
+<title>Using MIME in Mutt</title>
+
<para>
-<emphasis role="bold">Note:</emphasis> If you only need to fetch all messages to local mailbox
-you should consider using a specialized program, such as <ulink
-url="http://www.ccil.org/~esr/fetchmail"
->fetchmail</ulink
->
+There are three areas/menus in Mutt which deal with MIME, they are the
+pager (while viewing a message), the attachment menu and the compose
+menu.
</para>
-</sect1>
-
-<sect1 id="imap">
-<title>IMAP Support (OPTIONAL)</title>
+<sect2>
+<title>Viewing MIME messages in the pager</title>
<para>
-If Mutt was compiled with IMAP support (by running the <emphasis>configure</emphasis>
-script with the <emphasis>--enable-imap</emphasis> flag), it has the ability to work
-with folders located on a remote IMAP server.
+When you select a message from the index and view it in the pager, Mutt
+decodes the message to a text representation. Mutt internally supports
+a number of MIME types, including <literal>text/plain, text/enriched,
+message/rfc822, and message/news</literal>. In addition, the export
+controlled version of Mutt recognizes a variety of PGP MIME types,
+including PGP/MIME and application/pgp.
</para>
<para>
-You can access the remote inbox by selecting the folder
-<literal>imap://imapserver/INBOX</literal>, where <literal>imapserver</literal> is the name of the
-IMAP server and <literal>INBOX</literal> is the special name for your spool mailbox on
-the IMAP server. If you want to access another mail folder at the IMAP
-server, you should use <literal>imap://imapserver/path/to/folder</literal> where
-<literal>path/to/folder</literal> is the path of the folder you want to access.
-</para>
+Mutt will denote attachments with a couple lines describing them.
+These lines are of the form:
-<para>
-You can select an alternative port by specifying it with the server, ie:
-<literal>imap://imapserver:port/INBOX</literal>.
+<screen>
+[-- Attachment #1: Description --]
+[-- Type: text/plain, Encoding: 7bit, Size: 10000 --]
+</screen>
+
+Where the <literal>Description</literal> is the description or filename given for the
+attachment, and the <literal>Encoding</literal> is one of
+<literal>7bit/8bit/quoted-printable/base64/binary</literal>.
</para>
<para>
-You can also specify different username for each folder, ie:
-<literal>imap://username@imapserver[:port]/INBOX</literal>.
+If Mutt cannot deal with a MIME type, it will display a message like:
+
+<screen>
+[-- image/gif is unsupported (use 'v' to view this part) --]
+</screen>
+
</para>
+</sect2>
+
+<sect2 id="attach-menu">
+<title>The Attachment Menu</title>
+
<para>
-If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis>
-script with the <emphasis>--with-ssl</emphasis> flag), connections to IMAP servers
-can be encrypted. This naturally requires that the server supports
-SSL encrypted connections. To access a folder with IMAP/SSL, you should
-use <literal>imaps://[username@]imapserver[:port]/path/to/folder</literal> as your
-folder path.
+The default binding for <literal>view-attachments</literal> is `v', which displays the
+attachment menu for a message. The attachment menu displays a list of
+the attachments in a message. From the attachment menu, you can save,
+print, pipe, delete, and view attachments. You can apply these
+operations to a group of attachments at once, by tagging the attachments
+and by using the ``tag-prefix'' operator. You can also reply to the
+current message from this menu, and only the current attachment (or the
+attachments tagged) will be quoted in your reply. You can view
+attachments as text, or view them using the mailcap viewer definition.
</para>
<para>
-Pine-compatible notation is also supported, ie
-<literal>{[username@]imapserver[:port][/ssl]}path/to/folder</literal>
+Finally, you can apply the usual message-related functions (like
+<link linkend="resend-message">resend-message</link>, and the reply
+and forward functions) to attachments of type <literal>message/rfc822</literal>.
</para>
<para>
-Note that not all servers use / as the hierarchy separator. Mutt should
-correctly notice which separator is being used by the server and convert
-paths accordingly.
+See the help on the attachment menu for more information.
</para>
+</sect2>
+
+<sect2 id="compose-menu">
+<title>The Compose Menu</title>
+
<para>
-When browsing folders on an IMAP server, you can toggle whether to look
-at only the folders you are subscribed to, or all folders with the
-<emphasis>toggle-subscribed</emphasis> command. See also the
-<link linkend="imap-list-subscribed">$imap_list_subscribed</link> variable.
+The compose menu is the menu you see before you send a message. It
+allows you to edit the recipient list, the subject, and other aspects
+of your message. It also contains a list of the attachments of your
+message, including the main body. From this menu, you can print, copy,
+filter, pipe, edit, compose, review, and rename an attachment or a
+list of tagged attachments. You can also modifying the attachment
+information, notably the type, encoding and description.
</para>
<para>
-Polling for new mail on an IMAP server can cause noticeable delays. So, you'll
-want to carefully tune the
-<link linkend="mail-check">$mail_check</link>
-and
-<link linkend="timeout">$timeout</link>
-variables. Personally I use
+Attachments appear as follows:
<screen>
-set mail_check=90
-set timeout=15
+- 1 [text/plain, 7bit, 1K] /tmp/mutt-euler-8082-0 <no description>
+ 2 [applica/x-gunzip, base64, 422K] ~/src/mutt-0.85.tar.gz <no description>
</screen>
-with relatively good results over my slow modem line.
</para>
<para>
-Note that if you are using mbox as the mail store on UW servers prior to
-v12.250, the server has been reported to disconnect a client if another client
-selects the same folder.
+The '-' denotes that Mutt will delete the file after sending (or
+postponing, or canceling) the message. It can be toggled with the
+<literal>toggle-unlink</literal> command (default: u). The next field is the MIME
+content-type, and can be changed with the <literal>edit-type</literal> command
+(default: ˆT). The next field is the encoding for the attachment,
+which allows a binary message to be encoded for transmission on 7bit
+links. It can be changed with the <literal>edit-encoding</literal> command
+(default: ˆE). The next field is the size of the attachment,
+rounded to kilobytes or megabytes. The next field is the filename,
+which can be changed with the <literal>rename-file</literal> command (default: R).
+The final field is the description of the attachment, and can be
+changed with the <literal>edit-description</literal> command (default: d).
</para>
-<sect2>
-<title>The Folder Browser</title>
+</sect2>
-<para>
-As of version 1.2, mutt supports browsing mailboxes on an IMAP
-server. This is mostly the same as the local file browser, with the
-following differences:
+</sect1>
-<itemizedlist>
-<listitem>
+<sect1 id="mime-types">
+<title>MIME Type configuration with <literal>mime.types</literal></title>
<para>
-In lieu of file permissions, mutt displays the string "IMAP",
-possibly followed by the symbol "+", indicating
-that the entry contains both messages and subfolders. On
-Cyrus-like servers folders will often contain both messages and
-subfolders.
+When you add an attachment to your mail message, Mutt searches your
+personal mime.types file at <literal>${HOME}/.mime.types</literal>, and then
+the system mime.types file at <literal>/usr/local/share/mutt/mime.types</literal> or
+<literal>/etc/mime.types</literal>
</para>
-</listitem>
-<listitem>
<para>
-For the case where an entry can contain both messages and
-subfolders, the selection key (bound to <literal>enter</literal> by default)
-will choose to descend into the subfolder view. If you wish to view
-the messages in that folder, you must use <literal>view-file</literal> instead
-(bound to <literal>space</literal> by default).
+The mime.types file consist of lines containing a MIME type and a space
+separated list of extensions. For example:
+
+<screen>
+application/postscript ps eps
+application/pgp pgp
+audio/x-aiff aif aifc aiff
+</screen>
+
+A sample <literal>mime.types</literal> file comes with the Mutt distribution, and
+should contain most of the MIME types you are likely to use.
</para>
-</listitem>
-<listitem>
<para>
-You can create, delete and rename mailboxes with the
-<literal>create-mailbox</literal>, <literal>delete-mailbox</literal>, and
-<literal>rename-mailbox</literal> commands (default bindings: <literal>C</literal>,
-<literal>d</literal> and <literal>r</literal>, respectively). You may also
-<literal>subscribe</literal> and <literal>unsubscribe</literal> to mailboxes (normally
-these are bound to <literal>s</literal> and <literal>u</literal>, respectively).
+If Mutt can not determine the mime type by the extension of the file you
+attach, it will look at the file. If the file is free of binary
+information, Mutt will assume that the file is plain text, and mark it
+as <literal>text/plain</literal>. If the file contains binary information, then Mutt will
+mark it as <literal>application/octet-stream</literal>. You can change the MIME
+type that Mutt assigns to an attachment by using the <literal>edit-type</literal>
+command from the compose menu (default: ˆT). The MIME type is actually a
+major mime type followed by the sub-type, separated by a '/'. 6 major
+types: application, text, image, video, audio, and model have been approved
+after various internet discussions. Mutt recognizes all of these if the
+appropriate entry is found in the mime.types file. It also recognizes other
+major mime types, such as the chemical type that is widely used in the
+molecular modeling community to pass molecular data in various forms to
+various molecular viewers. Non-recognized mime types should only be used
+if the recipient of the message is likely to be expecting such attachments.
</para>
-</listitem>
-</itemizedlist>
+</sect1>
-</para>
-
-</sect2>
-
-<sect2>
-<title>Authentication</title>
+<sect1 id="mime-viewers">
+<title>MIME Viewer configuration with <literal>mailcap</literal></title>
<para>
-Mutt supports four authentication methods with IMAP servers: SASL,
-GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
-NTLM authentication for you poor exchange users out there, but it has
-yet to be integrated into the main tree). There is also support for
-the pseudo-protocol ANONYMOUS, which allows you to log in to a public
-IMAP server without having an account. To use ANONYMOUS, simply make
-your username blank or "anonymous".
+Mutt supports RFC 1524 MIME Configuration, in particular the Unix
+specific format specified in Appendix A of RFC 1524. This file format
+is commonly referred to as the mailcap format. Many MIME compliant
+programs utilize the mailcap format, allowing you to specify handling
+for all MIME types in one place for all programs. Programs known to
+use this format include Netscape, XMosaic, lynx and metamail.
</para>
<para>
-SASL is a special super-authenticator, which selects among several protocols
-(including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure
-method available on your host and the server. Using some of these methods
-(including DIGEST-MD5 and possibly GSSAPI), your entire session will be
-encrypted and invisible to those teeming network snoops. It is the best
-option if you have it. To use it, you must have the Cyrus SASL library
-installed on your system and compile mutt with the <emphasis>--with-sasl</emphasis> flag.
+In order to handle various MIME types that Mutt can not handle
+internally, Mutt parses a series of external configuration files to
+find an external handler. The default search string for these files
+is a colon delimited list containing the following files:
+
+<orderedlist>
+<listitem><para><literal>$HOME/.mailcap</literal></para></listitem>
+<listitem><para><literal>$PKGDATADIR/mailcap</literal></para></listitem>
+<listitem><para><literal>$SYSCONFDIR/mailcap</literal></para></listitem>
+<listitem><para><literal>/etc/mailcap</literal></para></listitem>
+<listitem><para><literal>/usr/etc/mailcap</literal></para></listitem>
+<listitem><para><literal>/usr/local/etc/mailcap</literal></para></listitem>
+</orderedlist>
+
+where <literal>$HOME</literal> is your home directory. The
+<literal>$PKGDATADIR</literal> and the
+<literal>$SYSCONFDIR</literal> directories depend on where mutt
+is installed: the former is the default for shared data, the
+latter for system configuration files.
</para>
<para>
-Mutt will try whichever methods are compiled in and available on the server,
-in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.
+The default search path can be obtained by running the following
+command:
</para>
+<screen>
+mutt -nF /dev/null -Q mailcap_path
+</screen>
+
<para>
-There are a few variables which control authentication:
+In particular, the metamail distribution will install a mailcap file,
+usually as <literal>/usr/local/etc/mailcap</literal>, which contains some baseline
+entries.
+</para>
-<itemizedlist>
-<listitem>
+<sect2>
+<title>The Basics of the mailcap file</title>
<para>
-<link linkend="imap-user">$imap_user</link> - controls
-the username under which you request authentication on the IMAP server,
-for all authenticators. This is overridden by an explicit username in
-the mailbox path (ie by using a mailbox name of the form
-<literal>{user@host}</literal>).
+A mailcap file consists of a series of lines which are comments, blank,
+or definitions.
</para>
-</listitem>
-<listitem>
<para>
-<link linkend="imap-pass">$imap_pass</link> - a
-password which you may preset, used by all authentication methods where
-a password is needed.
+A comment line consists of a # character followed by anything you want.
</para>
-</listitem>
-<listitem>
<para>
-<link linkend="imap-authenticators">$imap_authenticators</link> - a colon-delimited list of IMAP
-authentication methods to try, in the order you wish to try them. If
-specified, this overrides mutt's default (attempt everything, in the order
-listed above).
+A blank line is blank.
</para>
-</listitem>
-
-</itemizedlist>
+<para>
+A definition line consists of a content type, a view command, and any
+number of optional fields. Each field of a definition line is divided
+by a semicolon ';' character.
</para>
-</sect2>
-
-</sect1>
-
-<sect1 id="account-hook">
-<title>Managing multiple IMAP/POP accounts (OPTIONAL)</title>
-
<para>
-If you happen to have accounts on multiple IMAP and/or POP servers,
-you may find managing all the authentication settings inconvenient and
-error-prone. The account-hook command may help. This hook works like
-folder-hook but is invoked whenever you access a remote mailbox
-(including inside the folder browser), not just when you open the
-mailbox.
+The content type is specified in the MIME standard type/subtype method.
+For example,
+<literal>text/plain, text/html, image/gif, </literal>
+etc. In addition, the mailcap format includes two formats for
+wildcards, one using the special '*' subtype, the other is the implicit
+wild, where you only include the major type. For example, <literal>image/*</literal>, or
+<literal>video,</literal> will match all image types and video types,
+respectively.
</para>
<para>
-Some examples:
+The view command is a Unix command for viewing the type specified. There
+are two different types of commands supported. The default is to send
+the body of the MIME message to the command on stdin. You can change
+this behavior by using %s as a parameter to your view command.
+This will cause Mutt to save the body of the MIME message to a temporary
+file, and then call the view command with the %s replaced by
+the name of the temporary file. In both cases, Mutt will turn over the
+terminal to the view program until the program quits, at which time Mutt
+will remove the temporary file if it exists.
</para>
<para>
+So, in the simplest form, you can send a text/plain message to the
+external pager more on stdin:
<screen>
-account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
-account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
-account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
+text/plain; more
</screen>
-</para>
-
-</sect1>
+Or, you could send the message as a file:
-<sect1 id="urlview">
-<title>Start a WWW Browser on URLs (EXTERNAL)</title>
+<screen>
+text/plain; more %s
+</screen>
-<para>
-If a message contains URLs (<emphasis>unified resource locator</emphasis> = address in the
-WWW space like <emphasis>http://www.mutt.org/</emphasis>), it is efficient to get
-a menu with all the URLs and start a WWW browser on one of them. This
-functionality is provided by the external urlview program which can be
-retrieved at <ulink
-url="ftp://ftp.mutt.org/mutt/contrib/"
->ftp://ftp.mutt.org/mutt/contrib/</ulink
-> and the configuration commands:
+Perhaps you would like to use lynx to interactively view a text/html
+message:
<screen>
-macro index \cb |urlview\n
-macro pager \cb |urlview\n
+text/html; lynx %s
</screen>
+In this case, lynx does not support viewing a file from stdin, so you
+must use the %s syntax.
+<emphasis role="bold">Note:</emphasis> <emphasis>Some older versions of lynx contain a bug where they
+will check the mailcap file for a viewer for text/html. They will find
+the line which calls lynx, and run it. This causes lynx to continuously
+spawn itself to view the object.</emphasis>
</para>
-</sect1>
+<para>
+On the other hand, maybe you don't want to use lynx interactively, you
+just want to have it convert the text/html to text/plain, then you can
+use:
-<sect1 id="caching">
-<title>Local caching (OPTIONAL)</title>
+<screen>
+text/html; lynx -dump %s | more
+</screen>
-<para>
-Mutt contains two types of local caching: <emphasis>(1)</emphasis>
-the so-called ``header caching'' and <emphasis>(2)</emphasis> the
-so-called ``body caching'' which are both described in this section.
</para>
<para>
-These are optional which means they're not enabled by default.
-Details on how to enable either of these techniques are given in the
-following subsections.
+Perhaps you wish to use lynx to view text/html files, and a pager on
+all other text formats, then you would use the following:
+
+<screen>
+text/html; lynx %s
+text/*; more
+</screen>
+
+This is the simplest form of a mailcap file.
</para>
-<sect2 id="header-caching">
-<title>Header caching</title>
+</sect2>
+
+<sect2>
+<title>Secure use of mailcap</title>
<para>
-Mutt provides optional support for caching message headers for the
-following types of folders: IMAP, POP, Maildir and MH. Header caching
-greatly improves speed because for remote folders, headers
-usually only need to be downloaded once. For Maildir and MH, reading the
-headers from a single file is much faster than looking at possibly
-thousands of single files (since Maildir and MH use one file per message.)
+The interpretation of shell meta-characters embedded in MIME parameters
+can lead to security problems in general. Mutt tries to quote parameters
+in expansion of %s syntaxes properly, and avoids risky characters by
+substituting them, see the <link linkend="mailcap-sanitize">$mailcap_sanitize</link> variable.
</para>
<para>
-Header caching can be enabled via the configure script and the
-<emphasis>--enable-hcache</emphasis> option. It's not turned on
-by default because external database libraries are required: one
-of qdbm, gdbm or bdb must be present.
+Although mutt's procedures to invoke programs with mailcap seem to be
+safe, there are other applications parsing mailcap, maybe taking less care
+of it. Therefore you should pay attention to the following rules:
</para>
<para>
-If enabled, <link
-linkend="header-cache">$header_cache</link> can be
-used to either point to a file or a directory. If set to point to
-a file, one database file for all folders will be used (which may
-result in lower performance), but one file per folder if it points
-to a directory.
+<emphasis>Keep the %-expandos away from shell quoting.</emphasis>
+Don't quote them with single or double quotes. Mutt does this for
+you, the right way, as should any other program which interprets
+mailcap. Don't put them into backtick expansions. Be highly careful
+with eval statements, and avoid them if possible at all. Trying to fix
+broken behavior with quotes introduces new leaks - there is no
+alternative to correct quoting in the first place.
</para>
<para>
-For the one-file-per-folder case, database files will be named by MD5
-sums. They may be safely removed if a system is short on space. You
-can compute the name of the header cache file for a particular folder
-through a command like the following:
+If you have to use the %-expandos' values in context where you need
+quoting or backtick expansions, put that value into a shell variable
+and reference the shell variable where necessary, as in the following
+example (using <literal>$charset</literal> inside the backtick expansion is safe,
+since it is not itself subject to any further expansion):
</para>
<para>
+
<screen>
-$ printf '%s' '/path/to/folder' | md5sum
-$ printf '%s' 'imaps://user@host/path/to/folder' | md5sum
-$ printf '%s' 'pops://user@host' | md5sum
+text/test-mailcap-bug; cat %s; copiousoutput; test=charset=%{charset} \
+ && test "`echo $charset | tr '[A-Z]' '[a-z]'`" != iso-8859-1
</screen>
-</para>
-<para>
-The <literal>md5sum</literal> command may also be
-named <literal>md5</literal>, depending on your operating system.
</para>
</sect2>
-<sect2 id="body-caching">
-<title>Body caching</title>
+<sect2>
+<title>Advanced mailcap Usage</title>
-<para>
-In addition to caching message headers only, mutt can also cache
-whole message bodies. This results in faster display of messages
-for POP and IMAP folders because messages usually have to be
-downloaded only once.
-</para>
+<sect3>
+<title>Optional Fields</title>
<para>
-If the configure script is called with <emphasis>--enable-pop</emphasis>
-and/or <emphasis>--enable-imap</emphasis>, body caching will be
-built in as it does not require additional software packages such
-as database libraries.
-</para>
+In addition to the required content-type and view command fields, you
+can add semi-colon ';' separated fields to set flags and other options.
+Mutt recognizes the following optional fields:
+<variablelist>
+<varlistentry>
+<term>copiousoutput</term>
+<listitem>
<para>
-For configuration, the variable <link linkend="message-cachedir"
->$message_cachedir</link> must point to a
-directory. There, mutt will create a hierarchy of subdirectories
-named like: <literal>proto:user@hostname</literal> where
-<literal>proto</literal> is either ``pop'' or ``imap.'' Within
-there for each folder, mutt stores messages in single files (just
-like Maildir) so that with manual symlink creation these cache
-directories can be examined with mutt as read-only Maildir folders.
-</para>
+This flag tells Mutt that the command passes possibly large amounts of
+text on stdout. This causes Mutt to invoke a pager (either the internal
+pager or the external pager defined by the pager variable) on the output
+of the view command. Without this flag, Mutt assumes that the command
+is interactive. One could use this to replace the pipe to <literal>more</literal>
+in the <literal>lynx -dump</literal> example in the Basic section:
+
+<screen>
+text/html; lynx -dump %s ; copiousoutput
+</screen>
+This will cause lynx to format the text/html output as text/plain
+and Mutt will use your standard pager to display the results.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>needsterminal</term>
+<listitem>
<para>
-All files can be removed as needed if the consumed disk space
-becomes an issue as mutt will silently fetch missing items again.
+Mutt uses this flag when viewing attachments with <link linkend="auto-view">auto_view</link>, in order to decide whether it should honor the setting
+of the <link linkend="wait-key">$wait_key</link> variable or
+not. When an attachment is viewed using an interactive program, and the
+corresponding mailcap entry has a <emphasis>needsterminal</emphasis> flag, Mutt will use
+<link linkend="wait-key">$wait_key</link> and the exit status
+of the program to decide if it will ask you to press a key after the
+external program has exited. In all other situations it will not prompt
+you for a key.
</para>
-
-</sect2>
-
-</sect1>
-
-</chapter>
-
-<chapter id="mimesupport">
-<title>Mutt's MIME Support</title>
-
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>compose=<command></term>
+<listitem>
<para>
-Quite a bit of effort has been made to make Mutt the premier text-mode
-MIME MUA. Every effort has been made to provide the functionality that
-the discerning MIME user requires, and the conformance to the standards
-wherever possible. When configuring Mutt for MIME, there are two extra
-types of configuration files which Mutt uses. One is the
-<literal>mime.types</literal> file, which contains the mapping of file extensions to
-IANA MIME types. The other is the <literal>mailcap</literal> file, which specifies
-the external commands to use for handling specific MIME types.
+This flag specifies the command to use to create a new attachment of a
+specific MIME type. Mutt supports this from the compose menu.
</para>
-
-<sect1 id="using-mime">
-<title>Using MIME in Mutt</title>
-
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>composetyped=<command></term>
+<listitem>
<para>
-There are three areas/menus in Mutt which deal with MIME, they are the
-pager (while viewing a message), the attachment menu and the compose
-menu.
+This flag specifies the command to use to create a new attachment of a
+specific MIME type. This command differs from the compose command in
+that mutt will expect standard MIME headers on the data. This can be
+used to specify parameters, filename, description, etc. for a new
+attachment. Mutt supports this from the compose menu.
</para>
-
-<sect2>
-<title>Viewing MIME messages in the pager</title>
-
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>print=<command></term>
+<listitem>
<para>
-When you select a message from the index and view it in the pager, Mutt
-decodes the message to a text representation. Mutt internally supports
-a number of MIME types, including <literal>text/plain, text/enriched,
-message/rfc822, and message/news</literal>. In addition, the export
-controlled version of Mutt recognizes a variety of PGP MIME types,
-including PGP/MIME and application/pgp.
+This flag specifies the command to use to print a specific MIME type.
+Mutt supports this from the attachment and compose menus.
</para>
-
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>edit=<command></term>
+<listitem>
<para>
-Mutt will denote attachments with a couple lines describing them.
-These lines are of the form:
+This flag specifies the command to use to edit a specific MIME type.
+Mutt supports this from the compose menu, and also uses it to compose
+new attachments. Mutt will default to the defined editor for text
+attachments.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>nametemplate=<template></term>
+<listitem>
+<para>
+This field specifies the format for the file denoted by %s in the
+command fields. Certain programs will require a certain file extension,
+for instance, to correctly view a file. For instance, lynx will only
+interpret a file as <literal>text/html</literal> if the file ends in <literal>.html</literal>.
+So, you would specify lynx as a <literal>text/html</literal> viewer with a line in
+the mailcap file like:
<screen>
-[-- Attachment #1: Description --]
-[-- Type: text/plain, Encoding: 7bit, Size: 10000 --]
+text/html; lynx %s; nametemplate=%s.html
</screen>
-Where the <literal>Description</literal> is the description or filename given for the
-attachment, and the <literal>Encoding</literal> is one of
-<literal>7bit/8bit/quoted-printable/base64/binary</literal>.
</para>
-
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>test=<command></term>
+<listitem>
<para>
-If Mutt cannot deal with a MIME type, it will display a message like:
+This field specifies a command to run to test whether this mailcap
+entry should be used. The command is defined with the command expansion
+rules defined in the next section. If the command returns 0, then the
+test passed, and Mutt uses this entry. If the command returns non-zero,
+then the test failed, and Mutt continues searching for the right entry.
+<emphasis role="bold">Note:</emphasis> <emphasis>the content-type must match before Mutt performs the test.</emphasis>
+For example:
<screen>
-[-- image/gif is unsupported (use 'v' to view this part) --]
+text/html; netscape -remote 'openURL(%s)' ; test=RunningX
+text/html; lynx %s
</screen>
+In this example, Mutt will run the program RunningX which will return 0
+if the X Window manager is running, and non-zero if it isn't. If
+RunningX returns 0, then Mutt will call netscape to display the
+text/html object. If RunningX doesn't return 0, then Mutt will go on
+to the next entry and use lynx to display the text/html object.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
</para>
-</sect2>
+</sect3>
-<sect2 id="attach-menu">
-<title>The Attachment Menu</title>
+<sect3>
+<title>Search Order</title>
<para>
-The default binding for <literal>view-attachments</literal> is `v', which displays the
-attachment menu for a message. The attachment menu displays a list of
-the attachments in a message. From the attachment menu, you can save,
-print, pipe, delete, and view attachments. You can apply these
-operations to a group of attachments at once, by tagging the attachments
-and by using the ``tag-prefix'' operator. You can also reply to the
-current message from this menu, and only the current attachment (or the
-attachments tagged) will be quoted in your reply. You can view
-attachments as text, or view them using the mailcap viewer definition.
-</para>
+When searching for an entry in the mailcap file, Mutt will search for
+the most useful entry for its purpose. For instance, if you are
+attempting to print an <literal>image/gif</literal>, and you have the following
+entries in your mailcap file, Mutt will search for an entry with the
+print command:
-<para>
-Finally, you can apply the usual message-related functions (like
-<link linkend="resend-message">resend-message</link>, and the reply
-and forward functions) to attachments of type <literal>message/rfc822</literal>.
+<screen>
+image/*; xv %s
+image/gif; ; print= anytopnm %s | pnmtops | lpr; \
+ nametemplate=%s.gif
+</screen>
+
+Mutt will skip the <literal>image/*</literal> entry and use the <literal>image/gif</literal>
+entry with the print command.
</para>
<para>
-See the help on the attachment menu for more information.
+In addition, you can use this with <link linkend="auto-view">auto_view</link>
+to denote two commands for viewing an attachment, one to be viewed
+automatically, the other to be viewed interactively from the attachment
+menu. In addition, you can then use the test feature to determine which
+viewer to use interactively depending on your environment.
+
+<screen>
+text/html; netscape -remote 'openURL(%s)' ; test=RunningX
+text/html; lynx %s; nametemplate=%s.html
+text/html; lynx -dump %s; nametemplate=%s.html; copiousoutput
+</screen>
+
+For <link linkend="auto-view">auto_view</link>, Mutt will choose the third
+entry because of the copiousoutput tag. For interactive viewing, Mutt
+will run the program RunningX to determine if it should use the first
+entry. If the program returns non-zero, Mutt will use the second entry
+for interactive viewing.
</para>
-</sect2>
+</sect3>
-<sect2 id="compose-menu">
-<title>The Compose Menu</title>
+<sect3>
+<title>Command Expansion</title>
<para>
-The compose menu is the menu you see before you send a message. It
-allows you to edit the recipient list, the subject, and other aspects
-of your message. It also contains a list of the attachments of your
-message, including the main body. From this menu, you can print, copy,
-filter, pipe, edit, compose, review, and rename an attachment or a
-list of tagged attachments. You can also modifying the attachment
-information, notably the type, encoding and description.
-</para>
+The various commands defined in the mailcap files are passed to the
+<literal>/bin/sh</literal> shell using the system() function. Before the
+command is passed to <literal>/bin/sh -c</literal>, it is parsed to expand
+various special parameters with information from Mutt. The keywords
+Mutt expands are:
+<variablelist>
+<varlistentry>
+<term>%s</term>
+<listitem>
<para>
-Attachments appear as follows:
+As seen in the basic mailcap section, this variable is expanded
+to a filename specified by the calling program. This file contains
+the body of the message to view/print/edit or where the composing
+program should place the results of composition. In addition, the
+use of this keyword causes Mutt to not pass the body of the message
+to the view/print/edit program on stdin.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>%t</term>
+<listitem>
+<para>
+Mutt will expand %t to the text representation of the content
+type of the message in the same form as the first parameter of the
+mailcap definition line, ie <literal>text/html</literal> or
+<literal>image/gif</literal>.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>%{<parameter>}</term>
+<listitem>
+<para>
+Mutt will expand this to the value of the specified parameter
+from the Content-Type: line of the mail message. For instance, if
+Your mail message contains:
<screen>
-- 1 [text/plain, 7bit, 1K] /tmp/mutt-euler-8082-0 <no description>
- 2 [applica/x-gunzip, base64, 422K] ~/src/mutt-0.85.tar.gz <no description>
+Content-Type: text/plain; charset=iso-8859-1
</screen>
+then Mutt will expand %{charset} to iso-8859-1. The default metamail
+mailcap file uses this feature to test the charset to spawn an xterm
+using the right charset to view the message.
</para>
-
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>\%</term>
+<listitem>
<para>
-The '-' denotes that Mutt will delete the file after sending (or
-postponing, or canceling) the message. It can be toggled with the
-<literal>toggle-unlink</literal> command (default: u). The next field is the MIME
-content-type, and can be changed with the <literal>edit-type</literal> command
-(default: ˆT). The next field is the encoding for the attachment,
-which allows a binary message to be encoded for transmission on 7bit
-links. It can be changed with the <literal>edit-encoding</literal> command
-(default: ˆE). The next field is the size of the attachment,
-rounded to kilobytes or megabytes. The next field is the filename,
-which can be changed with the <literal>rename-file</literal> command (default: R).
-The final field is the description of the attachment, and can be
-changed with the <literal>edit-description</literal> command (default: d).
+This will be replaced by a %
</para>
+</listitem>
+</varlistentry>
+</variablelist>
+Mutt does not currently support the %F and %n keywords
+specified in RFC 1524. The main purpose of these parameters is for
+multipart messages, which is handled internally by Mutt.
+</para>
+
+</sect3>
</sect2>
-</sect1>
+<sect2>
+<title>Example mailcap files</title>
+
+<para>
+This mailcap file is fairly simple and standard:
+
+<programlisting>
+# I'm always running X :)
+video/*; xanim %s > /dev/null
+image/*; xv %s > /dev/null
+
+# I'm always running netscape (if my computer had more memory, maybe)
+text/html; netscape -remote 'openURL(%s)'
+</programlisting>
-<sect1 id="mime-types">
-<title>MIME Type configuration with <literal>mime.types</literal></title>
+</para>
<para>
-When you add an attachment to your mail message, Mutt searches your
-personal mime.types file at <literal>${HOME}/.mime.types</literal>, and then
-the system mime.types file at <literal>/usr/local/share/mutt/mime.types</literal> or
-<literal>/etc/mime.types</literal>
+This mailcap file shows quite a number of examples:
</para>
<para>
-The mime.types file consist of lines containing a MIME type and a space
-separated list of extensions. For example:
-<screen>
-application/postscript ps eps
-application/pgp pgp
-audio/x-aiff aif aifc aiff
-</screen>
+<programlisting>
+# Use xanim to view all videos Xanim produces a header on startup,
+# send that to /dev/null so I don't see it
+video/*; xanim %s > /dev/null
-A sample <literal>mime.types</literal> file comes with the Mutt distribution, and
-should contain most of the MIME types you are likely to use.
-</para>
+# Send html to a running netscape by remote
+text/html; netscape -remote 'openURL(%s)'; test=RunningNetscape
-<para>
-If Mutt can not determine the mime type by the extension of the file you
-attach, it will look at the file. If the file is free of binary
-information, Mutt will assume that the file is plain text, and mark it
-as <literal>text/plain</literal>. If the file contains binary information, then Mutt will
-mark it as <literal>application/octet-stream</literal>. You can change the MIME
-type that Mutt assigns to an attachment by using the <literal>edit-type</literal>
-command from the compose menu (default: ˆT). The MIME type is actually a
-major mime type followed by the sub-type, separated by a '/'. 6 major
-types: application, text, image, video, audio, and model have been approved
-after various internet discussions. Mutt recognizes all of these if the
-appropriate entry is found in the mime.types file. It also recognizes other
-major mime types, such as the chemical type that is widely used in the
-molecular modeling community to pass molecular data in various forms to
-various molecular viewers. Non-recognized mime types should only be used
-if the recipient of the message is likely to be expecting such attachments.
-</para>
+# If I'm not running netscape but I am running X, start netscape on the
+# object
+text/html; netscape %s; test=RunningX
-</sect1>
+# Else use lynx to view it as text
+text/html; lynx %s
-<sect1 id="mime-viewers">
-<title>MIME Viewer configuration with <literal>mailcap</literal></title>
+# This version would convert the text/html to text/plain
+text/html; lynx -dump %s; copiousoutput
-<para>
-Mutt supports RFC 1524 MIME Configuration, in particular the Unix
-specific format specified in Appendix A of RFC 1524. This file format
-is commonly referred to as the mailcap format. Many MIME compliant
-programs utilize the mailcap format, allowing you to specify handling
-for all MIME types in one place for all programs. Programs known to
-use this format include Netscape, XMosaic, lynx and metamail.
-</para>
+# I use enscript to print text in two columns to a page
+text/*; more %s; print=enscript -2Gr %s
-<para>
-In order to handle various MIME types that Mutt can not handle
-internally, Mutt parses a series of external configuration files to
-find an external handler. The default search string for these files
-is a colon delimited list containing the following files:
+# Netscape adds a flag to tell itself to view jpegs internally
+image/jpeg;xv %s; x-mozilla-flags=internal
-<orderedlist>
-<listitem><para><literal>$HOME/.mailcap</literal></para></listitem>
-<listitem><para><literal>$PKGDATADIR/mailcap</literal></para></listitem>
-<listitem><para><literal>$SYSCONFDIR/mailcap</literal></para></listitem>
-<listitem><para><literal>/etc/mailcap</literal></para></listitem>
-<listitem><para><literal>/usr/etc/mailcap</literal></para></listitem>
-<listitem><para><literal>/usr/local/etc/mailcap</literal></para></listitem>
-</orderedlist>
+# Use xv to view images if I'm running X
+# In addition, this uses the \ to extend the line and set my editor
+# for images
+image/*;xv %s; test=RunningX; \
+ edit=xpaint %s
-where <literal>$HOME</literal> is your home directory. The
-<literal>$PKGDATADIR</literal> and the
-<literal>$SYSCONFDIR</literal> directories depend on where mutt
-is installed: the former is the default for shared data, the
-latter for system configuration files.
-</para>
+# Convert images to text using the netpbm tools
+image/*; (anytopnm %s | pnmscale -xysize 80 46 | ppmtopgm | pgmtopbm |
+pbmtoascii -1x2 ) 2>&1 ; copiousoutput
+
+# Send excel spreadsheets to my NT box
+application/ms-excel; open.pl %s
+</programlisting>
-<para>
-The default search path can be obtained by running the following
-command:
</para>
-<screen>
-mutt -nF /dev/null -Q mailcap_path
-</screen>
+</sect2>
-<para>
-In particular, the metamail distribution will install a mailcap file,
-usually as <literal>/usr/local/etc/mailcap</literal>, which contains some baseline
-entries.
-</para>
+</sect1>
-<sect2>
-<title>The Basics of the mailcap file</title>
+<sect1 id="auto-view">
+<title>MIME Autoview</title>
<para>
-A mailcap file consists of a series of lines which are comments, blank,
-or definitions.
+In addition to explicitly telling Mutt to view an attachment with the
+MIME viewer defined in the mailcap file, Mutt has support for
+automatically viewing MIME attachments while in the pager.
</para>
<para>
-A comment line consists of a # character followed by anything you want.
+To work, you must define a viewer in the mailcap file which uses the
+<literal>copiousoutput</literal> option to denote that it is non-interactive.
+Usually, you also use the entry to convert the attachment to a text
+representation which you can view in the pager.
</para>
<para>
-A blank line is blank.
+You then use the <literal>auto_view</literal> muttrc command to list the
+content-types that you wish to view automatically.
</para>
<para>
-A definition line consists of a content type, a view command, and any
-number of optional fields. Each field of a definition line is divided
-by a semicolon ';' character.
-</para>
+For instance, if you set auto_view to:
-<para>
-The content type is specified in the MIME standard type/subtype method.
-For example,
-<literal>text/plain, text/html, image/gif, </literal>
-etc. In addition, the mailcap format includes two formats for
-wildcards, one using the special '*' subtype, the other is the implicit
-wild, where you only include the major type. For example, <literal>image/*</literal>, or
-<literal>video,</literal> will match all image types and video types,
-respectively.
-</para>
+<screen>
+auto_view text/html application/x-gunzip \
+ application/postscript image/gif application/x-tar-gz
+</screen>
-<para>
-The view command is a Unix command for viewing the type specified. There
-are two different types of commands supported. The default is to send
-the body of the MIME message to the command on stdin. You can change
-this behavior by using %s as a parameter to your view command.
-This will cause Mutt to save the body of the MIME message to a temporary
-file, and then call the view command with the %s replaced by
-the name of the temporary file. In both cases, Mutt will turn over the
-terminal to the view program until the program quits, at which time Mutt
-will remove the temporary file if it exists.
</para>
<para>
-So, in the simplest form, you can send a text/plain message to the
-external pager more on stdin:
+Mutt could use the following mailcap entries to automatically view
+attachments of these types.
<screen>
-text/plain; more
+text/html; lynx -dump %s; copiousoutput; nametemplate=%s.html
+image/*; anytopnm %s | pnmscale -xsize 80 -ysize 50 | ppmtopgm | \
+ pgmtopbm | pbmtoascii ; copiousoutput
+application/x-gunzip; gzcat; copiousoutput
+application/x-tar-gz; gunzip -c %s | tar -tf - ; copiousoutput
+application/postscript; ps2ascii %s; copiousoutput
</screen>
-Or, you could send the message as a file:
-
-<screen>
-text/plain; more %s
-</screen>
+</para>
-Perhaps you would like to use lynx to interactively view a text/html
-message:
+<para>
+``unauto_view'' can be used to remove previous entries from the autoview list.
+This can be used with message-hook to autoview messages based on size, etc.
+``unauto_view *'' will remove all previous entries.
+</para>
-<screen>
-text/html; lynx %s
-</screen>
+</sect1>
-In this case, lynx does not support viewing a file from stdin, so you
-must use the %s syntax.
-<emphasis role="bold">Note:</emphasis> <emphasis>Some older versions of lynx contain a bug where they
-will check the mailcap file for a viewer for text/html. They will find
-the line which calls lynx, and run it. This causes lynx to continuously
-spawn itself to view the object.</emphasis>
-</para>
+<sect1 id="alternative-order">
+<title>MIME Multipart/Alternative</title>
<para>
-On the other hand, maybe you don't want to use lynx interactively, you
-just want to have it convert the text/html to text/plain, then you can
-use:
+Mutt has some heuristics for determining which attachment of a
+multipart/alternative type to display. First, mutt will check the
+alternative_order list to determine if one of the available types
+is preferred. The alternative_order list consists of a number of
+mimetypes in order, including support for implicit and explicit
+wildcards, for example:
<screen>
-text/html; lynx -dump %s | more
+alternative_order text/enriched text/plain text application/postscript image/*
</screen>
</para>
<para>
-Perhaps you wish to use lynx to view text/html files, and a pager on
-all other text formats, then you would use the following:
-
-<screen>
-text/html; lynx %s
-text/*; more
-</screen>
+Next, mutt will check if any of the types have a defined
+<link linkend="auto-view">auto_view</link>, and use that. Failing
+that, Mutt will look for any text type. As a last attempt, mutt will
+look for any type it knows how to handle.
+</para>
-This is the simplest form of a mailcap file.
+<para>
+To remove a MIME type from the <literal>alternative_order</literal> list, use the
+<literal>unalternative_order</literal> command.
</para>
-</sect2>
+</sect1>
-<sect2>
-<title>Secure use of mailcap</title>
+<sect1 id="attachments">
+<title>Attachment Searching and Counting</title>
<para>
-The interpretation of shell meta-characters embedded in MIME parameters
-can lead to security problems in general. Mutt tries to quote parameters
-in expansion of %s syntaxes properly, and avoids risky characters by
-substituting them, see the <link linkend="mailcap-sanitize">$mailcap_sanitize</link> variable.
+If you ever lose track of attachments in your mailboxes, Mutt's
+attachment-counting and -searching support might be for you. You can
+make your message index display the number of qualifying attachments in
+each message, or search for messages by attachment count. You also can
+configure what kinds of attachments qualify for this feature with the
+attachments and unattachments commands.
+</para>
+
+<para>
+In order to provide this information, mutt needs to fully MIME-parse
+all messages affected first. This can slow down operation especially for
+remote mail folders such as IMAP because all messages have to be
+downloaded first regardless whether the user really wants to view them
+or not.
+</para>
+
+<para>
+The syntax is:
+</para>
+<screen>
+attachments {+|-}disposition mime-type
+unattachments {+|-}disposition mime-type
+attachments ?
+</screen>
+
+<para>
+Disposition is the attachment's Content-disposition type -- either
+"inline" or "attachment". You can abbreviate this to I or A.
</para>
<para>
-Although mutt's procedures to invoke programs with mailcap seem to be
-safe, there are other applications parsing mailcap, maybe taking less care
-of it. Therefore you should pay attention to the following rules:
+Disposition is prefixed by either a + symbolor a - symbol. If it's
+a +, you're saying that you want to allow this disposition and MIME
+type to qualify. If it's a -, you're saying that this disposition
+and MIME type is an exception to previous + rules. There are examples
+below of how this is useful.
</para>
<para>
-<emphasis>Keep the %-expandos away from shell quoting.</emphasis>
-Don't quote them with single or double quotes. Mutt does this for
-you, the right way, as should any other program which interprets
-mailcap. Don't put them into backtick expansions. Be highly careful
-with eval statements, and avoid them if possible at all. Trying to fix
-broken behavior with quotes introduces new leaks - there is no
-alternative to correct quoting in the first place.
+Mime-type is, unsurprisingly, the MIME type of the attachment you want
+to affect. A MIME type is always of the format "major/minor", where
+"major" describes the broad category of document you're looking at, and
+"minor" describes the specific type within that category. The major
+part of mim-type must be literal text (or the special token "*"), but
+the minor part may be a regular expression. (Therefore, "*/.*" matches
+any MIME type.)
</para>
<para>
-If you have to use the %-expandos' values in context where you need
-quoting or backtick expansions, put that value into a shell variable
-and reference the shell variable where necessary, as in the following
-example (using <literal>$charset</literal> inside the backtick expansion is safe,
-since it is not itself subject to any further expansion):
+The MIME types you give to the attachments directive are a kind of
+pattern. When you use the attachments directive, the patterns you
+specify are added to a list. When you use unattachments, the pattern
+is removed from the list. The patterns are not expanded and matched
+to specific MIME types at this time -- they're just text in a list.
+They're only matched when actually evaluating a message.
</para>
<para>
+Some examples might help to illustrate. The examples that are not
+commented out define the default configuration of the lists.
+</para>
<screen>
-text/test-mailcap-bug; cat %s; copiousoutput; test=charset=%{charset} \
- && test "`echo $charset | tr '[A-Z]' '[a-z]'`" != iso-8859-1
-</screen>
+## Removing a pattern from a list removes that pattern literally. It
+## does not remove any type matching the pattern.
+##
+## attachments +A */.*
+## attachments +A image/jpeg
+## unattachments +A */.*
+##
+## This leaves "attached" image/jpeg files on the allowed attachments
+## list. It does not remove all items, as you might expect, because the
+## second */.* is not a matching expression at this time.
+##
+## Remember: "unattachments" only undoes what "attachments" has done!
+## It does not trigger any matching on actual messages.
-</para>
-</sect2>
+## Qualify any MIME part with an "attachment" disposition, EXCEPT for
+## text/x-vcard and application/pgp parts. (PGP parts are already known
+## to mutt, and can be searched for with ~g, ~G, and ~k.)
+##
+## I've added x-pkcs7 to this, since it functions (for S/MIME)
+## analogously to PGP signature attachments. S/MIME isn't supported
+## in a stock mutt build, but we can still treat it specially here.
+##
+attachments +A */.*
+attachments -A text/x-vcard application/pgp.*
+attachments -A application/x-pkcs7-.*
-<sect2>
-<title>Advanced mailcap Usage</title>
+## Discount all MIME parts with an "inline" disposition, unless they're
+## text/plain. (Why inline a text/plain part unless it's external to the
+## message flow?)
+##
+attachments +I text/plain
-<sect3>
-<title>Optional Fields</title>
+## These two lines make Mutt qualify MIME containers. (So, for example,
+## a message/rfc822 forward will count as an attachment.) The first
+## line is unnecessary if you already have "attach-allow */.*", of
+## course. These are off by default! The MIME elements contained
+## within a message/* or multipart/* are still examined, even if the
+## containers themseves don't qualify.
+##
+#attachments +A message/.* multipart/.*
+#attachments +I message/.* multipart/.*
+
+## You probably don't really care to know about deleted attachments.
+attachments -A message/external-body
+attachments -I message/external-body
+</screen>
<para>
-In addition to the required content-type and view command fields, you
-can add semi-colon ';' separated fields to set flags and other options.
-Mutt recognizes the following optional fields:
-<variablelist>
+"attachments ?" will list your current settings in Muttrc format, so
+that it can be pasted elsewhere.
+</para>
+
+</sect1>
+
+<sect1 id="mime-lookup">
+<title>MIME Lookup</title>
-<varlistentry>
-<term>copiousoutput</term>
-<listitem>
<para>
-This flag tells Mutt that the command passes possibly large amounts of
-text on stdout. This causes Mutt to invoke a pager (either the internal
-pager or the external pager defined by the pager variable) on the output
-of the view command. Without this flag, Mutt assumes that the command
-is interactive. One could use this to replace the pipe to <literal>more</literal>
-in the <literal>lynx -dump</literal> example in the Basic section:
+Mutt's mime_lookup list specifies a list of mime-types that should not
+be treated according to their mailcap entry. This option is designed to
+deal with binary types such as application/octet-stream. When an attachment's
+mime-type is listed in mime_lookup, then the extension of the filename will
+be compared to the list of extensions in the mime.types file. The mime-type
+associated with this extension will then be used to process the attachment
+according to the rules in the mailcap file and according to any other configuration
+options (such as auto_view) specified. Common usage would be:
<screen>
-text/html; lynx -dump %s ; copiousoutput
+mime_lookup application/octet-stream application/X-Lotus-Manuscript
</screen>
-This will cause lynx to format the text/html output as text/plain
-and Mutt will use your standard pager to display the results.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>needsterminal</term>
-<listitem>
+
<para>
-Mutt uses this flag when viewing attachments with <link linkend="auto-view">auto_view</link>, in order to decide whether it should honor the setting
-of the <link linkend="wait-key">$wait_key</link> variable or
-not. When an attachment is viewed using an interactive program, and the
-corresponding mailcap entry has a <emphasis>needsterminal</emphasis> flag, Mutt will use
-<link linkend="wait-key">$wait_key</link> and the exit status
-of the program to decide if it will ask you to press a key after the
-external program has exited. In all other situations it will not prompt
-you for a key.
+In addition, the unmime_lookup command may be used to disable this feature
+for any particular mime-type if it had been set, for example, in a global
+muttrc.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>compose=<command></term>
-<listitem>
+
+</sect1>
+
+</chapter>
+
+<chapter id="optionalfeatures">
+<title>Optional features</title>
+
+<sect1 id="pop">
+<title>POP3 Support</title>
+
<para>
-This flag specifies the command to use to create a new attachment of a
-specific MIME type. Mutt supports this from the compose menu.
+If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis>
+script with the <emphasis>--enable-pop</emphasis> flag), it has the ability to work
+with mailboxes located on a remote POP3 server and fetch mail for local
+browsing.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>composetyped=<command></term>
-<listitem>
+
<para>
-This flag specifies the command to use to create a new attachment of a
-specific MIME type. This command differs from the compose command in
-that mutt will expect standard MIME headers on the data. This can be
-used to specify parameters, filename, description, etc. for a new
-attachment. Mutt supports this from the compose menu.
+You can access the remote POP3 mailbox by selecting the folder
+<literal>pop://popserver/</literal>.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>print=<command></term>
-<listitem>
+
<para>
-This flag specifies the command to use to print a specific MIME type.
-Mutt supports this from the attachment and compose menus.
+You can select an alternative port by specifying it with the server, ie:
+<literal>pop://popserver:port/</literal>.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>edit=<command></term>
-<listitem>
+
<para>
-This flag specifies the command to use to edit a specific MIME type.
-Mutt supports this from the compose menu, and also uses it to compose
-new attachments. Mutt will default to the defined editor for text
-attachments.
+You can also specify different username for each folder, ie:
+<literal>pop://username@popserver[:port]/</literal>.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>nametemplate=<template></term>
-<listitem>
-<para>
-This field specifies the format for the file denoted by %s in the
-command fields. Certain programs will require a certain file extension,
-for instance, to correctly view a file. For instance, lynx will only
-interpret a file as <literal>text/html</literal> if the file ends in <literal>.html</literal>.
-So, you would specify lynx as a <literal>text/html</literal> viewer with a line in
-the mailcap file like:
-<screen>
-text/html; lynx %s; nametemplate=%s.html
-</screen>
-
-</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>test=<command></term>
-<listitem>
<para>
-This field specifies a command to run to test whether this mailcap
-entry should be used. The command is defined with the command expansion
-rules defined in the next section. If the command returns 0, then the
-test passed, and Mutt uses this entry. If the command returns non-zero,
-then the test failed, and Mutt continues searching for the right entry.
-<emphasis role="bold">Note:</emphasis> <emphasis>the content-type must match before Mutt performs the test.</emphasis>
-For example:
+Polling for new mail is more expensive over POP3 than locally. For this
+reason the frequency at which Mutt will check for mail remotely can be
+controlled by the
+<link linkend="pop-checkinterval">$pop_checkinterval</link>
+variable, which defaults to every 60 seconds.
+</para>
-<screen>
-text/html; netscape -remote 'openURL(%s)' ; test=RunningX
-text/html; lynx %s
-</screen>
+<para>
+If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis>
+script with the <emphasis>--with-ssl</emphasis> flag), connections to POP3 servers
+can be encrypted. This naturally requires that the server supports
+SSL encrypted connections. To access a folder with POP3/SSL, you should
+use pops: prefix, ie:
+<literal>pops://[username@]popserver[:port]/</literal>.
+</para>
-In this example, Mutt will run the program RunningX which will return 0
-if the X Window manager is running, and non-zero if it isn't. If
-RunningX returns 0, then Mutt will call netscape to display the
-text/html object. If RunningX doesn't return 0, then Mutt will go on
-to the next entry and use lynx to display the text/html object.
+<para>
+Another way to access your POP3 mail is the <emphasis>fetch-mail</emphasis> function
+(default: G). It allows to connect to <link linkend="pop-host">$pop_host</link>, fetch all your new mail and place it in the
+local <link linkend="spoolfile">$spoolfile</link>. After this
+point, Mutt runs exactly as if the mail had always been local.
</para>
-</listitem>
-</varlistentry>
-</variablelist>
+
+<para>
+<emphasis role="bold">Note:</emphasis> If you only need to fetch all messages to local mailbox
+you should consider using a specialized program, such as <ulink
+url="http://www.ccil.org/~esr/fetchmail"
+>fetchmail</ulink
+>
</para>
-</sect3>
+</sect1>
-<sect3>
-<title>Search Order</title>
+<sect1 id="imap">
+<title>IMAP Support</title>
<para>
-When searching for an entry in the mailcap file, Mutt will search for
-the most useful entry for its purpose. For instance, if you are
-attempting to print an <literal>image/gif</literal>, and you have the following
-entries in your mailcap file, Mutt will search for an entry with the
-print command:
-
-<screen>
-image/*; xv %s
-image/gif; ; print= anytopnm %s | pnmtops | lpr; \
- nametemplate=%s.gif
-</screen>
-
-Mutt will skip the <literal>image/*</literal> entry and use the <literal>image/gif</literal>
-entry with the print command.
+If Mutt was compiled with IMAP support (by running the <emphasis>configure</emphasis>
+script with the <emphasis>--enable-imap</emphasis> flag), it has the ability to work
+with folders located on a remote IMAP server.
</para>
<para>
-In addition, you can use this with <link linkend="auto-view">auto_view</link>
-to denote two commands for viewing an attachment, one to be viewed
-automatically, the other to be viewed interactively from the attachment
-menu. In addition, you can then use the test feature to determine which
-viewer to use interactively depending on your environment.
-
-<screen>
-text/html; netscape -remote 'openURL(%s)' ; test=RunningX
-text/html; lynx %s; nametemplate=%s.html
-text/html; lynx -dump %s; nametemplate=%s.html; copiousoutput
-</screen>
+You can access the remote inbox by selecting the folder
+<literal>imap://imapserver/INBOX</literal>, where <literal>imapserver</literal> is the name of the
+IMAP server and <literal>INBOX</literal> is the special name for your spool mailbox on
+the IMAP server. If you want to access another mail folder at the IMAP
+server, you should use <literal>imap://imapserver/path/to/folder</literal> where
+<literal>path/to/folder</literal> is the path of the folder you want to access.
+</para>
-For <link linkend="auto-view">auto_view</link>, Mutt will choose the third
-entry because of the copiousoutput tag. For interactive viewing, Mutt
-will run the program RunningX to determine if it should use the first
-entry. If the program returns non-zero, Mutt will use the second entry
-for interactive viewing.
+<para>
+You can select an alternative port by specifying it with the server, ie:
+<literal>imap://imapserver:port/INBOX</literal>.
</para>
-</sect3>
+<para>
+You can also specify different username for each folder, ie:
+<literal>imap://username@imapserver[:port]/INBOX</literal>.
+</para>
-<sect3>
-<title>Command Expansion</title>
+<para>
+If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis>
+script with the <emphasis>--with-ssl</emphasis> flag), connections to IMAP servers
+can be encrypted. This naturally requires that the server supports
+SSL encrypted connections. To access a folder with IMAP/SSL, you should
+use <literal>imaps://[username@]imapserver[:port]/path/to/folder</literal> as your
+folder path.
+</para>
<para>
-The various commands defined in the mailcap files are passed to the
-<literal>/bin/sh</literal> shell using the system() function. Before the
-command is passed to <literal>/bin/sh -c</literal>, it is parsed to expand
-various special parameters with information from Mutt. The keywords
-Mutt expands are:
-<variablelist>
+Pine-compatible notation is also supported, ie
+<literal>{[username@]imapserver[:port][/ssl]}path/to/folder</literal>
+</para>
-<varlistentry>
-<term>%s</term>
-<listitem>
<para>
-As seen in the basic mailcap section, this variable is expanded
-to a filename specified by the calling program. This file contains
-the body of the message to view/print/edit or where the composing
-program should place the results of composition. In addition, the
-use of this keyword causes Mutt to not pass the body of the message
-to the view/print/edit program on stdin.
+Note that not all servers use / as the hierarchy separator. Mutt should
+correctly notice which separator is being used by the server and convert
+paths accordingly.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>%t</term>
-<listitem>
+
<para>
-Mutt will expand %t to the text representation of the content
-type of the message in the same form as the first parameter of the
-mailcap definition line, ie <literal>text/html</literal> or
-<literal>image/gif</literal>.
+When browsing folders on an IMAP server, you can toggle whether to look
+at only the folders you are subscribed to, or all folders with the
+<emphasis>toggle-subscribed</emphasis> command. See also the
+<link linkend="imap-list-subscribed">$imap_list_subscribed</link> variable.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>%{<parameter>}</term>
-<listitem>
+
<para>
-Mutt will expand this to the value of the specified parameter
-from the Content-Type: line of the mail message. For instance, if
-Your mail message contains:
+Polling for new mail on an IMAP server can cause noticeable delays. So, you'll
+want to carefully tune the
+<link linkend="mail-check">$mail_check</link>
+and
+<link linkend="timeout">$timeout</link>
+variables. Personally I use
<screen>
-Content-Type: text/plain; charset=iso-8859-1
+set mail_check=90
+set timeout=15
</screen>
-then Mutt will expand %{charset} to iso-8859-1. The default metamail
-mailcap file uses this feature to test the charset to spawn an xterm
-using the right charset to view the message.
+with relatively good results over my slow modem line.
</para>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>\%</term>
-<listitem>
+
<para>
-This will be replaced by a %
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-Mutt does not currently support the %F and %n keywords
-specified in RFC 1524. The main purpose of these parameters is for
-multipart messages, which is handled internally by Mutt.
+Note that if you are using mbox as the mail store on UW servers prior to
+v12.250, the server has been reported to disconnect a client if another client
+selects the same folder.
</para>
-</sect3>
-
-</sect2>
-
<sect2>
-<title>Example mailcap files</title>
+<title>The Folder Browser</title>
<para>
-This mailcap file is fairly simple and standard:
-
-<programlisting>
-# I'm always running X :)
-video/*; xanim %s > /dev/null
-image/*; xv %s > /dev/null
+As of version 1.2, mutt supports browsing mailboxes on an IMAP
+server. This is mostly the same as the local file browser, with the
+following differences:
-# I'm always running netscape (if my computer had more memory, maybe)
-text/html; netscape -remote 'openURL(%s)'
-</programlisting>
+<itemizedlist>
+<listitem>
+<para>
+In lieu of file permissions, mutt displays the string "IMAP",
+possibly followed by the symbol "+", indicating
+that the entry contains both messages and subfolders. On
+Cyrus-like servers folders will often contain both messages and
+subfolders.
</para>
+</listitem>
+<listitem>
<para>
-This mailcap file shows quite a number of examples:
+For the case where an entry can contain both messages and
+subfolders, the selection key (bound to <literal>enter</literal> by default)
+will choose to descend into the subfolder view. If you wish to view
+the messages in that folder, you must use <literal>view-file</literal> instead
+(bound to <literal>space</literal> by default).
</para>
+</listitem>
+<listitem>
<para>
+You can create, delete and rename mailboxes with the
+<literal>create-mailbox</literal>, <literal>delete-mailbox</literal>, and
+<literal>rename-mailbox</literal> commands (default bindings: <literal>C</literal>,
+<literal>d</literal> and <literal>r</literal>, respectively). You may also
+<literal>subscribe</literal> and <literal>unsubscribe</literal> to mailboxes (normally
+these are bound to <literal>s</literal> and <literal>u</literal>, respectively).
+</para>
+</listitem>
-<programlisting>
-# Use xanim to view all videos Xanim produces a header on startup,
-# send that to /dev/null so I don't see it
-video/*; xanim %s > /dev/null
-
-# Send html to a running netscape by remote
-text/html; netscape -remote 'openURL(%s)'; test=RunningNetscape
-
-# If I'm not running netscape but I am running X, start netscape on the
-# object
-text/html; netscape %s; test=RunningX
-
-# Else use lynx to view it as text
-text/html; lynx %s
-
-# This version would convert the text/html to text/plain
-text/html; lynx -dump %s; copiousoutput
-
-# I use enscript to print text in two columns to a page
-text/*; more %s; print=enscript -2Gr %s
-
-# Netscape adds a flag to tell itself to view jpegs internally
-image/jpeg;xv %s; x-mozilla-flags=internal
-
-# Use xv to view images if I'm running X
-# In addition, this uses the \ to extend the line and set my editor
-# for images
-image/*;xv %s; test=RunningX; \
- edit=xpaint %s
-
-# Convert images to text using the netpbm tools
-image/*; (anytopnm %s | pnmscale -xysize 80 46 | ppmtopgm | pgmtopbm |
-pbmtoascii -1x2 ) 2>&1 ; copiousoutput
-
-# Send excel spreadsheets to my NT box
-application/ms-excel; open.pl %s
-</programlisting>
+</itemizedlist>
</para>
</sect2>
-</sect1>
+<sect2>
+<title>Authentication</title>
-<sect1 id="auto-view">
-<title>MIME Autoview</title>
+<para>
+Mutt supports four authentication methods with IMAP servers: SASL,
+GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
+NTLM authentication for you poor exchange users out there, but it has
+yet to be integrated into the main tree). There is also support for
+the pseudo-protocol ANONYMOUS, which allows you to log in to a public
+IMAP server without having an account. To use ANONYMOUS, simply make
+your username blank or "anonymous".
+</para>
<para>
-In addition to explicitly telling Mutt to view an attachment with the
-MIME viewer defined in the mailcap file, Mutt has support for
-automatically viewing MIME attachments while in the pager.
+SASL is a special super-authenticator, which selects among several protocols
+(including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure
+method available on your host and the server. Using some of these methods
+(including DIGEST-MD5 and possibly GSSAPI), your entire session will be
+encrypted and invisible to those teeming network snoops. It is the best
+option if you have it. To use it, you must have the Cyrus SASL library
+installed on your system and compile mutt with the <emphasis>--with-sasl</emphasis> flag.
</para>
<para>
-To work, you must define a viewer in the mailcap file which uses the
-<literal>copiousoutput</literal> option to denote that it is non-interactive.
-Usually, you also use the entry to convert the attachment to a text
-representation which you can view in the pager.
+Mutt will try whichever methods are compiled in and available on the server,
+in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.
</para>
<para>
-You then use the <literal>auto_view</literal> muttrc command to list the
-content-types that you wish to view automatically.
-</para>
+There are a few variables which control authentication:
-<para>
-For instance, if you set auto_view to:
+<itemizedlist>
+<listitem>
-<screen>
-auto_view text/html application/x-gunzip \
- application/postscript image/gif application/x-tar-gz
-</screen>
+<para>
+<link linkend="imap-user">$imap_user</link> - controls
+the username under which you request authentication on the IMAP server,
+for all authenticators. This is overridden by an explicit username in
+the mailbox path (ie by using a mailbox name of the form
+<literal>{user@host}</literal>).
+</para>
+</listitem>
+<listitem>
+<para>
+<link linkend="imap-pass">$imap_pass</link> - a
+password which you may preset, used by all authentication methods where
+a password is needed.
</para>
+</listitem>
+<listitem>
<para>
-Mutt could use the following mailcap entries to automatically view
-attachments of these types.
+<link linkend="imap-authenticators">$imap_authenticators</link> - a colon-delimited list of IMAP
+authentication methods to try, in the order you wish to try them. If
+specified, this overrides mutt's default (attempt everything, in the order
+listed above).
+</para>
+</listitem>
-<screen>
-text/html; lynx -dump %s; copiousoutput; nametemplate=%s.html
-image/*; anytopnm %s | pnmscale -xsize 80 -ysize 50 | ppmtopgm | \
- pgmtopbm | pbmtoascii ; copiousoutput
-application/x-gunzip; gzcat; copiousoutput
-application/x-tar-gz; gunzip -c %s | tar -tf - ; copiousoutput
-application/postscript; ps2ascii %s; copiousoutput
-</screen>
+</itemizedlist>
</para>
-<para>
-``unauto_view'' can be used to remove previous entries from the autoview list.
-This can be used with message-hook to autoview messages based on size, etc.
-``unauto_view *'' will remove all previous entries.
-</para>
+</sect2>
</sect1>
-<sect1 id="alternative-order">
-<title>MIME Multipart/Alternative</title>
+<sect1 id="account-hook">
+<title>Managing multiple IMAP/POP accounts</title>
<para>
-Mutt has some heuristics for determining which attachment of a
-multipart/alternative type to display. First, mutt will check the
-alternative_order list to determine if one of the available types
-is preferred. The alternative_order list consists of a number of
-mimetypes in order, including support for implicit and explicit
-wildcards, for example:
-
-<screen>
-alternative_order text/enriched text/plain text application/postscript image/*
-</screen>
-
+If you happen to have accounts on multiple IMAP and/or POP servers,
+you may find managing all the authentication settings inconvenient and
+error-prone. The account-hook command may help. This hook works like
+folder-hook but is invoked whenever you access a remote mailbox
+(including inside the folder browser), not just when you open the
+mailbox.
</para>
<para>
-Next, mutt will check if any of the types have a defined
-<link linkend="auto-view">auto_view</link>, and use that. Failing
-that, Mutt will look for any text type. As a last attempt, mutt will
-look for any type it knows how to handle.
+Some examples:
</para>
<para>
-To remove a MIME type from the <literal>alternative_order</literal> list, use the
-<literal>unalternative_order</literal> command.
+
+<screen>
+account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
+account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
+account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
+</screen>
+
</para>
</sect1>
-<sect1 id="attachments">
-<title>Attachment Searching and Counting</title>
+<sect1 id="caching">
+<title>Local caching</title>
<para>
-If you ever lose track of attachments in your mailboxes, Mutt's
-attachment-counting and -searching support might be for you. You can
-make your message index display the number of qualifying attachments in
-each message, or search for messages by attachment count. You also can
-configure what kinds of attachments qualify for this feature with the
-attachments and unattachments commands.
+Mutt contains two types of local caching: <emphasis>(1)</emphasis>
+the so-called ``header caching'' and <emphasis>(2)</emphasis> the
+so-called ``body caching'' which are both described in this section.
</para>
<para>
-In order to provide this information, mutt needs to fully MIME-parse
-all messages affected first. This can slow down operation especially for
-remote mail folders such as IMAP because all messages have to be
-downloaded first regardless whether the user really wants to view them
-or not.
+These are optional which means they're not enabled by default.
+Details on how to enable either of these techniques are given in the
+following subsections.
</para>
-<para>
-The syntax is:
-</para>
-<screen>
-attachments {+|-}disposition mime-type
-unattachments {+|-}disposition mime-type
-attachments ?
-</screen>
+<sect2 id="header-caching">
+<title>Header caching</title>
<para>
-Disposition is the attachment's Content-disposition type -- either
-"inline" or "attachment". You can abbreviate this to I or A.
+Mutt provides optional support for caching message headers for the
+following types of folders: IMAP, POP, Maildir and MH. Header caching
+greatly improves speed because for remote folders, headers
+usually only need to be downloaded once. For Maildir and MH, reading the
+headers from a single file is much faster than looking at possibly
+thousands of single files (since Maildir and MH use one file per message.)
</para>
<para>
-Disposition is prefixed by either a + symbolor a - symbol. If it's
-a +, you're saying that you want to allow this disposition and MIME
-type to qualify. If it's a -, you're saying that this disposition
-and MIME type is an exception to previous + rules. There are examples
-below of how this is useful.
+Header caching can be enabled via the configure script and the
+<emphasis>--enable-hcache</emphasis> option. It's not turned on
+by default because external database libraries are required: one
+of qdbm, gdbm or bdb must be present.
</para>
<para>
-Mime-type is, unsurprisingly, the MIME type of the attachment you want
-to affect. A MIME type is always of the format "major/minor", where
-"major" describes the broad category of document you're looking at, and
-"minor" describes the specific type within that category. The major
-part of mim-type must be literal text (or the special token "*"), but
-the minor part may be a regular expression. (Therefore, "*/.*" matches
-any MIME type.)
+If enabled, <link
+linkend="header-cache">$header_cache</link> can be
+used to either point to a file or a directory. If set to point to
+a file, one database file for all folders will be used (which may
+result in lower performance), but one file per folder if it points
+to a directory.
</para>
<para>
-The MIME types you give to the attachments directive are a kind of
-pattern. When you use the attachments directive, the patterns you
-specify are added to a list. When you use unattachments, the pattern
-is removed from the list. The patterns are not expanded and matched
-to specific MIME types at this time -- they're just text in a list.
-They're only matched when actually evaluating a message.
+For the one-file-per-folder case, database files will be named by MD5
+sums. They may be safely removed if a system is short on space. You
+can compute the name of the header cache file for a particular folder
+through a command like the following:
</para>
<para>
-Some examples might help to illustrate. The examples that are not
-commented out define the default configuration of the lists.
-</para>
-
<screen>
-## Removing a pattern from a list removes that pattern literally. It
-## does not remove any type matching the pattern.
-##
-## attachments +A */.*
-## attachments +A image/jpeg
-## unattachments +A */.*
-##
-## This leaves "attached" image/jpeg files on the allowed attachments
-## list. It does not remove all items, as you might expect, because the
-## second */.* is not a matching expression at this time.
-##
-## Remember: "unattachments" only undoes what "attachments" has done!
-## It does not trigger any matching on actual messages.
-
-
-## Qualify any MIME part with an "attachment" disposition, EXCEPT for
-## text/x-vcard and application/pgp parts. (PGP parts are already known
-## to mutt, and can be searched for with ~g, ~G, and ~k.)
-##
-## I've added x-pkcs7 to this, since it functions (for S/MIME)
-## analogously to PGP signature attachments. S/MIME isn't supported
-## in a stock mutt build, but we can still treat it specially here.
-##
-attachments +A */.*
-attachments -A text/x-vcard application/pgp.*
-attachments -A application/x-pkcs7-.*
-
-## Discount all MIME parts with an "inline" disposition, unless they're
-## text/plain. (Why inline a text/plain part unless it's external to the
-## message flow?)
-##
-attachments +I text/plain
-
-## These two lines make Mutt qualify MIME containers. (So, for example,
-## a message/rfc822 forward will count as an attachment.) The first
-## line is unnecessary if you already have "attach-allow */.*", of
-## course. These are off by default! The MIME elements contained
-## within a message/* or multipart/* are still examined, even if the
-## containers themseves don't qualify.
-##
-#attachments +A message/.* multipart/.*
-#attachments +I message/.* multipart/.*
-
-## You probably don't really care to know about deleted attachments.
-attachments -A message/external-body
-attachments -I message/external-body
+$ printf '%s' '/path/to/folder' | md5sum
+$ printf '%s' 'imaps://user@host/path/to/folder' | md5sum
+$ printf '%s' 'pops://user@host' | md5sum
</screen>
+</para>
<para>
-"attachments ?" will list your current settings in Muttrc format, so
-that it can be pasted elsewhere.
+The <literal>md5sum</literal> command may also be
+named <literal>md5</literal>, depending on your operating system.
</para>
-</sect1>
+</sect2>
-<sect1 id="mime-lookup">
-<title>MIME Lookup</title>
+<sect2 id="body-caching">
+<title>Body caching</title>
<para>
-Mutt's mime_lookup list specifies a list of mime-types that should not
-be treated according to their mailcap entry. This option is designed to
-deal with binary types such as application/octet-stream. When an attachment's
-mime-type is listed in mime_lookup, then the extension of the filename will
-be compared to the list of extensions in the mime.types file. The mime-type
-associated with this extension will then be used to process the attachment
-according to the rules in the mailcap file and according to any other configuration
-options (such as auto_view) specified. Common usage would be:
+In addition to caching message headers only, mutt can also cache
+whole message bodies. This results in faster display of messages
+for POP and IMAP folders because messages usually have to be
+downloaded only once.
+</para>
-<screen>
-mime_lookup application/octet-stream application/X-Lotus-Manuscript
-</screen>
+<para>
+If the configure script is called with <emphasis>--enable-pop</emphasis>
+and/or <emphasis>--enable-imap</emphasis>, body caching will be
+built in as it does not require additional software packages such
+as database libraries.
+</para>
+<para>
+For configuration, the variable <link linkend="message-cachedir"
+>$message_cachedir</link> must point to a
+directory. There, mutt will create a hierarchy of subdirectories
+named like: <literal>proto:user@hostname</literal> where
+<literal>proto</literal> is either ``pop'' or ``imap.'' Within
+there for each folder, mutt stores messages in single files (just
+like Maildir) so that with manual symlink creation these cache
+directories can be examined with mutt as read-only Maildir folders.
</para>
<para>
-In addition, the unmime_lookup command may be used to disable this feature
-for any particular mime-type if it had been set, for example, in a global
-muttrc.
+All files can be removed as needed if the consumed disk space
+becomes an issue as mutt will silently fetch missing items again.
</para>
+</sect2>
+
</sect1>
</chapter>
projects / neomutt / commitdiff