Just got off my butt and made a few changes ... and wrote most of the first
chapter (building and installing mutt).
Kai: I've taken most of your imap howto (that is, the ./configure ... make
install part <g>) and moved it to the building mutt section, where it belongs.
No sense repeating all of that every time we have to describe how to build mutt
with some option or the other. Also cleaned up some typos / grammar errors
throughout.
See attached - and we'll discuss the content on the list before commiting it
(mrinal, can you take care of it?)
That's better for two reasons - far more content will be generated this way
rather than when people have to cvs everything off the server, and also, the
discussions will be archived on sourceforge for others to see.
Mutt Users List: If y'all don't have any hassles, the mutt-newbie docs (a small
sgml file) will be posted to the mutt-users list once in a while (whenever some
significant release is out) for comment. The current bit is just an intro and
two chapters ... we'd welcome howtos (and suggestions) - please join the
mutt-newbie list at http://mutt-newbie.sourceforge.net if you would like to
contribute.
FYI, the current maintainers of this site are Kai Blin, Mrinal Kalakrishnan and
me (Telsa Gwynne, Bruno Postle and a few others are also on the list ...)
--
Suresh Ramasubramanian + Wallopus Malletus Indigenensis
mallet @ cluestick.org + Lumber Cartel of India, tinlcI
No man is an island, but some of us are long peninsulas.
<!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book id="mutt-newbie" >
<bookinfo>
<title>The Mutt Newbie Guide</title>
<authorgroup>
<author>
<firstname>Suresh</firstname>
<surname>Ramasubramanian</surname>
</author>
<author>
<firstname>Sven</firstname>
<surname>Guckes</surname>
</author>
<author>
<firstname>Mrinal</firstname>
<surname>Kalakrishnan</surname>
</author>
<author>
<firstname>Kai</firstname>
<surname>Blin</surname>
</author>
</authorgroup>
</bookinfo>
<toc></toc>
<chapter id="intro">
<title>Introduction</title>
<blockquote>
<attribution>Michael Elkins</attribution>
<para>All mail clients suck. This one just sucks less.</para>
</blockquote>
<para>
Mutt is a mail program. Actually, it is a mixture of mail
programs, taking only the best features of several mail programs
- elm, pine, and others. It's mixture makes it a <quote>mongrel
of mailers</quote>, hence it's name - <quote>mutt</quote>.
</para>
<para>
The original author of Mutt was Michael Elkins.
</para>
<para>
Mutt has much more features than Microsoft Outlook Express and
other such 'doze brokenware, and streets ahead of (say) PINE,
because
</para>
<simplelist type="vert">
<member>It sucks less (so says Michael Elkins)</member>
<member>It rocks (so say all of us)</member>
<member>Vi is the default editor</member>
<member><link linkend="imap">It sports IMAP support</link></member>
<member><ulink url="http://www.mutt.org/#features">Has lots of other
cool features</ulink></member>
</simplelist>
<sect1 id="upandrunning">
<title>Get up and running with Mutt</title>
<para>
Mutt will work out of the box, but there are a few things
which may have to be tweaked. For example, you might want to
get your mail via POP from within Mutt - then you need to
install it such that it contains the code for POP support.
Other installation options add code for colored text, use of
Gnu regular expressions, and protocols such as GSS, IMAP, PGP,
SSL. However, quite a lot of these tweaks will be to your
"muttrc" - the user's configuration file (usually
$HOME/.muttrc).
</para>
</sect1>
</chapter>
<chapter id="installation">
<title>Getting, compiling and installing mutt</title>
<section id="gettingmutt">
<title>Downloading mutt packages / source code</title>
<para>
Most distributions of Unix (and especially Linux / BSD) come bundled with
readymade mutt packages (RPMs in the case of RedHat / SuSE etc, .debs in
Debian etc). You can just install this readymade package (read your
distribution's manual on how to do this) and skip the rest of this section.
</para>
<para>
Alternatively, you can download the latest version of mutt and compile it,
customizing it to your tastes and needs. Just go right on to ftp.mutt.org
(or one of the download mirrors listed at <ulink
url="http://www.mutt.org/download.html">the mutt download page</ulink>.
</para>
<para>
First, you have to get the Mutt sourcecode from the <ulink
url="http://www.mutt.org">Mutt Homepage</ulink>. There go to downloads. You
should get the latest version - that is, the one with the highest number,
e.g. 1.2.5. The higher the number the better.
</para>
</section>
<section id="compilingmutt">
<title>Compiling Mutt from the sources</title>
<para>
It is actually quite easy to compile and install mutt from the sources -
as the GNU configure based compile / install routine works flawlessly -
and also allows you to customize the configuration as you need.
</para>
<para>
After downloading, you should move it into a temporary directory and
untar and unzip it. You do this by typing
</para>
<cmdsynopsis>
<command>
tar -xvzf mutt-x.y.z.tar.gz
</command>
</cmdsynopsis>
<para>
at the command prompt. Then change into the newly created
directory and read the <emphasis>README</emphasis> and
<emphasis>INSTALL</emphasis> files carefully. You can
configure Mutt with the default options enabled by typing
</para>
<cmdsynopsis>
<command>
./configure
</command>
</cmdsynopsis>
<para>
That should work for most people. If your system requires it, or if
you need some advanced feature, you can add additional options such as
the <emphasis> --[feature-name]</emphasis> option with which we will be
dealing later.
</para>
<para>
After the ./configure, type
</para>
<cmdsynopsis>
<command>
make keymap_defs
</command>
</cmdsynopsis>
<para>
This will configure your keyboard mappings for use with mutt. Then you
can go on as usual, doing a
</para>
<cmdsynopsis>
<command>
make
</command>
</cmdsynopsis>
<para>
in order to generate a 'makefile'. To build mutt with the options you
selected (or the default options), become root, either by doing a
</para>
<cmdsynopsis>
<command>
su root
</command>
</cmdsynopsis>
<para>
(or logout of your session and login as root). To install Mutt, type
</para>
<cmdsynopsis>
<command>
make install
</command>
</cmdsynopsis>
<para>
Congratulations - you have just compiled mutt. Sit back and have a
beer (or a coke, if you wish) ;)
</para>
</section>
</chapter>
<chapter id="basics">
<title>Basic usage</title>
</chapter>
<chapter id="configuration">
<title>Configuration</title>
</chapter>
<chapter id="advanced">
<title>Advanced usage</title>
</chapter>
<chapter id="imap">
<title>Mutt and IMAP</title>
<para>
One of the useful features Mutt includes is IMAP support.
This chapter concentrates on
</para>
<simplelist type="vert">
<member>How to build Mutt with IMAP and/or SSL support</member>
<member>What to add to your .muttrc file for IMAP</member>
<member>Using IMAP/SSL to read your mailbox</member>
</simplelist>
<section id="muttwithimap">
<title>Building Mutt with IMAP</title>
<para>
To use IMAP, your version of Mutt must be compiled with the
IMAP option enabled. To check whether you have an IMAP enabled
version, type
</para>
<cmdsynopsis>
<command>
mutt -v
</command>
</cmdsynopsis>
<para>
Then look for the text <emphasis>+USE_IMAP</emphasis>. If you
see this, your version is already IMAP-enabled and you can
skip to <link linkend="imapinmuttrc">section 2</link>.
If it shows -USE_IMAP, please read on.
</para>
<para>
Download a copy of the mutt source code, as described above, and untar
it into a directory. Then, specify that you want Mutt with imap
enabled. Instead of just ./configure, type
</para>
<cmdsynopsis>
<command>
./configure --enable-imap
</command>
</cmdsynopsis>
<para>
Of course you can add additional options such as the
<emphasis> --with-ssl</emphasis> option with which we will be
dealing later.
</para>
<para>
Then do a make keymap_defs and make install to install your new, IMAP
capable build of Mutt.
</para>
</section>
<section id="imapinmuttrc">
<title>Additions to muttrc</title>
<para>
To use Mutt with IMAP, you'll have to change some of the
settings in your .muttrc file.
</para>
<para>
Let's assume the name of the IMAP server is imap.example.com
for the following example entries. Let's also assume the
username is fred and he has the mailboxes inbox (this one is
default), important and private.
</para>
<simplelist type="vert">
<member>set spoolfile={imap.example.com}</member>
<member>mailboxes {imap.example.com}inbox {imap.example.com}important
{imap.example.com}private</member>
<member>set imap_user = fred</member>
<member>set imap_checkinterval = 120</member>
<member>You don't want to use the set imap_pass variable!!</member>
</simplelist>
</section>
<section id="muttssl">
<title>Using the secure IMAP/SSL connection</title>
<para>
If you want to be on the safe side, Mutt also has a SSL (Secure Socket
Layer) support. This section describes how to compile Mutt with it and
how to use it.
</para>
<para>
In essence its like before when enabeling IMAP support. Just proceed as
before, until you reach the part where you come to the <emphasis>
./configure</emphasis> part. There you should type
</para>
<cmdsynopsis>
<command>
./configure --enable-imap --with-ssl
</command>
</cmdsynopsis>
<para>
Now you can proceed as before. Your next change will be something in
your .muttrc, and then, you're finished and have a secure e mail
client. Keep tight.
</para>
<para>
<literallayout>
In your .muttrc add the following: set certificate_file =
~/.mutt_certificate Also, you'll have to change you mailbox names. So,
given the previous example, change it from {imap.example.com}inbox to
<emphasis>{imap.example.com/ssl}inbox</emphasis> Repeat this for all
your mailboxes. Thats it.
</literallayout>
</para>
<para>
On your first connection to a server with ssl-encryption mutt will ask
you whether it should (<emphasis>r</emphasis>)eject, accept the
certificate (<emphasis>o</emphasis>)nce or
(<emphasis>a</emphasis>)lways accept the certificate. If you are sure
that it is a valid certificate, type <emphasis>a</emphasis>.
</para>
<para>
The certificate is saved to the $certificate_file so you'll se this
question only once.
</para>
</section>
</chapter>
<chapter id="troubleshooting">
<title>Troubleshooting</title>
</chapter>
<chapter id="resources">
<title>Resources</title>
</chapter>
<chapter id="tips">
<title>Tips and Tricks</title>
</chapter>
</book>
