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