source: networking/mailnews/mutt.xml@ cd3335ad

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY mutt-download-http "http://ftp.mutt.org/pub/mutt/mutt-&mutt-version;.tar.gz">
  <!ENTITY mutt-download-ftp  "ftp://ftp.mutt.org/pub/mutt/mutt-&mutt-version;.tar.gz">
  <!ENTITY mutt-md5sum        "f1564f81ed5f8bacb7e041edc71d5347">
  <!ENTITY mutt-size          "4.1 MB">
  <!ENTITY mutt-buildsize     "42 MB (plus a further 6MB for the PDF manual)">
  <!ENTITY mutt-time          "0.3 SBU (plus a further 0.2 SBU to build the PDF manual)">
]>

<sect1 id="mutt" xreflabel="Mutt-&mutt-version;">
  <?dbhtml filename="mutt.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Mutt-&mutt-version;</title>

  <indexterm zone="mutt">
    <primary sortas="a-mutt">mutt</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Mutt</title>

    <para>The <application>Mutt</application> package contains a Mail User
    Agent. This is useful for reading, writing, replying to, saving, and
    deleting your email.</para>

    &lfs83_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Download (HTTP): <ulink url="&mutt-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&mutt-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &mutt-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &mutt-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &mutt-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &mutt-time;</para>
      </listitem>
    </itemizedlist>

    <!--<bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Required patch: <ulink
        url="&patch-root;/mutt-&mutt-version;-upstream_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>-->

    <bridgehead renderas="sect3">Mutt Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="aspell"/>,
      <xref linkend="cyrus-sasl"/>,
      <xref linkend="gdb"/>,
      <xref linkend="gnupg2"/>,
      <xref linkend="gpgme"/>,
      <ulink url="http://www.citi.umich.edu/projects/nfsv4/linux/">libgssapi</ulink>,
      <xref linkend="libidn"/>,
      <xref linkend="mitkrb"/>,
      <ulink url="http://mixmaster.sourceforge.net/">Mixmaster</ulink>,
      an <xref linkend="server-mail"/> (that provides a <command>sendmail</command> command),
      <xref linkend="slang"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="db"/> or
      <ulink url="http://fallabs.com/qdbm/">QDBM</ulink> or
      <ulink url="http://fallabs.com/tokyocabinet/">Tokyo Cabinet</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (To Regenerate HTML
    Documentation)</bridgehead>
    <para role="optional">
      <xref linkend="libxslt"/> and either
      <xref linkend="lynx"/>,
      <xref linkend="w3m"/>, or
      <ulink url="http://elinks.or.cz/">ELinks</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (To Generate PDF Manual)</bridgehead>
    <para role="optional">
      <xref linkend="docbook-dsssl"/>,
      <xref linkend="openjade"/>, and
      <xref linkend="texlive"/> (or <xref linkend="tl-installer"/> with
      <command>pdfjadetex</command> installed)
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/mutt"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Mutt</title>

    <para><application>Mutt</application> requires a group named
    <systemitem class="groupname">mail</systemitem>.  You can
    add this group, if it does not exist, with this command:</para>

<screen role="root"><userinput>groupadd -g 34 mail</userinput></screen>

    <para>If you did not install an <xref linkend="server-mail"/>, you need to
    modify the ownership of <filename class="directory">/var/mail</filename>
    with this command:</para>

<screen role="root"><userinput>chgrp -v mail /var/mail</userinput></screen>

    <para><application>Mutt</application> will rebuild the html documentation
    if <application>libxslt</application> is present, then use that to update
    the text manual - even if none of the specified browsers are present. That
    will create an empty text file, so we will save the shipped file.
    </para>

    <para>If you intend to create the PDF version of the manual, apply the
    following sed:</para>

<screen><userinput>sed -i 's/\(pdfjadetex manual.tex;\)/\1 \1 \1/' doc/Makefile.in</userinput></screen>

    <para>Install <application>Mutt</application> by running the following
    commands:</para>

<screen><userinput>cp -v doc/manual.txt{,.shipped} &amp;&amp;
./configure --prefix=/usr                           \
            --sysconfdir=/etc                       \
            --with-docdir=/usr/share/doc/mutt-&mutt-version; \
            --with-ssl                              \
            --enable-external-dotlock               \
            --enable-pop                            \
            --enable-imap                           \
            --enable-hcache                         \
            --enable-sidebar                        &amp;&amp;
make &amp;&amp;</userinput></screen>

    <para>To generate the PDF manual with <xref linkend="texlive"/>, run
    the following command:</para>

<screen><userinput>make -C doc manual.pdf</userinput></screen>

    <para>This package does not come with a test suite.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

    <screen role='root'><userinput>make install &amp;&amp;
test -s doc/manual.txt ||
  install -v -m644 doc/manual.txt.shipped \
  /usr/share/doc/mutt-&mutt-version;/manual.txt</userinput></screen>

    <para>If you generated the PDF manual, install it
    by issuing the following command as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role='root'><userinput>install -v -m644 doc/manual.pdf \
    /usr/share/doc/mutt-&mutt-version;</userinput></screen>

    <note>
      <para>
        If you used a DESTDIR method to only install to a temporary location as
        a regular user (as part of a package menagement process), you will need
        to run the following as the <systemitem class="username">root</systemitem>
        user after completing the real install:
      </para>

<screen role="nodump"><userinput>chown root:mail /usr/bin/mutt_dotlock &amp;&amp;
chmod -v 2755 /usr/bin/mutt_dotlock</userinput></screen>
    </note>


  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>sed -i 's/\(pdfjadetex manual.tex;\)/\1 \1 \1/'
    doc/Makefile.in</parameter>: TeX engines sometimes need to be run
    multiple times to fix up references. In this case the engine
    has to run three times to fix page references in the Table of Contents
    and the List of Tables.</para>

    <para><parameter>--enable-external-dotlock</parameter>: In some circumstances
    the mutt-dotlock program is not created. This switch ensures it is always
    created.</para>

    <para><parameter>--enable-pop</parameter>: This switch enables
    POP3 support.</para>

    <para><parameter>--enable-imap</parameter>: This switch enables
    IMAP support.</para>

    <para><parameter>--enable-hcache</parameter>: This switch enables
    header caching.</para>

    <para><parameter>--enable-sidebar</parameter>: This switch enables support
    for the sidebar (a list of mailboxes). It is off by default, but can be
    turned on by <command>:set sidebar_visible</command> in mutt (and off again
    with ':unset'), or it can be enabled in  <filename>~/.muttrc</filename>.</para>

    <para><parameter>--with-ssl</parameter>: This parameter adds SSL/TLS
    support from openssl in POP3/IMAP/SMTP.</para>

    <para><option>--enable-smtp</option>: This switch enables
    SMTP relay support.</para>

    <para><option>--with-idn2</option>: Use this parameter if both libidn and
    libidn2 have been installed, and you wish to use libidn2 here.</para>

    <para><option>--with-sasl</option>: This parameter adds
    authentication support from <xref linkend="cyrus-sasl"/> in POP3/IMAP/SMTP
    if they are enabled. Depending on the server configuration, this may not
    be needed for POP3 or IMAP. However, it is needed for SMTP
    authentication.</para>

    <!-- we do not normally list all possible switches. LFS installs ncurses.
    <para><option>\-\-with-slang</option>: Use <application>S-Lang
    </application> instead of <application>Ncurses</application>.</para> -->

    <para><command>test -s doc/manual.txt || install -v -m644 doc/manual.txt.shipped ...</command>:
    if the text manual is now empty (<application>libxslt</application> is
    installed, but without any of the specified text browsers), install the
    saved copy <emphasis>after</emphasis> running 'make install'
    <emphasis>(which would itself empty manual.txt if the shipped file had
    already been copied back)</emphasis>.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Mutt</title>

    <sect3 id="mutt-config">
      <title>Config Files</title>

      <para><filename>/etc/Muttrc</filename>, <filename>~/.muttrc</filename>,
      <filename>/etc/mime.types</filename>, <filename>~/.mime.types</filename></para>

      <indexterm zone="mutt mutt-config">
        <primary sortas="e-etc-Muttrc">/etc/Muttrc</primary>
      </indexterm>

      <indexterm zone="mutt mutt-config">
        <primary sortas="e-AA.muttrc">~/.muttrc</primary>
      </indexterm>

      <indexterm zone="mutt mutt-config">
        <primary sortas="e-etc-mime.types">/etc/mime.types</primary>
      </indexterm>

      <indexterm zone="mutt mutt-config">
        <primary sortas="e-AA.mime.types">~/.mime.types</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>No changes in these files are necessary to begin using
      <application>Mutt</application>.  When you are ready to make changes, the
      man page for <filename>muttrc</filename> is a good starting place.</para>

      <para>In order to utilize <application>GnuPG</application>, use the following
      command:</para>

<screen><userinput>cat /usr/share/doc/mutt-&mutt-version;/samples/gpg.rc &gt;&gt; ~/.muttrc</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>flea, mutt, mutt_dotlock, muttbug, pgpewrap, pgpring, and
        smime_keys</seg>
        <seg>None</seg>
        <seg>/usr/share/doc/mutt-&mutt-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="flea">
        <term><command>flea</command></term>
        <listitem>
          <para>is a script showing where to report bugs.</para>
          <indexterm zone="mutt flea">
            <primary sortas="b-flea">flea</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mutt-prog">
        <term><command>mutt</command></term>
        <listitem>
          <para>is a Mail User Agent (MUA) which enables you to read, write
          and delete your email.</para>
          <indexterm zone="mutt mutt-prog">
            <primary sortas="b-mutt">mutt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mutt_dotlock">
        <term><command>mutt_dotlock</command></term>
        <listitem>
          <para>implements the mail spool file lock.</para>
          <indexterm zone="mutt mutt_dotlock">
            <primary sortas="b-mutt_dotlock">mutt_dotlock</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="muttbug">
        <term><command>muttbug</command></term>
        <listitem>
                <para>is a script identical to <command>flea</command>.</para>
          <indexterm zone="mutt muttbug">
            <primary sortas="b-muttbug">muttbug</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pgpewrap">
        <term><command>pgpewrap</command></term>
        <listitem>
          <para>prepares a command line for the <xref linkend="gnupg2"/>
          utilities.</para>
          <indexterm zone="mutt pgpewrap">
            <primary sortas="b-pgpewrap">pgpewrap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pgpring">
        <term><command>pgpring</command></term>
        <listitem>
          <para>is a key ring dumper for <ulink
          url="http://www.pgp.com/">PGP</ulink>. It is not needed for
          <xref linkend="gnupg2"/>.</para>
          <indexterm zone="mutt pgpring">
            <primary sortas="b-pgpring">pgpring</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="smime_keys">
        <term><command>smime_keys</command></term>
        <listitem>
          <para>manages a keystore for S/MIME certificates.</para>
          <indexterm zone="mutt smime_keys">
            <primary sortas="b-smime_keys">smime_keys</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>