Version 0.1

Pronounced /'zɛfiːmæp/ or ZE-fee-map.

zephymap is a utility to receive zephyr notifications of mail on IMAP servers.
This is acheived by running zephymap.py on a computer or server of your choice
and having it check the IMAP servers you indicate in your config file (see
below) and notifying you of new messages via zephyr notification on a class of
your choice.

**NOTE**: Due to the specifics of implementation, a SIGINT (Ctrl-C) will not
kill zephymap. The proper signal to send zephymap is SIGQUIT (Ctrl-\).


INSTALLING LIBRARIES
================================================================================
zephymap requires python-zephyr in order to send notifications, which requires
libzephyr-dev, which may or may not require comerr-dev. libzephyr-dev is known
to work on linerva, and is in the Ubuntu/Debian repositories.

To install python-zephyr:
1. Determine which version of python you are using via 'python --version'; 2.5
   and 2.6 are both known to work.

2. Run 

   mkdir -p ~/.local/lib/python2.5/site-packages

   (replacing ~/.local with a directory of your choice, and 2.5 with 2.6 if
   appropriate).

3. Open your .bashrc_profile or other suitable dotfile (e.g., .bashrc.mine) and
   add the line

   export PYTHONPATH=~/.local/lib/python2.5/site-packages:$PYTHONPATH

   where the directory is the one you made in step 2.

3. Either download python-zephyr from:
   
   http://github.com/ebroder/python-zephyr/downloads

   and unpack the archive, or (if you feel like using the development version)
   clone the git repo by running:
   
   git clone git://github.com/ebroder/python-zephyr.git

   Either way, cd into the created python-zephyr directory.

4. Run

   python setup.py install --prefix=~/.local

   where ~/.local is the directory containing the lib/ directory from step
   2. This should install python-zephyr.

INSTALLING ZEPHYMAP
================================================================================
zephymap itself requires no special setup.

1. Create a directory into which to download zephymap.

2. Download a copy, either from

   http://github.com/lightquake/zephymap/downloads

   or get the latest development build (not guaranteed to be stable or even
   work) via

   git clone git://github.com/lightquake/zephymap.git
   
3. Set up the ~/.zephymap.conf configuration file as described in the
   CONFIGURATION section

4. Run zephymap:
   
   python zephymap.py

5. Subscribe to the class zephymap is sending zephyrs to (default MAIL). In
   barnowl,

   :sub MAIL * me

   will do this, where 'me' is replaced with your username.

CONFIGURATION
================================================================================
zephymap reads from a config file in your home directory named ".zephymap.conf".
This file must be of the following format:

[zephyr]
recipient: joeuser
[Mailbox 1]
server: imap.foo.com
username: username1
password: password1
[Mailbox 2]
server: imap.baz.com
username: username2
ssl: true

The [mailbox] section names (the string inside the []) should contain a short
meaningful name for the mail server it defines. This will appear in the
instance of zephyrs sent by zephymap.

The [zephyr] section has the following (case sensitive) options and must be
named such:

recipient   The zephyr user to whom zephymap should make the zephyrs readable.

class       The class to which zephymap will send mail notification zephyrs.
            This is the class to which the user identified in "recipient" will
            need to be subscribed in order to see the zephyrs. The default is
            "MAIL".

Each IMAP [mailbox] section has the following (caseinsensitive) options:

server      The URI of the IMAP server (e.g., "imap.gmail.com" for Gmail and
            "imap.exchange.mit.edu" for MIT's Exchange email server)

username    The username for the account on the indicated server.

password    The password for the account on the indicated server. Leaving this
            option out will cause zephymap to prompt you to input your password
            at startup. This is the suggested behaviour for the security
            concious.

interval    An interval value in seconds that indicates the time to wait between
            checking the mailbox for new messages. It cannot be set less than 10
            seconds. The default is 20 seconds.

ssl         A boolean value that indicates whether or not the server utilizes
            ssl. Default is true.

port        An integer value that indicates the port to be used to access the IMAP
            server. The default for an SSL server is 993, and the default for a
            non-SSL server is 143.

include     A semi-colon separated list of folder names to be included. If left
            blank, the default is all folders. Subfolders can be included by
            indicating "folder/subfolder"; for example,

            MIT/SIPB; zephymap; INBOX

            Note that spaces in the middle of folder names are important, but
            spaces at the beginning or end are not.


exclude     A semi-colon separated list of folder names to be excluded even if
            they exist in the include list. The default is to exclude none. Syntax
            is identical to that of the "include" option.

regex       A boolean option that causes include and exclude to interpret their
            arguments as Perl-style regular expressions. Use this option only if
            you are familiar with regular expressions. Note that the regex will
            automatically be case-insensitive

Contact Patrick at [email protected] or on (MIT) zephyr via the zephymap class.