<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">

<book id="libetpan-readme">
  <bookinfo>
    <date>2003-12-03</date>
    <title>libEtPan!</title>
    <authorgroup>
      <author>
        <firstname>Viet Hoa</firstname>
        <surname>DINH</surname>
      </author>
    </authorgroup>
    <copyright>
      <year>2003</year>
      <holder>DINH Viet Hoa</holder>
    </copyright>
  </bookinfo>
  <toc></toc>
  
  <chapter id="introduction">
    <title>Introduction</title>
    
    <!-- description -->
    <sect1 id="description">
      <title>Description</title>
      <para>
        The purpose of this mail library is to provide a portable,
        efficient middleware for different kinds of mail access
        (IMAPrev4, POP3, NNTP, mbox, MH, Maildir).
      </para>
      
      <para>
        You have two kinds of mailbox access, either using low-level
        functions with a different interface for each kind of access
        or using higher-level functions, using a driver to wrap the
        higher-level API. The API will be the same for each kind of
        mail access using the higher-level API.
      </para>
    </sect1>
    
    <!-- authors -->
    <sect1 id="author">
      <title>Author</title>
      <sect2 id="main-auth">
        <title>Main author</title>
        <para>
          DINH Viet Hoa <email>hoa@users.sourceforge.net</email>
        </para>
      </sect2>
      <sect2 id="contrib">
        <title>Contributors</title>
        <para>
          <itemizedlist>
            <listitem>
              <para>
                Wim Delvaux <!-- wim.delvaux.adaptiveplanet.com -->
              </para>
            </listitem>
            <listitem>
              <para>
                Melvin Hadasht <!-- melvin.hadasht@free.fr -->
              </para>
            </listitem>
            <listitem>
              <para>
                David Woodhouse <!-- dwmw2@infradead.org -->
              </para>
            </listitem>
            <listitem>
              <para>
                Juergen Graf <!-- libetpan@codeguy.org -->
              </para>
            </listitem>
            <listitem>
              <para>
                Zsolt VARGA <!-- redax@redax.hu -->
              </para>
            </listitem>
            <listitem>
              <para>
                Gael Roualland <!-- gael.roualland@dial.oleane.com -->
              </para>
            </listitem>
            <listitem>
              <para>
                Toni Willberg <!-- toniw@iki.fi -->
              </para>
            </listitem>
			<listitem>
			  <para>
			    Rajko Albrecht <!-- ral@alwins-world.de -->
			  </para>
			</listitem>
			<listitem>
			  <para>
			    Nikita V. Youshchenko <!-- yoush@cs.msu.su -->
			  </para>
			</listitem>
			<listitem>
			  <para>
			    Frederic Devernay <!-- Frederic.Devernay@inrialpes.fr -->
			  </para>
			</listitem>
			<listitem>
			  <para>
			    Michael Leupold <!-- leupold@leunet.de -->
			  </para>
			</listitem>
			<listitem>
			  <para>
			    Colin Leroy <!-- colin@colino.net -->
			  </para>
			</listitem>
          </itemizedlist>
        </para>
      </sect2>
    </sect1>
  </chapter>
  
  <!-- installation -->
  <chapter id="installation">
    <title>Installation</title>
    
    <sect1 id="dependencies">
      <title>Dependencies</title>
      
      <!-- dependencies for users -->
      <sect2 id="depend-users">
        <title>Dependencies for users</title>
        
        <itemizedlist>
          <listitem>
            <para>
              <ulink url="http://www.openssl.org">OpenSSL</ulink>
              (optional but recommended)
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="http://www.sleepycat.com">Berkeley
              DB</ulink> (optional but recommended)
            </para>
          </listitem>
          <listitem>
            <para>
              POSIX Thread (required)
            </para>
          </listitem>
        </itemizedlist>
      </sect2>
      <!-- dependencies for developers -->
      <sect2 id="depend-developers">
        <title>Dependencies for developers</title>
        
        <itemizedlist>
          <listitem>
            <para>
              <ulink url="http://www.gnu.org/software/autoconf">
                autoconf
              </ulink>
              2.13
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink url="http://www.gnu.org/software/automake">
                automake
              </ulink>
              1.4
            </para>
          </listitem>
          <listitem>
            <para>
              <ulink
                url="http://www.gnu.org/software/libtool/libtool.html">
                libtool
              </ulink>
              1.4.3
            </para>
          </listitem>
          <listitem>
            <para>
              jade and some SGML tools will be required
            </para>
          </listitem>
        </itemizedlist>
      </sect2>
    </sect1>
    <!-- packages -->
    <sect1 id="packages">
      <title>Existing packages</title>

      <para>
        Before you try to compile it, you have to know that packages 
        exist for some systems.
      </para>
      
      <!-- FreeBSD -->
      <sect2 id="package-freebsd">
        <title>FreeBSD</title>
        <para>
          you can find it in ports/mail/libetpan.
        </para>
      </sect2>

	  <!-- Debian -->
	  <sect2 id="package-debian">
	    <title>Debian</title>
		<para>
		  This is in the package collection.
		</para>
      </sect2>
	  
      <!-- Mandrake -->
      <sect2 id="package-mandrake">
        <title>Mandrake Linux</title>
        <para>
          This is in the package collection.
        </para>
      </sect2>
    </sect1>
    
    <!-- compilation -->
    <sect1 id="compilation">
      <title>Compilation</title>
      
      <para>
        Generic installation instructions are in the
        <filename>INSTALL</filename> file
        You can pass the following extra options to configure :
      </para>

      <!-- FreeBSD -->
      <sect2 id="compile-freebsd">
        <title>FreeBSD</title>
        <itemizedlist>
          <listitem>
            <para>
              make sure libiconv is installed from the ports collection (see
              <command>pkg_info</command>).
            </para>
          </listitem>
          <listitem>
            <para>
              issue configure with the following parameter:
              <screen>
<prompt>$</prompt> <userinput>./configure --with-libiconv-prefix=/usr/local</userinput>
              </screen>
            </para>
          </listitem>
        </itemizedlist>
      </sect2>
      
      <!-- MacOS X -->
      <sect2 id="compile-macosx">
        <title>Mac OS X</title>
        <itemizedlist>
          <listitem>
            <para>
              in tests/option-parser.c, change the inclusion
              of <filename>getopt.h</filename> to
              <filename>gnugetopt/getopt.h</filename>
            </para>
          </listitem>
          <listitem>
            <para>
              in <filename>tests/Makefile</filename>, add
              <command>-I/sw/include</command> for the
              <command>CFLAGS</command> and
                -L/sw/lib -lgnugetopt for the LDFLAGS.
            </para>
          </listitem>
        </itemizedlist>
      </sect2>

      <!-- Linux -->
      <sect2 id="linux">
        <title>Linux</title>
        <itemizedlist>
          <listitem>
            <warning>
              <para>
                Since libEtPan! is making high usage of
                <command>mmap()</command> even for
                writing, when your mailboxes are on
                <command>NFS</command> filesystem with
                a Linux server, it is advised to use option
                <command>no_subtree_check</command> in
                <filename>/etc/exports</filename>.
                This should avoid corruption of data.
              </para>
              <para>
                The problem exist in Linux 2.4.22 and earlier versions.
              </para>
            </warning>
          </listitem>
          <listitem>
            <para>
              On RedHat systems, you have to configure using the
              following command line :
              <command>./configure --with-openssl=/usr/kerberos</command>
            </para>
          </listitem>
          <listitem>
            <para>
              On Debian systems, if the <command>./autogen</command>
              script fails on missing <command>AM_ICONV</command>, you
              have to install <command>gettext</command> package.
            </para>
          </listitem>
        </itemizedlist>
      </sect2>
      
      <!-- configure -->
      <sect2 id="configure">
        <title>configure</title>
        <para>
          You can use the following options :
        </para>
        <itemizedlist>
          <listitem>
            <para>
              <command>--enable-debug</command>    Compiles with
              debugging turned on
            </para>
          </listitem>
          <listitem>
            <para>
              <command>--enable-optim</command>    Turns on some
              optimizations flags for gcc
            </para>
          </listitem>
          <listitem>
            <para>
              <command>--without-openssl</command> Disables OpenSSL (do
              not look for it)
            </para>
          </listitem>
        </itemizedlist>
      </sect2>
      <sect2 id="install">
        <title>Compile and install</title>
        <para>
          Download the package and do the following :
        </para>
        <programlisting>
$ tar xzvf libetpan-XX.XX.tar.gz      # to decompress the package

$ cd libetpan-XX.XX

$ ./configure --help                 # to get options of configure

$ ./configure                        # you can specify your own options

$ make                               # to compile the package

$ su

# make install

# logout
        </programlisting>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="use">
    <title>Use of libEtPan!</title>
    
    <sect1 id="hotmail">
      <title>How to open an Hotmail mailbox</title>
      <para>
        If you wish to access hotmail using libEtPan!, you can, by
        using <ulink url="http://hotwayd.sf.net">hotwayd</ulink>.
        Then, create a POP3 storage with the given parameters :
        command as clear text for connection type
        (<command>CONNECTION_TYPE_COMMAND</command>),
        <command>"/usr/bin/hotwayd"</command>
        as command, plain text authentication
        (<command>ePOP3_AUTH_TYPE_PLAIN</command>),
        full hotmail address as login
        (<command>foobar@hotmail.com</command> or
        <command>foobar@hotmail.com/mailbox_name</command> if you want
        to access a specific mailbox) and give your password.
      </para>
    </sect1>
  </chapter>
</book>
