                              %% ELMO %%

 1. What is Elmo?
 2. Installing Elmo
 3. Configuring Elmo
     I.   Functions
     II.  Variables
     III. Flags
     IV.  Keys
 4. FAQ
 5. Contact

This is user documentation for Elmo.


Last update: 10/03/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.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 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 below,
feel free to experiment.

I. Functions

  abook_show - open address book window

  abook_hide - close this window

  abook_sort - sort address book

  abook_next - move bar to the next position

  abook_prev - move bar to the previous position

  abook_next_page - move on to the next page

  abook_prev_page - move to the previous page

  abook_first - move bar to the first position

  abook_last - move bar to the last position

  abook_hit - select / unselect this address

  abook_hit_all - revert selection

  abook_set - select this address

  abook_unset - unselect this address

  abook_set_all - select all

  abook_unset_all - unselect all

  abook_change_name - change name

  abook_change_email - change email

  abook_change_sex - change sex

  abook_change_official - change official flag

  abook_remove - delete address(es)

  abook_insert - insert new address

  abook_compose - compose new message

  abook_add_show - open address list

  abook_add_hide - close this window

  abook_add_next - move on to the next position

  abook_add_prev - move to the previous position

  abook_add_next_page - move on to the next page

  abook_add_prev_page - move to the previous page

  abook_add_first - move to the first position

  abook_add_last - move to the last position

  abook_add_hit - add this address to addressbook

  attach_show - show attachments

  attach_hide - close this window

  attach_refresh - refresh this window

  attach_hit - display this attachment.
  If there is a handler defined for this kind of attachment,
  then the handler is executed.  If elmo is a handler, then
  attachment content is shown in elmo window.

  attach_next - move on to the next position

  attach_prev - move to the previous position

  attach_next_page - move on to the next page

  attach_prev_page - move to the previous page

  attach_first - move to the first position

  attach_last - move to the last position

  attach_save - save attachment to file

  attach_save_all - save all attachments in specified directory

  box_selection_next - move on to the next position

  box_selection_prev - move to the previous position

  box_selection_next_page - move on to the next page

  box_selection_prev_page - move to the previous page

  box_selection_first - move to the first position

  box_selection_last - move to the last position

  box_selection_re_read - re-read mailbox

  box_selection_hit - open the selected box

  folder_page_next - move on to the next page

  folder_page_prev - move to the previous page

  folder_bar_next - move bar to the next position

  folder_bar_prev - move bar to the previous position

  folder_bar_first - move bar to the first position

  folder_bar_last - move bar to the last position

  folder_scroll_down - scroll window down

  folder_scroll_up - scroll window up

  folder_recenter - place bar in a center of the screen

  folder_update - re-read mailbox

  folder_flush - remove spam and refresh the view

  folder_search_forward - search forward

  folder_search_backward - search backward

  folder_search_backspace - delete last character

  folder_sort_threads - group mails in threads

  folder_sort_date - sort messages by date

  folder_sort_from - sort messages by from

  folder_sort_subject - sort messages by subject

  folder_toggle_flag - toggle flag

  folder_flag_all - flag all messages

  folder_unflag_all - unflag all messages

  folder_flag_invert - invert flag

  folder_flag_duplicates - flag messages that are duplicates.
  Set flag on all the messages, that are duplicates of other
  messages in the box.  It is useful to remove them.

  folder_remove_flag - removes message flag

  folder_spam_check - check if selected messages are spam

  folder_spam_check_all - check all messages that were not checked if they are spam

  folder_spam_delete - delete message as a spam

  folder_spam_flush - scan messages according to their spam indicator and delete spam

  folder_spam_is_not - unmark message incorrectly recognized as spam

  folder_delete_mail - delete a message (or move to trash).
  If you have a trash field defined in your .elmorc file, than move
  selected messages to trash folder.  Otherwise delete them.

  folder_kill_mail - permanently delete message.
  Remove selected messages from the box.  It is then impossible
  to recover them.

  folder_move_mail - move selected message to another box

  folder_make_read - mark selected messages as read

  folder_at_leave - this function is executed each time a box is being left

  folder_at_bar_move - this function is executed each time a bar in folder moves

  fetch_all - fetch all messages from the server

  fetch_open - open window with message list

  fetch_close - close connection

  fetch_next - move on to the next position

  fetch_prev - move to the previous position

  fetch_next_page - move on to the next page

  fetch_prev_page - move to the previous position

  fetch_first - move to the first position

  fetch_last - move to the last position

  fetch_rset - reset state of the connection

  fetch_del_mail - delete selected message

  fetch_get_mail - fetch selected message

  fetch_mark_mail - mark message as fetched

  mailreader_close - close this window

  mailreader_line_up - scroll up

  mailreader_line_down - scroll down

  mailreader_page_up - scroll page up

  mailreader_page_down - scroll page down

  mailreader_top - move to the top

  mailreader_bottom - move to the bottom

  mailreader_header_switch - toggle display mode (header / message)

  mailreader_show - open message window

  mailreader_load - load selected message to mailreader window

  sender_go - send.
  Move message to outbox.  This function doesn't send a message yet.
  You should run smtp_flush_outbox to send all messages from outbox.

  sender_open_new - compose new message.
  Create a new message.  You are asked for message recepients, and
  subject.  Then an editor is opened.  After closing editor, you
  are taken to the window, where you can send or abort the message.

  sender_open_reply - reply to the message.
  Reply to the selected message.  After closing editor, you are
  taken to the window, where you can send or abort the message.

  sender_open_reply_all - reply to all recepients.
  Reply to the selected message.  The message is addressed not
  only to the author of the message, but to other recepients
  as well.

  sender_open_fwd - forward the message.
  Forward the selected message.  You are asked for recepients
  of the message.

  sender_open_edit - edit selected message.
  You can edit a message in draft or outbox.  After closing
  editor, you are taken to the window, where you can send or
  abort the message.  Please note that the edited message
  is removed from the box.

  sender_close - close this window.
  Cancel the message.  You will be asked if you wish to move
  it to drafts, so you can finish it, and send later.  Please
  don't save a message with attachments, as it may be unreadable
  when you try to edit it later.

  sender_prev - move to the previous position

  sender_next - move on to the next position

  sender_prev_page - move to the previous page

  sender_next_page - move on to the next page

  sender_first - move to the first position

  sender_last - move to the last position

  sender_change_smtp - change smtp server.
  Change smtp sever, via which the message is going to be
  sent.  Changing smtp server affects from field, but changing
  from doesn't affect smtp server.

  sender_change_from - change from

  sender_change_reply_to - change reply-to

  sender_change_to - change to

  sender_change_cc - change cc

  sender_change_bcc - change bcc

  sender_change_subject - change subject

  sender_add_attachment - attach a file

  sender_delete_attachment - remove attachment

  sender_change_type - change content-type of attachment

  choose_next - move on to the next selection

  choose_prev - move to the previous selection

  choose_first - move to the first selection

  choose_last - move to the last selection

  choose_cancel - cancel selection

  cmd_quit - quit elmo

  cmd_nothing - do noting.
  Particularly useful, when you want to disable a key.

  cmd_after_startup - executed right after startup.
  Particularly useful, when you want to perform some actions
  at the very beginning.

  help_open - open help window

  help_close - close help window

  help_scroll_up - scroll up one line

  help_scroll_down - scroll down one line

  help_prev_page - scroll up one page

  help_next_page - scroll down one page

  help_beg - move to the top

  help_end - move to the bottom

  mybox_create_box - creates a new box

  read_abort - abort reading input

  read_accept - accept the input

  read_forward_char - move forward a character

  read_backward_char - move back a character

  read_forward_word - move forward over a word

  read_backward_word - move back over a word

  read_begin - move to the start of the line

  read_end - move to the end of the line

  read_del_char_fwd - delete the character at point

  read_del_char_back - delete the character behind the cursor

  read_del_word_fwd - delete the word after the point

  read_del_word_back - delete the word behind the cursor

  read_kill_line - kill the text from point to the end of the line

  read_complete - attempt to perform completion on the text before point

  read_choose_first - move to the first completion

  read_choose_last - move to the last completion

  read_choose_next - move on to the next completion

  read_choose_prev - move to the previous completion

  interface_redraw - redraw the whole screen.
  Redraw the whole window.  Very useful, when one of other
  application corrupts your console.

  interface_next_window - switch to the next window.
  Bring next window to front.  It may cause some unexpected
  behaviour if windows overlap.  Sometimes it is better to
  close the window.

  interface_prev_window - switch to the previous window

  interface_num_window - switch to particular window.
  Check what key was pressed as last.  If it was a digit, then
  switch to the window with that number.  This function is mapped
  to \M-d (for all digits d) as default.

  debug_next - scroll down

  debug_prev - scroll up

  debug_next_page - scroll down one page

  debug_prev_page - scroll up one page

  debug_first - scroll to the top

  debug_last - scroll to the bottom

  debug_show - refresh the view

  smtp_flush_outbox - send all messages from outbox.
  Try to send all messages from outbox.  If transmission fails
  then the message is left in the outbox.  Otherwise it is moved
  to sent (or removed if sent is not defined in your .elmorc).

  stats_dump - dump statistics

  pgp_forget_passphrase - erease pgp passphrase from memory


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:
 + - attachment
 e - encrypted
 s - signed
   - no attachment


2nd column:
 N - New
 O - Old
   - read

3rd column:
 F - Flagged
 T - To be  deleted
 r - Replied
 f - Forwarded

4th 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 <sdas % gibas.org>

See also the THANKS file.

Mailing lists:

  * elmo-users % lists.sourceforge.net, for Elmo users
  * elmo-commit % lists.sourceforge.net, for developers
  * elmo-devel % lists.sourceforge.net, for developers

  * elmo-users-pl % lists.sourceforge.net, for polish users
  * elmo-devel-pl % lists.sourceforge.net, for polish developers
  
  