/[gentoo]/xml/htdocs/doc/en/guide-to-mutt.xml
Gentoo

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.21 - (hide annotations) (download) (as text)
Thu Aug 18 20:56:40 2011 UTC (3 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.20: +8 -6 lines
File MIME type: application/xml
Update from bug #304623, also correct XML usage internally thanks to Joshua Saddler

1 antifa 1.1 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.21 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v 1.20 2011/08/17 19:49:12 swift Exp $ -->
3 swift 1.3
4 swift 1.21 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 neysx 1.18
6 swift 1.21 <guide>
7 neysx 1.18
8 antifa 1.1 <title>QuickStart Guide to Mutt E-Mail</title>
9 neysx 1.18
10 neysx 1.10 <author title="Author">
11 swift 1.20 <mail link="grobian@gentoo.org">Fabian Groffen</mail>
12 swift 1.11 </author>
13 neysx 1.10
14     <abstract>
15 swift 1.20 This guide shows you how to begin using the powerful command line e-mail
16     client mutt.
17 neysx 1.10 </abstract>
18 antifa 1.1
19 fox2mike 1.15 <!-- The content of this document is licensed under the CC-BY-SA license -->
20     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21 swift 1.4 <license/>
22    
23 swift 1.21 <version>3</version>
24     <date>2011-08-18</date>
25 antifa 1.1
26     <chapter>
27 swift 1.20 <title>The Mutt e-mail client</title>
28 antifa 1.1 <section>
29     <body>
30    
31 neysx 1.10 <p>
32     If you're not a fan of e-mail clients with fancy graphical user interfaces, or
33 swift 1.20 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 neysx 1.10 </p>
36 antifa 1.1
37 neysx 1.10 <p>
38 swift 1.20 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 neysx 1.10 </p>
42 antifa 1.1
43 neysx 1.10 <p>
44 swift 1.20 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 neysx 1.10 </p>
50 antifa 1.1
51     </body>
52     </section>
53     </chapter>
54    
55     <chapter>
56 swift 1.20 <title>Acquiring Mutt</title>
57 antifa 1.1 <section>
58     <body>
59    
60 neysx 1.10 <p>
61 swift 1.20 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 neysx 1.10 </p>
68 antifa 1.1
69 swift 1.20 <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 antifa 1.1 </pre>
75    
76 neysx 1.10 <p>
77 swift 1.20 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 neysx 1.10 </p>
85 antifa 1.1
86 swift 1.20 <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>
98 antifa 1.1
99 neysx 1.10 <p>
100 swift 1.20 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 antifa 1.1 </p>
108    
109 neysx 1.10 <p>
110 swift 1.20 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 swift 1.21 <c>ssl</c>. Most likely this is in your global USE already anyway. If you intend
116     to authenticate yourself when sending e-mail, be sure to also include
117     <c>sasl</c> in your USE-flags, since that's a prerequisite for that.
118 neysx 1.10 </p>
119 antifa 1.1
120 neysx 1.10 <p>
121 swift 1.20 Last but not least, there is the <c>sidebar</c> USE-flag. It enables an
122     extension to Mutt that can show a navigation pane of available mailboxes on the
123     left hand side of the screen. While this is not a recommended feature for
124     absolute newcomers (it is nowhere mentioned in any official docs, since it
125     simply isn't official), more experienced users might like its functionality.
126     Luckily, just enabling the USE-flag doesn't make it visible at all, meaning you
127     don't even notice it's enabled.
128 neysx 1.10 </p>
129 antifa 1.1
130     </body>
131     </section>
132     </chapter>
133    
134     <chapter>
135 swift 1.20 <title>Configuring Mutt</title>
136 neysx 1.18 <section>
137 antifa 1.1 <body>
138    
139 neysx 1.10 <p>
140 swift 1.20 After you emerged mutt with your USE-flags of choice, the only necessary step is
141     to create a <path>.muttrc</path> file in your home directory. Muttrc's are to
142     be found in many places on the web and in Mutt's documentation. In
143     <path>/usr/share/doc/mutt-&lt;version&gt;/samples</path> you can find some
144     muttrc samples that are from the official distribution. We discuss a very
145     minimal <path>.muttrc</path> for an IMAP based account with SMTP mail delivery
146     below.
147     </p>
148    
149     <pre caption="A .muttrc example file">
150     # character set on messages that we send
151     set send_charset="utf-8"
152     # if there is no character set given on incoming messages, it is probably windows
153     set assumed_charset="iso-8859-1"
154    
155     # make sure Vim knows mutt is a mail client and that we compose an UTF-8 encoded message
156     set editor="vim -c 'set syntax=mail ft=mail enc=utf-8'"
157    
158     # just scroll one line instead of full page
159     set menu_scroll=yes
160    
161     # we want to see some MIME types inline, see below this code listing for explanation
162     auto_view application/msword
163     auto_view application/pdf
164    
165     # make default search pattern to search in To, Cc and Subject
166     set simple_search="~f %s | ~C %s | ~s %s"
167    
168     # threading preferences, sort by threads
169     set sort=threads
170     set strict_threads=yes
171    
172     # show spam score (from SpamAssassin only) when reading a message
173     spam "X-Spam-Score: ([0-9\\.]+).*" "SA: %1"
174     set pager_format = " %C - %[%H:%M] %.20v, %s%* %?H? [%H] ?"
175    
176     # do not show all headers, just a few
177     ignore *
178     unignore From To Cc Bcc Date Subject
179     # and in this order
180     unhdr_order *
181     hdr_order From: To: Cc: Bcc: Date: Subject:
182    
183     # brighten up stuff with colours, for more colouring examples see:
184     # http://aperiodic.net/phil/configs/mutt/colors
185     color normal white black
186     color hdrdefault green default
187     color quoted green default
188     color quoted1 yellow default
189     color quoted2 red default
190     color signature cyan default
191     color indicator brightyellow red
192     color error brightred default
193     color status brightwhite blue
194     color tree brightmagenta black
195     color tilde blue default
196     color attachment brightyellow default
197     color markers brightred default
198     color message white black
199     color search brightwhite magenta
200     color bold brightyellow default
201     # if you don't like the black progress bar at the bottom of the screen,
202     # comment out the following line
203     color progress white black
204    
205     # personality settings
206     set realname = "Andrew Dalziel"
207     set from = "andy@mail.server"
208     alternates "andrew@mail.server|andrew.dalziel@mail.server"
209     # this file must exist, and contains your signature, comment it out if
210     # you don't want a signature to be used
211     set signature = ~/.signature
212    
213     # aliases (sort of address book)
214     source ~/.aliases
215    
216     # IMAP connection settings
217     set mail_check=60
218     set imap_keepalive=300
219    
220     # IMAP account settings
221     set folder=imaps://andy@imap.mail.server/
222     set spoolfile=imaps://andy@imap.mail.server/
223     set record=imaps://andy@imap.mail.server/Sent
224     set postponed=imaps://andy@imap.mail.server/Drafts
225    
226     # use headercache for IMAP (make sure this is a directory for performance!)
227     set header_cache=/var/tmp/.mutt
228    
229     # mailboxes we want to monitor for new mail
230     mailboxes "="
231     mailboxes "=Lists"
232 antifa 1.1
233 swift 1.20 # mailing lists we are on (these are regexps!)
234     subscribe "gentoo-.*@gentoo\\.org"
235 antifa 1.1
236 swift 1.20 # SMTP mailing configuration (for sending mail)
237     set smtp_url=smtp://mail.server/
238 antifa 1.1 </pre>
239    
240 neysx 1.10 <note>
241 swift 1.20 It is good practice to review all settings from the example above. There are
242     many more, and some preferences may actually not match yours. Keep that in mind
243     when you feel that Mutt at first doesn't really work the way you like.
244 neysx 1.10 </note>
245 antifa 1.1
246 neysx 1.10 <p>
247 swift 1.20 The example <path>.muttrc</path> above sets up an IMAP account, uses an SMTP
248     server to send mail, stores its cache in <path>/var/tmp/.mutt</path>, reads the
249     known address aliases (think of it as an address book) from
250     <path>~/.aliases</path> and appends the signature from <path>~/.signature</path>
251     when composing new mail. For some IMAP servers it may be necessary to change the
252     spool, record and postponed directories, as the folders <path>Sent</path> and
253     <path>Drafts</path> may be under a folder called <path>INBOX</path>. Simply
254     trying this out with Mutt is the simplest way to figure this out.
255 neysx 1.10 </p>
256 antifa 1.1
257 neysx 1.10 <p>
258 swift 1.20 Once your <path>.muttrc</path> is setup, you are ready to launch Mutt by just
259     running <c>mutt</c>. If you entered a valid IMAP server url, Mutt will prompt
260     you for your password and afterwards load all messages for you. Note that the
261     first time entering your mailbox may take a while if you have quite some
262     messages, since Mutt's header cache is still empty. If this succeeds you're in
263     your IMAP mailbox ready to go.
264 antifa 1.1 </p>
265    
266 neysx 1.10 <p>
267 swift 1.20 Navigation is intuitive, as is reading messages by just pressing the enter key
268     or space bar. Mutt is quite Vim alike in that it uses key strokes to perform
269     most of its actions. You best read Mutt's manual on the web to get yourself
270     known with all existing functions (or press ? in Mutt) and what key they are
271     bound to, or better, what key you like it to be bound to. Some essential keys
272     are <c>m</c> (for message) to start composing a new message, <c>q</c> for quit,
273     <c>r</c> for reply, <c>s</c> for save and <c>p</c> for print.
274 neysx 1.10 </p>
275 antifa 1.1
276 neysx 1.10 <p>
277 swift 1.20 One of the features that Mutt has that is still not in today's most savvy email
278     clients is the ability to display attachments inline through some viewer. The
279     auto_view directive in the .muttrc file tells Mutt which attachments (based on
280     their MIME-type) it should view inline. To figure out how to do that, Mutt uses
281     mailcap files to lookup how to display a certain MIME-type. Usually the system
282     wide mailcap file isn't sufficient here, so you better start a
283     <path>~/.mailcap</path> file to put items in there for <c>copiousoutput</c> that
284     Mutt can display inline.
285 neysx 1.10 </p>
286 antifa 1.1
287 neysx 1.10 <p>
288 swift 1.20 In the example <path>.muttrc</path> above <c>auto_view</c> is enabled for
289     <c>application/msword</c> and <c>application/pdf</c> files. These two show
290     the extreme usefulness of this capability, because it means meeting notes sent
291     as doc file now are perfectly fine readable without having to save the
292     attachment and open it in OpenOffice. Instead the text just shows up in the
293     message reader, that is, if you have a matching entry in your
294     <path>~/.mailcap</path> file.
295 neysx 1.10 </p>
296 antifa 1.1
297 swift 1.20 <pre caption="Example .mailcap file">
298     application/msword; antiword '%s'; copiousoutput; description=Word Document;
299     nametemplate=%s.doc
300     application/pdf; pdftotext '%s' -; copiousoutput; description=PDF Document;
301     nametemplate=%s.pdf
302 antifa 1.1 </pre>
303    
304 neysx 1.10 <p>
305 swift 1.20 The above <path>.mailcap</path> example tells mutt what to do to "view"
306     <c>msword</c> and <c>pdf</c> files. For the former it should run a program
307     called <c>antiword</c> (emerge <c>app-text/antiword</c>), for the latter the
308     program <c>pdftotext</c> (emerge <c>app-text/poppler</c>). You can go wild with
309     these to for example display rendered HTML (give <c>app-text/vilistextum</c> a
310     try), render vcards, or show ASCII representation of attached images. All you
311     need to do is define how to call the program in your <path>.mailcap</path>, and
312     tell Mutt to try to view it inline using the <c>auto_view</c> directive.
313 neysx 1.10 </p>
314 antifa 1.1
315     </body>
316     </section>
317     </chapter>
318    
319     <chapter>
320 swift 1.20 <title>Conclusions</title>
321 antifa 1.1 <section>
322     <body>
323    
324 neysx 1.10 <p>
325 swift 1.20 Mutt is a very versatile console email client. If you like the concept, Mutt
326     can be altered to behave in nearly any way through its configuration. Search
327     the web to find others explaining how they did "it", or find one of the many
328     patches that exist to make Mutt do even more. Gentoo applies a couple of very
329     popular patches to Mutt, so make sure to check <c>mutt -v</c> if you want
330     something more to make sure it is not yet already at your disposal. While
331     learning Mutt is not necessarily easy, once it is in your fingers, it can make
332     your mail experience much faster and efficient than with other clients.
333     Searching for example is quite powerful if you know how to hit the right flags
334     and know which regular expression narrows your search down. Enjoy Mutting!
335 swift 1.11 </p>
336    
337     </body>
338     </section>
339     </chapter>
340 antifa 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20