                              %% ELMO %%

 1. What is Elmo?
 2. Installing Elmo
 3. Configuring Elmo
 4. FAQ
 5. Contact

This is user documentation for Elmo.


Last update: 10/05/2003.

                          = 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.sh (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
   * POP3 support
   * a Bayesian mail filter!
   * an address-book
   * threading
   * colors
   * keymaps and hooks
   * maildir and (partial) mbox support
   * MIME support (including support for encoded headers)

                         = 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.sh, 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_barnext


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

Another way is to define a hook:


     hook folder_delete_mail folder_barnext



Which means: "whenever the function folderdeletemail is invoked,
the function folderbarnext 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".

But how do we know what exactly a given function or variable
is responsible for? You can find a complete reference below,
feel free to experiment.

I. Functions






II. Variables

-- 

* addressbook
  
  The path to your addressbook file.

  default: ~/.addressbook

  Example:

  set addressbook ~/.elmo/addressbook

* autoflush

  Whether to refresh the folder view automatically when a letter is deleted.

  default: not set (no refresh)

  set autoflush on

* relativenames

  When set, you will be only displayed inbox instead of /home/user/mail...

  default: not set

  set relativenames on

* indentstring

  short string used when quoting the original author while
  replying to him/her

  default: "> "

  The string may contain the following special combinations:

  %f - name and surname or nickname (the part before the address)
  %F - as above plus address
  %s - subject
  %% - the % character
  %i - initials
  %x - from, limited to 16 characters and filled with spaces up to 16
  %d - full date
  %D - short date
  %I - letter index (for debugging purposes)
  %S - letter size
  %$ - current flags
  %? - has a '+' sign if the letter has attachments
  

* lineformat

  The column format in the main (folder) window.

  default: '%?%$

  The string may contain the following special combinations:

  %f - name and surname or nickname (the part before the address)
  %F - as above plus address
  %s - subject
  %% - the % character
  %i - initials
  %x - from, limited to 16 characters and filled with spaces up to 16
  %d - full date
  %D - short date 
  %I - letter index (for debugging purposes)
  %S - letter size
  %$ - current flags
  %? - has a '+' sign if the letter has attachments
  


* sigfile

  The signature file, appended at the end of the letter.  It could
  also be a program that writes your signature to the standard
  output.  In such a case, it should be prepended with '|'.
 
  default: not set
 
  Example:
 
  set signature ~/.signature
  set signature |/usr/games/fortune
 
* sigdashes

  Whether to use '-- ' before the signature.

  Default: not set (don't add)

  Example:

  set sigdashes on

* editor

  Your favorite editor used when composing mail.

  Default: "$EDITOR %f" / "jed %f"

  Example: "zile +%d %f"

* mailbox

  Mailbox.

  Fields:

     * name     -- box name
     * root     -- path to the directory containing subboxes
     * start    -- which box open at the beginning (default: inbox)
     * sent     -- where to store sent mail (default: sent)
     * drafts   -- where to store unsent mail (default: drafts)
     * trash    -- where to put store removed messages (default:
                   remove message permanently)
     * spam     -- where to put messages removed as spam (default:
                   remove them permanently)
     * protect  -- wheter to protect box against spam (default: no)

* popacc

  POP3 account.

  Fields:

     * name     -- account name
     * server   -- server address (example: pop3.doe.com)
     * port     -- server port (optional)
     * username -- user name
     * password -- password
     * limit    -- if set, will cause elmo to delete fetched messages
                   (beginning with the oldest one) until maildrop is
                   not bigger than limit (example: 4M, 1000K)

* smtpacc

  SMTP account.

  Fields:

     * name    -- account name
     * server  -- server address (example: smtp.doe.com)
     * port    -- server port (optional)
     * myname -- your name, as appearing before your e-mail address
                  in the From: field
     * email   -- your email, as appearing in the From: field




III. Flags 



1st column:
 N - New
 O - Old
   - read

2nd column:
 F - Flagged
 T - To be  deleted
 r - Replied
 f - Forwarded

3rd column:
 ? - not checked

   - not spam



IV. 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. You can find the default values below.





                               = FAQ =

Q: I heard many good things about the Bayesian spam filter. How to ues it?

A: It's very simple. First, you should add the "protect" field to your 
mailbox. It enables the filter for that mailbox.We will probably also
want to set the "spam" field to the name of a mailbox where detected
spam will be moved. If it's not defined, spam will be deleted.
Now whenever you wish to delete spam that the filter couldn't detect,
use folder_spam_delete.

Example:



set mailbox {
name: "mybox"
root: ~/Gdzies
trash: trash
spam: spam
protect: yes
}

key folder d folderspamdelete



If, on the other hand, the filter made a mistake, you can use the
function mail_spam_isnot on a given message.

Q: Why Elmo isn't a part of the GNU Project?

A: Of course we would be more than happy to make Elmo a part of the
GNU Project. But nowadays it's not so easy. Richard Stallman wrote us:

----------------------------------------------------------------------
Our evaluators looked at Elmo.  They say it is basically a good program
(though it needs documentation to be of real use).  However, it does
a job for which we already have good free software.  It does not make sense
for the GNU Project to release another mail reader.

So we decided not to make Elmo a GNU package.  I'm sorry if that's
a disappointment.

How about if you work on a program to do a job for which there is no
free software now?  If you do an equally good job on a project like
that, we would definitely want it as a GNU package.
----------------------------------------------------------------------

We will ask the evaluators to reconsider their decision once Elmo
user base gets large enough.

Q: Elmo quit unexpectedly and I got the message: "You have found a bug.
Please consult the documentation for instructions.". What should I do?

A: The instructions are very simple: if you have gdb installed, just run the
command



gdb elmo



and then



run



You should see something similar to the following:



Program received signal SIGSEGV, Segmentation fault.
[Switching to Thread 16384 (LWP 20050)]
mailarraysortdate (marray=0x0) at mail.c:595
595       if (marray->order != ORDER_DATE){
(gdb) 



Now, it's enough to type "where" and send us the output.
It will look like:



(gdb) where
(gdb)



Note that you need to have elmo compiled with different flags (-g
-O0).  If you got elmo with your distribution (rpm or deb package)
then there is no way you can get the output above.
You can also type 



valgrind 2> boom.txt elmo



and send us the file boom.txt. If you have neither gdb nor valgrind 
installed, you can use the command



strace -o boom elmo



and send us the file boom.txt.

Thank you!

Q: How do I read my mail from local mbox file?

A: Suppose you have set mailbox to be at ~/mailbox, and you have your
mail delivered to /var/mail/johnny.
johnny@localhost:~$ ln -s /var/mail/johnny ~/mailbox/localmailbox
Remember, that elmo doesn't show how many messages are in the mbox
file, and you won't be able to anything with these messages but read
them.

Q: How to run elmo by pressing a special key on the keyboard?

A: Many modern keyboards have additional keys which can be put to
a good use. First, you should check what is the scancode of the
key. For example, when you press one of this special keys, the 
kernel will print on the screen something like:

   *  keyboard: unknown scancode e0 65

In this case log in as root and type the following:

   * setkeycodes e065 120

Now in the file /etc/console/boottime.kmap.gz you should change
the line:

   * keycode 120 =
to

   * keycode 120 = F20

The last thing to do is to add the following:

   *  "\e[34~": "elmo\n"

to your ~/.inputrc. Now whenever you press that special key,
elmo will start.

Q: How to use Emacs with Elmo?

A: Emacs is an excellent editing environment which can well be used
with elmo while composing mail. How to make this experience more 
pleasant?

First, add the following:

   * (server-start)
   * (global-font-lock-mode 1)
   * (setq auto-mode-alist (cons '("elmo\-......$" . mail-mode) auto-mode-alist))

to your ~/.emacs. The first line will start an Emacs server for
use with emacsclient. The second will turn on syntax highlighting
globally. The last one will turn on mail-mode whenever we edit
a file with the name starting with "elmo-".

Now start emacs on one of your vt's and add

   * 'emacsclient +%d %f'

to your ~/.elmorc. Whenever you compose mail, emacsclient will
connect to the server and you will be able to enjoy font coloring.





                             = Contact =

Homepage:

  * http://elmo.sourceforge.net

Principal author:

  * rzyjontko <rzyj % plusnet.pl>

Additional authors:

  * Artur Skura <artur.skura % javart.com.pl>

See also the THANKS file.

Mailing lists:

  * elmo-users, for Elmo users
  * elmo-commit, for developers



