VMH - Vim Mail Handler ====================== 1. Introduction The vmh program consists of a vim script file, a perl library used by this script file and a few additional template files. It is meant as an addition or replacement for xmh and/or mh, two mail handlers running on must Unix system. This program will currently only run on UNIX systems. I wrote this scripts so that I could use all the features of vim while reading, filing and writing email messages, even if there is no X around, and without having to use the mouse. As I was using xmh and mh before, I decided to use the same directory layout as those programs, but with the extension that the directory structure could be as deep as necessary (xmh allows only one level). Therefore, vmh assumes that your email is stored in $HOME/Mail, with incoming email being in $HOME/Mail/inbox, and each message uses one file, the filename being a number. **************************************************************************** * * * WARNING: THIS IS STILL VERY UNSTABLE SOFTWARE. IF YOU USE IT TO ACTUALLY * * SEND AND RECEIVE EMAIL, BAD THINGS MAY HAPPEN! EMAIL COULD BE SENT TO * * THE WRONG PERSON, EMAILS YOU GET OR SEND COULD BE LOST, YOUR SYSTEM * * ADMINISTRATOR OR ISP ADMINISTRATOR MAY COME AFTER YOU BECAUSE OF FAULTY * * MAIL MESSAGES, YOUR COMPUTER MAY EXPLODE OR ANYTHING ELSE COULD HAPPEN. * * USE IT AT YOUR OWN RISK! YOU HAVE BEEN WARNED!!! * * * **************************************************************************** 2. Contacts / WWW I've put this program on the WEB to make it available to others. Hopefully, users will add more functionality and send it back to me so that I can add it and redistribute it again. Please send all email regarding this program to vmh@fleiner.com The newest version can always be downloaded from http://www.fleiner.com/vmh/ 3. New Features in version 0.2 - simple addressbook - Sorting mailing lists in the inbox folder - sending of mime compliant emails - decoding mime emails in place and/or piping data to programs or files - several small bugs have been fixed 4. Installation There is no installation script (this is deliberate, as I want you to look at the scripts, as some things are currently hardwired which will eventually become options of an install script. You need the following programs in order to be able to use vmh: - vim version 5.3 (newer versions work too), compiled with perl support (this is unfortunately no longer the default, you may have to reconfigure vim and recompile it) - The mh mail handler programs (actually, you will only need the 'inc' program - To read and write mime encoded email mmencode or mimencode is needed (this program is part of the metamail package and is often already installed. - to send email a working sendmail with the correct /etc/sendmail.cf is needed - To sign, encrypt and decrypt you will need gpg (GnuPG) or PGP, however, the hooks to use them are not included thanks to some US export laws. After you unpacked the archive file in some directory, you should find the following files: README this file vmh.vim vim script to initialize the vmh.pl the perl library, loaded automatically by vmh.vim default template for newly created emails reply template for replies forward template for forwards mime.top template for mime emails First, edit 'default', 'reply', 'forward' and 'mime.top' to define your email address and signature. If you have never used mh or xmh send yourself an email and then type > inc until it arrived. This will create the $HOME/Mail directory. Note that if you have a POP or IMAP email box you will need a program like fetchmail to regularly fetch your email and deliver it locally (or, if you write a perlscript such that vmh can actually read POP boxes, I will include it in the distribution :-) Now create two directories: $HOME/Mail/drafts $HOME/Mail/sent and copy the files 'reply', 'default' and 'forward' into $HOME/Mail/drafts and 'address' into $HOME/Mail Check vmh.pl to see if you need to change some of the variables at the beginning of the file (you should at least change $nocc). Create a script called vmh which changes its directory to the installation directory of vmh (i.e. where vmh.vim and vmh.pl can be found) and executes vmh -s vmh.vim). Example: #!/bin/sh cd $HOME/vmh vim -s vmh.vim If you would like to add functionality to vmh, you can create your own vim script and call your script instead of vmh.vim at the beginning. Just make sure that at some point you use :source vmh.vim. Now you should be able to start vmh by typing > vmh 5. Using vmh 5.1 Special Keys Whenever I use vmh, I use it inside an rxvt terminal emulator. This program has the special "feature" that it sends an character to vim whenever I press character (i.e. if I press t vim will see t). Therefore all the special functions available inside vmh are mappings of the form c and de, which c, d, and e being some characters or numbers. If your terminal emulator does send real characters to vim you may want to change vmh.vim (this will probably be an installation or even runtime option at some point). The same is probably true of the GUI version of vim, but I have never tried to run vmh in the gui version. 5.2 VMH Windows VMH has 5 different windows: email: used to display an email message you got or sent draft: used to work on an email message you want to send vmh_cache: lists of all the emails in a directory vim_dirs: list of all directories address: the address book When you start vmh, it will open two windows: the top one lists the email messages available in your inbox, and the bottom one is empty. The Cursor is in the upper window. Note that inbox has a very special property which is not shared among other directory windows: the mail messages are sorted in order to get email messages and replies together, and to sort out email lists. In order to get email lists working correctly you need to edit vmh.pl (search for the variables mailinglists and youremail) 5.3 Special Keys available in each window: vmh_cache and email (they have the same mappings, unless specifically noted). In most cases there is a current message, which is shown in the vmh_cache with a '>' as the very first character (a '*' denotes a new message). only vmh_cache: displays the message under the cursor in the window below and switches to this window zs rescans the directory structure. only mail: a open address book and insert email under cursor (the email extraction is not particularly great and needs some more work) zf write the current mime portion to a file (you should position the cursor in the header if possible, but not on the divider between mime parts) zt Replace the current mime part with the decoded version. Works for text/plain and text/html. In the latter case lynx is used to convert html to text. zx Show the current mime file with 'xv' (only useful if it is an image) zg Show the current mime file with 'gimp' (only useful if it is an image) zn Show the current mime file with 'netscape'. Only useful for html, gif and jpeg files. This will also only work if netscape is already running. zl Show the current mime file with 'lynx'. Only useful for html of course. zp Print the mime file to stdout (decoded of course) zd delete the current mime atttachment both windows: j displays the message after the current message k displays the message before the current message n displays the next message after the current one which has not been marked for deletion or moving into another directory p displays the next message before the current one which has not been marked for deletion or moving into another directory d mark the current message as one that needs to be deleted, and display the next message that is not marked g Switch to another directory. This will show you the list of all available directories. Move to the one you want and type m move a message to another directory. This will show you the list of all available directories. Select the one you want and type . After you selected the directory, the next unmarked message will be displayed. If you want to create a new directory, simply insert it in this file and type return. It will be created as soon as you commit the changes. c Commit the changes (emails are deleted and/or moved to other directories. Note that emails are not really deleted, but renamed such that there first character becomes a ','. However, if there is already such a file, it will be overwritten s Similar to commit, but also renames all remaining messages such that there is no longer "a hole" while counting them. zm pipes the current email message to metamail. Useful if it is a mime encoded email message. However, there are other options to read mime email: zi call 'inc' in order to include newly arrived messages. e Create a new email f Forward the current email r Reply to the current email (BE SURE TO CHECK THE HEADERS, THERE ARE SOME ERRORS CURRENTLY WHICH MANGLE IT!) The draft window Note that you can store the draft and reopen it later if you need. x Send the email fa Call the program 'fortune' and add the result to the signature (can be used several times, it will always replace the last version. zm Start a mime encoded email message (useful if you want to add attachments). You can do this whenever you wan, even after you wrote the mail message. za Attach a file (works only after creating a mime mail with zm zd Delete current mime attachment fs Call the program 'fortune' to create a one line fortune. qs Sign message with your gpg key (uses gpg) vmh_dir window either switch to the given directory or move the current email to this directory (depends on how you opened the window) q close this window g open the directory under the cursor m move the current email to the directory under the cursor address window close window and paste address under cursor into draft at the current cursor position email to this directory (depends on how you opened the window) q close this window i close window and insert current address at the cursor position (anything after a ':' is ignored) s sort window 6. Some internals Most of the file operations are done with perl script, while jumping around the windows is done with vim functions. Emails are sent by piping them through /usr/lib/sendmail. Make sure that you always send a valid email, there are nearly no sanity checks. For example, there must be an empty line after the header lines (really empty, with no spaces or tabs). Don't add multiple Cc: or To: lines, as I don't know how sendmail will react to this. If you are not sure about the format, read rfc821 and rfc822 for more details. 7. TODO-LIST (in no particular order) - Online Help - Better support for GPG - Support for PGP - Support for POP and IMAP servers (although you can always use fetchmail instead, and I believe some versions of mh support POP) - Better error checking before sending emails - perl script to replace 'inc'