Contents of /xml/htdocs/doc/en/guide-to-mutt.xml

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.20 - (show annotations) (download) (as text)
Wed Aug 17 19:49:12 2011 UTC (6 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.19: +230 -486 lines
File MIME type: application/xml
Bug #304623 - Rewrite of guide-to-mutt.xml. Thanks to Fabian Groffen

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: $ -->
4 <!DOCTYPE guide SYSTEM "http://www.gentoo.org/dtd/guide.dtd">
6 <guide link="http://www.gentoo.org/doc/en/guide-to-mutt.xml">
8 <title>QuickStart Guide to Mutt E-Mail</title>
10 <author title="Author">
11 <mail link="grobian@gentoo.org">Fabian Groffen</mail>
12 </author>
14 <abstract>
15 This guide shows you how to begin using the powerful command line e-mail
16 client mutt.
17 </abstract>
19 <!-- The content of this document is licensed under the CC-BY-SA license -->
20 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21 <license/>
23 <version>2</version>
24 <date>2011-08-17</date>
26 <chapter>
27 <title>The Mutt e-mail client</title>
28 <section>
29 <body>
31 <p>
32 If you're not a fan of e-mail clients with fancy graphical user interfaces, or
33 you just like to be able to quickly read some mail over an SSH connection, the
34 class of console-based mail clients might be for you.
35 </p>
37 <p>
38 Mutt is one of the current console-based mail clients that's still under active
39 development and has a vast crowd of active supporters (and users). It is
40 powerful, highly customisable, small and efficient.
41 </p>
43 <p>
44 While Mutt was originally designed to read mail from the local mbox mail spool
45 (e.g. <path>/var/spool/mail/</path>), nowadays it comes with full support for
46 Maildir stored folders, remote fetching from POP3 servers and complete
47 management of IMAP accounts. For a full description of what Mutt can do, please
48 read the Mutt manual and Mutt website at <uri>http://www.mutt.org/</uri>.
49 </p>
51 </body>
52 </section>
53 </chapter>
55 <chapter>
56 <title>Acquiring Mutt</title>
57 <section>
58 <body>
60 <p>
61 Starting your Mutt adventure simply requires you to emerge it.
62 Unfortunately, Mutt has a lots of options, which enable or disable certain
63 functionalities of Mutt. We now briefly discuss the most important USE-flags
64 that you may want to enable based on your intended usage of Mutt. Please note
65 that enabling most of them won't harm your Mutt, but may make it do more than an
66 experienced Mutt user would like.
67 </p>
69 <pre caption="Mutt's USE-flags">
70 % <i>emerge -pv mutt</i>
71 [ebuild N ] mail-client/mutt-1.5.21-r1 USE="gdbm gpg imap mbox nls nntp \
72 sidebar smime smtp ssl -berkdb -crypt -debug -doc -gnutls \
73 -idn -pop -qdbm -sasl -tokyocabinet"
74 </pre>
76 <p>
77 First off, for newcomers, the <c>imap</c> USE-flag is most probably the most
78 important one. Enabling it won't hurt anything, so if you're unsure what
79 account you're going to use Mutt with, just enable it. Most email providers,
80 even free ones such as GMail, use IMAP these days, for it is the most convenient
81 way to store email that is accessed from multiple clients at the same time
82 and/or different locations. Because IMAP keeps all mail at the server, Mutt
83 just downloads the messages that you want to view.
84 </p>
86 <p>
87 Often you happen to jump through a couple of messages a couple of times shortly
88 after each other, which would require to download the same message over and
89 over again. Since this simply is a waste, Mutt uses a so-called header cache
90 (hcache) to keep the most important bits of messages that it needs. This
91 hcache is backed by a db-library, of which four flavours exist: <c>gdbm</c>,
92 <c>berkdb</c>, <c>qdbm</c> and <c>tokyocabinet</c>. If you don't have any
93 preference yourself, pick gdbm or berkdb. Most likely you will have both
94 already installed on your system. Enabling the USE-flags for more than one
95 hcache backend will make Mutt choose one it likes best. It will always use
96 at most one.
97 </p>
99 <p>
100 While IMAP is important for reading mail, sending mail requires a mail server.
101 Mutt can talk to a mail server that exists on the local system, but often that's
102 not the case, or simply not a good solution for e.g. laptop users that often
103 travel around. Mutt comes with SMTP support which gets enabled by the <c>smtp</c>
104 USE-flag. Again, enabling it if you're not sure doesn't harm. Mutt's SMTP
105 support allows you just to send mail over a mail server of your choice; usually
106 the one that you are given by your email provider.
107 </p>
109 <p>
110 Both IMAP and SMTP mostly go over encrypted channels these days, hence if you
111 enabled any of both, it is wise to also enable either of the <c>ssl</c> or
112 <c>gnutls</c> USE-flags. Both just add the secure variants (imaps and smtps) to
113 Mutt's list of supported protocols using either OpenSSL's or GNUTLS'
114 implementation. If you don't have a strong preference for either, just go for
115 <c>ssl</c>. Most likely this is in your global USE already anyway.
116 </p>
118 <p>
119 Last but not least, there is the <c>sidebar</c> USE-flag. It enables an
120 extension to Mutt that can show a navigation pane of available mailboxes on the
121 left hand side of the screen. While this is not a recommended feature for
122 absolute newcomers (it is nowhere mentioned in any official docs, since it
123 simply isn't official), more experienced users might like its functionality.
124 Luckily, just enabling the USE-flag doesn't make it visible at all, meaning you
125 don't even notice it's enabled.
126 </p>
128 </body>
129 </section>
130 </chapter>
132 <chapter>
133 <title>Configuring Mutt</title>
134 <section>
135 <body>
137 <p>
138 After you emerged mutt with your USE-flags of choice, the only necessary step is
139 to create a <path>.muttrc</path> file in your home directory. Muttrc's are to
140 be found in many places on the web and in Mutt's documentation. In
141 <path>/usr/share/doc/mutt-&lt;version&gt;/samples</path> you can find some
142 muttrc samples that are from the official distribution. We discuss a very
143 minimal <path>.muttrc</path> for an IMAP based account with SMTP mail delivery
144 below.
145 </p>
147 <pre caption="A .muttrc example file">
148 # character set on messages that we send
149 set send_charset="utf-8"
150 # if there is no character set given on incoming messages, it is probably windows
151 set assumed_charset="iso-8859-1"
153 # make sure Vim knows mutt is a mail client and that we compose an UTF-8 encoded message
154 set editor="vim -c 'set syntax=mail ft=mail enc=utf-8'"
156 # just scroll one line instead of full page
157 set menu_scroll=yes
159 # we want to see some MIME types inline, see below this code listing for explanation
160 auto_view application/msword
161 auto_view application/pdf
163 # make default search pattern to search in To, Cc and Subject
164 set simple_search="~f %s | ~C %s | ~s %s"
166 # threading preferences, sort by threads
167 set sort=threads
168 set strict_threads=yes
170 # show spam score (from SpamAssassin only) when reading a message
171 spam "X-Spam-Score: ([0-9\\.]+).*" "SA: %1"
172 set pager_format = " %C - %[%H:%M] %.20v, %s%* %?H? [%H] ?"
174 # do not show all headers, just a few
175 ignore *
176 unignore From To Cc Bcc Date Subject
177 # and in this order
178 unhdr_order *
179 hdr_order From: To: Cc: Bcc: Date: Subject:
181 # brighten up stuff with colours, for more colouring examples see:
182 # http://aperiodic.net/phil/configs/mutt/colors
183 color normal white black
184 color hdrdefault green default
185 color quoted green default
186 color quoted1 yellow default
187 color quoted2 red default
188 color signature cyan default
189 color indicator brightyellow red
190 color error brightred default
191 color status brightwhite blue
192 color tree brightmagenta black
193 color tilde blue default
194 color attachment brightyellow default
195 color markers brightred default
196 color message white black
197 color search brightwhite magenta
198 color bold brightyellow default
199 # if you don't like the black progress bar at the bottom of the screen,
200 # comment out the following line
201 color progress white black
203 # personality settings
204 set realname = "Andrew Dalziel"
205 set from = "andy@mail.server"
206 alternates "andrew@mail.server|andrew.dalziel@mail.server"
207 # this file must exist, and contains your signature, comment it out if
208 # you don't want a signature to be used
209 set signature = ~/.signature
211 # aliases (sort of address book)
212 source ~/.aliases
214 # IMAP connection settings
215 set mail_check=60
216 set imap_keepalive=300
218 # IMAP account settings
219 set folder=imaps://andy@imap.mail.server/
220 set spoolfile=imaps://andy@imap.mail.server/
221 set record=imaps://andy@imap.mail.server/Sent
222 set postponed=imaps://andy@imap.mail.server/Drafts
224 # use headercache for IMAP (make sure this is a directory for performance!)
225 set header_cache=/var/tmp/.mutt
227 # mailboxes we want to monitor for new mail
228 mailboxes "="
229 mailboxes "=Lists"
231 # mailing lists we are on (these are regexps!)
232 subscribe "gentoo-.*@gentoo\\.org"
234 # SMTP mailing configuration (for sending mail)
235 set smtp_url=smtp://mail.server/
236 </pre>
238 <note>
239 It is good practice to review all settings from the example above. There are
240 many more, and some preferences may actually not match yours. Keep that in mind
241 when you feel that Mutt at first doesn't really work the way you like.
242 </note>
244 <p>
245 The example <path>.muttrc</path> above sets up an IMAP account, uses an SMTP
246 server to send mail, stores its cache in <path>/var/tmp/.mutt</path>, reads the
247 known address aliases (think of it as an address book) from
248 <path>~/.aliases</path> and appends the signature from <path>~/.signature</path>
249 when composing new mail. For some IMAP servers it may be necessary to change the
250 spool, record and postponed directories, as the folders <path>Sent</path> and
251 <path>Drafts</path> may be under a folder called <path>INBOX</path>. Simply
252 trying this out with Mutt is the simplest way to figure this out.
253 </p>
255 <p>
256 Once your <path>.muttrc</path> is setup, you are ready to launch Mutt by just
257 running <c>mutt</c>. If you entered a valid IMAP server url, Mutt will prompt
258 you for your password and afterwards load all messages for you. Note that the
259 first time entering your mailbox may take a while if you have quite some
260 messages, since Mutt's header cache is still empty. If this succeeds you're in
261 your IMAP mailbox ready to go.
262 </p>
264 <p>
265 Navigation is intuitive, as is reading messages by just pressing the enter key
266 or space bar. Mutt is quite Vim alike in that it uses key strokes to perform
267 most of its actions. You best read Mutt's manual on the web to get yourself
268 known with all existing functions (or press ? in Mutt) and what key they are
269 bound to, or better, what key you like it to be bound to. Some essential keys
270 are <c>m</c> (for message) to start composing a new message, <c>q</c> for quit,
271 <c>r</c> for reply, <c>s</c> for save and <c>p</c> for print.
272 </p>
274 <p>
275 One of the features that Mutt has that is still not in today's most savvy email
276 clients is the ability to display attachments inline through some viewer. The
277 auto_view directive in the .muttrc file tells Mutt which attachments (based on
278 their MIME-type) it should view inline. To figure out how to do that, Mutt uses
279 mailcap files to lookup how to display a certain MIME-type. Usually the system
280 wide mailcap file isn't sufficient here, so you better start a
281 <path>~/.mailcap</path> file to put items in there for <c>copiousoutput</c> that
282 Mutt can display inline.
283 </p>
285 <p>
286 In the example <path>.muttrc</path> above <c>auto_view</c> is enabled for
287 <c>application/msword</c> and <c>application/pdf</c> files. These two show
288 the extreme usefulness of this capability, because it means meeting notes sent
289 as doc file now are perfectly fine readable without having to save the
290 attachment and open it in OpenOffice. Instead the text just shows up in the
291 message reader, that is, if you have a matching entry in your
292 <path>~/.mailcap</path> file.
293 </p>
295 <pre caption="Example .mailcap file">
296 application/msword; antiword '%s'; copiousoutput; description=Word Document;
297 nametemplate=%s.doc
298 application/pdf; pdftotext '%s' -; copiousoutput; description=PDF Document;
299 nametemplate=%s.pdf
300 </pre>
302 <p>
303 The above <path>.mailcap</path> example tells mutt what to do to "view"
304 <c>msword</c> and <c>pdf</c> files. For the former it should run a program
305 called <c>antiword</c> (emerge <c>app-text/antiword</c>), for the latter the
306 program <c>pdftotext</c> (emerge <c>app-text/poppler</c>). You can go wild with
307 these to for example display rendered HTML (give <c>app-text/vilistextum</c> a
308 try), render vcards, or show ASCII representation of attached images. All you
309 need to do is define how to call the program in your <path>.mailcap</path>, and
310 tell Mutt to try to view it inline using the <c>auto_view</c> directive.
311 </p>
313 </body>
314 </section>
315 </chapter>
317 <chapter>
318 <title>Conclusions</title>
319 <section>
320 <body>
322 <p>
323 Mutt is a very versatile console email client. If you like the concept, Mutt
324 can be altered to behave in nearly any way through its configuration. Search
325 the web to find others explaining how they did "it", or find one of the many
326 patches that exist to make Mutt do even more. Gentoo applies a couple of very
327 popular patches to Mutt, so make sure to check <c>mutt -v</c> if you want
328 something more to make sure it is not yet already at your disposal. While
329 learning Mutt is not necessarily easy, once it is in your fingers, it can make
330 your mail experience much faster and efficient than with other clients.
331 Searching for example is quite powerful if you know how to hit the right flags
332 and know which regular expression narrows your search down. Enjoy Mutting!
333 </p>
335 </body>
336 </section>
337 </chapter>
338 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20