Gentoo Archives: gentoo-doc-cvs

From: "Sven Vermeulen (swift)" <swift@g.o>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] gentoo commit in xml/htdocs/doc/en: guide-to-mutt.xml
Date: Wed, 17 Aug 2011 19:49:31
Message-Id: 20110817194912.54FAC2004C@flycatcher.gentoo.org
1 swift 11/08/17 19:49:12
2
3 Modified: guide-to-mutt.xml
4 Log:
5 Bug #304623 - Rewrite of guide-to-mutt.xml. Thanks to Fabian Groffen
6
7 Revision Changes Path
8 1.20 xml/htdocs/doc/en/guide-to-mutt.xml
9
10 file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml?rev=1.20&view=markup
11 plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml?rev=1.20&content-type=text/plain
12 diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml?r1=1.19&r2=1.20
13
14 Index: guide-to-mutt.xml
15 ===================================================================
16 RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v
17 retrieving revision 1.19
18 retrieving revision 1.20
19 diff -u -r1.19 -r1.20
20 --- guide-to-mutt.xml 17 Sep 2006 16:08:36 -0000 1.19
21 +++ guide-to-mutt.xml 17 Aug 2011 19:49:12 -0000 1.20
22 @@ -1,259 +1,128 @@
23 <?xml version='1.0' encoding="UTF-8"?>
24 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v 1.19 2006/09/17 16:08:36 neysx Exp $ -->
25 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/guide-to-mutt.xml,v 1.20 2011/08/17 19:49:12 swift Exp $ -->
26
27 -<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
28 +<!DOCTYPE guide SYSTEM "http://www.gentoo.org/dtd/guide.dtd">
29
30 -<guide link="/doc/en/guide-to-mutt.xml">
31 +<guide link="http://www.gentoo.org/doc/en/guide-to-mutt.xml">
32
33 <title>QuickStart Guide to Mutt E-Mail</title>
34
35 <author title="Author">
36 - <mail link="mikpolniak@××××××××.net">Mike Polniak</mail>
37 -</author>
38 -<author title="Editor">
39 - <mail link="antifa@g.o">Ken Nowack</mail>
40 -</author>
41 -<author title="Contributor">
42 - <mail link="hitch17@×××××.com">John Hitchings</mail>
43 + <mail link="grobian@g.o">Fabian Groffen</mail>
44 </author>
45
46 <abstract>
47 -This guide shows you how to begin using the powerful command line tools for
48 -e-mail: fetchmail, procmail, mutt, nbsmtp, msmtp.
49 +This guide shows you how to begin using the powerful command line e-mail
50 +client mutt.
51 </abstract>
52
53 <!-- The content of this document is licensed under the CC-BY-SA license -->
54 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
55 <license/>
56
57 -<version>1.7</version>
58 -<date>2006-09-17</date>
59 +<version>2</version>
60 +<date>2011-08-17</date>
61
62 <chapter>
63 -<title>Introduction to E-Mail</title>
64 +<title>The Mutt e-mail client</title>
65 <section>
66 <body>
67
68 <p>
69 If you're not a fan of e-mail clients with fancy graphical user interfaces, or
70 -if you would just like to experiment with other mail clients before deciding
71 -which is best for you, here is the easy way to begin using these powerful
72 -command line tools:
73 -</p>
74 -
75 -<p>
76 -<b>fetchmail, procmail, mutt &amp; smtp</b>
77 -</p>
78 -
79 -<p>
80 -These programs are not only powerful and highly customizable but also small and
81 -efficient. Once you are up and running with this e-mail system you will be
82 -amazed at what you can do with it.
83 +you just like to be able to quickly read some mail over an SSH connection, the
84 +class of console-based mail clients might be for you.
85 </p>
86
87 <p>
88 -Because this is a quick start guide, we will eliminate the Mail Transfer Agent
89 -(MTA) such as sendmail, postfix or exim. This means no complex MTA
90 -configuration. It also eliminates using port 25 for mail service.
91 +Mutt is one of the current console-based mail clients that's still under active
92 +development and has a vast crowd of active supporters (and users). It is
93 +powerful, highly customisable, small and efficient.
94 </p>
95
96 <p>
97 -We can do this because fetchmail can force the mail it retrieves directly to a
98 -Mail Delivery Agent (MDA) rather than forwarding to port 25. And we don't need
99 -to use a complex MTA for plain old outgoing mail delivery.
100 -</p>
101 -
102 -<p>
103 -These are the programs you will need to get your e-mail running.
104 -</p>
105 -
106 -<pre caption="Getting needed programs">
107 -# <i>emerge fetchmail nbsmtp procmail mutt</i>
108 -</pre>
109 -
110 -<p>
111 -Then just four quick steps to configure files and you will be up and running a
112 -brand new e-mail system.
113 +While Mutt was originally designed to read mail from the local mbox mail spool
114 +(e.g. <path>/var/spool/mail/</path>), nowadays it comes with full support for
115 +Maildir stored folders, remote fetching from POP3 servers and complete
116 +management of IMAP accounts. For a full description of what Mutt can do, please
117 +read the Mutt manual and Mutt website at <uri>http://www.mutt.org/</uri>.
118 </p>
119
120 -<impo>
121 -After each step you can run a test to make sure the setup is correct. This
122 -means you will have a complete working e-mail system when you are done.
123 -</impo>
124 -
125 </body>
126 </section>
127 </chapter>
128
129 <chapter>
130 -<title>Fetchmail</title>
131 +<title>Acquiring Mutt</title>
132 <section>
133 <body>
134
135 <p>
136 -Fetchmail fetches mail from remote servers and forwards it to your local
137 -machines delivery system. To use it you need to set up a
138 -<path>.fetchmailrc</path> file in your home directory like this example:
139 -</p>
140 -
141 -<pre caption="Sample .fetchmailrc">
142 -<i>poll mail.myisp.net protocol pop3 user "myname" password "mypasswd"</i>
143 -</pre>
144 -
145 -<p>
146 -Once you have created a <path>.fetchmailrc</path> file, you have to change the
147 -permissions on the file using the chmod command. The file must be readable only
148 -by the file owner. Set the permissions with the following command:
149 -</p>
150 -
151 -<pre caption="Changing Permissions">
152 -$ <i>chmod 600 .fetchmailrc</i>
153 -</pre>
154 -
155 -<p>
156 -To see fetchmail in action, use the verbose mode (-v). To fetch all messages
157 -use -a. And you must use the option -m to tell fetchmail to send the mail to
158 -procmail.
159 -</p>
160 -
161 -<warn>
162 -While testing, it's a good idea to tell fetchmail to keep (-k) the mail on the
163 -remote server in case something goes wrong and you need to fetch it again.
164 -</warn>
165 -
166 -<p>
167 -Run it now to see fetchmail in action!
168 +Starting your Mutt adventure simply requires you to emerge it.
169 +Unfortunately, Mutt has a lots of options, which enable or disable certain
170 +functionalities of Mutt. We now briefly discuss the most important USE-flags
171 +that you may want to enable based on your intended usage of Mutt. Please note
172 +that enabling most of them won't harm your Mutt, but may make it do more than an
173 +experienced Mutt user would like.
174 </p>
175
176 -<pre caption="Fetchmail test #1">
177 -$ <i>fetchmail -akv -m "/usr/bin/procmail -d %T"</i>
178 +<pre caption="Mutt's USE-flags">
179 +% <i>emerge -pv mutt</i>
180 +[ebuild N ] mail-client/mutt-1.5.21-r1 USE="gdbm gpg imap mbox nls nntp \
181 + sidebar smime smtp ssl -berkdb -crypt -debug -doc -gnutls \
182 + -idn -pop -qdbm -sasl -tokyocabinet"
183 </pre>
184
185 <p>
186 -Once you have a working mail system you can set this as a cron job or put it in
187 -a monitor like gkrellm. Fetchmail can also run in a daemon mode for which you
188 -specify a polling interval in seconds.
189 +First off, for newcomers, the <c>imap</c> USE-flag is most probably the most
190 +important one. Enabling it won't hurt anything, so if you're unsure what
191 +account you're going to use Mutt with, just enable it. Most email providers,
192 +even free ones such as GMail, use IMAP these days, for it is the most convenient
193 +way to store email that is accessed from multiple clients at the same time
194 +and/or different locations. Because IMAP keeps all mail at the server, Mutt
195 +just downloads the messages that you want to view.
196 </p>
197
198 -</body>
199 -</section>
200 -</chapter>
201 -
202 -<chapter>
203 -<title>Procmail</title>
204 -<section>
205 -<body>
206 -
207 <p>
208 -Procmail is the processor that filters the mail that is forwarded to it by
209 -fetchmail. It also acts as the MDA to deliver mail to your mailboxes where mutt
210 -(your e-mail client) can read it.
211 +Often you happen to jump through a couple of messages a couple of times shortly
212 +after each other, which would require to download the same message over and
213 +over again. Since this simply is a waste, Mutt uses a so-called header cache
214 +(hcache) to keep the most important bits of messages that it needs. This
215 +hcache is backed by a db-library, of which four flavours exist: <c>gdbm</c>,
216 +<c>berkdb</c>, <c>qdbm</c> and <c>tokyocabinet</c>. If you don't have any
217 +preference yourself, pick gdbm or berkdb. Most likely you will have both
218 +already installed on your system. Enabling the USE-flags for more than one
219 +hcache backend will make Mutt choose one it likes best. It will always use
220 +at most one.
221 </p>
222
223 <p>
224 -To use procmail you need to create a <path>.procmailrc</path> file in your home
225 -directory. For our quickstart purposes we will use a very simple
226 -<path>.procmailrc</path> that will filter mail from three gentoo mailing lists
227 -into these mailboxes:<e>gentoo-dev, gentoo-user</e> and <e>gentoo-announce</e>
228 +While IMAP is important for reading mail, sending mail requires a mail server.
229 +Mutt can talk to a mail server that exists on the local system, but often that's
230 +not the case, or simply not a good solution for e.g. laptop users that often
231 +travel around. Mutt comes with SMTP support which gets enabled by the <c>smtp</c>
232 +USE-flag. Again, enabling it if you're not sure doesn't harm. Mutt's SMTP
233 +support allows you just to send mail over a mail server of your choice; usually
234 +the one that you are given by your email provider.
235 </p>
236
237 -<note>
238 -The procmail filter rules are called recipes, and I have also included recipes
239 -to filter out some spam.
240 -</note>
241 -
242 -<pre caption="Sample .procmailrc">
243 -MAILDIR=$HOME/MuttMail ##you better make sure it exists
244 -LOGFILE=$HOME/.procmaillog
245 -LOGABSTRACT=no
246 -#VERBOSE=on...is only used for debugging
247 -VERBOSE=off
248 -FORMAIL=/usr/bin/formail
249 -NL="
250 -"
251 -##recipe lines begin with :0
252 -##dont put comments on recipe lines
253 -##disable a recipe with the false condition !
254 -##condition lines begin with * and regex is your friend
255 -##conditions are anded and everything after * is fed straight into egrep
256 -##one action line follows the conditions, in this case it is a mailbox name
257 -
258 -#catch duplicates using formail
259 -:0 Whc: .msgid.lock
260 -| $FORMAIL -D 16384 .msgid.cache
261 -
262 -:0 a
263 -$MAILDIR/duplicates
264 -
265 -#people we always allow mail from
266 -:0
267 -* ^From:.*(craig\@hotmail|renee\@local.com)
268 -$MAILDIR/friends
269 -
270 -#now flush some spam out
271 -:0
272 -* ^Subject:.*(credit|cash|money|debt|sex|sale|loan)
273 -$MAILDIR/spam
274 -
275 -#no more html messages
276 -:0
277 -* ^Content-Type:.*html
278 -$MAILDIR/junk
279 -
280 -#now put my mail lists into mailboxes
281 -:0
282 -* ^List-Id:.*gentoo-user
283 -gentoo-user
284 -
285 -:0
286 -* ^List-Id:.*gentoo-dev
287 -gentoo-dev
288 -
289 -:0
290 -* ^List-Id:.*gentoo-announce
291 -gentoo-announce
292 -
293 -#catch any other gentoo mail
294 -:0
295 -* ^From:.*gentoo.org
296 -gentoo
297 -
298 -:0
299 -* ^From:.*@freshmeat\.net
300 -freshmeat
301 -
302 -################################
303 -# Last rule: mail that gets #
304 -# this far goes in default box #
305 -################################
306 -:0
307 -* .*
308 -default
309 -
310 -# End of file
311 -</pre>
312 -
313 -<note>
314 -It is only required to make the MAILDIR <path>$HOME/MuttMail</path> as Procmail
315 -will create all the mailbox files as needed in this directory using the names
316 -on the action lines. For some useful links visit
317 -<uri>http://www.procmail.org/</uri>
318 -</note>
319 -
320 <p>
321 -You can now test <path>.procmailrc</path> by re-running the fetchmail command
322 -we tested in the first step. Remember the -k option to keep all mail on the
323 -remote server so we have it if we need to rerun it.
324 +Both IMAP and SMTP mostly go over encrypted channels these days, hence if you
325 +enabled any of both, it is wise to also enable either of the <c>ssl</c> or
326 +<c>gnutls</c> USE-flags. Both just add the secure variants (imaps and smtps) to
327 +Mutt's list of supported protocols using either OpenSSL's or GNUTLS'
328 +implementation. If you don't have a strong preference for either, just go for
329 +<c>ssl</c>. Most likely this is in your global USE already anyway.
330 </p>
331
332 -
333 -<pre caption="Procmail test #1">
334 -$ <i>fetchmail -akv -m "/usr/bin/procmail -d %T"</i>
335 -</pre>
336 -
337 <p>
338 -Now that fetchmail and procmail have run, go to <path>$HOME/MuttMail</path> and
339 -read your messages with <c>less</c> or your file manager.
340 +Last but not least, there is the <c>sidebar</c> USE-flag. It enables an
341 +extension to Mutt that can show a navigation pane of available mailboxes on the
342 +left hand side of the screen. While this is not a recommended feature for
343 +absolute newcomers (it is nowhere mentioned in any official docs, since it
344 +simply isn't official), more experienced users might like its functionality.
345 +Luckily, just enabling the USE-flag doesn't make it visible at all, meaning you
346 +don't even notice it's enabled.
347 </p>
348
349 </body>
350 @@ -261,244 +130,184 @@
351 </chapter>
352
353 <chapter>
354 -<title>Mutt e-mail client</title>
355 +<title>Configuring Mutt</title>
356 <section>
357 <body>
358
359 <p>
360 -Mutt is used to read and compose e-mail. It is powerful and highly customizable
361 -but also small and efficient.
362 -</p>
363 +After you emerged mutt with your USE-flags of choice, the only necessary step is
364 +to create a <path>.muttrc</path> file in your home directory. Muttrc's are to
365 +be found in many places on the web and in Mutt's documentation. In
366 +<path>/usr/share/doc/mutt-&lt;version&gt;/samples</path> you can find some
367 +muttrc samples that are from the official distribution. We discuss a very
368 +minimal <path>.muttrc</path> for an IMAP based account with SMTP mail delivery
369 +below.
370 +</p>
371 +
372 +<pre caption="A .muttrc example file">
373 +# character set on messages that we send
374 +set send_charset="utf-8"
375 +# if there is no character set given on incoming messages, it is probably windows
376 +set assumed_charset="iso-8859-1"
377 +
378 +# make sure Vim knows mutt is a mail client and that we compose an UTF-8 encoded message
379 +set editor="vim -c 'set syntax=mail ft=mail enc=utf-8'"
380 +
381 +# just scroll one line instead of full page
382 +set menu_scroll=yes
383 +
384 +# we want to see some MIME types inline, see below this code listing for explanation
385 +auto_view application/msword
386 +auto_view application/pdf
387 +
388 +# make default search pattern to search in To, Cc and Subject
389 +set simple_search="~f %s | ~C %s | ~s %s"
390 +
391 +# threading preferences, sort by threads
392 +set sort=threads
393 +set strict_threads=yes
394 +
395 +# show spam score (from SpamAssassin only) when reading a message
396 +spam "X-Spam-Score: ([0-9\\.]+).*" "SA: %1"
397 +set pager_format = " %C - %[%H:%M] %.20v, %s%* %?H? [%H] ?"
398 +
399 +# do not show all headers, just a few
400 +ignore *
401 +unignore From To Cc Bcc Date Subject
402 +# and in this order
403 +unhdr_order *
404 +hdr_order From: To: Cc: Bcc: Date: Subject:
405 +
406 +# brighten up stuff with colours, for more colouring examples see:
407 +# http://aperiodic.net/phil/configs/mutt/colors
408 +color normal white black
409 +color hdrdefault green default
410 +color quoted green default
411 +color quoted1 yellow default
412 +color quoted2 red default
413 +color signature cyan default
414 +color indicator brightyellow red
415 +color error brightred default
416 +color status brightwhite blue
417 +color tree brightmagenta black
418 +color tilde blue default
419 +color attachment brightyellow default
420 +color markers brightred default
421 +color message white black
422 +color search brightwhite magenta
423 +color bold brightyellow default
424 +# if you don't like the black progress bar at the bottom of the screen,
425 +# comment out the following line
426 +color progress white black
427 +
428 +# personality settings
429 +set realname = "Andrew Dalziel"
430 +set from = "andy@××××.server"
431 +alternates "andrew@××××.server|andrew.dalziel@××××.server"
432 +# this file must exist, and contains your signature, comment it out if
433 +# you don't want a signature to be used
434 +set signature = ~/.signature
435 +
436 +# aliases (sort of address book)
437 +source ~/.aliases
438 +
439 +# IMAP connection settings
440 +set mail_check=60
441 +set imap_keepalive=300
442 +
443 +# IMAP account settings
444 +set folder=imaps://andy@×××××××××.server/
445 +set spoolfile=imaps://andy@×××××××××.server/
446 +set record=imaps://andy@×××××××××.server/Sent
447 +set postponed=imaps://andy@×××××××××.server/Drafts
448 +
449 +# use headercache for IMAP (make sure this is a directory for performance!)
450 +set header_cache=/var/tmp/.mutt
451 +
452 +# mailboxes we want to monitor for new mail
453 +mailboxes "="
454 +mailboxes "=Lists"
455
456 -<p>
457 -Mutt supports reading and writing of four different mailbox formats: mbox,
458 -MMDF, MH and Maildir. The mailbox type is autodetected. In our case we are
459 -using the mbox format, where all messages of a mailbox are stored in a single
460 -file.
461 -</p>
462 -
463 -<p>
464 -Mutt also has the ability to work with folders located on a remote IMAP server.
465 -See IMAP Support in section 4.11 of the Mutt manual and the Mutt web site
466 -<uri>http://www.mutt.org/</uri>
467 -</p>
468 -
469 -<p>
470 -When you emerged mutt in the first step it installed a configuration file in
471 -<path>/etc/mutt/Muttrc</path>. You also need to create a <path>.muttrc</path>
472 -file in your home directory.
473 -</p>
474 -
475 -<pre caption="Sample .muttrc">
476 -<comment>(Be sure to read the fine Mutt manual in /usr/share/doc/mutt*)
477 -(Any settings here override the system settings in /etc/mutt/Muttrc)</comment>
478 -
479 -# <i>cp /etc/mutt/Muttrc ~/.muttrc</i>
480 -# <i>nano -w .muttrc</i>
481 -set pager_context=1
482 -set pager_index_lines=6 #show a mini-index in pager
483 -set menu_scroll
484 -set pgp_verify_sig=no #dont show pgp in pager
485 -set status_on_top #put status line at top
486 -set sort=threads #sort by message threads in index
487 -
488 -set status_format=" %r %b %f %n Del %d Msgs %m %l %> (%P)"
489 -set pager_format="%-10.10i %[!%a %b %d %R]"
490 -set date_format="!%H:%M %a %d %b "
491 -set index_format="%4C %Z %[%b%d] %-15.15F %s"
492 -set folder_format="%2C %t %8s %d %N %f"
493 -
494 -#set sendmail="/usr/bin/nbsmtp -d isp.net -h smtp.isp.net -f yourname@×××.net"
495 -
496 -#set from="default-mailaddress" #set to your from address
497 -#set realname="myname"
498 -
499 -set record="$HOME/MuttMail/sent" #sent mail is saved here
500 -set delete=yes #delete without prompting
501 -set include=yes #quote msg in reply
502 -set fast_reply=yes #no prompting on reply
503 -set beep=no #no noise
504 -set markers=no #no + on wrapped lines
505 -set confirmappend=no #no prompt for save to =keep
506 -set to_chars=" +TCF" #no L for mail_list
507 -
508 -set folder = $HOME/MuttMail
509 -mailboxes =gentoo-user
510 -mailboxes =gentoo-dev
511 -mailboxes =gentoo-announce
512 -mailboxes =gentoo
513 -mailboxes =freshmeat
514 -mailboxes =duplicates
515 -mailboxes =default
516 -mailboxes =friends
517 -mailboxes =junk
518 -mailboxes =spam
519 -mailboxes =keep
520 -
521 -save-hook .* =keep #default mbox to (s)ave mail is =keep
522 -subscribe gentoo-user gentoo-dev #subscribed to these lists
523 -
524 -bind pager h display-toggle-weed #toggle headers with h key
525 -
526 -# simulate the old url menu
527 -macro index \cb |urlview\n 'call urlview to extract URLs out of a message'
528 -macro pager \cb |urlview\n 'call urlview to extract URLs out of a message'
529 -
530 -#run fetchmail by hitting key of G
531 -macro index G "!fetchmail -a -m 'procmail -d %T'\r"
532 -macro pager G "!fetchmail -a -m 'procmail -d %T'\r"
533 -
534 -#use to edit .muttrc and then source it...no restart necessary
535 -macro generic ,sm ":source $HOME/.muttrc\r"
536 -macro generic \cj "!rxvt -bg wheat -e joe $HOME/.muttrc\r"
537 -
538 -# default list of header fields to weed out when displaying mail
539 -#ignore them all and then unignore what you want to see
540 -ignore *
541 -unignore Date To From: Subject X-Mailer Organization User-Agent
542 -hdr_order Date From To Subject X-Mailer User-Agent Organization
543 -
544 -##your Mutt has to have some colors
545 -##these are for four levels of quoted text
546 -##they override the system settings in /etc/mutt/Muttrc
547 -
548 -#color quoted green default
549 -color quoted1 magenta blue
550 -#color quoted2 yellow default
551 -#color quoted3 red default
552 -#color signature cyan cyan
553 -
554 -
555 -#this color setup is copied from /etc/mutt/Muttrc.color
556 -#comment it out if you want the default colors in /etc/mutt/Muttrc
557 -# Je vois la vie en rose :-)
558 -color hdrdefault brightcyan blue
559 -color header brightwhite blue "^from:"
560 -color header brightwhite blue "^subject:"
561 -
562 -color quoted brightgreen blue
563 -color signature brightwhite blue
564 -
565 -color indicator blue green
566 -
567 -color error red black
568 -mono error bold
569 -color status black cyan
570 -mono status bold
571 -color tree yellow blue
572 -
573 -color tilde brightmagenta blue
574 -color body brightwhite blue "[-a-z_0-9.]+@[-a-z_0-9.]+"
575 -mono body bold "[-a-z_0-9.]+@[-a-z_0-9.]+"
576 -color body brightyellow black "^Good signature"
577 -mono body bold "^Good signature"
578 -color body brightwhite red "^Bad signature from.*"
579 -mono body bold "^Bad signature from.*"
580 -color normal white blue
581 -color message green black
582 -color attachment brightgreen blue
583 +# mailing lists we are on (these are regexps!)
584 +subscribe "gentoo-.*@gentoo\\.org"
585
586 -# End of file...but it can go on and on and on....:)
587 +# SMTP mailing configuration (for sending mail)
588 +set smtp_url=smtp://mail.server/
589 </pre>
590
591 -<p>
592 -For the record, this is just a sample <path>.muttrc</path>. There are many more
593 -options that you can configure, such as integration with GPG. Have a look at
594 -<uri>http://www.dotfiles.com/index.php?app_id=27</uri> for more examples and
595 -help.
596 -</p>
597 -
598 -<p>
599 -You are now ready to test your <path>.muttrc</path>.
600 -</p>
601 -
602 -<pre caption="Testing .muttrc">
603 -$ <i>mutt -y</i>
604 -</pre>
605 -
606 -<p>
607 -This should open Mutt with a menu showing the Mutt mailboxes that you created
608 -in Test 2 when you ran the fetchmail command.
609 -</p>
610 -
611 -<p>
612 -Type the ? for help in navigating the Mutt Mailboxes.
613 -</p>
614 -
615 -</body>
616 -</section>
617 -</chapter>
618 -
619 -<chapter>
620 -<title>SMTP</title>
621 -<section>
622 -<body>
623 -
624 -<p>
625 -The final step is setting up nbsmtp the 'No-Brainer SMTP' used to send mail to
626 -your SMTP server. This setup is the easiest of all, as it only requires adding
627 -an entry in your <path>.muttrc</path> file.
628 -</p>
629 -
630 -<p>
631 -domain: The domain you want nbsmtp to say it belongs to. This will almost
632 -invariably be the same as the domain in your e-mail address.
633 -</p>
634 +<note>
635 +It is good practice to review all settings from the example above. There are
636 +many more, and some preferences may actually not match yours. Keep that in mind
637 +when you feel that Mutt at first doesn't really work the way you like.
638 +</note>
639
640 <p>
641 -from@addr: This is the address you want nbsmtp to say the message is from. Note
642 -that this can be different than the "From:" line in your MUA.
643 +The example <path>.muttrc</path> above sets up an IMAP account, uses an SMTP
644 +server to send mail, stores its cache in <path>/var/tmp/.mutt</path>, reads the
645 +known address aliases (think of it as an address book) from
646 +<path>~/.aliases</path> and appends the signature from <path>~/.signature</path>
647 +when composing new mail. For some IMAP servers it may be necessary to change the
648 +spool, record and postponed directories, as the folders <path>Sent</path> and
649 +<path>Drafts</path> may be under a folder called <path>INBOX</path>. Simply
650 +trying this out with Mutt is the simplest way to figure this out.
651 </p>
652
653 <p>
654 -host: This is the smtp server you are sending to.
655 +Once your <path>.muttrc</path> is setup, you are ready to launch Mutt by just
656 +running <c>mutt</c>. If you entered a valid IMAP server url, Mutt will prompt
657 +you for your password and afterwards load all messages for you. Note that the
658 +first time entering your mailbox may take a while if you have quite some
659 +messages, since Mutt's header cache is still empty. If this succeeds you're in
660 +your IMAP mailbox ready to go.
661 </p>
662
663 -<pre caption="Adding SMTP support">
664 -$ <i>nano -w .muttrc</i>
665 -set sendmail="/usr/bin/nbsmtp -d isp.net -h smtp.isp.net -f urname@×××.net"
666 -</pre>
667 -
668 <p>
669 -You are now ready to send a message. So in the Mutt pager or index hit the
670 -<c>m</c> key to compose a test message to send to your e-mail address. Mutt
671 -will use the value of the EDITOR or VISUAL for the composition editor unless
672 -you set <c>editor=</c> in the <path>.muttrc</path>. When you are done composing
673 -hit <c>y</c> to send your message. If there are no errors you will see 'sending
674 -mail' followed by 'Mail sent.'
675 +Navigation is intuitive, as is reading messages by just pressing the enter key
676 +or space bar. Mutt is quite Vim alike in that it uses key strokes to perform
677 +most of its actions. You best read Mutt's manual on the web to get yourself
678 +known with all existing functions (or press ? in Mutt) and what key they are
679 +bound to, or better, what key you like it to be bound to. Some essential keys
680 +are <c>m</c> (for message) to start composing a new message, <c>q</c> for quit,
681 +<c>r</c> for reply, <c>s</c> for save and <c>p</c> for print.
682 </p>
683
684 <p>
685 -Remember in <path>.muttrc</path> we have set where to save sent mail with
686 -<c>set record="$HOME/MuttMail/sent"</c>
687 +One of the features that Mutt has that is still not in today's most savvy email
688 +clients is the ability to display attachments inline through some viewer. The
689 +auto_view directive in the .muttrc file tells Mutt which attachments (based on
690 +their MIME-type) it should view inline. To figure out how to do that, Mutt uses
691 +mailcap files to lookup how to display a certain MIME-type. Usually the system
692 +wide mailcap file isn't sufficient here, so you better start a
693 +<path>~/.mailcap</path> file to put items in there for <c>copiousoutput</c> that
694 +Mutt can display inline.
695 </p>
696
697 <p>
698 -Now to complete the test, run fetchmail again to get all your mail and verify
699 -you have received the message you sent to your e-mail address. When you find
700 -your test message, hit the <c>h</c> key to toggle a view of all the headers and
701 -see the complete mail transfer path.
702 +In the example <path>.muttrc</path> above <c>auto_view</c> is enabled for
703 +<c>application/msword</c> and <c>application/pdf</c> files. These two show
704 +the extreme usefulness of this capability, because it means meeting notes sent
705 +as doc file now are perfectly fine readable without having to save the
706 +attachment and open it in OpenOffice. Instead the text just shows up in the
707 +message reader, that is, if you have a matching entry in your
708 +<path>~/.mailcap</path> file.
709 </p>
710
711 -<note>
712 -There is one more program you probably want to add called urlview. This
713 -extracts the urls in message texts and sends them to your browser.
714 -</note>
715 -
716 -<pre caption="Getting urlview">
717 -# <i>emerge urlview</i>
718 +<pre caption="Example .mailcap file">
719 +application/msword; antiword '%s'; copiousoutput; description=Word Document;
720 +nametemplate=%s.doc
721 +application/pdf; pdftotext '%s' -; copiousoutput; description=PDF Document;
722 +nametemplate=%s.pdf
723 </pre>
724
725 <p>
726 -Then create <path>~/.urlview</path> by copying the configuration file from
727 -<path>/usr/share/doc/urlview*/</path> and setting your browser command.
728 -</p>
729 -
730 -<p>
731 -You now have a powerful and highly customizable mail system. To take advantage
732 -of its flexibility, read all the manuals and docs and find the many user
733 -configuration files available on the web: search for <path>procmailrc</path> and
734 -<path>muttrc</path>.
735 +The above <path>.mailcap</path> example tells mutt what to do to "view"
736 +<c>msword</c> and <c>pdf</c> files. For the former it should run a program
737 +called <c>antiword</c> (emerge <c>app-text/antiword</c>), for the latter the
738 +program <c>pdftotext</c> (emerge <c>app-text/poppler</c>). You can go wild with
739 +these to for example display rendered HTML (give <c>app-text/vilistextum</c> a
740 +try), render vcards, or show ASCII representation of attached images. All you
741 +need to do is define how to call the program in your <path>.mailcap</path>, and
742 +tell Mutt to try to view it inline using the <c>auto_view</c> directive.
743 </p>
744
745 </body>
746 @@ -506,86 +315,21 @@
747 </chapter>
748
749 <chapter>
750 -<title>Authenticated SMTP</title>
751 +<title>Conclusions</title>
752 <section>
753 -<title>Using nbSMTP</title>
754 <body>
755
756 <p>
757 -If you need to pass a username and password to your SMTP server, you can edit
758 -the <c>set sendmail</c> command in your <path>.muttrc</path> to include <c>-U
759 -&lt;username&gt; -P &lt;password&gt;</c>, like this:
760 -</p>
761 -
762 -<pre caption="Setting username and password for SMTP">
763 -set sendmail="/usr/bin/nbsmtp -U <i>username</i> -P <i>password</i> -d isp.net -h smtp.isp.net -f urname@×××.net"
764 -</pre>
765 -
766 -<p>
767 -If you do not want this information to be present in your <path>.muttrc</path>
768 -file, you can also create a <path>.nbsmtprc</path> file in which you include all
769 -information:
770 -</p>
771 -
772 -<pre caption="~/.nbsmtprc example">
773 -auth_user = <i>username</i>
774 -auth_pass = <i>password</i>
775 -</pre>
776 -
777 -</body>
778 -</section>
779 -<section>
780 -<title>Alternative: Using msmtp</title>
781 -<body>
782 -
783 -<p>
784 -<c>msmtp</c> is a simple alternative to <c>nbsmtp</c> with similar
785 -possibilities.
786 -</p>
787 -
788 -<pre caption="Installing msmtp">
789 -# <i>emerge msmtp</i>
790 -</pre>
791 -
792 -<p>
793 -Now login as a normal user and configure msmtp by creating a
794 -<path>~/.msmtprc</path> file, filling in your SMTP server's information.
795 -Remember to set the permissions to a secure value!
796 -</p>
797 -
798 -<pre caption="Configuring msmtp">
799 -$ <i>nano -w .msmtprc</i>
800 -account default
801 -host <i>smtp.your_provider.net</i>
802 -from <i>your_username@×××××××××.net</i>
803 -<comment>#see man page for more auth options</comment>
804 -auth login
805 -user <i>your_username</i>
806 -password <i>your_password</i>
807 -<comment>#If your SMTP Server supports TLS encryption, uncomment the next line
808 -#tls</comment>
809 -</pre>
810 -
811 -<p>
812 -Now set the permissions of the file to a secure value:
813 -</p>
814 -
815 -<pre caption="Setting the permissions for the configuration file">
816 -$ <i>chmod 600 .msmtprc</i>
817 -</pre>
818 -
819 -<p>
820 -Finally, edit or add the following line to <path>.muttrc</path>
821 -</p>
822 -
823 -<pre caption="Using msmtp with Mutt">
824 -$ <i>nano -w .muttrc</i>
825 -set sendmail="/usr/bin/msmtp"
826 -</pre>
827 -
828 -<p>
829 -Fire up <c>mutt</c> and send yourself a test email to see if it worked! See
830 -the msmtp man page for more options and another example.
831 +Mutt is a very versatile console email client. If you like the concept, Mutt
832 +can be altered to behave in nearly any way through its configuration. Search
833 +the web to find others explaining how they did "it", or find one of the many
834 +patches that exist to make Mutt do even more. Gentoo applies a couple of very
835 +popular patches to Mutt, so make sure to check <c>mutt -v</c> if you want
836 +something more to make sure it is not yet already at your disposal. While
837 +learning Mutt is not necessarily easy, once it is in your fingers, it can make
838 +your mail experience much faster and efficient than with other clients.
839 +Searching for example is quite powerful if you know how to hit the right flags
840 +and know which regular expression narrows your search down. Enjoy Mutting!
841 </p>
842
843 </body>