From: Rocco Rutte Date: Thu, 1 Nov 2007 10:45:44 +0000 (+0100) Subject: Manual: Move POP3, IMAP and cache-related sections to their own chapter. X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=65bccee6ef699581a0605fa8af671a5ae91e062f;p=neomutt Manual: Move POP3, IMAP and cache-related sections to their own chapter. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 173f352a7..57dde87f4 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,7 +27,7 @@ EXTRA_DIST = dotlock.man \ HTML_DOCFILES = manual.html index.html intro.html gettingstarted.html \ configuration.html mimesupport.html advancedusage.html \ - tuning.html reference.html miscellany.html + optionalfeatures.html tuning.html reference.html miscellany.html BUILT_DISTFILES = stamp-doc-xml stamp-doc-chunked manual.txt $(HTML_DOCFILES) diff --git a/doc/manual.xml.head b/doc/manual.xml.head index 1c97ecf2a..a37cf695d 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -4630,1325 +4630,1330 @@ message). Refer to the man page on sendmail for more details on DSN. - -POP3 Support (OPTIONAL) + +Start a WWW Browser on URLs (EXTERNAL) -If Mutt was compiled with POP3 support (by running the configure -script with the --enable-pop flag), it has the ability to work -with mailboxes located on a remote POP3 server and fetch mail for local -browsing. - +If a message contains URLs (unified resource locator = address in the +WWW space like http://www.mutt.org/), 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 ftp://ftp.mutt.org/mutt/contrib/ and the configuration commands: - -You can access the remote POP3 mailbox by selecting the folder -pop://popserver/. - + +macro index \cb |urlview\n +macro pager \cb |urlview\n + - -You can select an alternative port by specifying it with the server, ie: -pop://popserver:port/. - -You can also specify different username for each folder, ie: -pop://username@popserver[:port]/. - + - -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 -$pop_checkinterval -variable, which defaults to every 60 seconds. - + - -If Mutt was compiled with SSL support (by running the configure -script with the --with-ssl 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: -pops://[username@]popserver[:port]/. - + +Mutt's MIME Support -Another way to access your POP3 mail is the fetch-mail function -(default: G). It allows to connect to $pop_host, fetch all your new mail and place it in the -local $spoolfile. 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 +mime.types file, which contains the mapping of file extensions to +IANA MIME types. The other is the mailcap file, which specifies +the external commands to use for handling specific MIME types. + +Using MIME in Mutt + -Note: If you only need to fetch all messages to local mailbox -you should consider using a specialized program, such as fetchmail +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. - - - -IMAP Support (OPTIONAL) + +Viewing MIME messages in the pager -If Mutt was compiled with IMAP support (by running the configure -script with the --enable-imap 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 text/plain, text/enriched, +message/rfc822, and message/news. In addition, the export +controlled version of Mutt recognizes a variety of PGP MIME types, +including PGP/MIME and application/pgp. -You can access the remote inbox by selecting the folder -imap://imapserver/INBOX, where imapserver is the name of the -IMAP server and INBOX 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 imap://imapserver/path/to/folder where -path/to/folder is the path of the folder you want to access. - +Mutt will denote attachments with a couple lines describing them. +These lines are of the form: - -You can select an alternative port by specifying it with the server, ie: -imap://imapserver:port/INBOX. + +[-- Attachment #1: Description --] +[-- Type: text/plain, Encoding: 7bit, Size: 10000 --] + + +Where the Description is the description or filename given for the +attachment, and the Encoding is one of +7bit/8bit/quoted-printable/base64/binary. -You can also specify different username for each folder, ie: -imap://username@imapserver[:port]/INBOX. +If Mutt cannot deal with a MIME type, it will display a message like: + + +[-- image/gif is unsupported (use 'v' to view this part) --] + + + + + +The Attachment Menu + -If Mutt was compiled with SSL support (by running the configure -script with the --with-ssl 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 imaps://[username@]imapserver[:port]/path/to/folder as your -folder path. +The default binding for view-attachments 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. -Pine-compatible notation is also supported, ie -{[username@]imapserver[:port][/ssl]}path/to/folder +Finally, you can apply the usual message-related functions (like +resend-message, and the reply +and forward functions) to attachments of type message/rfc822. -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. + + + +The Compose Menu + -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 -toggle-subscribed command. See also the -$imap_list_subscribed 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. -Polling for new mail on an IMAP server can cause noticeable delays. So, you'll -want to carefully tune the -$mail_check -and -$timeout -variables. Personally I use +Attachments appear as follows: -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> -with relatively good results over my slow modem line. -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 +toggle-unlink command (default: u). The next field is the MIME +content-type, and can be changed with the edit-type 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 edit-encoding 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 rename-file command (default: R). +The final field is the description of the attachment, and can be +changed with the edit-description command (default: d). - -The Folder Browser + - -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: + - - + +MIME Type configuration with <literal>mime.types</literal> -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 ${HOME}/.mime.types, and then +the system mime.types file at /usr/local/share/mutt/mime.types or +/etc/mime.types - - -For the case where an entry can contain both messages and -subfolders, the selection key (bound to enter by default) -will choose to descend into the subfolder view. If you wish to view -the messages in that folder, you must use view-file instead -(bound to space by default). +The mime.types file consist of lines containing a MIME type and a space +separated list of extensions. For example: + + +application/postscript ps eps +application/pgp pgp +audio/x-aiff aif aifc aiff + + +A sample mime.types file comes with the Mutt distribution, and +should contain most of the MIME types you are likely to use. - - -You can create, delete and rename mailboxes with the -create-mailbox, delete-mailbox, and -rename-mailbox commands (default bindings: C, -d and r, respectively). You may also -subscribe and unsubscribe to mailboxes (normally -these are bound to s and u, 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 text/plain. If the file contains binary information, then Mutt will +mark it as application/octet-stream. You can change the MIME +type that Mutt assigns to an attachment by using the edit-type +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. - - + - - - - - -Authentication + +MIME Viewer configuration with <literal>mailcap</literal> -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. -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 --with-sasl 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: + + +$HOME/.mailcap +$PKGDATADIR/mailcap +$SYSCONFDIR/mailcap +/etc/mailcap +/usr/etc/mailcap +/usr/local/etc/mailcap + + +where $HOME is your home directory. The +$PKGDATADIR and the +$SYSCONFDIR directories depend on where mutt +is installed: the former is the default for shared data, the +latter for system configuration files. -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: + +mutt -nF /dev/null -Q mailcap_path + + -There are a few variables which control authentication: +In particular, the metamail distribution will install a mailcap file, +usually as /usr/local/etc/mailcap, which contains some baseline +entries. + - - + +The Basics of the mailcap file -$imap_user - 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 -{user@host}). +A mailcap file consists of a series of lines which are comments, blank, +or definitions. - - -$imap_pass - 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. - - -$imap_authenticators - 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. - - - + +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. - - - - - -Managing multiple IMAP/POP accounts (OPTIONAL) - -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, +text/plain, text/html, image/gif, +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, image/*, or +video, will match all image types and video types, +respectively. -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. +So, in the simplest form, you can send a text/plain message to the +external pager more on stdin: -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 - - - +Or, you could send the message as a file: - -Start a WWW Browser on URLs (EXTERNAL) + +text/plain; more %s + - -If a message contains URLs (unified resource locator = address in the -WWW space like http://www.mutt.org/), 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 ftp://ftp.mutt.org/mutt/contrib/ and the configuration commands: +Perhaps you would like to use lynx to interactively view a text/html +message: -macro index \cb |urlview\n -macro pager \cb |urlview\n +text/html; lynx %s +In this case, lynx does not support viewing a file from stdin, so you +must use the %s syntax. +Note: 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. - + +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: - -Local caching (OPTIONAL) + +text/html; lynx -dump %s | more + - -Mutt contains two types of local caching: (1) -the so-called ``header caching'' and (2) the -so-called ``body caching'' which are both described in this section. -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: + + +text/html; lynx %s +text/*; more + + +This is the simplest form of a mailcap file. - -Header caching + + + +Secure use of mailcap -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 $mailcap_sanitize variable. -Header caching can be enabled via the configure script and the ---enable-hcache 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: -If enabled, $header_cache 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. +Keep the %-expandos away from shell quoting. +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. -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 $charset inside the backtick expansion is safe, +since it is not itself subject to any further expansion): + -$ 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 - - -The md5sum command may also be -named md5, depending on your operating system. - -Body caching + +Advanced mailcap Usage - -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. - + +Optional Fields -If the configure script is called with --enable-pop -and/or --enable-imap, body caching will be -built in as it does not require additional software packages such -as database libraries. - +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: + + +copiousoutput + -For configuration, the variable $message_cachedir must point to a -directory. There, mutt will create a hierarchy of subdirectories -named like: proto:user@hostname where -proto 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. - +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 more +in the lynx -dump example in the Basic section: + + +text/html; lynx -dump %s ; copiousoutput + +This will cause lynx to format the text/html output as text/plain +and Mutt will use your standard pager to display the results. + + + + +needsterminal + -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 auto_view, in order to decide whether it should honor the setting +of the $wait_key variable or +not. When an attachment is viewed using an interactive program, and the +corresponding mailcap entry has a needsterminal flag, Mutt will use +$wait_key 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. - - - - - - - - -Mutt's MIME Support - + + + +compose=<command> + -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 -mime.types file, which contains the mapping of file extensions to -IANA MIME types. The other is the mailcap 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. - - -Using MIME in Mutt - + + + +composetyped=<command> + -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. - - -Viewing MIME messages in the pager - + + + +print=<command> + -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 text/plain, text/enriched, -message/rfc822, and message/news. 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. - + + + +edit=<command> + -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. + + + + +nametemplate=<template> + + +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 text/html if the file ends in .html. +So, you would specify lynx as a text/html viewer with a line in +the mailcap file like: -[-- Attachment #1: Description --] -[-- Type: text/plain, Encoding: 7bit, Size: 10000 --] +text/html; lynx %s; nametemplate=%s.html -Where the Description is the description or filename given for the -attachment, and the Encoding is one of -7bit/8bit/quoted-printable/base64/binary. - + + + +test=<command> + -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. +Note: the content-type must match before Mutt performs the test. +For example: -[-- image/gif is unsupported (use 'v' to view this part) --] +text/html; netscape -remote 'openURL(%s)' ; test=RunningX +text/html; lynx %s +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. + + + + - + - -The Attachment Menu + +Search Order -The default binding for view-attachments 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. - +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 image/gif, and you have the following +entries in your mailcap file, Mutt will search for an entry with the +print command: - -Finally, you can apply the usual message-related functions (like -resend-message, and the reply -and forward functions) to attachments of type message/rfc822. + +image/*; xv %s +image/gif; ; print= anytopnm %s | pnmtops | lpr; \ + nametemplate=%s.gif + + +Mutt will skip the image/* entry and use the image/gif +entry with the print command. -See the help on the attachment menu for more information. +In addition, you can use this with auto_view +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. + + +text/html; netscape -remote 'openURL(%s)' ; test=RunningX +text/html; lynx %s; nametemplate=%s.html +text/html; lynx -dump %s; nametemplate=%s.html; copiousoutput + + +For auto_view, 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. - + - -The Compose Menu + +Command Expansion -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. - +The various commands defined in the mailcap files are passed to the +/bin/sh shell using the system() function. Before the +command is passed to /bin/sh -c, it is parsed to expand +various special parameters with information from Mutt. The keywords +Mutt expands are: + + +%s + -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. + + + + +%t + + +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 text/html or +image/gif. + + + + +%{<parameter>} + + +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: -- 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 +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. - + + + +\% + -The '-' denotes that Mutt will delete the file after sending (or -postponing, or canceling) the message. It can be toggled with the -toggle-unlink command (default: u). The next field is the MIME -content-type, and can be changed with the edit-type 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 edit-encoding 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 rename-file command (default: R). -The final field is the description of the attachment, and can be -changed with the edit-description command (default: d). +This will be replaced by a % + + + +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. + + + - + +Example mailcap files + + +This mailcap file is fairly simple and standard: + + +# 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)' + - -MIME Type configuration with <literal>mime.types</literal> + -When you add an attachment to your mail message, Mutt searches your -personal mime.types file at ${HOME}/.mime.types, and then -the system mime.types file at /usr/local/share/mutt/mime.types or -/etc/mime.types +This mailcap file shows quite a number of examples: -The mime.types file consist of lines containing a MIME type and a space -separated list of extensions. For example: - -application/postscript ps eps -application/pgp pgp -audio/x-aiff aif aifc aiff - + +# 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 mime.types file comes with the Mutt distribution, and -should contain most of the MIME types you are likely to use. - +# Send html to a running netscape by remote +text/html; netscape -remote 'openURL(%s)'; test=RunningNetscape - -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 text/plain. If the file contains binary information, then Mutt will -mark it as application/octet-stream. You can change the MIME -type that Mutt assigns to an attachment by using the edit-type -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. - +# 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 - -MIME Viewer configuration with <literal>mailcap</literal> +# This version would convert the text/html to text/plain +text/html; lynx -dump %s; copiousoutput - -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. - +# I use enscript to print text in two columns to a page +text/*; more %s; print=enscript -2Gr %s - -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 - -$HOME/.mailcap -$PKGDATADIR/mailcap -$SYSCONFDIR/mailcap -/etc/mailcap -/usr/etc/mailcap -/usr/local/etc/mailcap - +# 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 $HOME is your home directory. The -$PKGDATADIR and the -$SYSCONFDIR directories depend on where mutt -is installed: the former is the default for shared data, the -latter for system configuration files. - +# 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 + - -The default search path can be obtained by running the following -command: - -mutt -nF /dev/null -Q mailcap_path - + - -In particular, the metamail distribution will install a mailcap file, -usually as /usr/local/etc/mailcap, which contains some baseline -entries. - + - -The Basics of the mailcap file + +MIME Autoview -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. -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 +copiousoutput 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. -A blank line is blank. +You then use the auto_view muttrc command to list the +content-types that you wish to view automatically. -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. - +For instance, if you set auto_view to: - -The content type is specified in the MIME standard type/subtype method. -For example, -text/plain, text/html, image/gif, -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, image/*, or -video, will match all image types and video types, -respectively. - + +auto_view text/html application/x-gunzip \ + application/postscript image/gif application/x-tar-gz + - -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. -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. -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 -Or, you could send the message as a file: - - -text/plain; more %s - + -Perhaps you would like to use lynx to interactively view a text/html -message: + +``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. + - -text/html; lynx %s - + -In this case, lynx does not support viewing a file from stdin, so you -must use the %s syntax. -Note: 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. - + +MIME Multipart/Alternative -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: -text/html; lynx -dump %s | more +alternative_order text/enriched text/plain text application/postscript image/* -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: - - -text/html; lynx %s -text/*; more - +Next, mutt will check if any of the types have a defined +auto_view, 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. + -This is the simplest form of a mailcap file. + +To remove a MIME type from the alternative_order list, use the +unalternative_order command. - + - -Secure use of mailcap + +Attachment Searching and Counting -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 $mailcap_sanitize 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. + + + +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. + + + +The syntax is: + + +attachments {+|-}disposition mime-type +unattachments {+|-}disposition mime-type +attachments ? + + + +Disposition is the attachment's Content-disposition type -- either +"inline" or "attachment". You can abbreviate this to I or A. -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. -Keep the %-expandos away from shell quoting. -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.) -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 $charset 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. +Some examples might help to illustrate. The examples that are not +commented out define the default configuration of the lists. + -text/test-mailcap-bug; cat %s; copiousoutput; test=charset=%{charset} \ - && test "`echo $charset | tr '[A-Z]' '[a-z]'`" != iso-8859-1 - +## 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-.* - -Advanced mailcap Usage +## 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 - -Optional Fields +## 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 + -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: - +"attachments ?" will list your current settings in Muttrc format, so +that it can be pasted elsewhere. + + + + + +MIME Lookup - -copiousoutput - -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 more -in the lynx -dump 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: -text/html; lynx -dump %s ; copiousoutput +mime_lookup application/octet-stream application/X-Lotus-Manuscript -This will cause lynx to format the text/html output as text/plain -and Mutt will use your standard pager to display the results. - - - -needsterminal - + -Mutt uses this flag when viewing attachments with auto_view, in order to decide whether it should honor the setting -of the $wait_key variable or -not. When an attachment is viewed using an interactive program, and the -corresponding mailcap entry has a needsterminal flag, Mutt will use -$wait_key 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. - - - -compose=<command> - + + + + + + +Optional features + + +POP3 Support + -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 configure +script with the --enable-pop flag), it has the ability to work +with mailboxes located on a remote POP3 server and fetch mail for local +browsing. - - - -composetyped=<command> - + -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 +pop://popserver/. - - - -print=<command> - + -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: +pop://popserver:port/. - - - -edit=<command> - + -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: +pop://username@popserver[:port]/. - - - -nametemplate=<template> - - -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 text/html if the file ends in .html. -So, you would specify lynx as a text/html viewer with a line in -the mailcap file like: - -text/html; lynx %s; nametemplate=%s.html - - - - - - -test=<command> - -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. -Note: the content-type must match before Mutt performs the test. -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 +$pop_checkinterval +variable, which defaults to every 60 seconds. + - -text/html; netscape -remote 'openURL(%s)' ; test=RunningX -text/html; lynx %s - + +If Mutt was compiled with SSL support (by running the configure +script with the --with-ssl 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: +pops://[username@]popserver[:port]/. + -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. + +Another way to access your POP3 mail is the fetch-mail function +(default: G). It allows to connect to $pop_host, fetch all your new mail and place it in the +local $spoolfile. After this +point, Mutt runs exactly as if the mail had always been local. - - - + + +Note: If you only need to fetch all messages to local mailbox +you should consider using a specialized program, such as fetchmail - + - -Search Order + +IMAP Support -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 image/gif, and you have the following -entries in your mailcap file, Mutt will search for an entry with the -print command: - - -image/*; xv %s -image/gif; ; print= anytopnm %s | pnmtops | lpr; \ - nametemplate=%s.gif - - -Mutt will skip the image/* entry and use the image/gif -entry with the print command. +If Mutt was compiled with IMAP support (by running the configure +script with the --enable-imap flag), it has the ability to work +with folders located on a remote IMAP server. -In addition, you can use this with auto_view -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. - - -text/html; netscape -remote 'openURL(%s)' ; test=RunningX -text/html; lynx %s; nametemplate=%s.html -text/html; lynx -dump %s; nametemplate=%s.html; copiousoutput - +You can access the remote inbox by selecting the folder +imap://imapserver/INBOX, where imapserver is the name of the +IMAP server and INBOX 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 imap://imapserver/path/to/folder where +path/to/folder is the path of the folder you want to access. + -For auto_view, 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. + +You can select an alternative port by specifying it with the server, ie: +imap://imapserver:port/INBOX. - + +You can also specify different username for each folder, ie: +imap://username@imapserver[:port]/INBOX. + - -Command Expansion + +If Mutt was compiled with SSL support (by running the configure +script with the --with-ssl 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 imaps://[username@]imapserver[:port]/path/to/folder as your +folder path. + -The various commands defined in the mailcap files are passed to the -/bin/sh shell using the system() function. Before the -command is passed to /bin/sh -c, it is parsed to expand -various special parameters with information from Mutt. The keywords -Mutt expands are: - +Pine-compatible notation is also supported, ie +{[username@]imapserver[:port][/ssl]}path/to/folder + - -%s - -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. - - - -%t - + -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 text/html or -image/gif. +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 +toggle-subscribed command. See also the +$imap_list_subscribed variable. - - - -%{<parameter>} - + -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 +$mail_check +and +$timeout +variables. Personally I use -Content-Type: text/plain; charset=iso-8859-1 +set mail_check=90 +set timeout=15 -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. - - - -\% - + -This will be replaced by a % - - - - -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. - - - - -Example mailcap files +The Folder Browser -This mailcap file is fairly simple and standard: - - -# 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)' - + + + +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. + + -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 enter by default) +will choose to descend into the subfolder view. If you wish to view +the messages in that folder, you must use view-file instead +(bound to space by default). + + +You can create, delete and rename mailboxes with the +create-mailbox, delete-mailbox, and +rename-mailbox commands (default bindings: C, +d and r, respectively). You may also +subscribe and unsubscribe to mailboxes (normally +these are bound to s and u, respectively). + + - -# 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 - + - + +Authentication - -MIME Autoview + +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". + -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 --with-sasl flag. -To work, you must define a viewer in the mailcap file which uses the -copiousoutput 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. -You then use the auto_view muttrc command to list the -content-types that you wish to view automatically. - +There are a few variables which control authentication: - -For instance, if you set auto_view to: + + - -auto_view text/html application/x-gunzip \ - application/postscript image/gif application/x-tar-gz - + +$imap_user - 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 +{user@host}). + + + + +$imap_pass - a +password which you may preset, used by all authentication methods where +a password is needed. + + -Mutt could use the following mailcap entries to automatically view -attachments of these types. +$imap_authenticators - 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). + + - -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 - + - -``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. - + - -MIME Multipart/Alternative + +Managing multiple IMAP/POP accounts -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: - - -alternative_order text/enriched text/plain text application/postscript image/* - - +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. -Next, mutt will check if any of the types have a defined -auto_view, 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: -To remove a MIME type from the alternative_order list, use the -unalternative_order command. + + +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"' + + - -Attachment Searching and Counting + +Local caching -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: (1) +the so-called ``header caching'' and (2) the +so-called ``body caching'' which are both described in this section. -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. - -The syntax is: - - -attachments {+|-}disposition mime-type -unattachments {+|-}disposition mime-type -attachments ? - + +Header caching -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.) -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 +--enable-hcache option. It's not turned on +by default because external database libraries are required: one +of qdbm, gdbm or bdb must be present. -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, $header_cache 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. -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: -Some examples might help to illustrate. The examples that are not -commented out define the default configuration of the lists. - - -## 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 + -"attachments ?" will list your current settings in Muttrc format, so -that it can be pasted elsewhere. +The md5sum command may also be +named md5, depending on your operating system. - + - -MIME Lookup + +Body caching -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. + - -mime_lookup application/octet-stream application/X-Lotus-Manuscript - + +If the configure script is called with --enable-pop +and/or --enable-imap, body caching will be +built in as it does not require additional software packages such +as database libraries. + + +For configuration, the variable $message_cachedir must point to a +directory. There, mutt will create a hierarchy of subdirectories +named like: proto:user@hostname where +proto 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. -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. + +