source: networking/mailnews/mutt.xml@ 67cd226

<?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 "https://bitbucket.org/mutt/mutt/downloads/mutt-&mutt-version;.tar.gz">
  <!ENTITY mutt-download-ftp  "ftp://ftp.mutt.org/pub/mutt/mutt-&mutt-version;.tar.gz">
  <!ENTITY mutt-md5sum        "fd3355084e48a97e14980d18c268cd14">
  <!ENTITY mutt-size          "5.3 MB">
  <!ENTITY mutt-buildsize     "47 MB">
  <!ENTITY mutt-time          "0.4 SBU">
]>

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

  <sect1info>
    <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>

    &lfs112_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;-memleak-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>-->

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

    <bridgehead renderas="sect4">Recommended (for a text version of the manual)</bridgehead>
    <para role="recommended">
      <xref linkend="lynx"/>, or
      <xref linkend="Links"/> (or
      <ulink url="&w3m-url;">W3m</ulink>, or
      <ulink url="&elinks-url;">ELinks</ulink>) - please read the Note.
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="aspell"/>,
      <xref linkend="cyrus-sasl"/>,
      <xref linkend="docbook-utils"/>,
      <xref linkend="gdb"/>,
      <xref linkend="gnupg2"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="gpgme"/>,
      <xref linkend="libidn"/>,
      <xref linkend="mitkrb"/>,
      an <xref linkend="server-mail"/> (that provides a <command>sendmail</command> command),
      <xref linkend="slang"/>,
      <xref linkend="sqlite"/>,
      <ulink url="http://www.citi.umich.edu/projects/nfsv4/linux/">libgssapi</ulink>,
      <ulink url="http://mixmaster.sourceforge.net/">Mixmaster</ulink>,
      <!-- from configure: \-\-with-bdb[=DIR] Use BerkeleyDB4 if gdbm is not
      available but gdbm is installed in LFS, so do not mention BerkeleyDB
      <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 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>

    <note>
      <para>
        <application>Mutt</application> ships with an HTML version of its
        manual, but the text version is no longer provided because differences
        in the formatting from different text browsers compared to the shipped
        version caused complaints. To get a text file, the following are used
        in order of preference: <application>lynx</application> with overstriking
        (backspaces) for emphasis, <application>w3m</application> or
        <application>elinks</application>: the latter two apparently provide
        plain text. Plain text is generally preferred unless reading the HTML
        manual, so the instructions below use <application>lynx</application>
        if available, or else <application>links</application> to produce plain
        text.
      </para>
    </note>

    <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>
      Install <application>Mutt</application> by running the following
      commands:
    </para>

<!--<para>
      First apply the patch to prevent a memory leak:
    </para>

<screen><userinput>patch -Np1 -i ../mutt-&mutt-version;-memleak-1.patch</userinput></screen>-->

    <para>
      To ensure that a plain text manual is created when using
      <application>lynx</application> or to otherwise use
      <application>links</application> to produce it (instead of
      <application>elinks</application>), run the following command:
    </para>

<screen><userinput>sed  -e 's/ -with_backspaces//' \
     -e 's/elinks/links/'       \
     -e 's/-no-numbering -no-references//' \
     -i doc/Makefile.in</userinput></screen>

    <para>
      Now configure and build the application:
    </para>

<screen><userinput>./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</userinput></screen>

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

<screen remap="doc"><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</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' remap='doc'><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 management 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>

      <para>
        An info file is now installed, so you will also need to recreate the
        <filename>/usr/share/info/dir</filename> as described when
        <application>Texinfo</application> was installed in LFS.
      </para>
    </note>


  </sect2>

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

    <para>
      <parameter>sed ... -e 's/ -with_backspaces//' ...</parameter>: This turns
      off the backspaces used for overstriking when <application>lynx</application>
      is used, resulting in readable plain text when using <command>view</command>.
    </para>

    <para>
      <parameter>sed ... -e 's/elinks/links/' ...</parameter>: This allows
      <command>links</command> to be run instead of <command>elinks</command>
      which is not in the book.
    </para>

    <para>
      <parameter>sed ... -e 's/-no-numbering -no-references//' ...</parameter>:
      This removes switches which are not understood by <command>links</command>.
    </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-autocrypt --with-sqlite3</option>: These two
      switches add support for passive protection against data collection,
      using gnupg and gpgme (gpgme is enabled by autocrypt). See <ulink
      url="http://www.mutt.org/doc/manual/#autocryptdoc">The Manual</ulink>.
    </para>

    <para>
      <option>--enable-gpgme</option>: This switch enables GPG support
      through the GPGME package. Use this switch if you want GPG support in
      Mutt.
    </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> -->

  </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>, and
        <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, mutt_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="mutt_pgpring">
        <term><command>pgpring</command></term>
        <listitem>
          <para>
            is a key ring dumper for
            <ulink url="http://www.openpgp.org/about/">PGP</ulink>. It is not
            needed for <xref linkend="gnupg2"/>
          </para>
          <indexterm zone="mutt mutt_pgpring">
            <primary sortas="b-mutt_pgpring">mutt_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>