<row><entry><literal><create-alias></literal></entry><entry>named Mutt function</entry></row>
<row><entry><literal>ˆG</literal></entry><entry>Control+G key combination</entry></row>
<row><entry><literal>$mail_check</literal></entry><entry>Mutt configuration option</entry></row>
+<row><entry><literal>$HOME</literal></entry><entry>environment variable</entry></row>
</tbody>
</tgroup>
</table>
interactive commands.
</para>
+<para>
+Mutt is configured through variables which, if the user wants to
+permanently use a non-default value, are written to configuration
+files. Mutt supports a rich config file syntax to make even complex
+configuration files readable and commentable.
+</para>
+
<para>
Because Mutt allows for customizing almost all key bindings, there are
so-called <quote>functions</quote> which can be executed manually (using the
using <link linkend="history-file">$history_file</link>.
You may cycle through them at an editor prompt by using the
<literal><history-up></literal> and/or
-<literal><history-down></literal> commands.
+<literal><history-down></literal> commands. But notice that Mutt
+does not remember the currently entered text, it only cycles through
+history and wraps around at the end or beginning.
</para>
<para>
</itemizedlist>
<para>
-Mutt automatically filters out repeated items from the history. It
+Mutt automatically filters out consecutively repeated items from the history. It
also mimics the behavior of some shells by ignoring items starting
with a space. The latter feature can be useful in macros to not clobber
the history's valuable entries with unwanted entries.
<para>
Similar to many other mail clients, there are two modes in which mail is
-read in Mutt. The first is the index of messages in the mailbox, which is
-called the <quote>index</quote> in Mutt. The second mode is the display of the
+read in Mutt. The first is a list of messages in the mailbox, which is
+called the <quote>index</quote> menu in Mutt. The second mode is the display of the
message contents. This is called the <quote>pager.</quote>
</para>
<title>The Pager</title>
<para>
-By default, Mutt uses its builtin pager to display the contents of messages.
-The pager is very similar to the Unix program <emphasis>less</emphasis> though not nearly as
-featureful.
+By default, Mutt uses its builtin pager to display the contents of
+messages (an external pager such as <literal>less(1)</literal> can be
+configured, see <link linkend="pager">$pager</link> variable).
+The pager is very similar to the Unix program <literal>less(1)</literal>
+though not nearly as featureful.
</para>
<table id="tab-key-pager">
Note that the search commands in the pager take regular expressions,
which are not quite the same as the more
complex <link linkend="patterns">patterns</link> used by the search
-command in the index. This is because the pager only performs simple
-text search, whereas the index provides boolean filtering on several
-aspects of messages.
+command in the index. This is because patterns are used to select messages by
+criteria whereas the pager already displays a selected message.
</para>
</note>
<title>Threaded Mode</title>
<para>
-When the mailbox is <link linkend="sort">sorted</link> by <emphasis>threads</emphasis>, there are
-a few additional functions available in the <emphasis>index</emphasis> and <emphasis>pager</emphasis> modes
-as shown in <xref linkend="tab-key-threads"/>.
+So-called <quote>threads</quote> provide a hierarchy of messages where
+replies are linked to their parent message(s). This organizational form
+is extremely useful in mailing lists where different parts of the
+discussion diverge. Mutt displays threads as a tree structure.
+</para>
+
+<para>
+In Mutt, when a mailbox is <link linkend="sort">sorted</link>
+by <emphasis>threads</emphasis>, there are a few additional functions
+available in the <emphasis>index</emphasis>
+and <emphasis>pager</emphasis> modes as shown in
+<xref linkend="tab-key-threads"/>.
</para>
<table id="tab-key-threads">
</tgroup>
</table>
-<note>
<para>
Collapsing a thread displays only the first message
in the thread and hides the others. This is useful when threads
contain so many messages that you can only see a handful of threads on
the screen. See %M in <link linkend="index-format">$index_format</link>.
For example, you could use "%?M?(#%03M)&(%4l)?" in <link linkend="index-format">$index_format</link> to optionally
-display the number of hidden messages if the thread is collapsed.
+display the number of hidden messages if the thread is
+collapsed. The <literal>%?<char>?<if-part>&<else-part>?</literal>
+syntax is explained in detail in
+<link linkend="formatstrings-conditionals">format string conditionals</link>.
</para>
-</note>
<para>
-See also: <link linkend="strict-threads">$strict_threads</link>.
+Technically, every reply should contain a list of its parent messages in
+the thread tree, but not all do. In these cases, Mutt groups them by
+subject which can be controlled using the
+<link linkend="strict-threads">$strict_threads</link> variable.
</para>
</sect2>
<emphasis>Bouncing</emphasis> a message sends the message as-is to the recipient you
specify. <emphasis>Forwarding</emphasis> a message allows you to add comments or
modify the message you are forwarding. These items are discussed
-in greater detail in the next chapter <quote><link linkend="forwarding-mail">Forwarding
+in greater detail in the next section <quote><link linkend="forwarding-mail">Forwarding
and Bouncing Mail</link>.</quote>
</para>
Mutt will then enter the <emphasis>compose</emphasis> menu and prompt you for the
recipients to place on the <quote>To:</quote> header field. Next, it will ask
you for the <quote>Subject:</quote> field for the message, providing a default if
-you are replying to or forwarding a message. See also
+you are replying to or forwarding a message. You again
+have the chance to adjust recipients, subject, and security settings
+right before actually sending the message. See also
<link linkend="askcc">$askcc</link>,
<link linkend="askbcc">$askbcc</link>,
<link linkend="autoedit">$autoedit</link>,
<link linkend="bounce">$bounce</link>,
<link linkend="fast-reply">$fast_reply</link>,
and <link linkend="include">$include</link>
-for changing how Mutt asks these questions.
+for changing how and if Mutt asks these questions.
</para>
<para>
<para>
When editing the header because of <link linkend="edit-headers">$edit_headers</link>
being set, there are a several pseudo headers available which
-will not be included in sent messages.
+will not be included in sent messages but trigger special Mutt behavior.
</para>
<sect3 id="fcc-header">
<para>
If you specify
+</para>
+<para>
<literal>Fcc:</literal> <emphasis>filename</emphasis>
+</para>
+<para>
as a header, Mutt will pick up <emphasis>filename</emphasis>
just as if you had used the <literal><edit-fcc></literal> function in the <emphasis>compose</emphasis> menu.
</para>
<para>
You can also attach files to your message by specifying
+</para>
-<literal>Attach:</literal> <emphasis>filename</emphasis> [ <emphasis>description</emphasis> ]
+<para>
+<literal>Attach:</literal> <emphasis>filename</emphasis>
+[ <emphasis>description</emphasis> ]
+</para>
+<para>
where <emphasis>filename</emphasis> is the file to attach and <emphasis>description</emphasis> is an
optional string to use as the description of the attached file. Spaces
in filenames have to be escaped using backslash (<quote>\</quote>).
attachment, depending on the value of the <link linkend="mime-forward">$mime_forward</link> variable. Decoding of attachments,
like in the pager, can be controlled by the <link linkend="forward-decode">$forward_decode</link> and <link linkend="mime-forward-decode">$mime_forward_decode</link> variables,
respectively. The desired forwarding format may depend on the content,
-therefore <emphasis>$mime_forward</emphasis> is a quadoption which, for
+therefore <link linkend="mime-forward">$mime_forward</link> is a quadoption which, for
example, can be set to <quote>ask-no</quote>.
</para>
The hash mark, or pound sign
(<quote>#</quote>), is used as a <quote>comment</quote> character. You can use it to
annotate your initialization file. All text after the comment character
-to the end of the line is ignored. For example,
+to the end of the line is ignored.
</para>
<example id="ex-ec-comment">
not interpreted for shell variables or quoting with a backslash [see
next paragraph]), while double quotes indicate a string for which
should be evaluated. For example, backticks are evaluated inside of double
-quotes, but <emphasis role="bold">not</emphasis> for single quotes.
+quotes, but <emphasis>not</emphasis> for single quotes.
</para>
<para>
-\ quotes the next character, just as in shells such as bash and zsh.
+<quote>\</quote> quotes the next character, just as in shells such as bash and zsh.
For example, if want to put quotes <quote>"</quote> inside of a string, you can use
<quote>\</quote> to force the next character to be a literal instead of interpreted
character.
</para>
<para>
-A \ at the end of a line can be used to split commands over
-multiple lines, provided that the split points don't appear in the
-middle of command names.
+A <quote>\</quote> at the end of a line can be used to split commands over
+multiple lines as it <quote>escapes</quote> the line end, provided that the split points don't appear in the
+middle of command names. Lines are first concatenated before
+interpretation so that a multi-line can be commented by commenting out
+the first line only.
</para>
+<example id="ex-rc-split">
+<title>Splitting long configuration commands over several lines</title>
+<screen>
+set status_format="some very \
+long value split \
+over several lines"
+</screen>
+</example>
+
<para>
It is also possible to substitute the output of a Unix command in an
initialization file. This is accomplished by enclosing the command in
-backticks (``). For example,
+backticks (``). In <xref linkend="ex-rc-backtick"/>, the output of the
+Unix command <quote>uname -a</quote> will be substituted before the
+line is parsed.
+Since initialization files are line oriented, only
+the first line of output from the Unix command will be substituted.
</para>
<example id="ex-rc-backtick">
</screen>
</example>
-<para>
-The output of the Unix command <quote>uname -a</quote> will be substituted before the
-line is parsed.
-</para>
-
-<note>
-<para>
-Since initialization files are line oriented, only
-the first line of output from the Unix command will be substituted.
-</para>
-</note>
-
<para>
Both environment variables and mutt variables can be accessed by
prepending <quote>$</quote> to the name of the variable. For example,
<para>
will cause mutt to save outgoing messages to a folder named
-<quote>sent_on_kremvax</quote> if the environment variable HOSTNAME is set to
+<quote>sent_on_kremvax</quote> if the environment variable <literal>$HOSTNAME</literal> is set to
<quote>kremvax.</quote> (See <link linkend="record">$record</link> for
details.)
</para>
If a configuration file is not encoded in the same character set the
<link linkend="config-charset">$config_charset</link>
variable should be used: all lines starting with the next are recoded
-from $config_charset to $charset.
+from <link linkend="config-charset">$config_charset</link>
+to <link linkend="charset">$charset</link>.
</para>
<para>
<itemizedlist>
<listitem><para>These variables should be set early in a configuration
-file with $charset preceding $config_charset so Mutt
-know what character set to convert to.</para></listitem>
+file with <link linkend="charset">$charset</link> preceding
+<link linkend="config-charset">$config_charset</link> so Mutt
+knows what character set to convert to.</para></listitem>
-<listitem><para>If $config_charset is set, it should be set
+<listitem><para>If <link linkend="config-charset">$config_charset</link> is set, it should be set
in each configuration file because the value is global and <emphasis>not</emphasis>
per configuration file.</para></listitem>
<note>
<para>
If you want to create an alias for more than
-one address, you <emphasis role="bold">must</emphasis> separate the addresses with a comma (<quote>,</quote>).
+one address, you <emphasis>must</emphasis> separate the addresses with a comma (<quote>,</quote>).
</para>
</note>
order for the new aliases to take effect you need to explicitly <link linkend="source">source</link> this file too.
</para>
-<para>
-For example:
-</para>
-
<example id="ex-alias-external">
<title>Configuring external alias files</title>
<screen>
In addition, at the various address prompts, you can use the tab character
to expand a partial alias to the full alias. If there are multiple matches,
mutt will bring up a menu with the matching aliases. In order to be
-presented with the full list of aliases, you must hit tab with out a partial
+presented with the full list of aliases, you must hit tab without a partial
alias, such as at the beginning of the prompt or after a comma denoting
multiple addresses.
</para>
Settings are <emphasis>not</emphasis> restored when you leave the mailbox.
For example, a command action to perform is to change the sorting method
based upon the mailbox being read:
-</para>
-</note>
<screen>
-folder-hook mutt set sort=threads
-</screen>
+folder-hook mutt set sort=threads</screen>
-<para>
However, the sorting method is not restored to its previous value when
reading a different mailbox. To specify a <emphasis>default</emphasis> command, use the
pattern <quote>.</quote> before other folder-hooks adjusting a value on a per-folder basis
-because folder-hooks are evaluated in the order given in the configuration file.
+because folder-hooks are evaluated in the order given in the
+configuration file.
+</para>
+</note>
+
+<para>
The following example will set the <link linkend="sort">sort</link> variable
to <literal>date-sent</literal> for all folders but to <literal>threads</literal>
for all folders containing <quote>mutt</quote> in their name.
<para>
Optionally you can specify a descriptive text after <emphasis>sequence</emphasis>,
-which is shown in the help screens.
+which is shown in the help screens if they contain a description.
</para>
<note>
<para>
If your terminal supports color, you can spice up Mutt by creating your own
color scheme. To define the color of an object (type of information), you
-must specify both a foreground color <emphasis role="bold">and</emphasis> a background color (it is not
+must specify both a foreground color <emphasis>and</emphasis> a background color (it is not
possible to only specify one or the other).
</para>
<listitem><para>message (informational messages)</para></listitem>
<listitem><para>normal</para></listitem>
<listitem><para>quoted (text matching <link linkend="quote-regexp">$quote_regexp</link> in the body of a message)</para></listitem>
-<listitem><para>quoted1, quoted2, ..., quoted<emphasis role="bold">N</emphasis> (higher levels of quoting)</para></listitem>
+<listitem><para>quoted1, quoted2, ..., quoted<emphasis>N</emphasis> (higher levels of quoting)</para></listitem>
<listitem><para>search (hiliting of words in the pager)</para></listitem>
<listitem><para>signature</para></listitem><listitem><para>status (mode lines used to display info about the mailbox or message)</para></listitem>
<listitem><para>tilde (the <quote>˜</quote> used to pad blank lines in the pager)</para></listitem>
<note>
<para>
The uncolor command can be applied to the index object only. It
-removes entries from the list. You <emphasis role="bold">must</emphasis> specify the same pattern
+removes entries from the list. You <emphasis>must</emphasis> specify the same pattern
specified in the color command for it to be removed. The pattern <quote>*</quote> is
a special token which means to clear the color index list of all entries.
</para>
<para>
Mutt also recognizes the keywords <emphasis>color0</emphasis>, <emphasis>color1</emphasis>, …,
-<emphasis>color</emphasis><emphasis role="bold">N-1</emphasis> (<emphasis role="bold">N</emphasis> being the number of colors supported
+<emphasis>color</emphasis><emphasis>N-1</emphasis> (<emphasis>N</emphasis> being the number of colors supported
by your terminal). This is useful when you remap the colors for your
display (for example by changing the color associated with <emphasis>color2</emphasis>
for your xterm), since color names may then lose their normal meaning.
</para>
+<anchor id="mono"/>
<para>
If your terminal does not support color, it is still possible change the video
-attributes through the use of the <quote>mono</quote> command:
+attributes through the use of the <quote>mono</quote> command. Usage:
</para>
-<anchor id="mono"/>
-<para>Usage:</para>
-
<cmdsynopsis>
<command>mono</command>
<arg choice="plain">
</sect1>
-<sect1 id="ignore">
+<sect1 id="msg-hdr-display">
<title>Message header display</title>
+<sect2 id="ignore">
+<title>Selecting Headers</title>
+
<para>Usage:</para>
<cmdsynopsis>
<quote>unignore *</quote> will remove all tokens from the ignore list.
</para>
-<para>
-For example:
-</para>
-
<example id="ex-header-weeding">
<title>Header weeding</title>
<screen>
</screen>
</example>
-<anchor id="hdr-order"/>
+</sect2>
+
+<sect2 id="hdr-order">
+<title>Ordering Displayed Headers</title>
+
<para>Usage:</para>
<cmdsynopsis>
</screen>
</example>
+</sect2>
</sect1>
<sect1 id="alternates">
<para>
Mutt has a few nice features for <link linkend="using-lists">handling mailing lists</link>. In order to take advantage of them, you must
specify which addresses belong to mailing lists, and which mailing
-lists you are subscribed to. Once you have done this, the <link linkend="list-reply"><literal><list-reply></literal></link> function will work for all known lists.
+lists you are subscribed to. Mutt also has limited support for
+auto-detecting mailing lists: it supports parsing
+<literal>mailto:</literal> links in the common
+<literal>List-Post:</literal> header which has the same effect as
+specifying the list address via the <literal>lists</literal> command
+(except the group feature). Once you have done this, the
+<link linkend="list-reply"><literal><list-reply></literal></link>
+function will work for all known lists.
Additionally, when you send a message to a subscribed list, mutt will
add a Mail-Followup-To header to tell other users' mail user agents
not to send copies of replies to your personal address.
receiving personal CCs of list messages. Also note that the generation
of the Mail-Followup-To header is controlled by the
<link linkend="followup-to">$followup_to</link>
-configuration variable.
+configuration variable since it's common practice on some mailing lists
+to send Cc upons replies (which is more a group- than a list-reply).
</para>
</note>
</para>
<para>
-You can use regular expressions with both commands. To mark all
-messages sent to a specific bug report's address on mutt's bug
+You can use regular expressions with both commands. To mark all
+messages sent to a specific bug report's address on Debian's bug
tracking system as list mail, for instance, you could say
-<quote>subscribe [0-9]*@bugs.guug.de</quote>. Often, it's sufficient to just
-give a portion of the list's e-mail address.
+</para>
+
+<screen>
+subscribe [0-9]*.*@bugs.debian.org</screen>
+
+<para>
+as it's often, it's sufficient to just give a portion of the list's e-mail address.
</para>
<para>
Specify as much of the address as you need to to remove ambiguity. For
example, if you've subscribed to the Mutt mailing list, you will receive mail
-addressed to <emphasis>mutt-users@mutt.org</emphasis>. So, to tell Mutt
-that this is a mailing list, you could add <quote>lists mutt-users@</quote> to your
+addressed to <literal>mutt-users@mutt.org</literal>. So, to tell Mutt
+that this is a mailing list, you could add <literal>lists mutt-users@</literal> to your
initialization file. To tell mutt that you are subscribed to it,
-add <quote>subscribe mutt-users</quote> to your initialization file instead.
+add <literal>subscribe mutt-users</literal> to your initialization file instead.
If you also happen to get mail from someone whose address is
-<emphasis>mutt-users@example.com</emphasis>, you could use
-<quote>lists ^mutt-users@mutt\\.org$</quote>
-or <quote>subscribe ^mutt-users@mutt\\.org$</quote> to
+<literal>mutt-users@example.com</literal>, you could use
+<literal>lists ^mutt-users@mutt\\.org$</literal>
+or <literal>subscribe ^mutt-users@mutt\\.org$</literal> to
match only mail from the actual list.
</para>
unreliable, the
<link linkend="check-mbox-size">$check_mbox_size</link>
option can be used to make Mutt track and consult file sizes for new
-mail detection instead.
+mail detection instead which won't work for size-neutral changes.
</para>
</sect1>
<para>
The <literal>my_hdr</literal> command allows you to create your own header
-fields which will be added to every message you send.
+fields which will be added to every message you send and appear in the
+editor if <link linkend="edit-headers">$edit_headers</link> is set.
</para>
<para>
For example, if you would like to add an <quote>Organization:</quote> header field to
-all of your outgoing messages, you can put the command
+all of your outgoing messages, you can put the command something like
+shown in <xref linkend="ex-my-hdr"/> in your <literal>.muttrc</literal>.
</para>
<example id="ex-my-hdr">
</screen>
</example>
-<para>
-in your <literal>.muttrc</literal>.
-</para>
-
<note>
<para>
Space characters are <emphasis>not</emphasis> allowed between the keyword and
<emphasis>mailbox</emphasis> after it was expanded.
</para>
-<para>
-Examples:
-</para>
-
<example id="ex-save-hook-exando">
<title>Using %-expandos in <literal>save-hook</literal></title>
<screen>
See <xref linkend="pattern-hook"/> for information on the exact format of <emphasis>pattern</emphasis>.
</para>
-<para>
-Example: <literal>fcc-hook [@.]aol\\.com$ +spammers</literal>
-</para>
+<screen>fcc-hook [@.]aol\\.com$ +spammers</screen>
<para>
-The above will save a copy of all messages going to the aol.com domain to
+...will save a copy of all messages going to the aol.com domain to
the `+spammers' mailbox by default. Also see the <link linkend="fcc-save-hook">fcc-save-hook</link> command.
</para>
<note>
<para>
-<literal>reply-hook</literal>s are matched <emphasis role="bold">before</emphasis> the <literal>send-hook</literal>, <emphasis role="bold">regardless</emphasis>
+<literal>reply-hook</literal>s are matched <emphasis>before</emphasis> the <literal>send-hook</literal>, <emphasis>regardless</emphasis>
of the order specified in the user's configuration file.
</para>
</note>
<note>
<para>
-send-hook's are only executed once after getting the initial
+<literal>send-hook</literal>'s are only executed once after getting the initial
list of recipients. Adding a recipient after replying or editing the
message will not cause any send-hook to be executed. Also note that
-<literal>my_hdr</literal> commands which modify recipient headers, or the message's
+<link linkend="my-hdr"><literal>my_hdr</literal></link> commands which modify recipient headers, or the message's
subject, don't have any effect on the current message when executed
-from a send-hook.
+from a <literal>send-hook</literal>.
</para>
</note>
contain control characters, key names and function names like the sequence
string in the <link linkend="macro">macro</link> command. You may use it to
automatically run a sequence of commands at startup, or when entering
-certain folders. For example, the following command will automatically
-collapse all threads when entering a folder:
+certain folders. For example, <xref linkend="ex-folder-hook-push"/>
+shows how to automatically collapse all threads when entering a folder.
</para>
<example id="ex-folder-hook-push">
<para>
This command can be used to execute any function. Functions are
listed in the <link linkend="functions">function reference</link>.
-<quote>exec function</quote> is equivalent to <quote>push <function></quote>.
+<quote><literal>exec function</literal></quote> is equivalent to
+<quote><literal>push <function></literal></quote>.
</para>
</sect1>
</para>
<para>
-The <literal>unscore</literal> command removes score entries from the list. You <emphasis role="bold">must</emphasis>
+The <literal>unscore</literal> command removes score entries from the list. You <emphasis>must</emphasis>
specify the same pattern specified in the <literal>score</literal> command for it to be
removed. The pattern <quote>*</quote> is a special token which means to clear the list
of all score entries.
If you're using multiple spam filters, a message can have more than
one spam-related header. You can define <literal>spam</literal> patterns for each
filter you use. If a message matches two or more of these patterns, and
-the $spam_separator variable is set to a string, then the
+the <link linkend="spam-separator">$spam_separator</link> variable is set to a string, then the
message's spam tag will consist of all the <emphasis>format</emphasis> strings joined
-together, with the value of $spam_separator separating
+together, with the value of <link linkend="spam-separator">$spam_separator</link> separating
them.
</para>
<para>
-For example, suppose I use DCC, SpamAssassin, and PureMessage. I might
-define these spam settings:
+For example, suppose one uses DCC, SpamAssassin, and PureMessage, then
+the configuration might look like in <xref linkend="ex-spam"/>.
</para>
<example id="ex-spam">
</example>
<para>
-If I then received a message that DCC registered with <quote>many</quote> hits
+If then a message is received that DCC registered with <quote>many</quote> hits
under the <quote>Fuz2</quote> checksum, and that PureMessage registered with a
97% probability of being spam, that message's spam tag would read
<literal>90+/DCC-Fuz2, 97/PM</literal>. (The four characters before <quote>=many</quote> in a
</para>
<para>
-If the $spam_separator variable is unset, then each
+If the <link linkend="spam-separator">$spam_separator</link> variable is unset, then each
spam pattern match supersedes the previous one. Instead of getting
joined <emphasis>format</emphasis> strings, you'll get only the last one to match.
</para>
<para>
The spam tag is what will be displayed in the index when you use
-<literal>%H</literal> in the <literal>$index_format</literal> variable. It's also the
+<literal>%H</literal> in the <link linkend="index-format">$index_format</link> variable. It's also the
string that the <literal>˜H</literal> pattern-matching expression matches against for
<literal><search></literal> and <literal><limit></literal> functions. And it's what sorting by spam
attribute will use as a sort key.
<para>
Since mutt expands such values already when parsing the configuration
file(s), the value of <literal>$my_delete</literal> in the
-last example would be the value of <literal>$delete</literal> exactly
+last example would be the value of <link linkend="delete">$delete</link> exactly
as it was at that point during parsing the configuration file. If
-another statement would change the value for <literal>$delete</literal>
+another statement would change the value for <link linkend="delete">$delete</link>
later in the same or another file, it would have no effect on
<literal>$my_delete</literal>. However, the expansion can
be deferred to runtime, as shown in the next example, when escaping the
<link linkend="index-format">$index_format</link>,
<link linkend="pager-format">$pager_format</link>,
<link linkend="status-format">$status_format</link>,
-and other <quote>*_format</quote> variables. These can be very straightforward,
+and other related variables. These can be very straightforward,
and it's quite possible you already know how to use them.
</para>
<para>
Some of the modifiers are borrowed right out of C (though you might
know them from Perl, Python, shell, or another language). These are
-the [-]m.n modifiers, as in <literal>%-12.12s</literal>. As with
+the <literal>[-]m.n</literal> modifiers, as in <literal>%-12.12s</literal>. As with
such programming languages, these modifiers allow you to specify the
minimum and maximum size of the resulting string, as well as its
justification. If the <quote>-</quote> sign follows the percent, the string will
follow, that's the maximum space allowable -- the string will not be
permitted to exceed that width, no matter its natural size. Each of
these three elements is optional, so that all these are legal format
-strings:
-<literal>%-12s</literal>
-<literal>%4c</literal>
-<literal>%.15F</literal>
-<literal>%-12.15L</literal>
+strings: <literal>%-12s</literal>, <literal>%4c</literal>,
+<literal>%.15F</literal> and <literal>%-12.15L</literal>.
</para>
<para>
above), it will force the string to be centered within its minimum
space range. For example, <literal>%=14y</literal> will reserve 14
characters for the %y expansion -- that's the X-Label: header, in
-<literal>$index_format</literal>. If the expansion
+<link linkend="index-format">$index_format</link>. If the expansion
results in a string less than 14 characters, it will be centered in a
14-character space. If the X-Label for a message were "test", that
-expansion would look like <quote> test </quote>.
+expansion would look like <quote> test </quote>.
</para>
<para>
<note>
<para>
-Note that <quote>\</quote>
+<quote>\</quote>
must be quoted if used for a regular expression in an initialization
command: <quote>\\</quote>.
</para>
<note>
<para>
-Note that the regular expression can be enclosed/delimited by either "
+The regular expression can be enclosed/delimited by either "
or ' which is useful if the regular expression includes a white-space
character. See <xref linkend="muttrc-syntax"/>
for more information on " and ' delimiter processing. To match a
<para>
A list of characters enclosed by <quote>[</quote> and <quote>]</quote> matches any
single character in that list; if the first character of the list
-is a caret <quote>ˆ</quote> then it matches any character <emphasis role="bold">not</emphasis> in the
-list. For example, the regular expression <emphasis role="bold">[0123456789]</emphasis>
+is a caret <quote>ˆ</quote> then it matches any character <emphasis>not</emphasis> in the
+list. For example, the regular expression <emphasis>[0123456789]</emphasis>
matches any single digit. A range of ASCII characters may be specified
by giving the first and last characters, separated by a hyphen
<quote>-</quote>. Most metacharacters lose their special meaning inside
Note that the brackets in these
class names are part of the symbolic names, and must be included
in addition to the brackets delimiting the bracket list. For
-example, <emphasis role="bold">[[:digit:]]</emphasis> is equivalent to
-<emphasis role="bold">[0-9]</emphasis>.
+example, <emphasis>[[:digit:]]</emphasis> is equivalent to
+<emphasis>[0-9]</emphasis>.
</para>
</note>
<para>
A collating symbol is a multi-character collating element enclosed in
<quote>[.</quote> and <quote>.]</quote>. For example, if <quote>ch</quote> is a collating
-element, then <emphasis role="bold">[[.ch.]]</emphasis> is a regexp that matches
-this collating element, while <emphasis role="bold">[ch]</emphasis> is a regexp that
+element, then <emphasis>[[.ch.]]</emphasis> is a regexp that matches
+this collating element, while <emphasis>[ch]</emphasis> is a regexp that
matches either <quote>c</quote> or <quote>h</quote>.
</para>
</listitem>
characters that are equivalent. The name is enclosed in <quote>[=</quote>
and <quote>=]</quote>. For example, the name <quote>e</quote> might be used to
represent all of <quote>è</quote> <quote>é</quote> and <quote>e</quote>. In this case,
-<emphasis role="bold">[[=e=]]</emphasis> is a regexp that matches any of
+<emphasis>[[=e=]]</emphasis> is a regexp that matches any of
<quote>è</quote>, <quote>é</quote> and <quote>e</quote>.
</para>
</listitem>
<para>
Special attention has to be
-made when using regular expressions inside of patterns. Specifically,
+payed when using regular expressions inside of patterns. Specifically,
Mutt's parser for these patterns will strip one level of backslash (<quote>\</quote>),
which is normally used for quoting. If it is your intention to use a
backslash in the regular expression, you will need to use two backslashes
<para>
Mutt supports two versions of so called <quote>simple searches</quote>. These are
issued if the query entered for searching, limiting and similar
-operations does not seem contain a valid pattern modifier (i.e. it does not contain
+operations does not seem to contain a valid pattern modifier (i.e. it does not contain
one of these characters: <quote>˜</quote>, <quote>=</quote> or <quote>%</quote>). If the query is
supposed to contain one of these special characters, they must be escaped
by prepending a backslash (<quote>\</quote>).
<para>
would select messages which contain the word <quote>mutt</quote> in the list of
-recipients <emphasis role="bold">and</emphasis> that have the word <quote>elkins</quote> in the <quote>From</quote> header
+recipients <emphasis>and</emphasis> that have the word <quote>elkins</quote> in the <quote>From</quote> header
field.
</para>
<note>
<para>
If a regular expression contains parenthesis, or a vertical bar
-("|"), you <emphasis role="bold">must</emphasis> enclose the expression in double or single quotes since
+("|"), you <emphasis>must</emphasis> enclose the expression in double or single quotes since
those characters are also used to separate different parts of Mutt's
pattern language. For example: <literal>~f "me@(mutt\.org|cs\.hmc\.edu)"</literal>
-</para>
-</note>
-
-<para>
Without the quotes, the parenthesis wouldn't end.
This would be separated to two OR'd patterns: <emphasis>˜f me@(mutt\.org</emphasis>
and <emphasis>cs\.hmc\.edu)</emphasis>. They are never what you want.
</para>
+</note>
</sect2>
Mutt supports two types of dates, <emphasis>absolute</emphasis> and <emphasis>relative</emphasis>.
</para>
+<sect3 id="date-absolute">
+<title>Absolute Dates</title>
+
<para>
-<emphasis role="bold">Absolute</emphasis>. Dates <emphasis role="bold">must</emphasis> be in DD/MM/YY format (month and year are
+Dates <emphasis>must</emphasis> be in DD/MM/YY format (month and year are
optional, defaulting to the current month and year). An example of a valid
range of dates is:
</para>
</para>
<para>
-<emphasis role="bold">Error Margins</emphasis>. You can add error margins to absolute dates.
+You can add error margins to absolute dates.
An error margin is a sign (+ or -), followed by a digit, followed by
one of the units in <xref linkend="tab-date-units"/>. As a special case, you can replace the
sign by a <quote>*</quote> character, which is equivalent to giving identical plus and minus error margins.
Limit to messages matching: ~d 15/1/2001*2w
</screen>
+</sect3>
+
+<sect3 id="dates-relative">
+<title>Relative Dates</title>
+
<para>
-<emphasis role="bold">Relative</emphasis>. This type of date is relative to the current date, and may
+This type of date is relative to the current date, and may
be specified as:
</para>
<listitem>
<para>
-><emphasis>offset</emphasis> (messages older than <emphasis>offset</emphasis> units)
+><emphasis>offset</emphasis> for messages older than <emphasis>offset</emphasis> units
</para>
</listitem>
<listitem>
<para>
-<<emphasis>offset</emphasis> (messages newer than <emphasis>offset</emphasis> units)
+<<emphasis>offset</emphasis> for messages newer than <emphasis>offset</emphasis> units
</para>
</listitem>
<listitem>
<para>
-=<emphasis>offset</emphasis> (messages exactly <emphasis>offset</emphasis> units old)
+=<emphasis>offset</emphasis> for messages exactly <emphasis>offset</emphasis> units old
</para>
</listitem>
<note>
<para>
All dates used when searching are relative to the
-<emphasis role="bold">local</emphasis> time zone, so unless you change the setting of your <link linkend="index-format">$index_format</link> to include a
-<literal>%[...]</literal> format, these are <emphasis role="bold">not</emphasis> the dates shown
+<emphasis>local</emphasis> time zone, so unless you change the setting of your <link linkend="index-format">$index_format</link> to include a
+<literal>%[...]</literal> format, these are <emphasis>not</emphasis> the dates shown
in the main index.
</para>
</note>
+</sect3>
+
</sect2>
</sect1>
<para>
Once you have tagged the desired messages, you can use the
<quote>tag-prefix</quote> operator, which is the <quote>;</quote> (semicolon) key by default.
-When the <quote>tag-prefix</quote> operator is used, the <emphasis role="bold">next</emphasis> operation will
+When the <quote>tag-prefix</quote> operator is used, the <emphasis>next</emphasis> operation will
be applied to all tagged messages if that operation can be used in that
manner. If the <link linkend="auto-tag">$auto_tag</link>
variable is set, the next operation applies to the tagged messages
<para>
In <link linkend="macro">macros</link> or <link linkend="push">push</link> commands,
-you can use the <quote>tag-prefix-cond</quote> operator. If there are no tagged
-messages, mutt will "eat" the rest of the macro to abort it's execution.
-Mutt will stop "eating" the macro when it encounters the <quote>end-cond</quote>
-operator; after this operator the rest of the macro will be executed as
+you can use the <literal><tag-prefix-cond></literal> operator. If there are no tagged
+messages, mutt will <quote>eat</quote> the rest of the macro to abort it's execution.
+Mutt will stop <quote>eating</quote> the macro when it encounters the <literal><end-cond></literal>
+operator; after this operator the rest of the macro will be executed as
normal.
</para>
reading, or to whom you are sending mail. In the Mutt world, a <emphasis>hook</emphasis>
consists of a <link linkend="regexp">regular expression</link> or
<link linkend="patterns">pattern</link> along with a
-configuration option/command. See
+configuration option/command. See:
<itemizedlist>
<para>
If a hook changes configuration settings, these changes remain
effective until the end of the current mutt session. As this is generally
-not desired, a default hook needs to be added before all other hooks to
-restore configuration defaults. Here is an example with send-hook and the
-my_hdr directive:
+not desired, a <quote>default</quote> hook needs to be added before all
+other hooks of that type to restore configuration defaults.
</para>
</note>
-<example id="ex-send-hook-my-hdr">
-<title>Combining <literal>send-hook</literal> and <literal>my_hdr</literal></title>
+<example id="ex-default-hook">
+<title>Specifying a <quote>default</quote> hook</title>
<screen>
send-hook . 'unmy_hdr From:'
send-hook ~C'^b@b\.b$' my_hdr from: c@c.c
</screen>
</example>
+<para>
+In <xref linkend="ex-default-hook"/>, by default the value of
+<link linkend="from">$from</link>
+and <link linkend="realname">$realname</link>
+is not overridden. When sending messages either To: or Cc:
+to <literal><b@b.b></literal>, the From: header is changed to
+<literal><c@c.c></literal>.
+</para>
+
<sect2 id="pattern-hook" xreflabel="Message Matching in Hooks">
<title>Message Matching in Hooks</title>
<para>
There are a number of built in shortcuts which refer to specific mailboxes.
These shortcuts can be used anywhere you are prompted for a file or mailbox
-path.
+path or in path-related configuration variables. Note that these only
+work at the beginning of a string.
</para>
<itemizedlist>
</itemizedlist>
+<para>
+For example, to store a copy of outgoing messages in the folder they
+were composed in,
+a <link linkend="folder-hook">folder-hook</link> can
+be used to set <link linkend="record">$record</link>:
+</para>
+
+<screen>
+folder-hook . 'set record=ˆ'</screen>
+
</sect1>
<sect1 id="using-lists">
things, the first of which is the ability to show the name of a list
through which you received a message (i.e., of a subscribed list) in
the <emphasis>index</emphasis> menu display. This is useful to distinguish between
-personal and list mail in the same mailbox. In the <link linkend="index-format">$index_format</link> variable, the escape <quote>%L</quote>
-will return the string <quote>To <list></quote> when <quote>list</quote> appears in the
+personal and list mail in the same mailbox. In the <link linkend="index-format">$index_format</link> variable, the expando <quote>%L</quote>
+will print the string <quote>To <list></quote> when <quote>list</quote> appears in the
<quote>To</quote> field, and <quote>Cc <list></quote> when it appears in the <quote>Cc</quote>
-field (otherwise it returns the name of the author).
+field (otherwise it prints the name of the author).
</para>
<para>
Conversely, when group-replying or list-replying to a message which
has a <literal>Mail-Followup-To</literal> header, mutt will respect this header if
the <link linkend="honor-followup-to">$honor_followup_to</link> configuration
-variable is set. Using list-reply will in this case also make sure
+variable is set. Using <link linkend="list-reply">list-reply</link> will in this case also make sure
that the reply goes to the mailing list, even if it's not specified
in the list of recipients in the <literal>Mail-Followup-To</literal>.
</para>
The <quote>X-Label:</quote> header field can be used to further identify mailing
lists or list subject matter (or just to annotate messages
individually). The <link linkend="index-format">$index_format</link> variable's <quote>%y</quote> and
-<quote>%Y</quote> escapes can be used to expand <quote>X-Label:</quote> fields in the
+<quote>%Y</quote> expandos can be used to expand <quote>X-Label:</quote> fields in the
index, and Mutt's pattern-matcher can match regular expressions to
<quote>X-Label:</quote> fields with the <quote>˜y</quote> selector. <quote>X-Label:</quote> is not a
standard message header field, but it can easily be inserted by procmail
<para>
For the index, by default Mutt displays the number of mailboxes with new
mail in the status bar, please refer to the
-<link linkend="index-format">$index_format</link>
+<link linkend="status-format">$status_format</link>
variable for details.
</para>
<para>
Mutt has the ability to dynamically restructure threads that are broken
either by misconfigured software or bad behavior from some
-correspondents. This allows to clean your mailboxes formats) from these
+correspondents. This allows to clean your mailboxes from these
annoyances which make it hard to follow a discussion.
</para>
<title>Linking threads</title>
<para>
-Some mailers tend to "forget" to correctly set the "In-Reply-To:" and
-"References:" headers when replying to a message. This results in broken
+Some mailers tend to <quote>forget</quote> to correctly set the <quote>In-Reply-To:</quote> and
+<quote>References:</quote> headers when replying to a message. This results in broken
discussions because Mutt has not enough information to guess the correct
threading.
You can fix this by tagging the reply, then moving to the parent message
and using the <literal><link-threads></literal> function (bound to & by default). The
-reply will then be connected to this "parent" message.
+reply will then be connected to this parent message.
</para>
<para>
You can also connect multiple children at once, tagging them and using the
-tag-prefix command (';') or the auto_tag option.
+<literal><tag-prefix></literal> command (';') or the <link linkend="auto-tag">$auto_tag</link> option.
</para>
</sect2>
<para>
On mailing lists, some people are in the bad habit of starting a new
-discussion by hitting "reply" to any message from the list and changing
+discussion by hitting <quote>reply</quote> to any message from the list and changing
the subject to a totally unrelated one.
You can fix such threads by using the <literal><break-thread></literal> function (bound
by default to #), which will turn the subthread starting from the
<title>The Attachment Menu</title>
<para>
-The default binding for <literal>view-attachments</literal> is `v', which displays the
+The default binding for <literal><view-attachments></literal> is <quote>v</quote>, 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 <quote>tag-prefix</quote> operator. You can also reply to the
+and by using the <literal><tag-prefix></literal> 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>
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
+<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
+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).
+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).
+changed with the <literal><edit-description></literal> command (default: d).
</para>
</sect2>
<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
+personal <literal>mime.types</literal> file at <literal>${HOME}/.mime.types</literal>, and then
+the system <literal>mime.types</literal> file at <literal>/usr/local/share/mutt/mime.types</literal> or
<literal>/etc/mime.types</literal>
</para>
<para>
-The mime.types file consist of lines containing a MIME type and a space
+The <literal>mime.types</literal> file consist of lines containing a MIME type and a space
separated list of extensions. For example:
</para>
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>
+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
+appropriate entry is found in the <literal>mime.types</literal> 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
</sect1>
<sect1 id="mailcap">
-<title>MIME Viewer configuration with <literal>mailcap</literal></title>
+<title>MIME Viewer configuration with mailcap</title>
<para>
Mutt supports RFC 1524 MIME Configuration, in particular the Unix
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.
+<literal>text/html</literal> object. If RunningX doesn't return 0, then Mutt will go on
+to the next entry and use lynx to display the <literal>text/html</literal> object.
</para>
</listitem>
</varlistentry>
<para>
The various commands defined in the mailcap files are passed to the
-<literal>/bin/sh</literal> shell using the system() function. Before the
+<literal>/bin/sh</literal> shell using the <literal>system(3)</literal> 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:
</para>
<para>
-You then use the <literal>auto_view</literal> muttrc command to list the
-content-types that you wish to view automatically.
-</para>
-
-<para>
-For instance, if you set auto_view to:
+You then use the auto_view muttrc command to list the
+content-types that you wish to view automatically. For instance, if you
+set it to:
</para>
<screen>
</screen>
<para>
-<quote>unauto_view</quote> 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 can be used to remove previous entries from the autoview list.
+This can be used with <link linkend="message-hook">message-hook</link> to autoview messages based on size, etc.
<quote>unauto_view *</quote> will remove all previous entries.
</para>
<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:
+<literal>multipart/alternative</literal> type to display. First, mutt will check the
+alternative_order list
+to determine if one of the available types is preferred. It consists of
+a number of mimetypes in order, including support for implicit and
+explicit wildcards, for example:
</para>
<screen>
</para>
<para>
-To remove a MIME type from the <literal>alternative_order</literal> list, use the
-<literal>unalternative_order</literal> command.
+To remove a MIME type from the alternative_order list, use the
+unalternative_order command.
</para>
</sect1>
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.
+<literal>attachments</literal> and <literal>unattachments</literal> commands.
</para>
<para>
The syntax is:
</para>
-<screen>
-attachments {+|-}disposition mime-type
-unattachments {+|-}disposition mime-type
-attachments ?
-</screen>
+<cmdsynopsis>
+<command>attachments</command>
+<arg choice="plain">
+<replaceable>{ + | - }disposition</replaceable>
+</arg>
+<arg choice="plain">
+<replaceable>mime-type</replaceable>
+</arg>
+</cmdsynopsis>
+
+<cmdsynopsis>
+<command>unattachments</command>
+<arg choice="plain">
+<replaceable>{ + | - }disposition</replaceable>
+</arg>
+<arg choice="plain">
+<replaceable>mime-type</replaceable>
+</arg>
+</cmdsynopsis>
+
+<cmdsynopsis>
+<command>attachments</command>
+<arg choice="plain">
+<replaceable>?</replaceable>
+</arg>
+</cmdsynopsis>
<para>
-Disposition is the attachment's Content-disposition type -- either
+<emphasis>disposition</emphasis> is the attachment's Content-Disposition type -- either
<literal>inline</literal> or <literal>attachment</literal>.
You can abbreviate this to <literal>I</literal> or <literal>A</literal>.
</para>
</para>
<para>
-Mime-type is, unsurprisingly, the MIME type of the attachment you want
+<emphasis>mime-type</emphasis> is, unsurprisingly, the MIME type of the attachment you want
to affect. A MIME type is always of the format <literal>major/minor</literal>, where
<literal>major</literal> describes the broad category of document you're looking at, and
<literal>minor</literal> describes the specific type within that category. The major
<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
+deal with binary types such as <literal>application/octet-stream</literal>. 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
+be compared to the list of extensions in the <literal>mime.types</literal> 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>
<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.
+In addition, the <literal>unmime_lookup</literal> 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>
</sect1>
</para>
<para>
-Since all protocols by mutt support authentication, the username may be
+Since all protocols supported by mutt support, the username may be
given directly in the URL instead of using the <literal>pop_user</literal> or
<literal>imap_user</literal> variables. It may contain the <quote>@</quote> symbol
being used by many mail systems as part of the login name. A password can be
</para>
<para>
-For IMAP for example, you can select an alternative port by specifying it with the
-server: <literal>imap://imapserver:port/INBOX</literal>. You can also specify different
-username for each folder: <literal>imap://username@imapserver[:port]/INBOX</literal>
+For IMAP for example, you can also specify different
+usernames for each folder: <literal>imap://username@imapserver[:port]/INBOX</literal>
or <literal>imap://username2@imapserver[:port]/path/to/folder</literal>.
-Replacing <literal>imap://</literal> by <literal>imaps://</literal>
-would make mutt attempt to connect using SSL or TLS on a different port
-to encrypt the communication.
</para>
</sect2>
<title>POP3 Support</title>
<para>
-If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis>
+If Mutt is 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 you only need to fetch all messages to a
local mailbox you should consider using a specialized program, such as
-<literal>fetchmail</literal>, <literal>getmail</literal> or similar.
+<literal>fetchmail(1)</literal>, <literal>getmail(1)</literal> or similar.
</para>
</note>
<link linkend="mail-check">$mail_check</link>
and
<link linkend="timeout">$timeout</link>
-variables. Personally I use
+variables. Reasonable values are:
</para>
<screen>
</screen>
<para>
-with relatively good results over my slow modem line.
+with relatively good results even over slow modem lines.
</para>
<note>
<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><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
+<literal><subscribe></literal> and <literal><unsubscribe></literal> to mailboxes (normally
these are bound to <literal>s</literal> and <literal>u</literal>, respectively).
</para>
</listitem>
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".
+your username blank or <quote>anonymous</quote>.
</para>
<para>
<para>
If you happen to have accounts on multiple IMAP, POP and/or SMTP 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
+error-prone. The <link linkend="account-hook">account-hook</link> command may help. This hook works like
+<link linkend="folder-hook">folder-hook</link> but is invoked whenever you access a remote mailbox
(including inside the folder browser), not just when you open the
-mailbox which includes (for example) polling for new mail, storing Fcc
+mailbox. This includes (for example) polling for new mail, storing Fcc
messages and saving messages to a folder. As a consequence,
-account-hook should only be used to set connection-related settings such
+<link linkend="account-hook">account-hook</link> should only be used to set connection-related settings such
as passwords or tunnel commands but not settings such as sender
address or name (because in general it should be considered unpredictable
-which account-hook was last used).
+which <link linkend="account-hook">account-hook</link> was last used).
</para>
<para>
to a directory.
</para>
-<para>
-For the one-file-per-folder case, database files for remote folders
-will be named according to their URL while database files for local
-folders will be named by the MD5 checksums of their path. These database
-files may be safely removed if a system is short on space. You
-can compute the name of the header cache file for a particular local folder
-through a command like the following:
-</para>
-
-<screen>
-$ printf '%s' '/path/to/folder' | md5sum
-</screen>
-
-<para>
-The <literal>md5sum</literal> command may also be
-named <literal>md5</literal>, depending on your operating system.
-</para>
-
</sect2>
<sect2 id="body-caching">
directory. There, mutt will create a hierarchy of subdirectories
named like: <literal>proto:user@hostname</literal> where
<literal>proto</literal> is either <quote>pop</quote> or <quote>imap.</quote> 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>
+there for each folder, mutt stores messages in single files.
All files can be removed as needed if the consumed disk space
becomes an issue as mutt will silently fetch missing items again.
</para>
one-file-per message storage (Maildir and MH), mutt's
performance can be greatly improved using
<link linkend="header-caching">header caching</link>.
-Using a single database per folder may further increase
-performance.
+using a single database per folder.
</para>
</listitem>
<row><entry>-x</entry><entry>simulate the mailx(1) compose mode</entry></row>
<row><entry>-y</entry><entry>show a menu containing the files specified by the mailboxes command</entry></row>
<row><entry>-z</entry><entry>exit immediately if there are no messages in the mailbox</entry></row>
-<row><entry>-Z</entry><entry>open the first folder with new message,exit immediately if none</entry></row>
+<row><entry>-Z</entry><entry>open the first folder with new message, exit immediately if none</entry></row>
</tbody>
</tgroup>
</table>
<arg choice="opt"><option>-F</option>
<replaceable>muttrc</replaceable>
</arg>
-<arg choice="opt"><option>-a</option>
-<replaceable>file</replaceable>
-</arg>
<arg choice="opt"><option>-c</option>
<replaceable>address</replaceable>
</arg>
<arg choice="opt"><option>-s</option>
<replaceable>subject</replaceable>
</arg>
-<arg choice="opt">
<arg choice="opt" rep="repeat">
+<option>-a</option>
<replaceable>file</replaceable>
</arg>
-<arg choice="plain">--</arg>
-</arg>
+<arg choice="opt">--</arg>
<arg choice="plain">
<replaceable>address</replaceable>
</arg>
input from the file you wish to send. For example,
</para>
-<para>
-<literal>mutt -s "data set for run #2" professor@bigschool.edu
-< ˜/run2.dat</literal>
-</para>
+<screen>
+mutt -s "data set for run #2" professor@bigschool.edu < ˜/run2.dat</screen>
<para>
-This command will send a message to <quote>professor@bigschool.edu</quote> with a subject
+will send a message to <literal><professor@bigschool.edu></literal> with a subject
of <quote>data set for run #2</quote>. In the body of the message will be the contents
of the file <quote>˜/run2.dat</quote>.
</para>
<para>
-All files passed with -a <emphasis>file</emphasis> will be attached as a MIME
+All files passed with <literal>-a</literal> <emphasis>file</emphasis> will be attached as a MIME
part to the message. To attach several files, use <quote>--</quote> to separate files and
-recipient addresses: <literal>mutt -a *.png -- some@one.org</literal>
+recipient addresses:
</para>
+<screen>
+mutt -a *.png -- some@one.org</screen>
+
+<note>
+<para>
+The <literal>-a</literal> option must be last in the option list.
+</para>
+</note>
+
</sect1>
<sect1 id="commands">
<replaceable class="parameter">address</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="alias">unalias</link></command>
<arg choice="opt" rep="repeat">
<replaceable>regexp</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="alternates">unalternates</link></command>
<arg choice="opt" rep="repeat">
<replaceable>mimetype</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="alternative-order">unalternative-order</link></command>
<group choice="req">
</cmdsynopsis>
</listitem>
+<listitem>
+<cmdsynopsis>
+<command><link linkend="attachments">attachments</link></command>
+<arg choice="plain">
+<replaceable>{ + | - }disposition</replaceable>
+</arg>
+<arg choice="plain">
+<replaceable>mime-type</replaceable>
+</arg>
+</cmdsynopsis>
+
+<cmdsynopsis>
+<command><link linkend="attachments">unattachments</link></command>
+<arg choice="plain">
+<replaceable>{ + | - }disposition</replaceable>
+</arg>
+<arg choice="plain">
+<replaceable>mime-type</replaceable>
+</arg>
+</cmdsynopsis>
+</listitem>
+
<listitem>
<cmdsynopsis>
<command><link linkend="auto-view">auto-view</link></command>
<replaceable>mimetype</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="auto-view">unauto-view</link></command>
<replaceable class="parameter">pattern</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="color">uncolor</link></command>
<arg choice="plain">
</cmdsynopsis>
</listitem>
+<listitem>
+<cmdsynopsis>
+<command><link linkend="crypt-hook">crypt-hook</link></command>
+<arg choice="plain">
+<replaceable class="parameter">pattern</replaceable>
+</arg>
+<arg choice="plain">
+<replaceable class="parameter">keyid</replaceable>
+</arg>
+</cmdsynopsis>
+</listitem>
+
<listitem>
<cmdsynopsis>
<command><link linkend="exec">exec</link></command>
</arg>
</group>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="addrgroup">ungroup</link></command>
<arg choice="opt" rep="repeat">
<replaceable class="parameter">header</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="hdr-order">unhdr_order</link></command>
<group choice="req">
<replaceable class="parameter">pattern</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="ignore">unignore</link></command>
<group choice="req">
<replaceable class="parameter">regexp</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="lists">unlists</link></command>
<arg choice="opt" rep="repeat">
<replaceable class="parameter">mailbox</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="mailboxes">unmailboxes</link></command>
<group choice="req">
<replaceable>mimetype</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="mime-lookup">unmime-lookup</link></command>
<group choice="req">
<replaceable class="parameter">pattern</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="mono">unmono</link></command>
<arg choice="plain">
<replaceable class="parameter">string</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="my-hdr">unmy_hdr</link></command>
<group choice="req">
</cmdsynopsis>
</listitem>
-<listitem>
-<cmdsynopsis>
-<command><link linkend="crypt-hook">crypt-hook</link></command>
-<arg choice="plain">
-<replaceable class="parameter">pattern</replaceable>
-</arg>
-<arg choice="plain">
-<replaceable class="parameter">keyid</replaceable>
-</arg>
-</cmdsynopsis>
-</listitem>
-
<listitem>
<cmdsynopsis>
<command><link linkend="push">push</link></command>
</cmdsynopsis>
</listitem>
-<listitem>
-<cmdsynopsis>
-<command><link linkend="set">reset</link></command>
-<arg choice="plain">
-<replaceable class="parameter">variable</replaceable>
-</arg>
-<arg choice="opt" rep="repeat">
-<replaceable class="parameter">variable</replaceable>
-</arg>
-</cmdsynopsis>
-</listitem>
-
<listitem>
<cmdsynopsis>
<command><link linkend="save-hook">save-hook</link></command>
<replaceable class="parameter">value</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="score">unscore</link></command>
<group choice="req">
</group>
<arg choice="opt" rep="repeat"/>
</cmdsynopsis>
-</listitem>
-<listitem>
+<cmdsynopsis>
+<command><link linkend="set">toggle</link></command>
+<arg choice="plain">
+<replaceable class="parameter">variable</replaceable>
+</arg>
+<arg choice="opt" rep="repeat">
+<replaceable class="parameter">variable</replaceable>
+</arg>
+</cmdsynopsis>
+
<cmdsynopsis>
<command><link linkend="set">unset</link></command>
<arg choice="plain">
<replaceable class="parameter">variable</replaceable>
</arg>
</cmdsynopsis>
+
+<cmdsynopsis>
+<command><link linkend="set">reset</link></command>
+<arg choice="plain">
+<replaceable class="parameter">variable</replaceable>
+</arg>
+<arg choice="opt" rep="repeat">
+<replaceable class="parameter">variable</replaceable>
+</arg>
+</cmdsynopsis>
</listitem>
<listitem>
<replaceable class="parameter">format</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="spam">nospam</link></command>
<group choice="req">
<replaceable class="parameter">regexp</replaceable>
</arg>
</cmdsynopsis>
-</listitem>
-<listitem>
<cmdsynopsis>
<command><link linkend="subscribe">unsubscribe</link></command>
<arg choice="opt" rep="repeat">
</cmdsynopsis>
</listitem>
-<listitem>
-<cmdsynopsis>
-<command><link linkend="set">toggle</link></command>
-<arg choice="plain">
-<replaceable class="parameter">variable</replaceable>
-</arg>
-<arg choice="opt" rep="repeat">
-<replaceable class="parameter">variable</replaceable>
-</arg>
-</cmdsynopsis>
-</listitem>
-
<listitem>
<cmdsynopsis>
<command><link linkend="unhook">unhook</link></command>
projects / mutt / commitdiff