etPan - new generation
----------------------

Index
-----

1. Description
1.2. Current features
1.3. Planned features
2. Authors
2.1. Main author
2.2. Contributors
3. Dependencies
3.1. External program dependencies
3.2. dependencies
4. How to start ?
4.1. Definition
4.2. Starting
4.2.1. Configure your folder tree
4.2.1.1. Virtual node
4.2.1.2. mbox
4.2.1.3. POP3
4.2.1.4. IMAP
4.2.1.5. NNTP - News
4.2.1.6. MH
4.2.1.7. maildir
4.2.1.7. Choose default folder
4.2.1.8. Choose default sent folder
4.2.1.9. Choose default draft folder
4.2.2. Configure global options
4.2.3. Open a folder
4.2.4. Message list view
4.2.5. Message view
4.2.6. Message edition
4.2.6.1. Edit the header fields
4.2.6.2. MIME message editor
5. Problems
5.1. NFS with Linux server
5.2. UTF-8
6. Conclusion


1. Description
--------------

etPan is a mail client that is based on libEtPan!


1.2. Current features
---------------------

- IMAP4rev1 / POP3 / NNTP / mbox / mh / maildir
- virtual folder tree
- multiple folder views and message views
- smart multi-threading
- PGP signing and encryption (using GnuPG as external command) 
- S/MIME signing and encryption (using OpenSSL as external command)
- SPAM process (using bogofilter as external command)
- user interface for configuration edition


1.3. Planned features
---------------------

- perl scripting


2. Authors
----------

2.1. Main author
----------------

	DINH Viet Hoa           <hoa@users.sourceforge.net>


2.2. Contributors
-----------------

	David Woodhouse         <dwmw2@infradead.org>
	Melvin Hadasht          <melvin.hadasht@free.fr>


3. Dependencies
---------------

3.1. External program dependencies
----------------------------------

- sendmail     (sendmail command, must accept parameter -t)

  This will use _PATH_SENDMAIL in /usr/include/paths.h or
"/usr/sbin/sendmail" if this #define does not exist.
This program is currently necessary to send mails.
The possibility for sending mail without external program is planned.

- bogofilter   (bogofilter command, must be in search PATH for program)
  This is necessary if you use the SPAM management.  

- GnuPG        (pgp command, must be in search PATH for program)
  This is necessary if you want to encrypt or sign, verify, decrypt 
messages with OpenPGP.

- OpenSSL      (openssl command, must be in search PATH for program)
  This is necessary if you want to encrypt or sign, verify, decrypt 
messages with S/MIME.

- vi           (vi command, must be in search PATH for program)
  Editor is customizable but if you specify none, vi is used.


3.2. dependencies
-----------------

* users

- libEtPan! (version 0.30)
- perl (tested with perl 5.8)

* developers

- autoconf (tested with Autoconf version 2.13)
- automake (tested with GNU automake 1.4-p4)
- libtool (tested GNU libtool 1.4.2a)


4. How to start ?
-----------------

4.1. Definition
---------------

* Message

    A message is the common e-mail message or news message you read
or send.


* MIME part

    A message can have attachment such as images or other documents.
The attachment are organized into a tree structure.


* Mailbox

    A mailbox will contain a given number of messages.


* Storage

    A storage is a "physical" localisation of your mailbox. This can be
on a filesystem (local or remote disk, this is the case of MH, mbox and
maildir), or this can be on a remote host (this is the case for POP3,
IMAP or NNTP).


* Folder

    A storage, for the same user, can contain a given number of mailboxes,
depending the storage capabilities, then, the storage driver capabilities.
With etPan!, MH, IMAP and NNTP storages can have more than one mailbox.
The mailboxes will be called folders. On storage where we only have one
mailbox, the unique mailbox is the unique folder.


* Account

    An account consists in an e-mail address, a complete name and other
parameters that are necessary to compose messages.


* Virtual folder tree

    In etPan, you can have any folder tree layout. It does not depend 
on your physical directory layout. You can also do weird things such as
adding an IMAP folder as a child of a mbox folder.


4.2. Starting
-------------

You can use '?' or F1 key for help.

Ctrl-L to view the console log.

Ctrl-X, Ctrl-W to switch between different views.

You should have the default system mailbox in the virtual folder tree.


4.2.1. Configure your folder tree
---------------------------------

When you are in the folder list view, press Ctrl-E to open the
folder tree configuration editor.

* WARNING *
Note that this will close all windows even for message edition,
then, be careful.

'y' is used to save the configuration and return to folder tree view,
Ctrl-G to cancel all modifications.

4.2.1.1. Virtual node
---------------------

You can add nodes just for the layout.

Choose the virtual parent node of your folder.
Press 'a' to add a folder.

- Enter the name of the folder.

- Storage must remain (no storage), you can press 'd' to
    set "no storage".

- Press 'y' when you have finished.
    Ctrl-G to cancel.


4.2.1.2. mbox
-------------

Choose the virtual parent node of your folder.
Press 'a' to add a folder.

- Enter the name of the folder.

- Choose the storage (the storage for the folder is the mbox file).

    Press [Enter] and a list of storages appears.

    If it does not appear in the list, you can add it by pressing 'a'.

    In the storage properties :
	
	- enter the name.

	- choose the type of the storage with left/right arrow keys
	    until you find "mbox" type.

	- enter the path (you can use [TAB] to complete filename).

	- Press 'y' to confirm creation of the storage,
            Ctrl-G to cancel.

    In the list, to modify the storage, press 'e' on the storage.

    Press [Enter] to choose the storage, Ctrl-G to cancel.

- Choose the account

    Press [Enter] and a list of accounts appears.

    You can choose an existant account or if there is no account in
    the list, you can create one by pressing 'a'.

    In the account properties :

	- enter the identifier of the account, that's the thing that
	    will be displayed in the list of account.
        - enter the display name (this is the name that will be used 
	    as the sender name)
	- enter your e-mail address
	- enter your signature
	- optionally, you can choose your S/MIME certificate
	    and private key files for S/MIME signing and encryption.
	- default security driver and encryption is not yet modifiable using
	    the user interface.
	- Press 'y' to confirm creation of the storage,
            Ctrl-G to cancel.

    Press [Enter] to choose the account, Ctrl-G to cancel.

    The chosen account will be used to compose message.

- Choose the sent folder

    Press [Enter] and the list of folders appears.

    press [Enter] to choose one.

    You can only choose among the folders that already exist.

    The chosen folder will be used to store the sent messages.

- Choose the draft folder

    The chosen folder will be used to store the postponed messages.

- You can set a default recipient

    When composing a new message in this folder, the recipient will
      automatically be filled with the given recipient.
    You can use [TAB] to complete with address book.

- With left/right arrow, you can set if the information about messages
    count, recent messages and unseen messages number will be updated
    periodically or not.

- Press 'y' when you have finished, Ctrl-G to cancel.


4.2.1.3. POP3
-------------

The operation is almost the same, except for creation of the storage.

When you create the storage, you have to :

- Enter the name of the storage

- with left/right arrow, choose "POP3"

- choose the type of connection :

    - clear text connection : no encryption

    - use STARTTLS on clear text connection : STARTTLS will be used,
        clear connection, encryption will be used if the server support it,
	else, fails.

    - try STARTTLS, encryption will be used if the server support it,
	else, use clear connection.

    - TLS connection (SLL) : encrypted connection

    - use a command to connect, clear text dialog

    - use a command to connect, use STARTTLS dialog

    - use a command to connect, try STARTTLS dialog

    - use a command to connect, TLS dialog

- enter the name of the mail server (hostname).

- enter the port to connect to the mail server if this is not a
    standard port.

- you can choose authentication

    - plain text authentication

    - APOP authentication

    - try APOP authentication, if it fails, fallback on plain text.

    SASL is not yet implemented.

- choose the login and the password.

- Press 'y' when you have finished, Ctrl-G to cancel.


4.2.1.4. IMAP
-------------

The operation is almost the same as for POP3.

The process to create the storage is almost the same as for POP3,
except :

- with left/right arrow, choose "IMAP" for the type.

- authentication : only "plain authentication" is available.

    SASL will be implemented later.

In the folder properties, you have to choose the mailbox name.
In the mailbox name input, you can press [TAB] to complete the name.
If the IMAP mailbox does not exist, you will be asked for creation of
the mailbox.


4.2.1.5. NNTP - News
--------------------

The operation is almost the same as for POP3.

The process to create the storage is almost the same as for POP3,
except :

- with left/right arrow, choose "NNTP" for the type.

- authentication : only "plain authentication" is available.

In the folder properties, you have to choose the mailbox name.
In the mailbox name input, you can press [TAB] to complete the name.
(WARNING, when you will press [TAB] for the first time, there will be
  a long delay to retrieve the newsgroups list).

You can choose a maximum number of articles to list.


4.2.1.6. MH
-----------

The operation is almost the same as for mbox.

The process to create the storage is almost the same as for mbox,
except :

- with left/right arrow, choose "MH" for the type.

- the path you will choose is a directory.
   Note that the directory must exist before you choose it.
   (you can do a simple mkdir to create it).

In the folder properties, you can choose the location of the mailbox.
   This is a directory.


4.2.1.7. maildir
----------------

The operation is almost the same as for mbox.

The process to create the storage is almost the same as for mbox,
except :

- with left/right arrow, choose "maildir" for the type.

- the path you will choose is a directory.
   Note that the directory must exist before you choose it.
   (you can do a simple mkdir to create it).


4.2.1.7. Choose default folder
------------------------------

The default folder is the folder that will be first opened when
you run etPan!. (This is not yet implemented)

In the folder tree configuration editor, you can move the cursor
on the folder you want and press 's' to set the default folder.


4.2.1.8. Choose default sent folder
-----------------------------------

If your sent folder will be almost the same for every folder, you
can set a default folder to store the sent messages. This is the
default sent folder.

In the folder tree configuration editor, you can move the cursor
on the folder you want and press shift-'S' to set the default sent
folder.


4.2.1.9. Choose default draft folder
-----------------------------------

If your draft folder will be almost the same for every folder, you
can set a draft folder to store the messages that are not finished.
This is the default draft folder.

In the folder tree configuration editor, you can move the cursor
on the folder you want and press 'p' to set the default draft
folder.


4.2.2. Configure global options
-------------------------------

In the folder tree configuration editor, you can press 'g' to open
the global options editor.

You can choose the charsets.

- "display charset" is the charset of the terminal.
    Note that UTF-8 charset for display is not yet supported for
    the display selection will be removed in the future since it
    can be detected.

- "editor charset" is the charset of the text editor.
    It will be most of time the same as the "display charset".

- "message charset" is the default characters set of the message
    (this is used to display texts extracted from the message)
     Default is iso-8859-1 and should remains this.

- "editor" is the path of the text editor that will be used.
    It must accept the syntax : $EDITOR +$line filename
    You can use [TAB] to complete.

- "sendmail" is the path of sendmail that will be used.
    It must accept the syntax : $SENDMAIL -t < filename
    You can use [TAB] to complete.

- "reply quote limit". When people are replying, sometime, they
    make it remains all the previous quoted messages, not always
    necessary. This allow etPan! to remove automatically text quoted
    with more quotes than this limit.

- "network timeout" is the delay before a connection is considered
    disconnected when there is no response.

- "poll delay" is the time interval between to updates of folder 
    information. When a folder is opened, it is also polled for new 
    messages to display. This interval of time is used for the poll.


4.2.3. Open a folder
--------------------

To view a folder, in the folder list view, you have to move the cursor 
on the folder, and press [Enter].


4.2.4. Message list view
------------------------

In the message list view, to open a message, you have to move the cursor
on it and press [Enter].

To compose a new message, press 'm'.


4.2.5. Message view
-------------------

In the message view, to save an attachment, you have to press 'v' to view
the MIME structure, select the part to save and press 's', enter the
filename.

To reply to a message, press 'r'.

To reply to a message with all recipient, press 'g'.

To reply only to the author, press 'a'.

To forward a message, press 'f'.

To forward a message as attachment, press 'F'.


4.2.6. Message edition
----------------------

4.2.6.1. Edit the header fields
-------------------------------

Move the cursor on the field to edit and press [Enter].
(Note: the Date can't be edited)

When editing address field, you can press [TAB] to complete using
address book (press [TAB] a second time to complete with the good syntax).

Press 't' to add recipients.

Press 'c' to add a carbon-copy (Cc) field.

Press 'b' to add a blinded carbon-copy (Bcc) field.

Press 'd' to delete a field.

Press 'y' when you have finished to edit header fields, Ctrl-G to cancel.

  You may be brought to the edition of the text part of the message.
Write your message. When you have finished, save the text and exit
the editor.
  The MIME message editor will then be opened.


4.2.6.2. MIME message editor
----------------------------

To add an attachment, you have to select the parent node of the new 
  MIME part you want to add (commonly, you will select the
  main message/rfc822 part), press shift-A, enter the filename
  (it can be completed with [TAB]).

Press 'e' to reedit a given MIME part.

Press 'd' to delete a given MIME part.

Press [Enter] to view it a MIME part.

When you have finished, press 'y' to send the message or 'q' to exit
(the message will not be saved).

Note that postpone message or any equivalent has not yet been implemented.
As an alternative, you can select the main message/rfc822 part and press
's' to save it to a file.



5. Problems
-----------

5.1. NFS with Linux server
--------------------------

Since libEtPan! is making high usage of mmap() even for writing, 
when your mailboxes are on NFS filesystem with a Linux server, 
it is advised to use option "no_subtree_check" in /etc/exports.

This should avoid corruption of data.

The problem exist in Linux 2.4.22 and earlier versions.


5.2. UTF-8
----------

etPan! does not yet support completely terminals with UTF-8 characters 
set or more generally, terminals with multibytes characters set.


5.3. S/MIME Root certificates from Verisign/Thawte
--------------------------------------------------

Verisign : http://www.verisign.com/support/roots.html
Thawte : http://www.thawte.com/html/SUPPORT/primus_intro.html

Copy the PEM files (this should be the .txt files) to the CA directory.
default is "~/.libetpan/config/smime/CA".


6. Conclusion
-------------

  Enjoy penguins or beasties.

