This bug is mainly to remind me that I probably need to write up about what changed in Mutt these days to make the existing doc (which is linked from the ebuild) a bit outdated. - Mutt has smtp support built in these days, hence no need for an external MTA (drop lengthy SMTP sections) - I think the doc should describe IMAP, which Mutt can read without any help of other tools either - fetchmail/procmail setup probably should be an alternative route - should enable header cache, set it to a dir for performance - probably slim down the example .muttrc and link to some examples on the web
By all means; improvements are greatly welcomed! Doesn't have to be GuideXML patches; you can just put it in plain text so that we can get it into the guide ASAP. Thankya very much!
This is the work I got sofar. It's not finished, but I just post it to assure it won't get lost. 1. The Mutt e-mail client If you're not a fan of e-mail clients with fancy graphical user interfaces, or you just like to be able to quickly read some mail over an SSH connection, the class of console-based mail clients might be for you. Mutt is one of the current console-based mail clients that's still under active development and has a vast crowd of active supporters (and users). It is powerful, highly customisable, small and efficient. While Mutt was originally designed to read mail from the local mbox mail spool (e.g. /var/spool/mail/), nowadays it comes with full support for Maildir stored folders, remote fetching from POP3 servers and complete management of IMAP accounts. For a full description of what Mutt can do, please read the Mutt manual and Mutt website at http://www.mutt.org/. 2. Acquiring Mutt Starting your Mutt adventure simply requires you to emerge it. (How else) Unfortunately, Mutt has a lots of options, which enable or disable certain functionalities of Mutt. We now briefly discuss the most important USE-flags that you may want to enable based on your intended usage of Mutt. Please note that enabling most of them won't harm your Mutt, but may make it do more than an experienced Mutt user would like. Code Listing 1.1: Mutt's USE-flags % emerge -pv mutt [ebuild N ] mail-client/mutt-1.5.20-r17 USE="gdbm gpg imap mbox nls nntp sidebar smime smtp ssl -berkdb -crypt -debug -doc -gnutls -idn -pop -qdbm -sasl -tokyocabinet" First off, for newcomers, the imap USE-flag is most probably the most important one. Enabling it won't hurt anything, so if you're unsure what account you're going to use Mutt with, just enable it. Most email providers, even free ones such as GMail, use IMAP these days, for it is the most convenient way to store email that is accessed from multiple clients at the same time. Because IMAP keeps all mail at the server, Mutt just downloads the messages that you want to view. Often you happen to jump through a couple of messages a couple of times shortly after each other, which would require to download the same message over and over again. Since this simply is a waste, Mutt uses a so-called header cache (hcache) to keep the most important bits of messages that it needs to show them in a list. This hcache is backed by a db-library, of which four flavours exist: gdbm, berkdb, qdbm and tokyocabinet. If you don't have any preference yourself, pick gdbm or berkdb. Most likely you will have both already installed on your system. Enabling the USE-flags for more than one hcache backend will make Mutt choose one it likes best. It will always use at most one. While IMAP is important for reading mail, sending mail requires a mail server. Mutt can talk to a mail server that exists on the local system, but often that's not the case, or simply not a good solution for e.g. laptop users that often travel around. Mutt comes with SMTP support, that's enabled by the smtp USE-flag. Again, enabling it if you're not sure doesn't harm. Mutt's SMTP support allows you just to send mail over a mail server of your choice; usually the one that you are given by your email provider. Both IMAP and SMTP mostly go over encrypted channels these days, hence if you enabled any of both, it is wise to also enable either of the ssl or gnutls USE-flags. Both just add the secure variants (imaps and smtps) to Mutt's list of supported protocols using either OpenSSL's or GNUTLS' implementation. If you don't have a strong preference for either, just go for ssl. Most likely this is in your global USE already anyway. Last but not least, there is the sidebar USE-flag. It enables an extension to Mutt that can show a navigation pane of available mailboxes on the left hand side of the screen. While this is not a recommended feature for absolute newcomers (it is nowhere mentioned in any official docs, since it simply isn't official), more experienced users might like its functionality. Luckily, just enabling the USE-flag doesn't make it visible at all, meaning you don't even notice it's enabled. 3. Configuring Mutt After you emerged mutt with your USE-flags of choice, the first step is to create a .muttrc file in your home directory. Muttrc's are to be found in many places on the web and in Mutt's documentation. In /usr/share/doc/mutt-<version>/samples you can find some muttrc samples that are from the official distribution. We discuss a very minimal .muttrc for an IMAP based account with SMTP mail delivery below.
This should be the last piece (restarted 3 with some typo fixes) 3. Configuring Mutt After you emerged mutt with your USE-flags of choice, the only necessary step is to create a .muttrc file in your home directory. Muttrc's are to be found in many places on the web and in Mutt's documentation. In /usr/share/doc/mutt-<version>/samples you can find some muttrc samples that are from the official distribution. We discuss a very minimal .muttrc for an IMAP based account with SMTP mail delivery below. Code Listing 1.2: A .muttrc example file # character set on messages that we send set send_charset="utf-8" # if there is no character set given on incoming messages, it is probably windows set assumed_charset="iso-8859-1" # make sure Vim knows mutt is a mail client and that we compose an UTF-8 encoded message set editor="vim -c 'set syntax=mail ft=mail enc=utf-8'" # just scroll one line instead of full page set menu_scroll=yes # we want to see some MIME types inline, see below this code listing for explanation auto_view application/msword auto_view application/pdf # make default search pattern to search in To, Cc and Subject set simple_search="~f %s | ~C %s | ~s %s" # threading preferences set sort=threads set strict_threads=yes # show spam score (from SpamAssassin only) when reading a message spam "X-Spam-Score: ([0-9\\.]+).*" "SA: %1" set pager_format = " %C - %[%H:%M] %.20v, %s%* %?H? [%H] ?" # do not show all headers, just a few ignore * unignore From Date Subject To Cc Bcc # and in this order unhdr_order * hdr_order From: To: Cc: Bcc: Date: Subject: # brighten up stuff with colours, for more colouring examples see: # http://aperiodic.net/phil/configs/mutt/colors color normal white black color hdrdefault green default color quoted green default color quoted1 yellow default color quoted2 red default color signature cyan default color indicator brightyellow red color error brightred default color status brightwhite blue color tree brightmagenta black color tilde blue default color attachment brightyellow default color markers brightred default color message white black color search brightwhite magenta color bold brightyellow default # personality settings set realname = "Andrew Dalziel" set from = "andy@mail.server" alternates "andrew@mail.server|andrew.dalziel@mail.server" set signature = ~/.signature # aliases (sort of addressbook) source ~/.aliases # IMAP connection settings set mail_check=60 set imap_keepalive=300 # IMAP account settings set folder=imaps://andy@imap.mail.server/ set spoolfile=imaps://andy@imap.mail.server/ set record=imaps://andy@imap.mail.server/Sent set postponed=imaps://andy@imap.mail.server/Drafts # use headercache for IMAP (make sure this is a directory!) set header_cache=/var/tmp/.muttcache # mailboxes we want to monitor for new mail mailboxes "=" mailboxes "=Lists" # mailing lists we are on (these are regexps!) subscribe "gentoo-.*@gentoo\\.org" # SMTP mailing configuration (for sending mail) set smtp_url=smtp://my.mail.server/ The example .muttrc above sets up an IMAP account, uses an SMTP server to send mail, stores its cache in /var/tmp/.muttcache, reads the known address aliases (think of it as an addressbook) from ~/.aliases and appends the signature from ~/.signature when composing new mail. For some IMAP servers it may be necessary to change the spool, record and postponed directories, as the folders Sent and Drafts may be under a folder called INBOX. Simply trying this out with Mutt is the simplest way to figure this out. Once your .muttrc is setup, you are ready to launch Mutt by just running mutt. If you entered a valid IMAP server url, Mutt will prompt you for your password and afterwards load all messages for you. Note that the first time entering your mailbox may take a while if you have quite some messages, since Mutt's header cache is still empty. If this succeeds you're in your IMAP mailbox ready to go. Navigation is intuitive, as is reading messages by just pressing the enter key or space bar. Mutt is quite Vim alike in that it uses key strokes to perform most of its actions. You best read Mutt's manual on the web to get yourself known with all existing functions (or press ? in Mutt) and what key they are bound to, or better, what key you like it to be bound to. Some essential keys are m for message to start composing a new message, q for quit, r for reply, s for save and p for print. One of the features that Mutt has that is still not in today's most savvy email clients is the ability to display attachments inline through some viewer. The auto_view directive in the .muttrc file tells Mutt which attachments based on their MIME-type it should view inline. To figure out how to do that, Mutt uses mailcap files to lookup how to display a certain MIME-type. Usually the system wide mailcap file isn't sufficient here, so you better start a ~/.mailcap file to put items in there for copiousoutput that Mutt can display inline. In the example .muttrc above auto_view is enabled for application/msword and application/pdf files. These two show the extreme usefulness of this capability, because it means meeting notes sent as doc file now are perfectly fine readable without having to save the attachment and open it in OpenOffice. Instead the text just shows up in the message reader, that is, if you have a matching entry in your ~/.mailcap file. Code Listing 1.3: Example .mailcap file application/msword; antiword '%s'; copiousoutput; description=Word Document; nametemplate=%s.doc application/pdf; pdftotext '%s' -; copiousoutput; description=PDF Document; nametemplate=%s.pdf Above .mailcap example tells mutt what to do to "view" msword and pdf files. For the former it should run a program called antiword (emerge app-text/antiword), for the latter the program pdftotext (emerge app-text/poppler). You can go wild with these to for example display rendered HTML (give app-text/vilistextum a try), render vcards, or show ASCII representation of attached images. All you need to do is define how to call the program in your .mailcap, and tell Mutt to try to view it inline using the auto_view directive. 4. Conclusions Mutt is a very versatile console email client. If you like the concept, Mutt can be altered to behave in nearly any way through its configuration. Search the web to find others explaining how they did "it", or find one of the many patches that exist to make Mutt do even more. Gentoo applies a couple of very popular patches to Mutt, so make sure to check mutt -v if you want something more to make sure it is not yet already at your disposal. While learning Mutt is not necessarily easy, once it is in your fingers, it can make your mail experience much faster and efficient than with other clients. Searching for example is quite powerful if you know how to hit the right flags and know where which regular expression narrows your search down. Enjoy Mutting!
@docs-team: I decided to do a full rewrite of the guide (ignoring the formatting and stuff for the moment). The original stuff on fetchmail, procmail and bsmtp is not relevant for Mutt IMO, but perhaps it is worth saving and putting it in a separate document? What best can I do now to get the text acceptable for you to review/fix and put online?
Created attachment 249339 [details] guide-to-mutt.xml http://dev.gentoo.org/~grobian/guide-to-mutt.xml
(In reply to comment #5) > Created an attachment (id=249339) [details] > guide-to-mutt.xml > > http://dev.gentoo.org/~grobian/guide-to-mutt.xml > Hi, thanks for the update. However, I need this in a .patch/.diff format, but only after the <p> contents are untabbed. We don't use tabs in GuideXML, so a diff of the current draft would generate lots of false positives for ++ and -- changes. Once this is done, I'll have an easier time comparing it to the current version, which gets the updates committed sooner. Thanks a bunch!
Created attachment 250405 [details] guide-to-mutt.xml with tabs removed Removed the tabs from <p>
I'm sorry I didn't abide to the coding standards, I wasn't aware of any actually. Is David's version fine? I can easily replace the tabs to any spacing. But before you go about doing diffs, as said before, I ended up doing a full rewrite, so nothing of the original text is still in place, except for a fuzzy match on the first 1 or 2 lines of the introduction. So whether or not you ignore whitespace in your diff, it will be humongeous, as it is a completely different document. Thanks!
(In reply to comment #8) > I'm sorry I didn't abide to the coding standards, I wasn't aware of any > actually. Is David's version fine? I can easily replace the tabs to any > spacing. David's version fixes some of the problems, so yeah, I can do the rest. BTW, you might want to checkout both our guide on GuideXML that explains its coding standards[1], and a good sample guide for how things look[2] [1] http://www.gentoo.org/doc/en/xml-guide.xml [2] http://www.gentoo.org/doc/en/xfce-config.xml?passthru=1 > But before you go about doing diffs, as said before, I ended up doing a full > rewrite, so nothing of the original text is still in place, except for a fuzzy > match on the first 1 or 2 lines of the introduction. Ah, right, I missed the bit where you said it was a complete rewrite. I'll just do a visual side-by-side inspection and see how it goes. Thanks for your efforts; hopefully it won't take me too long to commit stuff.
Please correct any awkward sentences and incorrect/weird-sounding English. If you need anything done (e.g. reindented or something) let me know, Vim can do most tricks with a couple of keystrokes. Thanks in advance.
Very nice. Thanks for the updated document! It's simple, gives a nice introduction to mutt (without becoming a mutt document per se, that's something for the mutt project) and shows how to use it with Gentoo (i.e. focus on USE flags, patches, etc.) The document is committed in CVS and should show up in about an hour online.
Thanks, I have a small change to the section on ssl for IMAP and SMTP: original: Both IMAP and SMTP mostly go over encrypted channels these days, hence if you enabled any of both, it is wise to also enable either of the ssl or gnutls USE-flags. Both just add the secure variants (imaps and smtps) to Mutt's list of supported protocols using either OpenSSL's or GNUTLS' implementation. If you don't have a strong preference for either, just go for ssl. Most likely this is in your global USE already anyway. I'd like to add the following: If you intend to authenticate yourself when sending email, be sure to also include sasl in your USE-flags, since that's a prerequisite for that. I will update the url in the mutt ebuilds to point the official location again.
