OXElmo - Email Client
              Derived from the original stable release elmo-1.2.0


                              %% ELMO %%

 0. Preface
 1. What is Elmo?
 2. Installing Elmo
 3. Configuring Elmo
     I.    Functions
     II.   Variables
     III.  Flags
     IV.   Hooks
     V.    Macros
     VI.   Keys
     VII.  Rules
     VIII. Templates
     IX.   Properties
     X.    MIME handlers
     XI.   Character sets
 4. Contact
 A. Function reference

--------------------------------------------------
Preface:

OXElmo started life as the stable release of elmo-1.2.0. This was a curses
based email client as released by rzyjontko. 

OXElmo is the same email client running as a standalone X app, which has an
Xlib only curses style interface. Due to the structure of the original elmo,
mouse integration is minimal, at best. OXElmo started life as a keystroke
driven app and remains so at this time. Due to differences between the
original curses and the current Xlib based GUI, the screen update will
occasionally show rough edges. These are logical artifacts (incompelete blank
screen filling, sub-window status not up to date until focus is received)
resulting from the underlying program structure.

There is a quasi-adaptation of a scrollbar on the active OXElmo sub-window,
copy&paste using the mouse of any text visible in the OXElmo window using
X-windows clipboard and the addition of a single keystroke to download all
email at once. Several bug fixes (SEGFAULTs) have also been implemented. 

The 'Esc' key, under X, is now usable and performs the same functions as 'q'.
In addition, using the 'Esc' or 'q' key during the download of multiple emails
or one long email is interruptable in a recoverable manner. The first 'Esc'
will stop the download; a second 'Esc' will reset the connection and delete
the list of 'fetch'able files.

Aside from the above, the operation is near identical to the original. The
remainder of this document and the acompanying Elmo_tutorial.txt are unchanged
from the release, and as such are fully applicable.

Terry Loveall, Oct. 15, 2004
email: <loveall % iinet.com>
Xwoaf OXElmo home page: http://modest-proposals.com/Hacklin.htm

--------------------------------------------------

This is user documentation for Elmo.


Last update: 19/04/2004.


                          = What is Elmo? =
                          =================

Elmo is a feature-rich, highly configurable and fast mail client. You
could call it a Mail User Agent, but it offers much more than
traditional MUA's.

While creating Elmo we try to realize the following objectives:

   * Elmo should be easy and pleasant to use.

The user should not be forced to configure many options before
using it, nor read a long user's manual. We provide a short script,
elmoconf.pl (in the src/ directory) which will create a configuration
file for you, providing reasonable defaults. You can start using
the full power of Elmo in half a minute!

   * Elmo should be very fast and efficient.

Elmo uses very efficient algorithms for several tasks. You shouldn't
be surprised when you discover how fast it opens your mail folder
with hundreds or even thousands of mail. For example, opening a folder
with 7,000 mails lasts only four seconds!

   * You should be able to modify Elmo as you like.

You, as a user of Elmo, are the most important in our project.
You should be able to configure your mail client as you like,
and nothing should constrain you. That's why our configuration file
has so many options: as your needs grow, you will be able
to make Elmo behave exactly as you wish.

Moreover, if you have suggestions, special wishes and advice,
we would like to hear from you! If time allows, we will gladly
incorporate your suggestions into a future version of Elmo.

   * Elmo will not require special external software.

With traditional MUA's, such as Mutt, you usually have to
set up an SMTP server, such as Sendmail, and often use
additional tools like fetchmail to get your mail. With Elmo
you can use this traditional approach but you don't have to:
Elmo can send and receive mail on its own, which means
you are less dependent.

   * Elmo should have a good, modular design.

While it may not seem important to you, it does influence
our ability to add new features to Elmo. We worked hard to
make Elmo easily extensible, using best software-development
methodologies.

A brief look at Elmo's features:

   * SMTP support (with authentication)
   * POP3 support
   * a Bayesian mail filter!
   * an addressbook
   * threading
   * colors
   * keymaps and hooks
   * maildir and (partial) mbox support
   * MIME support (including support for encoded headers)
   * partial PGP support (encoding, and signature verification)
   * OpenSSL support
   * partial UTF-8 support
   * interactive search



                         = Installing Elmo =
                         ===================

If you downloaded a release of elmo, unpack the archive and type

   * ./configure
   * make
   * su -c "make install"

You should be able to run Elmo now. But before that run the script
src/elmoconf.pl, which will create a configuration file,
~/.elmorc. You may wish to edit it, although the defaults should
be decent enough.




                         = Configuring Elmo =
                         ====================

In Elmo you can configure almost everything by modifying your
~/.elmorc file. The two main types of modifications are related
to functions and variables. Variables are set by the set
command in the configuration file. An example of could be
assigning a signature file:


    set sigfile ~/.signature


If you put the above line in your ~/.elmorc, Elmo
will try to include the ~/.signature file as a signature at the end
of your letter.

You can set a variable many times, and you will be prompted for a one
each time it is necessary.  There are also some variables that are
structural.  An example could be defining your POP3 account:


    set pop_acc {
      name:     doe.com
      server:   pop3.doe.com
      username: johnny
      password: jenny
    }


Functions, on the other hand, can be manipulated in two main ways.
The first is assigning a function to a key:


    key folder n folder_bar_next


Which means: "in folder view, pressing 'n' should invoke
the function 'folder_bar_next' (which means moving the
selection bar to the next mail)".

Another way is to define a hook:


    hook fetch_del_mail fetch_next


Which means: "whenever the function fetch_del_mail is invoked,
the function fetch_next should be invoked, too". Or, to put in
a friendlier way, "whenever we delete a letter, the selection
bar should be moved to the next position (in the fetch window)".

But how do we know what exactly a given function or variable
is responsible for?  You can find a complete reference at the 
end of this file, feel free to experiment.



I. Functions
------------

You can invoke any elmo function, at any time.  Simply press ':', and
you will be prompted for a function name.  Enter it's name, and press
enter.  The function will be executed.  If the function has some
hooks, they will be executed too.



II. Variables
-------------

You should refer to sample.elmorc file which comes with every Elmo
distribution (in doc subdirectory).  If you have Elmo installed from
the package, look at /usr/share/doc/elmo directory.

You will find a complete reference of all possible settings.



III. Flags 
----------

If you use a default theme, then you may see few columns of characters
before every message.  Here we list what do these characters mean:

1st column:
 + - attachment
 e - encrypted
 s - signed
   - no attachment

2nd column:
 F - Flagged
 N - New
 O - Old
   - Read

3rd column:
 D - To be deleted (only in fetch window)
 F - Message already fetched (only in fetch window)
 r - Replied
 f - Forwarded

4th column:
 ? - not checked
 # - spam
   - not spam



IV. Hooks
---------

Hooks are very useful if you always use two (or more) commands
together.  You may cause one of them be always executed once the
second is run.  Hook definition is very simple:

    hook <trigger-command> <hook-command>

If you then ever use a trigger command, a hook will be executed right
after the trigger finishes.  E.g.:

    hook folder_toggle_flag folder_bar_next

The command above may be used to move a bar to the next position each
time you press space in folder window, to select a message.  This hook
is taken from my personal .elmorc.  These are other hooks I use:

    hook sender_go mailreader_close
    hook abook_hit abook_next
    hook abook_compose abook_hide

There are few functions that do nothing, but are useful if you'd like
to add a hook to them:

   * folder_at_leave
   * folder_at_bar_move
   * cmd_after_startup

They are described shortly in appendix with list of functions.



V. Macros
---------

Sometimes you'd like to combine functionality of few commands without
loosing possibility of using them alone.  You should create a macro in
such a case.

    macro <name> {
       <optional-description>
       <body>
    }

Macro name may only consist of letters, digits, and underscore, and
must not begin with a digit.  Description is shown in help windows, if
you assign macro a keybinding.  If you supply no description, a
default one ("user defined macro") is set.  A description must be a
quoted string.  Body of macro is a list of commands that should be
executed, each on separate line.  E.g.:

    macro open_next_unread {
        "open next unread message"
        folder_next_unread
        mailreader_load
    }

This macro finds next unread message, and loads it to mailreader
window.  It may be executed just like any other function.  You may
press ':' at any time, and enter macro name, or assign macro a
keybinding e.g.:

    key mail n open_next_unread

Now it is possible to read new messages one by one, without leaving
mailreader window.

There are few things worth knowing:
  - you may add a hook to macro, but macro may not be a hook itself,
  - commands used in macro definition are executed without their
    hooks.



VI. Keys
--------

Elmo uses keymaps, just like Emacs and other configurable programs.
It means that you can make elmo use almost any key combination for
a given task you wish.

Key definition consists of few elements:

    key <state> <specifier> <command>

A state indicates, when you'd like a keybinding to be active, and may
be one of:

  * folder    - main elmo window with list of messages
  * mail      - mailreader window
  * select    - list of boxes in your mailbox
  * fetch     - list of messages available at your pop3 account
  * send      - message composition window
  * attach    - list of attachments (opened from mailreader)
  * abook     - addressbook
  * abook_add - list of address of a message (opened from mailreader)
  * ask       - when you are shown set of possible selections
  * help      - help window
  * read      - when you are prompted for a string
  * search    - when you enter a pattern to search

There are few ways of specifing a key.  

  Printable characters may be entered literally.  However some special
  characters need to be escaped with a backslash (these characters
  are: backslash, all kinds of parentheses, quotes, colon).  

  You may define a keybinding for ctrl+lowercase letter.  E.g.: \Cx

  Special keys: <tab>, <esc>, <up>, <down>, <left>, <right>, <pageup>,
  <pagedown>, <backspace>, <delete>, <insert>, <enter>, <home>, <end>,
  <space>, <f1>, <f2>, ...

  A three-digit octal code of a key pr