Description of configuration files
----------------------------------


Index
-----

1. Common format
2. global
2.1. Example
3. account
3.1. default record
3.2. other records
4. storage
4.1. Example
4.2. Description
4.2.1. imap
4.2.2. nntp
4.2.3 pop3
4.2.4 mbox
4.2.5. maildir
4.2.6. mh
5. vfolder
5.1. default record
5.2. other records
6. abook
6.1. default record
6.2. other records
7. color
7.1. Example
7.2. color names
7.5. color attributes
7.4. description
8. mime-config
8.1. Example
8.2. Description
9. smime-config
9.1. Example
9.2. Description


1. Common format
----------------

Each configuration file is a text file.

Each record of the configuration file starts with a line "id=[identifier]".
Each identifier must be different. There is a number of lines, which are
fields of this record. The format of these lines is "[name]=[value]".
It is considered there is a new record when there is
a new line "id=[identifier]"

The files are located in ~/.libetpan/config


2. global
---------

filename is ~/.libetpan/config/global


2.1. Example
------------

id = default
display-charset = iso-8859-1
editor-charset = iso-8859-1
message-charset = iso-8859-1
editor = pico
sendmail-path = /usr/sbin/sendmail
reply-quote-limit = -1
poll-folder-delay = 300
network-timeout = 60

There is only one record named "default".

- "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. Default is iso-8859-1.

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

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

- "sendmail" is the path of sendmail that will be used.
    It must accept the syntax : $SENDMAIL -t < filename

- "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.
    -1 to set no limit.
    the value is the maximum number of quotes.

- "network-timeout" is the delay before a connection is considered
    disconnected when there is no response.
    value is in seconds. 60 is the default value.

- "poll-folder-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.
    0 to disable poll.
    value is in seconds. 300 is the default value.


3. account
----------

filename is ~/.libetpan/config/account


3.1. default record
-------------------

id = default
account = sourceforge

The record named "default" will give the name of the default account in
the field "account". This name will refer to the "name" field of the
account records.


3.2. other records
------------------

id = 0
name = sourceforge
display = DINH Viet Hoa
addr = hoa@users.sourceforge.net
signature = /net/home/dinh/.signature
smime-cert = /net/home/dinh/.libetpan/config/smime/account/dinh-cert.pem
smime-key = /net/home/dinh/.libetpan/config/smime/account/dinh-key.pem
security-driver = pgp
security-encryption = signed

Each record contains information about one account.
One can define several records.

- "id" can be a sequence of numbers.

- "name" is the name we can refer the account with.

- "display" is the name that will displayed for the sender of the message
    you will compose with this account.

- "addr" is the e-mail address for this account.

- "signature" is the file that contains the signature.
    signature will be preceded by a single line with "-- " in the message
    you will compose.

- "smime-cert" is the file that contains your S/MIME certificate.

- "smime-key" is the file that contains your S/MIME private key.

- "security-driver" is the name of the driver that will be used
    to encrypt or sign by default.

- "security-encryption" is the name of the encryption used to sign or
    encrypt the message (this is a name specific to the driver).


4. storage
----------

filename is ~/.libetpan/config/storage


4.1. Example
------------

id = 0
name = imap-local
type = imap
hostname = homer
port = 143
connection = starttls
auth = plain
login = foo
password = <base64-encrypted(bar)>
cached = 1


4.2. Description
----------------

Each record contains information about one storage.
One can define several records.

- "id" can be a sequence of numbers.

- "name" is the name we can refer the storage with.

- "type" is the type of storage: imap, pop3, nntp, maildir, mbox or mh.

- "cached", if the given value is 1, the driver use a cache and store flags
    on disk if the type of storage does not support it when non-cached,
    else, it does not use a cache.
    imap, maildir can store flags without using a flags file.
    mbox, mh, nntp and pop3 must have "cached" set to 1 in order to use 
    flags.

- depending on the driver, we can have different options.

4.2.1. imap
-----------

- "hostname" is the name of IMAP server.

- "port" is the port to connect to. By default, the port is chosen 
    depending the connection type.

- "command" is the command to use to connect to if the connection type
    is command, command-starttls, command-try-starttls or command-tls.

- "connection" is the connection type.

     "plain" for clear text connection.
     "starttls" to use STARTTLS.
     "try-starttls" to try STARTTLS.
     "tls" to use TLS (SSL).
     "command" to use a command.
     "command-starttls" to use STARTTLS on a command.
     "command-try-starttls" to try STARTTLS on a command.
     "command-tls" to use a TLS dialog on a command.

- "auth" is the type of authentication. This is currently always "plain".
     Default value is "plain".

- "login" is your login on the IMAP server.

- "password" is the password. Note that password is base64 encoded.
     It can be generated with : "echo -n my_password | mimencode"


4.2.2. nntp
-----------

The options are the same as for IMAP, except "connection" which only 
supports "plain", "tls", "command" and "command-tls".


4.2.3 pop3
----------

The options are the same as for IMAP, except "auth" which supports
"plain", "apop" and "try-apop"

- "apop" to authenticate with APOP.

- "try-apop" to try APOP and to fallback on plain text authentication.


4.2.4 mbox
----------

For mbox, there is only one option :

- "location" is the name of the file that contains the mbox mailbox.


4.2.5. maildir
--------------

For maildir, there is only one option :

- "location" is the name of the directory that contains the maildir mailbox.


4.2.6. mh
---------

For mh, there is only one option :

- "location" is the name of the directory that contains the MH tree.


5. vfolder
----------

filename is ~/.libetpan/config/vfolder


5.1. default record
-------------------

id = default
folder = inbox
sent = sent/mail

- "id" must be set to "default"

- "folder" is the name of the folder that will be selected when etPan
    is started.

- "sent" is the name of the folder that will store the sent messages
    if none is defined for a given folder.


5.2. other records
------------------

id = 2
name = mail/fr/newsreader-fr
storage = news-free
location = fr.usenet.logiciels
account = news-unix
sent = mail/fr/sent
poll = 1
max = 0

- "id" can be a sequence of numbers.

- "name" is a virtual path to the folder in the tree,
    folder names have to be separated with '/'. Folders will be
    referenced with this name.

- "storage" is the name of the storage. It can be forgot if the folder
     is a virtual one (with no storage).

- "location" is the name of the mailbox in the storage if the storage
    supports multiple mailboxes, else you can forget this field.

- "account" is the account used to compose message in this folder.
     Default value will be the default account.

- "sent" is the name of the folder that will store the sent messages.

- "poll" is "0" (to disable poll of folder) or "1" (to enable it).

- "max" is used if the storage is a "nntp" storage.


6. abook
--------

filename is ~/.libetpan/config/abook


6.1. default record
-------------------

id = default
charset = iso-8859-1

- "id" must be set to "default"

- "charset" is the default charset to use to write the name
     of the persons in the address book.


6.2. other records
-------------------

id = 10
name = CRISPIN Mark
addr = MRC@CAC.Washington.EDU

- "id" can be a sequence of numbers.

- "name" is the name of the person.

- "addr" is the e-mail address of the person.


7. color
--------

filename is ~/.libetpan/config/color


7.1. Example
------------

id = 0
name = title
foreground = 2
background = 4
blink = 0
bold = 0
dim = 0
reverse = 0
standout = 0
underline = 0

7.2. color names
----------------

You have some colors to define :

- "title" : title of a window
- "sel-title" : title of a selected window
- "message" : log messages
- "status" : color of the status bar
- "main" : color of items in a window
- "selection" : selected item
- "viewer-header" : in a text viewer, color of a message header
- "viewer-normal" : in a text viewer, color of the text
- "viewer-signature" : in a text viewer, color of the signature
- "viewer-link" : in a text viewer, color of a link
- "viewer-description" : in a text viewer, color of the MIME part description
- "viewer-security" : in a text viewer, result of security process
- "viewer-error" : to highlight errors


7.5. color attributes
---------------------

- "blink" : Blinking
- "bold" : Extra bright or bold
- "dim" : Half bright
- "reverse" : Reverse video
- "standout" : Best highlighting mode of the terminal
- "underline" : Underlining


7.4. description
----------------

- "id" can be a sequence of numbers.

- "name" is one of the color names given above.

- "foreground" is a color number between 0 and 7. This defines the color
     of the text.

- "background"  is a color number between 0 and 7. This defines the color 
     of the background

- several attributes can be defines, the name of the field is one of
     the name given in color attributes section. 0 is to disable it,
     1 to enable.


8. mime-config
--------------

filename is ~/.libetpan/config/mime-config


8.1. Example
------------

id = 1
type = text/html
type-match = ^text/html$
renderer = | lynx -dump -stdin
viewer = | lynx -stdin
name = ^.*\.html?$
encoding = 8bit
ext = .html


8.2. Description
----------------

- "id" can be a sequence of numbers.

- "type" is the exact MIME content type.

- "type-match" is the content type to match for an attachment to
     guess that the file has the good type. This is a regular
     expression.

- "renderer" is the command to call for this attachment to render
     the MIME part in the text viewer. If the command starts with '|' (pipe),
     the file is given through a pipe. Else, filename can be given with '%f'.
     The file is extracted and extension given by "ext" field is 
     added to the temporary filename.

- "viewer" is the command to call to view the MIME part.

- "name" is the filename to match to guess that the file has the 
     good type.

- "encoding" is the default outgoing encoding when attaching a file
     of this MIME content type.

- "ext" is the default extension for this type of file.


9. smime-config
---------------

9.1. Example
------------

id = 0
CA-dir = /net/home/dinh/.libetpan/config/smime/CA
cert-dir = /net/home/dinh/.libetpan/config/smime/CA
private-keys-dir = /net/home/dinh/.libetpan/config/smime/private-keys-dir
CA-check = 1
auto-extract-cert = 0

9.2. Description
----------------

- "id" can be a anything.

- "CA-dir" is the directory where are stored the root certificates
     (certification authority).

- "cert-dir" is the directory where will be put all the certificates of
     other people and you certificates.

- "private-keys" is the directory where you will store you private keys.
     The files you will store there must be named [email]-private-key.pem
     and will be stored in PEM format.
     For example, if my address is hoa@users.sourceforge.net, the 
     file that will contain my private key is :
     "hoa@users.sourceforge.net-private-key.pem".

- "CA-check". Set this value to 1 if you want to check the signature.
     If this value is zero, the signed part will only be extracted 
     without verification.

- "auto-extract-cert". Set this value to 1 if you want that the 
     certificate of a person that signed a message to be stored when
     you read it, so that you can write him encrypted messages later.

