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: 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 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 { } 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 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: , , , , , , , , , , , , , , , , , ... A three-digit octal code of a key prepended with a backslash. E.g.: \015 Every key specifier may be additionaly prepended with "\M". The keybinding is active only when you press a key along with alt/meta key. VII. Rules ---------- A rule tells elmo where the newly fetched message should be delivered to. We have designed a simple pseudo-language that lets you define rules so that they seem to be sentences in your natural language. Let's take a look at a simple example: rule elmo { When SUBJECT header contains a string 'elmo', move the message to folder elmo. } This rule acts exactly how it is supposed to: moves messages to folder elmo, when they contain a string "elmo" somewhere in the subject. Elmo doesn't try to analyze a sentence itself, but it reduces it into few most important tokens. The example rule is reduced to: rule elmo { SUBJECT 'elmo' elmo. } and both rules are equivalents. First elmo looks for a capitalized header field name. It may be one of: SUBJECT, TO, CC, FROM, TOCC (which means TO or CC). Then elmo looks for a quoted string. If the string is single-quoted, the pattern is taken literally. Double- quoted string is supposed to be a valid regular expression, against which the header field is matched. The last thing is a name of a folder followed by a dot, or a semicolon. Let's take a look at more complex example: rule elmo_and { When SUBJECT header contains a string 'elmo', and TO header matches a regular expression "[Ee]lmo", move the message to folder elmo. } which is reduced to: rule elmo_and { SUBJECT 'elmo' TO "[Ee]lmo" elmo. } There may be more than one constraint before a folder name. They must all be satisfied for the rule to be executed. Sometimes you'd like to define a rule with an alternative. The only way to do it is to repeat the same destination folder. E.g.: rule elmo_or { When SUBJECT header contains a string 'elmo', move the message to folder elmo; same apply if TO header matches a regular expression "[Ee]lmo", just move it to elmo. } which is reduced to: rule elmo_or { SUBJECT 'elmo' elmo; TO "[Ee]lmo" elmo. } When a new message is fetched from a remote machine, elmo executes rules one by one in the same order, as they have been defined in configuration file. If the message satisfies all conditions of the rule, it is moved to the rule's destination folder. If there is no appropriate rule, the message is delivered to a folder defined by an "inbox" field of "mailbox" variable, or the folder "inbox" (if no such field is defined). When there is no folder, where a message could be delivered, it is dropped and may be found in tmp subdirectory of a current folder. VIII. Templates --------------- What happens when you compose a new message? Elmo tries to open a message template, and use it to create a new message which is then opened in your editor. The default template is installed in directory /usr/local/share/elmo (when compiling program from sources) or in /usr/share/elmo (when installing from a precompiled binary package, such as deb or rpm). It looks like: ---------------- begin ---------------- From: "$address.name" <$address.email> To: $to Subject: $subject $quote $=$mail.quoted $signature ---------------- end ---------------- It looks pretty similar to what you see in your editor, when composing a message, but is not exactly the same. All the tokens beginning with '$' are replaced during program run with appropriate values. For example: when you reply to a message, "$to" is replaced with author of the message, "$address.email" with your email address, and so on. You may control values of these properties, but we'll learn how to do it later. There is a special token "$=", which is used to point a place, where cursor should be placed when composing a message. You also have to properly define editor variable, so that your editor is told where to place a cursor. These are some examples: set editor 'emacs +%l %f' set editor 'emacsclient +%l %f' set editor 'jed -g %l %f' set editor 'nano +%l %f' Please refer to your editor's manual to learn how to invoke it with additional information about cursor's position. The only thing, that haven't yet been covered is how to place a "$" character in a template. You have to escape "$" with an additional "$". IX. Properties -------------- Sometimes setting a variable is not enough, because you'd like it to have different values depending on some other settings or situation, where the variable is used. That's why we developed properties. Suppose you use a different email account when sending messages to mailing lists, and different one for personal mail. You could say, that your email address depends on recepient's address. Let's look at an example: property address.email (to){ '@lists.sourceforge.net' => 'johnny@no.such.host.com' '' => 'johnny@personal.mail.com' } Now, whenever Elmo needs a value of your email address, it will first check value of property "to" to see if it contains a string @lists.sourceforge.net. When Elmo needs this value? Each time you compose a message (no matter if you compose a new one, reply, or forward) Elmo needs your email address to replace "$address.email" with it's value. If you define no property at all Elmo will still work, because it may guess what you meant, and use some predefined defaults. If the template file include a property, that Elmo doesn't know, and is not defined by user, it will put an empty string as property's value. We'll go through a more complicated example before listing all known properties with their default values: property quote (action mail.from.groups mail.from.sex mail.from.name_email){ 'reply' 'polish' 'F' => "%d napisala:" 'reply' 'polish' 'M' => "%d napisal:" 'reply' 'german' => "%d hat geschrieben:" 'reply' => "%d wrote:" '' => "" } When you reply to a message, you usually put a sentence that introduces a quoted message. I come from Poland, and we use different quotation when replying to a man, and different when replying to a woman. However the quotation should be german for german-speaking people, and english as a fallback. There are two ways, how you may match any value of the argument. First is to omit the constraint. I omitted mail.from.name_email in all alternatives because the quote property doesn't really depend on it. I omitted sex for german people, and groups for other people. The last alternative shows the second way of matching any value - just use an empty string. The property above is exhaustive. That is: there is no such combination of actual argument values, that couldn't be matched by one of alternatives. If we removed the last alternative, the property wouldn't be exhaustive any more. If Elmo encounters a combination, for which it cannot find a matching alternative, it uses it's default value. I have already written that property "quote" doesn't really depend on mail.from.name_email. So why have I listed it between parentheses? Because it is the only way I can refer to it's value in the result string. Use '%' character followed by n-th letter of alphabet (lowercase) to refer to n-th argument. Thus "%a" is replaced with value of the first argument, "%b" with second, and "%d" with fourth - mail.from.name_email in our example. X. MIME handlers ---------------- When you receive a message with an attachment, you may open the attached file without quitting Elmo. However you need to tell Elmo what program it should run. Attachments are sent with information about their type. You can see it in the window with list of attachments. You can then bind a program to a specific type, which will handle this type of attachments. Let's look at an example: handler image/* "image_viewer %f" It means that each time you press enter on an attachment, which type is image/* (where '*' means anything) you want a program image_viewer be executed with a name of the file containing the attachment. In other words: you want image_viewer to open images that come as attachments to messages. The order in which you define handlers is very important. Let's take a look at an example: handler text/html "links -no-connect -force-html file://%f" handler text/* elmo What we'd like to do is to open html attachments in links (a console web browser), and all other text attachments in elmo window. Unfortunately this won't work because the second rule will override the first setting, and elmo will open every text attachments, including text/html. To fix it, you need to reverse the order of these rules. When you send a message with attachments Elmo needs to know, what type does it have. Elmo has few predefined types, and uses the special type "application/octet-stream" as a fallback. You may extend the set by supplying a mime setting, like for example this one: mime application/pdf "\.pdf$" It says, that files that match a regular expression "\.pdf$" (whith pdf extension) are of type "application/pdf". XI. Character sets ------------------ Elmo may translate some character sets to some other. You only need to specify how. Let's take a look at an example: translate utf-8 iso-8859-2 translate windows-1250 iso-8859-2 Both settings make Elmo display text parts of messages according to the second character set when they are sent with the first character set. So each time I receive a utf-8 message, it is transparently converted to iso-8895-2, and displayed correctly on my terminal. This method has a drawback. It is impossible to display a message, that contains character from many character sets. This constraint comes from the ncurses library, which handles only single byte characters. Setting translate iso-8859-1 utf-8 will make elmo crash. = Contact = =========== Homepage: * http://elmo.sourceforge.net Principal author: * rzyjontko Additional authors: * Artur Skura * Krzysztof Gibas 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 = Function reference = ====================== abook_add_first - move to the first position abook_add_hide - close this window abook_add_hit - add this address to addressbook abook_add_last - move to the last position abook_add_next - move on to the next position abook_add_next_page - move on to the next page abook_add_prev - move to the previous position abook_add_prev_page - move to the previous page abook_add_show - open address list abook_change_email - change email abook_change_foreign - change foreign flag abook_change_groups - change groups abook_change_name - change name abook_change_official - change official flag abook_change_sex - change sex abook_compose - compose new message abook_first - move bar to the first position abook_hide - close this window abook_hit - select / unselect this address abook_hit_all - revert selection abook_insert - insert new address abook_last - move bar to the last position abook_next - move bar to the next position abook_next_page - move on to the next page abook_prev - move bar to the previous position abook_prev_page - move to the previous page abook_remove - delete address(es) abook_search_backward - search backward abook_search_forward - search forward abook_set - select this address abook_set_all - select all abook_show - open address book window abook_sort - sort address book abook_unset - unselect this address abook_unset_all - unselect all attach_first - move to the first position attach_hide - close 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_last - move to the last position attach_next - move on to the next position attach_next_page - move on to the next page attach_prev - move to the previous position attach_prev_page - move to the previous page attach_refresh - refresh this window attach_save - save attachment to file attach_save_all - save all attachments in specified directory attach_show - show attachments box_selection_first - move to the first position box_selection_hit - open the selected box box_selection_last - move to the last position box_selection_next - move on to the next position box_selection_next_page - move on to the next page box_selection_prev - move to the previous position box_selection_prev_page - move to the previous page box_selection_re_read - re-read mailbox box_selection_search_backward - search forward box_selection_search_forward - search backward choose_cancel - cancel selection choose_first - move to the first selection choose_last - move to the last selection choose_next - move on to the next selection choose_prev - move to the previous selection cmd_after_startup - executed right after startup. Particularly useful, when you want to perform some actions at the very beginning. This function is executed only once during the program execution. cmd_nothing - do noting. Particularly useful, when you want to disable a key. cmd_quit - quit elmo debug_first - scroll to the top debug_last - scroll to the bottom debug_next - scroll down debug_next_page - scroll down one page debug_prev - scroll up debug_prev_page - scroll up one page debug_show - refresh the view fetch_all - fetch all messages from the server fetch_close - close connection fetch_del_mail - delete selected message. This command schedules a message to be deleted, right after the connection is closed. Such a message may not be fetched. fetch_first - move to the first position fetch_get_mail - fetch selected message fetch_last - move to the last position fetch_mark_mail - mark message as fetched fetch_next - move on to the next position fetch_next_page - move on to the next page fetch_open - open window with message list. Before a window is opened, elmo fetches headers of messages, that hasn't been fetched yet. You are then presented a list of messages, that you may fetch or delete. fetch_prev - move to the previous position fetch_prev_page - move to the previous position fetch_rset - reset state of the connection. This command clears a "delete" flag from all messages scheduled for deletion. They may fetched then. folder_at_bar_move - this function is executed each time a bar in folder moves folder_at_leave - this function is executed each time a box is being left folder_bar_first - move bar to the first position folder_bar_last - move bar to the last position folder_bar_next - move bar to the next position folder_bar_prev - move bar to the previous position 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_flag_all - flag all messages 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_flag_invert - invert flag folder_flush - remove spam and refresh the view folder_kill_mail - permanently delete message. Remove selected messages from the box. It is then impossible to recover them. folder_make_read - mark selected messages as read folder_move_mail - move selected message to another box folder_next_unread - move bar to next unread message folder_page_next - move on to the next page folder_page_prev - move to the previous page folder_prev_unread - move bar to previous unread message folder_recenter - place bar in a center of the screen folder_remove_flag - removes message flag folder_scroll_down - scroll window down folder_scroll_up - scroll window up folder_search_backward - search backward folder_search_forward - search forward folder_sort_date - sort messages by date folder_sort_from - sort messages by from folder_sort_subject - sort messages by subject folder_sort_threads - group mails in threads 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_toggle_flag - toggle flag folder_unflag_all - unflag all messages folder_update - re-read mailbox help_beg - move to the top help_close - close help window help_end - move to the bottom help_next_page - scroll down one page help_open - open help window help_prev_page - scroll up one page help_scroll_down - scroll down one line help_scroll_up - scroll up one line 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_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. interface_prev_window - switch to the previous window interface_redraw - redraw the whole screen. Redraw the whole window. Very useful, when one of other application corrupts your console. mailreader_bottom - move to the bottom mailreader_close - close this window mailreader_header_switch - toggle display mode (header / message) mailreader_line_down - scroll down mailreader_line_up - scroll up mailreader_load - load selected message to mailreader window mailreader_page_down - scroll page down mailreader_page_up - scroll page up mailreader_search_backward - search backward mailreader_search_forward - search forward mailreader_show - open message window mailreader_top - move to the top mybox_create_box - creates a new box pgp_forget_passphrase - erease pgp passphrase from memory read_abort - abort reading input read_accept - accept the input read_backward_char - move back a character read_backward_word - move back over a word read_begin - move to the start of the line 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 read_complete - attempt to perform completion on the text before point read_del_char_back - delete the character behind the cursor read_del_char_fwd - delete the character at point read_del_word_back - delete the word behind the cursor read_del_word_fwd - delete the word after the point read_end - move to the end of the line read_forward_char - move forward a character read_forward_word - move forward over a word read_kill_line - kill the text from point to the end of the line select_search_backspace - delete last character from search string select_search_backward - repeat backward search select_search_forward - repeat forward search sender_add_attachment - attach a file sender_change_bcc - change bcc sender_change_cc - change cc sender_change_from - change from sender_change_reply_to - change reply-to 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_subject - change subject sender_change_to - change to sender_change_type - change content-type of attachment 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_delete_attachment - remove attachment sender_first - move to the first position 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_last - move to the last position sender_next - move on to the next position sender_next_page - move on to the next page 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_open_fwd - forward the message. Forward the selected message. You are asked for recepients of the message. 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_prev - move to the previous position sender_prev_page - move to the previous page 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