« back to all changes in this revision
Viewing changes to doc/manual.xml.head
- browse files at revision 15
- compare with another revision
- download diff
- download tarball
- view history from revision 15
- Committer: Bazaar Package Importer
- Author(s): Christoph Berg, Adeodato Simó, Christoph Berg
- Date: 2007-11-03 23:00:04 UTC
- mfrom: (1.1.7 upstream)
- Revision ID: james.westby@ubuntu.com-20071103230004-43e36pnhub87junc
Tags: 1.5.17-1
[ Adeodato Simó ]
* Move the packaging back to Bazaar, adjust X-VCS-* accordingly.
[ Christoph Berg ]
* Mention libsasl2-modules-gssapi-mit in README.Debian. (Closes: #433425)
* Call autoreconf at build time, drop the autotools-update patch.
* Update menu file, add lintian override file.
* Refresh patches.
* New upstream version:
+ fix segfaults with single byte 8-bit characters in index_format.
(Closes: #420598, Mutt: #2882)
+ properly render subject headers with encoded linefeeds.
(Closes: #264014, Mutt: #1810)
+ only calls gnutls_error_is_fatal when gnutls_record_recv returns a
negative value. (Closes: #439775, Mutt: #2954)
+ Large file support for mutt_pretty_size().
(Closes: #352478, #416555, Mutt: #2191)
+ Do not consider empty pipes for filtering in format strings.
(Closes: #447340)
* Move the packaging back to Bazaar, adjust X-VCS-* accordingly.
[ Christoph Berg ]
* Mention libsasl2-modules-gssapi-mit in README.Debian. (Closes: #433425)
* Call autoreconf at build time, drop the autotools-update patch.
* Update menu file, add lintian override file.
* Refresh patches.
* New upstream version:
+ fix segfaults with single byte 8-bit characters in index_format.
(Closes: #420598, Mutt: #2882)
+ properly render subject headers with encoded linefeeds.
(Closes: #264014, Mutt: #1810)
+ only calls gnutls_error_is_fatal when gnutls_record_recv returns a
negative value. (Closes: #439775, Mutt: #2954)
+ Large file support for mutt_pretty_size().
(Closes: #352478, #416555, Mutt: #2191)
+ Do not consider empty pipes for filtering in format strings.
(Closes: #447340)
- files added:
- debian/fix-PATCHES.pl
- files removed:
- build-release
- files modified:
- ChangeLog
- depcomp *
added
removed
doc/manual.xml.head
197
197
<title>Moving Around in Menus</title>
198
198
199
199
<para>
200
Information is presented in menus, very similar to ELM. Here is a table
201
showing the common keys used to navigate menus in Mutt.
200
Information is presented in menus, very similar to ELM, see <xref linkend="tab-keys-nav"/>
201
for common keys used to navigate menus in Mutt.
202
202
</para>
203
203
204
204
<para>
205
205
206
<table>
206
<table id="tab-keys-nav">
207
207
<title>Most common navigation keys</title>
208
208
<tgroup cols="3">
209
209
<thead>
235
235
<para>
236
236
Mutt has a built-in line editor for inputting text, e.g. email
237
237
addresses or filenames. The keys used to manipulate text input are
238
very similar to those of Emacs. See the following table for a full
238
very similar to those of Emacs. See <xref linkend="tab-keys-editor"/> for a full
239
239
reference of available functions, their default key bindings, and
240
240
short descriptions.
241
241
</para>
242
242
243
243
<para>
244
244
245
<table>
245
<table id="tab-keys-editor">
246
246
<title>Most common line editor keys</title>
247
247
<tgroup cols="3">
248
248
<thead>
351
351
<title>The Message Index</title>
352
352
353
353
<para>
354
355
<table>
354
Common keys used to navigate through and manage messages in the index
355
are shown in <xref linkend="tab-key-index"/>.
356
</para>
357
358
<para>
359
360
<table id="tab-key-index">
356
361
<title>Most common message index keys</title>
357
362
<tgroup cols="2">
358
363
<thead>
585
590
586
591
<para>
587
592
588
<table>
593
<table id="tab-key-pager">
589
594
<title>Most common pager keys</title>
590
595
<tgroup cols="2">
591
596
<thead>
610
615
</para>
611
616
612
617
<para>
613
In addition, many of the functions from the <emphasis>index</emphasis> are available in
618
In addition to key bindings in <xref linkend="tab-key-pager"/>,
619
many of the functions from the <emphasis>index</emphasis> are available in
614
620
the pager, such as <emphasis>delete-message</emphasis> or <emphasis>copy-message</emphasis> (this is one
615
621
advantage over using an external pager to view messages).
616
622
</para>
629
635
<para>
630
636
Additionally, the internal pager supports the ANSI escape sequences for
631
637
character attributes. Mutt translates them into the correct color and
632
character settings. The sequences Mutt supports are:
633
</para>
634
635
<para>
636
637
<screen>
638
ESC [ Ps;Ps;Ps;...;Ps m where Ps =
639
0 All Attributes Off
640
1 Bold on
641
4 Underline on
642
5 Blink on
643
7 Reverse video on
644
3x Foreground color is x
645
4x Background color is x
646
647
Colors are
648
0 black
649
1 red
650
2 green
651
3 yellow
652
4 blue
653
5 magenta
654
6 cyan
655
7 white
656
</screen>
657
658
</para>
638
character settings. The sequences Mutt supports are
639
'\e[<emphasis>Ps</emphasis>;<emphasis>Ps</emphasis>;..<emphasis>Ps</emphasis>;m'
640
where <emphasis>Ps</emphasis> can be one of the codes shown in
641
<xref linkend="tab-ansi-esc"/>.
642
</para>
643
644
<table id="tab-ansi-esc">
645
<title>ANSI escape sequences</title>
646
<tgroup cols="2">
647
<thead>
648
<row><entry>Escape code</entry><entry>Description</entry></row>
649
</thead>
650
<tbody>
651
<row><entry>0</entry><entry>All Attributes Off</entry></row>
652
<row><entry>1</entry><entry>Bold on</entry></row>
653
<row><entry>4</entry><entry>Underline on</entry></row>
654
<row><entry>5</entry><entry>Blink on</entry></row>
655
<row><entry>7</entry><entry>Reverse video on</entry></row>
656
<row><entry>3<emphasis><color></emphasis></entry><entry>Foreground color is <emphasis><color></emphasis> (see <xref linkend="tab-color"/>)</entry></row>
657
<row><entry>4<emphasis><color></emphasis></entry><entry>Background color is <emphasis><color></emphasis> (see <xref linkend="tab-color"/>)</entry></row>
658
</tbody>
659
</tgroup>
660
</table>
661
662
<table id="tab-color">
663
<title>Color sequences</title>
664
<tgroup cols="2">
665
<thead>
666
<row><entry>Color code</entry><entry>Color</entry></row>
667
</thead>
668
<tbody>
669
<row><entry>0</entry><entry>Black</entry></row>
670
<row><entry>1</entry><entry>Red</entry></row>
671
<row><entry>2</entry><entry>Green</entry></row>
672
<row><entry>3</entry><entry>Yellow</entry></row>
673
<row><entry>4</entry><entry>Blue</entry></row>
674
<row><entry>5</entry><entry>Magenta</entry></row>
675
<row><entry>6</entry><entry>Cyan</entry></row>
676
<row><entry>7</entry><entry>White</entry></row>
677
</tbody>
678
</tgroup>
679
</table>
659
680
660
681
<para>
661
682
Mutt uses these attributes for handling text/enriched messages, and they
672
693
673
694
<para>
674
695
When the mailbox is <link linkend="sort">sorted</link> by <emphasis>threads</emphasis>, there are
675
a few additional functions available in the <emphasis>index</emphasis> and <emphasis>pager</emphasis> modes.
696
a few additional functions available in the <emphasis>index</emphasis> and <emphasis>pager</emphasis> modes
697
as shown in <xref linkend="tab-key-threads"/>.
676
698
</para>
677
699
678
700
<para>
679
701
680
<table>
702
<table id="tab-key-threads">
681
703
<title>Most common thread mode keys</title>
682
704
<tgroup cols="3">
683
705
<thead>
916
938
<title>Sending Mail</title>
917
939
918
940
<para>
919
The following bindings are available in the <emphasis>index</emphasis> for sending
920
messages.
941
The bindings shown in <xref linkend="tab-key-send"/> are available in the
942
<emphasis>index</emphasis> for sending messages.
921
943
</para>
922
944
923
945
<para>
924
946
925
<table>
947
<table id="tab-key-send">
926
948
<title>Most common mail sending keys</title>
927
949
<tgroup cols="3">
928
950
<thead>
976
998
977
999
<para>
978
1000
Once you have finished editing the body of your mail message, you are
979
returned to the <emphasis>compose</emphasis> menu. The following functions are available:
1001
returned to the <emphasis>compose</emphasis> menu providing the functions
1002
show in <xref linkend="tab-func-compose"/>.
980
1003
</para>
981
1004
982
1005
<para>
983
1006
984
<table>
1007
<table id="tab-func-compose">
985
1008
<title>Most common compose menu keys</title>
986
1009
<tgroup cols="3">
987
1010
<thead>
1108
1131
</para>
1109
1132
1110
1133
<para>
1111
The flags sequence (%f) will expand to one of the following flags:
1134
The flags sequence (%f) will expand to one of the flags in
1135
<xref linkend="tab-pgp-menuflags"/>.
1112
1136
1113
<table>
1137
<table id="tab-pgp-menuflags">
1114
1138
<title>PGP key menu flags</title>
1115
1139
<tgroup cols="2">
1116
1140
<thead>
1305
1329
that you specify. Bouncing a message uses the <link linkend="sendmail">$sendmail</link> command to send a copy to alternative addresses as if
1306
1330
they were the message's original recipients. Forwarding a message, on
1307
1331
the other hand, allows you to modify the message before it is resent
1308
(for example, by adding your own comments).
1309
</para>
1310
1311
<para>
1312
The following keys are bound by default:
1313
</para>
1314
1315
<para>
1316
1317
<table>
1332
(for example, by adding your own comments). The default key bindings
1333
are shown in <xref linkend="tab-key-fwd"/>.
1334
</para>
1335
1336
<para>
1337
1338
<table id="tab-key-fwd">
1318
1339
<title>Message forwarding/bouncing keys</title>
1319
1340
<tgroup cols="3">
1320
1341
<thead>
1785
1806
ignored, so that <emphasis>\CA</emphasis>, <emphasis>\Ca</emphasis>, <emphasis>\cA</emphasis> and <emphasis>\ca</emphasis> are all
1786
1807
equivalent. An alternative form is to specify the key as a three digit
1787
1808
octal number prefixed with a ``\'' (for example <emphasis>\177</emphasis> is
1788
equivalent to <emphasis>\c?</emphasis>).
1789
</para>
1790
1791
<para>
1792
In addition, <emphasis>key</emphasis> may consist of:
1793
</para>
1794
1795
<para>
1796
1797
<table>
1809
equivalent to <emphasis>\c?</emphasis>). In addition, <emphasis>key</emphasis> may
1810
be a symbolic name as shown in <xref linkend="tab-key-names"/>.
1811
</para>
1812
1813
<para>
1814
1815
<table id="tab-key-names">
1798
1816
<title>Symbolic key names</title>
1799
1817
<tgroup cols="2">
1800
1818
<thead>
2375
2393
<para>
2376
2394
To remove a regular expression from the <literal>alternates</literal> list, use the
2377
2395
<literal>unalternates</literal> command with exactly the same <emphasis>regexp</emphasis>.
2378
Likewise, if the <emphasis>regexp</emphasis> for a <literal>alternates</literal> command matches
2396
Likewise, if the <emphasis>regexp</emphasis> for an <literal>alternates</literal> command matches
2379
2397
an entry on the <literal>unalternates</literal> list, that <literal>unalternates</literal>
2380
2398
entry will be removed. If the <emphasis>regexp</emphasis> for <literal>unalternates</literal>
2381
2399
is ``*'', <emphasis>all entries</emphasis> on <literal>alternates</literal> will be removed.
3259
3277
3260
3278
</sect1>
3261
3279
3280
<sect1 id="formatstrings">
3281
<title>Format Strings</title>
3282
3283
<sect2>
3284
<title>Basic usage</title>
3285
3286
<para>
3287
Format strings are a general concept you'll find in several locations
3288
through the mutt configuration, especially in the
3289
<link linkend="index-format">$index_format"</link>,
3290
<link linkend="pager-format">$pager_format"</link>,
3291
<link linkend="status-format">$status_format"</link>,
3292
and other ``*_format'' variables. These can be very straightforward,
3293
and it's quite possible you already know how to use them.
3294
</para>
3295
3296
<para>
3297
The most basic format string element is a percent symbol followed
3298
by another character. For example, <literal>%s</literal>
3299
represents a message's Subject: header in the <link
3300
linkend="index-format">$index_format"</link> variable. The
3301
``expandos'' available are documented with each format variable, but
3302
there are general modifiers available with all formatting expandos,
3303
too. Those are our concern here.
3304
</para>
3305
3306
<para>
3307
Some of the modifers are borrowed right out of C (though you might
3308
know them from Perl, Python, shell, or another langugage). These are
3309
the [-]m.n modifiers, as in <literal>%-12.12s</literal>. As with
3310
such programming languages, these modifiers allow you to specify the
3311
minumum and maximum size of the resulting string, as well as its
3312
justification. If the ``-'' sign follows the percent, the string will
3313
be left-justified instead of right-justified. If there's a number
3314
immediately following that, it's the minimum amount of space the
3315
formatted string will occupy -- if it's naturally smaller than that, it
3316
will be padded out with spaces. If a decimal point and another number
3317
follow, that's the maximum space allowable -- the string will not be
3318
permitted to exceed that width, no matter its natural size. Each of
3319
these three elements is optional, so that all these are legal format
3320
strings:
3321
<literal>%-12s</literal>
3322
<literal>%4c</literal>
3323
<literal>%.15F</literal>
3324
<literal>%-12.15L</literal>
3325
</para>
3326
3327
<para>
3328
Mutt adds some other modifiers to format strings. If you use an equals
3329
symbol (<literal>=</literal>) as a numeric prefix (like the minus
3330
above), it will force the string to be centered within its minimum
3331
space range. For example, <literal>%=14y</literal> will reserve 14
3332
characters for the %y expansion -- that's the X-Label: header, in
3333
<literal>$index_format</literal>. If the expansion
3334
results in a string less than 14 characters, it will be centered in a
3335
14-character space. If the X-Label for a message were "test", that
3336
expansion would look like `` test ''.
3337
</para>
3338
3339
<para>
3340
There are two very little-known modifiers that affect the way that an
3341
expando is replaced. If there is an underline (``_'') character
3342
between any format modifiers (as above) and the expando letter, it will
3343
expands in all lower case. And if you use a colon (``:''), it will
3344
replace all decimal points with underlines.
3345
</para>
3346
3347
</sect2>
3348
3349
<sect2>
3350
<title>Filters</title>
3351
3352
<para>
3353
Any format string ending in a vertical bar (``|'') will be
3354
expanded and piped through the first word in the string, using spaces
3355
as separator. The string returned will be used for display.
3356
If the returned string ends in %, it will be passed through
3357
the formatter a second time. This allows the filter to generate a
3358
replacement format string including % expandos.
3359
</para>
3360
3361
<para>
3362
All % expandos in a format string are expanded before the script
3363
is called so that:
3364
</para>
3365
3366
<screen>
3367
set status_format="script.sh '%r %f (%L)'|"
3368
</screen>
3369
3370
<para>
3371
will make mutt expand <literal>%r</literal>,
3372
<literal>%f</literal> and <literal>%L</literal>
3373
before calling the script. The example also shows that arguments can be
3374
quoted: the script will receive the expanded string between the single quotes
3375
as the only argument.
3376
</para>
3377
3378
<para>
3379
A practical example is the <literal>mutt_xtitle</literal>
3380
script installed in the <literal>samples</literal>
3381
subdirectory of the mutt documentation: it can be used as filter for
3382
<literal>$status_format</literal> to set the current
3383
terminal's title, if supported.
3384
</para>
3385
3386
</sect2>
3387
3388
</sect1>
3389
3262
3390
</chapter>
3263
3391
3264
3392
<chapter id="advancedusage">
3653
3781
3654
3782
<para>
3655
3783
Many of Mutt's commands allow you to specify a pattern to match
3656
(limit, tag-pattern, delete-pattern, etc.). There are several ways to select
3657
messages:
3784
(limit, tag-pattern, delete-pattern, etc.). <xref linkend="tab-patterns"/>
3785
shows several ways select messages.
3658
3786
</para>
3659
3787
3660
3788
<para>
3661
3789
3662
<table>
3790
<table id="tab-patterns">
3663
3791
<title>Pattern modifiers</title>
3664
3792
<tgroup cols="2">
3665
3793
<thead>
3907
4035
<para>
3908
4036
<emphasis role="bold">Error Margins</emphasis>. You can add error margins to absolute dates.
3909
4037
An error margin is a sign (+ or -), followed by a digit, followed by
3910
one of the following units:
3911
3912
<screen>
3913
y years
3914
m months
3915
w weeks
3916
d days
3917
</screen>
3918
3919
As a special case, you can replace the sign by a ``*'' character,
3920
which is equivalent to giving identical plus and minus error margins.
4038
one of the units in <xref linkend="tab-date-units"/>. As a special case, you can replace the
4039
sign by a ``*'' character, which is equivalent to giving identical plus and minus error margins.
3921
4040
</para>
3922
4041
4042
<table id="tab-date-units">
4043
<title>Date units</title>
4044
<tgroup cols="2">
4045
<thead>
4046
<row><entry>Unit</entry><entry>Description</entry></row>
4047
</thead>
4048
<tbody>
4049
<row><entry>y</entry><entry>Years</entry></row>
4050
<row><entry>m</entry><entry>Months</entry></row>
4051
<row><entry>w</entry><entry>Weeks</entry></row>
4052
<row><entry>d</entry><entry>Days</entry></row>
4053
</tbody>
4054
</tgroup>
4055
</table>
4056
3923
4057
<para>
3924
4058
Example: To select any messages two weeks around January 15, 2001,
3925
4059
you'd use the following pattern:
3960
4094
</para>
3961
4095
3962
4096
<para>
3963
<emphasis>offset</emphasis> is specified as a positive number with one of the following
3964
units:
3965
3966
<screen>
3967
y years
3968
m months
3969
w weeks
3970
d days
3971
</screen>
3972
4097
<emphasis>offset</emphasis> is specified as a positive number with one of the units from <xref linkend="tab-date-units"/>.
3973
4098
</para>
3974
4099
3975
4100
<para>
4505
4630
4506
4631
</sect1>
4507
4632
4508
<sect1 id="pop">
4509
<title>POP3 Support (OPTIONAL)</title>
4510
4511
<para>
4512
If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis>
4513
script with the <emphasis>--enable-pop</emphasis> flag), it has the ability to work
4514
with mailboxes located on a remote POP3 server and fetch mail for local
4515
browsing.
4516
</para>
4517
4518
<para>
4519
You can access the remote POP3 mailbox by selecting the folder
4520
<literal>pop://popserver/</literal>.
4521
</para>
4522
4523
<para>
4524
You can select an alternative port by specifying it with the server, ie:
4525
<literal>pop://popserver:port/</literal>.
4526
</para>
4527
4528
<para>
4529
You can also specify different username for each folder, ie:
4530
<literal>pop://username@popserver[:port]/</literal>.
4531
</para>
4532
4533
<para>
4534
Polling for new mail is more expensive over POP3 than locally. For this
4535
reason the frequency at which Mutt will check for mail remotely can be
4536
controlled by the
4537
<link linkend="pop-checkinterval">$pop_checkinterval</link>
4538
variable, which defaults to every 60 seconds.
4539
</para>
4540
4541
<para>
4542
If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis>
4543
script with the <emphasis>--with-ssl</emphasis> flag), connections to POP3 servers
4544
can be encrypted. This naturally requires that the server supports
4545
SSL encrypted connections. To access a folder with POP3/SSL, you should
4546
use pops: prefix, ie:
4547
<literal>pops://[username@]popserver[:port]/</literal>.
4548
</para>
4549
4550
<para>
4551
Another way to access your POP3 mail is the <emphasis>fetch-mail</emphasis> function
4552
(default: G). It allows to connect to <link linkend="pop-host">$pop_host</link>, fetch all your new mail and place it in the
4553
local <link linkend="spoolfile">$spoolfile</link>. After this
4554
point, Mutt runs exactly as if the mail had always been local.
4555
</para>
4556
4557
<para>
4558
<emphasis role="bold">Note:</emphasis> If you only need to fetch all messages to local mailbox
4559
you should consider using a specialized program, such as <ulink
4560
url="http://www.ccil.org/~esr/fetchmail"
4561
>fetchmail</ulink
4562
>
4563
</para>
4564
4565
</sect1>
4566
4567
<sect1 id="imap">
4568
<title>IMAP Support (OPTIONAL)</title>
4569
4570
<para>
4571
If Mutt was compiled with IMAP support (by running the <emphasis>configure</emphasis>
4572
script with the <emphasis>--enable-imap</emphasis> flag), it has the ability to work
4573
with folders located on a remote IMAP server.
4574
</para>
4575
4576
<para>
4577
You can access the remote inbox by selecting the folder
4578
<literal>imap://imapserver/INBOX</literal>, where <literal>imapserver</literal> is the name of the
4579
IMAP server and <literal>INBOX</literal> is the special name for your spool mailbox on
4580
the IMAP server. If you want to access another mail folder at the IMAP
4581
server, you should use <literal>imap://imapserver/path/to/folder</literal> where
4582
<literal>path/to/folder</literal> is the path of the folder you want to access.
4583
</para>
4584
4585
<para>
4586
You can select an alternative port by specifying it with the server, ie:
4587
<literal>imap://imapserver:port/INBOX</literal>.
4588
</para>
4589
4590
<para>
4591
You can also specify different username for each folder, ie:
4592
<literal>imap://username@imapserver[:port]/INBOX</literal>.
4593
</para>
4594
4595
<para>
4596
If Mutt was compiled with SSL support (by running the <emphasis>configure</emphasis>
4597
script with the <emphasis>--with-ssl</emphasis> flag), connections to IMAP servers
4598
can be encrypted. This naturally requires that the server supports
4599
SSL encrypted connections. To access a folder with IMAP/SSL, you should
4600
use <literal>imaps://[username@]imapserver[:port]/path/to/folder</literal> as your
4601
folder path.
4602
</para>
4603
4604
<para>
4605
Pine-compatible notation is also supported, ie
4606
<literal>{[username@]imapserver[:port][/ssl]}path/to/folder</literal>
4607
</para>
4608
4609
<para>
4610
Note that not all servers use / as the hierarchy separator. Mutt should
4611
correctly notice which separator is being used by the server and convert
4612
paths accordingly.
4613
</para>
4614
4615
<para>
4616
When browsing folders on an IMAP server, you can toggle whether to look
4617
at only the folders you are subscribed to, or all folders with the
4618
<emphasis>toggle-subscribed</emphasis> command. See also the
4619
<link linkend="imap-list-subscribed">$imap_list_subscribed</link> variable.
4620
</para>
4621
4622
<para>
4623
Polling for new mail on an IMAP server can cause noticeable delays. So, you'll
4624
want to carefully tune the
4625
<link linkend="mail-check">$mail_check</link>
4626
and
4627
<link linkend="timeout">$timeout</link>
4628
variables. Personally I use
4629
4630
<screen>
4631
set mail_check=90
4632
set timeout=15
4633
</screen>
4634
4635
with relatively good results over my slow modem line.
4636
</para>
4637
4638
<para>
4639
Note that if you are using mbox as the mail store on UW servers prior to
4640
v12.250, the server has been reported to disconnect a client if another client
4641
selects the same folder.
4642
</para>
4643
4644
<sect2>
4645
<title>The Folder Browser</title>
4646
4647
<para>
4648
As of version 1.2, mutt supports browsing mailboxes on an IMAP
4649
server. This is mostly the same as the local file browser, with the
4650
following differences:
4651
4652
<itemizedlist>
4653
<listitem>
4654
4655
<para>
4656
In lieu of file permissions, mutt displays the string "IMAP",
4657
possibly followed by the symbol "+", indicating
4658
that the entry contains both messages and subfolders. On
4659
Cyrus-like servers folders will often contain both messages and
4660
subfolders.
4661
</para>
4662
</listitem>
4663
<listitem>
4664
4665
<para>
4666
For the case where an entry can contain both messages and
4667
subfolders, the selection key (bound to <literal>enter</literal> by default)
4668
will choose to descend into the subfolder view. If you wish to view
4669
the messages in that folder, you must use <literal>view-file</literal> instead
4670
(bound to <literal>space</literal> by default).
4671
</para>
4672
</listitem>
4673
<listitem>
4674
4675
<para>
4676
You can create, delete and rename mailboxes with the
4677
<literal>create-mailbox</literal>, <literal>delete-mailbox</literal>, and
4678
<literal>rename-mailbox</literal> commands (default bindings: <literal>C</literal>,
4679
<literal>d</literal> and <literal>r</literal>, respectively). You may also
4680
<literal>subscribe</literal> and <literal>unsubscribe</literal> to mailboxes (normally
4681
these are bound to <literal>s</literal> and <literal>u</literal>, respectively).
4682
</para>
4683
</listitem>
4684
4685
</itemizedlist>
4686
4687
</para>
4688
4689
</sect2>
4690
4691
<sect2>
4692
<title>Authentication</title>
4693
4694
<para>
4695
Mutt supports four authentication methods with IMAP servers: SASL,
4696
GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
4697
NTLM authentication for you poor exchange users out there, but it has
4698
yet to be integrated into the main tree). There is also support for
4699
the pseudo-protocol ANONYMOUS, which allows you to log in to a public
4700
IMAP server without having an account. To use ANONYMOUS, simply make
4701
your username blank or "anonymous".
4702
</para>
4703
4704
<para>
4705
SASL is a special super-authenticator, which selects among several protocols
4706
(including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure
4707
method available on your host and the server. Using some of these methods
4708
(including DIGEST-MD5 and possibly GSSAPI), your entire session will be
4709
encrypted and invisible to those teeming network snoops. It is the best
4710
option if you have it. To use it, you must have the Cyrus SASL library
4711
installed on your system and compile mutt with the <emphasis>--with-sasl</emphasis> flag.
4712
</para>
4713
4714
<para>
4715
Mutt will try whichever methods are compiled in and available on the server,
4716
in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.
4717
</para>
4718
4719
<para>
4720
There are a few variables which control authentication:
4721
4722
<itemizedlist>
4723
<listitem>
4724
4725
<para>
4726
<link linkend="imap-user">$imap_user</link> - controls
4727
the username under which you request authentication on the IMAP server,
4728
for all authenticators. This is overridden by an explicit username in
4729
the mailbox path (ie by using a mailbox name of the form
4730
<literal>{user@host}</literal>).
4731
</para>
4732
</listitem>
4733
<listitem>
4734
4735
<para>
4736
<link linkend="imap-pass">$imap_pass</link> - a
4737
password which you may preset, used by all authentication methods where
4738
a password is needed.
4739
</para>
4740
</listitem>
4741
<listitem>
4742
4743
<para>
4744
<link linkend="imap-authenticators">$imap_authenticators</link> - a colon-delimited list of IMAP
4745
authentication methods to try, in the order you wish to try them. If
4746
specified, this overrides mutt's default (attempt everything, in the order
4747
listed above).
4748
</para>
4749
</listitem>
4750
4751
</itemizedlist>
4752
4753
</para>
4754
4755
</sect2>
4756
4757
</sect1>
4758
4759
<sect1 id="account-hook">
4760
<title>Managing multiple IMAP/POP accounts (OPTIONAL)</title>
4761
4762
<para>
4763
If you happen to have accounts on multiple IMAP and/or POP servers,
4764
you may find managing all the authentication settings inconvenient and
4765
error-prone. The account-hook command may help. This hook works like
4766
folder-hook but is invoked whenever you access a remote mailbox
4767
(including inside the folder browser), not just when you open the
4768
mailbox.
4769
</para>
4770
4771
<para>
4772
Some examples:
4773
</para>
4774
4775
<para>
4776
4777
<screen>
4778
account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
4779
account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
4780
account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
4781
</screen>
4782
4783
</para>
4784
4785
</sect1>
4786
4787
4633
<sect1 id="urlview">
4788
4634
<title>Start a WWW Browser on URLs (EXTERNAL)</title>
4789
4635
4806
4652
4807
4653
</sect1>
4808
4654
4809
<sect1 id="caching">
4810
<title>Local caching (OPTIONAL)</title>
4811
4812
<para>
4813
Mutt contains two types of local caching: <emphasis>(1)</emphasis>
4814
the so-called ``header caching'' and <emphasis>(2)</emphasis> the
4815
so-called ``body caching'' which are both described in this section.
4816
</para>
4817
4818
<para>
4819
These are optional which means they're not enabled by default.
4820
Details on how to enable either of these techniques are given in the
4821
following subsections.
4822
</para>
4823
4824
<sect2 id="header-caching">
4825
<title>Header caching</title>
4826
4827
<para>
4828
Mutt provides optional support for caching message headers for the
4829
following types of folders: IMAP, POP, Maildir and MH. Header caching
4830
greatly improves speed because for remote folders, headers
4831
usually only need to be downloaded once. For Maildir and MH, reading the
4832
headers from a single file is much faster than looking at possibly
4833
thousands of single files (since Maildir and MH use one file per message.)
4834
</para>
4835
4836
<para>
4837
Header caching can be enabled via the configure script and the
4838
<emphasis>--enable-hcache</emphasis> option. It's not turned on
4839
by default because external database libraries are required: one
4840
of qdbm, gdbm or bdb must be present.
4841
</para>
4842
4843
<para>
4844
If enabled, <link
4845
linkend="header-cache">$header_cache</link> can be
4846
used to either point to a file or a directory. If set to point to
4847
a file, one database file for all folders will be used (which may
4848
result in lower performance), but one file per folder if it points
4849
to a directory.
4850
</para>
4851
4852
<para>
4853
For the one-file-per-folder case, database files will be named by MD5
4854
sums. They may be safely removed if a system is short on space. You
4855
can compute the name of the header cache file for a particular folder
4856
through a command like the following:
4857
</para>
4858
4859
<para>
4860
<screen>
4861
$ printf '%s' '/path/to/folder' | md5sum
4862
$ printf '%s' 'imaps://user@host/path/to/folder' | md5sum
4863
$ printf '%s' 'pops://user@host' | md5sum
4864
</screen>
4865
</para>
4866
4867
<para>
4868
The <literal>md5sum</literal> command may also be
4869
named <literal>md5</literal>, depending on your operating system.
4870
</para>
4871
4872
</sect2>
4873
4874
<sect2 id="body-caching">
4875
<title>Body caching</title>
4876
4877
<para>
4878
In addition to caching message headers only, mutt can also cache
4879
whole message bodies. This results in faster display of messages
4880
for POP and IMAP folders because messages usually have to be
4881
downloaded only once.
4882
</para>
4883
4884
<para>
4885
If the configure script is called with <emphasis>--enable-pop</emphasis>
4886
and/or <emphasis>--enable-imap</emphasis>, body caching will be
4887
built in as it does not require additional software packages such
4888
as database libraries.
4889
</para>
4890
4891
<para>
4892
For configuration, the variable <link linkend="message-cachedir"
4893
>$message_cachedir</link> must point to a
4894
directory. There, mutt will create a hierarchy of subdirectories
4895
named like: <literal>proto:user@hostname</literal> where
4896
<literal>proto</literal> is either ``pop'' or ``imap.'' Within
4897
there for each folder, mutt stores messages in single files (just
4898
like Maildir) so that with manual symlink creation these cache
4899
directories can be examined with mutt as read-only Maildir folders.
4900
</para>
4901
4902
<para>
4903
All files can be removed as needed if the consumed disk space
4904
becomes an issue as mutt will silently fetch missing items again.
4905
</para>
4906
4907
</sect2>
4908
4909
</sect1>
4910
4911
4655
</chapter>
4912
4656
4913
4657
<chapter id="mimesupport">
5014
4758
Attachments appear as follows:
5015
4759
5016
4760
<screen>
5017
- 1 [text/plain, 7bit, 1K] /tmp/mutt-euler-8082-0 <no description>
5018
2 [applica/x-gunzip, base64, 422K] ~/src/mutt-0.85.tar.gz <no description>
4761
- 1 [text/plain, 7bit, 1K] /tmp/mutt-euler-8082-0 <no description>
4762
2 [applica/x-gunzip, base64, 422K] ~/src/mutt-0.85.tar.gz <no description>
5019
4763
</screen>
5020
4764
5021
4765
</para>
5098
4842
<para>
5099
4843
In order to handle various MIME types that Mutt can not handle
5100
4844
internally, Mutt parses a series of external configuration files to
5101
find an external handler. The default search string for these files
5102
is a colon delimited list set to
4845
find an external handler. The default search string for these files
4846
is a colon delimited list containing the following files:
4847
4848
<orderedlist>
4849
<listitem><para><literal>$HOME/.mailcap</literal></para></listitem>
4850
<listitem><para><literal>$PKGDATADIR/mailcap</literal></para></listitem>
4851
<listitem><para><literal>$SYSCONFDIR/mailcap</literal></para></listitem>
4852
<listitem><para><literal>/etc/mailcap</literal></para></listitem>
4853
<listitem><para><literal>/usr/etc/mailcap</literal></para></listitem>
4854
<listitem><para><literal>/usr/local/etc/mailcap</literal></para></listitem>
4855
</orderedlist>
4856
4857
where <literal>$HOME</literal> is your home directory. The
4858
<literal>$PKGDATADIR</literal> and the
4859
<literal>$SYSCONFDIR</literal> directories depend on where mutt
4860
is installed: the former is the default for shared data, the
4861
latter for system configuration files.
4862
</para>
4863
4864
<para>
4865
The default search path can be obtained by running the following
4866
command:
4867
</para>
5103
4868
5104
4869
<screen>
5105
${HOME}/.mailcap:/usr/local/share/mutt/mailcap:/etc/mailcap:/etc/mailcap:/usr/etc/mailcap:/usr/local/etc/mailcap
4870
mutt -nF /dev/null -Q mailcap_path
5106
4871
</screen>
5107
4872
5108
where <literal>$HOME</literal> is your home directory.
5109
</para>
5110
5111
4873
<para>
5112
4874
In particular, the metamail distribution will install a mailcap file,
5113
4875
usually as <literal>/usr/local/etc/mailcap</literal>, which contains some baseline
5599
5361
For instance, if you set auto_view to:
5600
5362
5601
5363
<screen>
5602
auto_view text/html application/x-gunzip application/postscript image/gif application/x-tar-gz
5364
auto_view text/html application/x-gunzip \
5365
application/postscript image/gif application/x-tar-gz
5603
5366
</screen>
5604
5367
5605
5368
</para>
5610
5373
5611
5374
<screen>
5612
5375
text/html; lynx -dump %s; copiousoutput; nametemplate=%s.html
5613
image/*; anytopnm %s | pnmscale -xsize 80 -ysize 50 | ppmtopgm | pgmtopbm | pbmtoascii ; copiousoutput
5376
image/*; anytopnm %s | pnmscale -xsize 80 -ysize 50 | ppmtopgm | \
5377
pgmtopbm | pbmtoascii ; copiousoutput
5614
5378
application/x-gunzip; gzcat; copiousoutput
5615
5379
application/x-tar-gz; gunzip -c %s | tar -tf - ; copiousoutput
5616
5380
application/postscript; ps2ascii %s; copiousoutput
5808
5572
5809
5573
</chapter>
5810
5574
5575
<chapter id="optionalfeatures">
5576
<title>Optional features</title>
5577
5578
<sect1>
5579
<title>General notes</title>
5580
5581
<sect2>
5582
<title>Enabling/disabling features</title>
5583
5584
<para>
5585
Mutt supports several of optional features which can be enabled or
5586
disabled at compile-time by giving the <emphasis>configure</emphasis> script
5587
certain arguments. These are listed in the ``Optional features'' section of
5588
the <emphasis>configure --help</emphasis> output.
5589
</para>
5590
5591
<para>
5592
Which features are enabled or disabled can later be determined from the
5593
output of <literal>mutt -v</literal>. If a compile option starts with
5594
``+'' it is enabled and disabled if prefixed with ``-''. For example, if
5595
mutt was compiled using GnuTLS for encrypted communication instead of
5596
OpenSSL, <literal>mutt -v</literal> would contain:
5597
</para>
5598
5599
<screen>
5600
-USE_SSL_OPENSSL +USE_SSL_GNUTLS</screen>
5601
5602
</sect2>
5603
5604
<sect2 id="url-syntax">
5605
<title>URL syntax</title>
5606
5607
<para>
5608
Mutt optionally supports the IMAP, POP3 and SMTP protocols which require
5609
to access servers using URLs. The canonical syntax for specifying URLs
5610
in mutt is (an item enclosed in <literal>[]</literal> means it is optional and
5611
may be omitted):
5612
</para>
5613
5614
<screen>
5615
proto[s]://[username[:password]@]server[:port]/[path]
5616
</screen>
5617
5618
<para>
5619
<literal>proto</literal> is the communication protocol:
5620
<literal>imap</literal> for IMAP, <literal>pop</literal> for POP3 and
5621
<literal>smtp</literal> for SMTP. If ``s'' for ``secure communication''
5622
is appended, mutt will attempt to establish an encrypted communication
5623
using SSL or TLS. If no explicit port is given, mutt will use the
5624
system's default for the given protocol.
5625
</para>
5626
5627
<para>
5628
Since all protocols by mutt support authentication, the username may be
5629
given directly in the URL instead of using the <literal>pop_user</literal> or
5630
<literal>imap_user</literal> variables. A password can be given, too but
5631
is not recommended if the URL is specified in a configuration file on
5632
disk.
5633
</para>
5634
5635
<para>
5636
The optional path is only relevant for IMAP.
5637
</para>
5638
5639
<para>
5640
For IMAP for example, you can select an alternative port by specifying it with the
5641
server: <literal>imap://imapserver:port/INBOX</literal>. You can also specify different
5642
username for each folder: <literal>imap://username@imapserver[:port]/INBOX</literal>
5643
or <literal>imap://username2@imapserver[:port]/path/to/folder</literal>.
5644
Replacing <literal>imap://</literal> by <literal>imaps://</literal>
5645
would make mutt attempt to conect using SSL or TLS on a different port
5646
to encrypt the communication.
5647
</para>
5648
5649
</sect2>
5650
5651
</sect1>
5652
5653
<sect1 id="ssl">
5654
<title>SSL/TLS Support</title>
5655
5656
<para>
5657
If mutt is compiled with IMAP, POP3 and/or SMTP support, it can also be
5658
compiled with support for SSL or TLS using either OpenSSL or GnuTLS (
5659
by running the <emphasis>configure</emphasis> script with the
5660
<emphasis>--enable-ssl=...</emphasis> option for OpenSSL or
5661
<emphasis>--enable-gnutls=...</emphasis> for GnuTLS). Mutt can then
5662
attempt to encrypt communication with remote servers if these protocols
5663
are suffixed with ``s'' for ``secure communication''.
5664
</para>
5665
5666
</sect1>
5667
5668
<sect1 id="pop">
5669
<title>POP3 Support</title>
5670
5671
<para>
5672
If Mutt was compiled with POP3 support (by running the <emphasis>configure</emphasis>
5673
script with the <emphasis>--enable-pop</emphasis> flag), it has the ability to work
5674
with mailboxes located on a remote POP3 server and fetch mail for local
5675
browsing.
5676
</para>
5677
5678
<para>
5679
Remote POP3 servers can be accessed using URLs with the <literal>pop</literal> protocol
5680
for unencrypted and <literal>pops</literal> for encrypted
5681
communication, see <xref linkend="url-syntax"/> for details.
5682
</para>
5683
5684
<para>
5685
Polling for new mail is more expensive over POP3 than locally. For this
5686
reason the frequency at which Mutt will check for mail remotely can be
5687
controlled by the
5688
<link linkend="pop-checkinterval">$pop_checkinterval</link>
5689
variable, which defaults to every 60 seconds.
5690
</para>
5691
5692
<para>
5693
Another way to access your POP3 mail is the <emphasis>fetch-mail</emphasis> function
5694
(default: G). It allows to connect to <link linkend="pop-host">$pop_host</link>, fetch all your new mail and place it in the
5695
local <link linkend="spoolfile">$spoolfile</link>. After this
5696
point, Mutt runs exactly as if the mail had always been local.
5697
</para>
5698
5699
<para>
5700
<emphasis role="bold">Note:</emphasis> If you only need to fetch all messages to a
5701
local mailbox you should consider using a specialized program, such as
5702
<literal>fetchmail</literal>, <literal>getmail</literal> or similar.
5703
</para>
5704
5705
</sect1>
5706
5707
<sect1 id="imap">
5708
<title>IMAP Support</title>
5709
5710
<para>
5711
If Mutt was compiled with IMAP support (by running the <emphasis>configure</emphasis>
5712
script with the <emphasis>--enable-imap</emphasis> flag), it has the ability to work
5713
with folders located on a remote IMAP server.
5714
</para>
5715
5716
<para>
5717
You can access the remote inbox by selecting the folder by its URL
5718
(see <xref linkend="url-syntax"/> for details) using the
5719
<literal>imap</literal> or <literal>imaps</literal> protocol.
5720
Alternatively, a pine-compatible notation is also supported, ie
5721
<literal>{[username@]imapserver[:port][/ssl]}path/to/folder</literal>
5722
</para>
5723
5724
<para>
5725
Note that not all servers use ``/'' as the hierarchy separator. Mutt should
5726
correctly notice which separator is being used by the server and convert
5727
paths accordingly.
5728
</para>
5729
5730
<para>
5731
When browsing folders on an IMAP server, you can toggle whether to look
5732
at only the folders you are subscribed to, or all folders with the
5733
<emphasis>toggle-subscribed</emphasis> command. See also the
5734
<link linkend="imap-list-subscribed">$imap_list_subscribed</link> variable.
5735
</para>
5736
5737
<para>
5738
Polling for new mail on an IMAP server can cause noticeable delays. So, you'll
5739
want to carefully tune the
5740
<link linkend="mail-check">$mail_check</link>
5741
and
5742
<link linkend="timeout">$timeout</link>
5743
variables. Personally I use
5744
5745
<screen>
5746
set mail_check=90
5747
set timeout=15
5748
</screen>
5749
5750
with relatively good results over my slow modem line.
5751
</para>
5752
5753
<para>
5754
Note that if you are using mbox as the mail store on UW servers prior to
5755
v12.250, the server has been reported to disconnect a client if another client
5756
selects the same folder.
5757
</para>
5758
5759
<sect2>
5760
<title>The Folder Browser</title>
5761
5762
<para>
5763
As of version 1.2, mutt supports browsing mailboxes on an IMAP
5764
server. This is mostly the same as the local file browser, with the
5765
following differences:
5766
5767
<itemizedlist>
5768
<listitem>
5769
5770
<para>
5771
In lieu of file permissions, mutt displays the string "IMAP",
5772
possibly followed by the symbol "+", indicating
5773
that the entry contains both messages and subfolders. On
5774
Cyrus-like servers folders will often contain both messages and
5775
subfolders.
5776
</para>
5777
</listitem>
5778
<listitem>
5779
5780
<para>
5781
For the case where an entry can contain both messages and
5782
subfolders, the selection key (bound to <literal>enter</literal> by default)
5783
will choose to descend into the subfolder view. If you wish to view
5784
the messages in that folder, you must use <literal>view-file</literal> instead
5785
(bound to <literal>space</literal> by default).
5786
</para>
5787
</listitem>
5788
<listitem>
5789
5790
<para>
5791
You can create, delete and rename mailboxes with the
5792
<literal>create-mailbox</literal>, <literal>delete-mailbox</literal>, and
5793
<literal>rename-mailbox</literal> commands (default bindings: <literal>C</literal>,
5794
<literal>d</literal> and <literal>r</literal>, respectively). You may also
5795
<literal>subscribe</literal> and <literal>unsubscribe</literal> to mailboxes (normally
5796
these are bound to <literal>s</literal> and <literal>u</literal>, respectively).
5797
</para>
5798
</listitem>
5799
5800
</itemizedlist>
5801
5802
</para>
5803
5804
</sect2>
5805
5806
<sect2>
5807
<title>Authentication</title>
5808
5809
<para>
5810
Mutt supports four authentication methods with IMAP servers: SASL,
5811
GSSAPI, CRAM-MD5, and LOGIN (there is a patch by Grant Edwards to add
5812
NTLM authentication for you poor exchange users out there, but it has
5813
yet to be integrated into the main tree). There is also support for
5814
the pseudo-protocol ANONYMOUS, which allows you to log in to a public
5815
IMAP server without having an account. To use ANONYMOUS, simply make
5816
your username blank or "anonymous".
5817
</para>
5818
5819
<para>
5820
SASL is a special super-authenticator, which selects among several protocols
5821
(including GSSAPI, CRAM-MD5, ANONYMOUS, and DIGEST-MD5) the most secure
5822
method available on your host and the server. Using some of these methods
5823
(including DIGEST-MD5 and possibly GSSAPI), your entire session will be
5824
encrypted and invisible to those teeming network snoops. It is the best
5825
option if you have it. To use it, you must have the Cyrus SASL library
5826
installed on your system and compile mutt with the <emphasis>--with-sasl</emphasis> flag.
5827
</para>
5828
5829
<para>
5830
Mutt will try whichever methods are compiled in and available on the server,
5831
in the following order: SASL, ANONYMOUS, GSSAPI, CRAM-MD5, LOGIN.
5832
</para>
5833
5834
<para>
5835
There are a few variables which control authentication:
5836
5837
<itemizedlist>
5838
<listitem>
5839
5840
<para>
5841
<link linkend="imap-user">$imap_user</link> - controls
5842
the username under which you request authentication on the IMAP server,
5843
for all authenticators. This is overridden by an explicit username in
5844
the mailbox path (ie by using a mailbox name of the form
5845
<literal>{user@host}</literal>).
5846
</para>
5847
</listitem>
5848
<listitem>
5849
5850
<para>
5851
<link linkend="imap-pass">$imap_pass</link> - a
5852
password which you may preset, used by all authentication methods where
5853
a password is needed.
5854
</para>
5855
</listitem>
5856
<listitem>
5857
5858
<para>
5859
<link linkend="imap-authenticators">$imap_authenticators</link> - a colon-delimited list of IMAP
5860
authentication methods to try, in the order you wish to try them. If
5861
specified, this overrides mutt's default (attempt everything, in the order
5862
listed above).
5863
</para>
5864
</listitem>
5865
5866
</itemizedlist>
5867
5868
</para>
5869
5870
</sect2>
5871
5872
</sect1>
5873
5874
<sect1 id="smtp">
5875
<title>SMTP Support</title>
5876
5877
<para>
5878
Besides supporting traditional mail delivery through a
5879
sendmail-compatible program, mutt supports delivery through SMTP if it
5880
was configured and built with <literal>--enable-smtp</literal>.
5881
</para>
5882
5883
<para>
5884
If the configuration variable
5885
<link linkend="smtp-url">$smtp_url</link> is set, mutt
5886
will contact the given SMTP server to deliver messages; if it is unset,
5887
mutt will use the program specified by <link linkend="sendmail">$sendmail</link>.
5888
</para>
5889
5890
<para>
5891
For details on the URL syntax, please see <xref linkend="url-syntax"/>.
5892
</para>
5893
5894
<para>
5895
The built-in SMTP support supports encryption (the <literal>smtps</literal> protocol
5896
using SSL or TLS) as well as SMTP authentication using SASL. The authentication mechanisms
5897
for SASL are specified in <link linkend="smtp-authenticators">$smtp_authenticators</link>
5898
defaulting to an empty list which makes mutt try all available methods
5899
from most-secure to least-secure.
5900
</para>
5901
5902
</sect1>
5903
5904
<sect1 id="account-hook">
5905
<title>Managing multiple accounts</title>
5906
5907
<para>
5908
If you happen to have accounts on multiple IMAP, POP and/or SMTP servers,
5909
you may find managing all the authentication settings inconvenient and
5910
error-prone. The account-hook command may help. This hook works like
5911
folder-hook but is invoked whenever you access a remote mailbox
5912
(including inside the folder browser), not just when you open the
5913
mailbox.
5914
</para>
5915
5916
<para>
5917
Some examples:
5918
</para>
5919
5920
<para>
5921
5922
<screen>
5923
account-hook . 'unset imap_user; unset imap_pass; unset tunnel'
5924
account-hook imap://host1/ 'set imap_user=me1 imap_pass=foo'
5925
account-hook imap://host2/ 'set tunnel="ssh host2 /usr/libexec/imapd"'
5926
account-hook smtp://user@host3/ 'set tunnel="ssh host3 /usr/libexec/smtpd"'
5927
</screen>
5928
5929
</para>
5930
5931
</sect1>
5932
5933
<sect1 id="caching">
5934
<title>Local caching</title>
5935
5936
<para>
5937
Mutt contains two types of local caching: <emphasis>(1)</emphasis>
5938
the so-called ``header caching'' and <emphasis>(2)</emphasis> the
5939
so-called ``body caching'' which are both described in this section.
5940
</para>
5941
5942
<para>
5943
These are optional which means they're not enabled by default.
5944
Details on how to enable either of these techniques are given in the
5945
following subsections.
5946
</para>
5947
5948
<sect2 id="header-caching">
5949
<title>Header caching</title>
5950
5951
<para>
5952
Mutt provides optional support for caching message headers for the
5953
following types of folders: IMAP, POP, Maildir and MH. Header caching
5954
greatly improves speed because for remote folders, headers
5955
usually only need to be downloaded once. For Maildir and MH, reading the
5956
headers from a single file is much faster than looking at possibly
5957
thousands of single files (since Maildir and MH use one file per message.)
5958
</para>
5959
5960
<para>
5961
Header caching can be enabled via the configure script and the
5962
<emphasis>--enable-hcache</emphasis> option. It's not turned on
5963
by default because external database libraries are required: one
5964
of qdbm, gdbm or bdb must be present.
5965
</para>
5966
5967
<para>
5968
If enabled, <link
5969
linkend="header-cache">$header_cache</link> can be
5970
used to either point to a file or a directory. If set to point to
5971
a file, one database file for all folders will be used (which may
5972
result in lower performance), but one file per folder if it points
5973
to a directory.
5974
</para>
5975
5976
<para>
5977
For the one-file-per-folder case, database files will be named by MD5
5978
sums. They may be safely removed if a system is short on space. You
5979
can compute the name of the header cache file for a particular folder
5980
through a command like the following:
5981
</para>
5982
5983
<para>
5984
<screen>
5985
$ printf '%s' '/path/to/folder' | md5sum
5986
$ printf '%s' 'imaps://user@host/path/to/folder' | md5sum
5987
$ printf '%s' 'pops://user@host' | md5sum
5988
</screen>
5989
</para>
5990
5991
<para>
5992
The <literal>md5sum</literal> command may also be
5993
named <literal>md5</literal>, depending on your operating system.
5994
</para>
5995
5996
</sect2>
5997
5998
<sect2 id="body-caching">
5999
<title>Body caching</title>
6000
6001
<para>
6002
In addition to caching message headers only, mutt can also cache
6003
whole message bodies. This results in faster display of messages
6004
for POP and IMAP folders because messages usually have to be
6005
downloaded only once.
6006
</para>
6007
6008
<para>
6009
If the configure script is called with <emphasis>--enable-pop</emphasis>
6010
and/or <emphasis>--enable-imap</emphasis>, body caching will be
6011
built in as it does not require additional software packages such
6012
as database libraries.
6013
</para>
6014
6015
<para>
6016
For configuration, the variable <link linkend="message-cachedir"
6017
>$message_cachedir</link> must point to a
6018
directory. There, mutt will create a hierarchy of subdirectories
6019
named like: <literal>proto:user@hostname</literal> where
6020
<literal>proto</literal> is either ``pop'' or ``imap.'' Within
6021
there for each folder, mutt stores messages in single files (just
6022
like Maildir) so that with manual symlink creation these cache
6023
directories can be examined with mutt as read-only Maildir folders.
6024
</para>
6025
6026
<para>
6027
All files can be removed as needed if the consumed disk space
6028
becomes an issue as mutt will silently fetch missing items again.
6029
</para>
6030
6031
</sect2>
6032
6033
</sect1>
6034
6035
</chapter>
6036
5811
6037
<chapter id="tuning">
5812
6038
<title>Performance tuning</title>
5813
6039
Loggerhead is a web-based interface for Breezy
Version: 2.0.1