                              %% ELMO %%

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

This is user documentation for Elmo.


Last update: 16/08/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 (with authentication)
   * 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.pl, which will create a configuration file,
~/.elmorc. You may wish to edit it, although the defaults should
be decent enough.

If you experience problems with linking elmo (unresolved symbols with
gettext in their names) try running configure with --disable-nls
switch.

                         = 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 below,
feel free to experiment.

I. Functions






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.



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
 # - spam
   - 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.





                               = 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. You 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 folder_spam_delete

If, on the other hand, the filter made a mistake, you can use the
function mail_spam_is_not 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)]
  mail_array_sort_date (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.

Note that you need to have an unstripped elmo binary compiled with
debugging symbols.  If you got elmo with your distribution (rpm or deb
package) then there is no way you can get the desired output.

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.txt 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 do 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

  set editor '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>
  * Krzysztof Gibas <duparyba % wp.pl>

See also the THANKS file.

Mailing lists:

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