libetpan/doc

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