exmh.README

Brent Welch, welch@parc.xerox.com

Last modified: Mon Nov 29 14:29:50 PST 1993
exmh version: 1.1
See exmh.CHANGES for what's new in this version.

exmh is a TCL/TK based interface to the MH mail system.
All you need is wish (3.3 is best, 3.2 should work) and MH (I have 6.7).

(When I tried TK3.4, wish crashes.  I've had mixed reports on this.)

Thanks go to Ed Oskiewicz for inspiring me with an initial verison,
which is much modified by now.  Thanks also go to many beta testers
that put up with buggy versions and suggested many features that
are now part of exmh.  Feature requests that come with code diffs
to implement them are especially nice.

As well as providing the usual layer on top of MH commands, exmh
has a number of other features:

    Color feedback in the scan listing so you can easily identify
    unseen messages (blue), the current message (red), deleted
    messages (gray background), and moved messages (yellow background).
    Xresources control these color choices.

    Monochrome displays highlight unseen messages with underline,
    current message in reverse video, deleted messages with cross-hatching
    background, and moved messages with stippled background.

    A folder display with one label per folder.  Color highlights
    indicate the current folder (red), folders with unseen messages
    in them (blue), and the target folder for moves (yellow background).
    Nested folders are highlighted by a shadow box.  A cache of
    recently visted folder buttons is also maintained.  Monochrome
    highlights are reverse video for the current folder, bold box
    for folders with unseen messages, and stippled box for the
    target of move operations.

    Clever scan caching.  MH users know that scan is slow, so
    exmh tries hard to cache the current state of the folder to
    avoid scanning.  Moves and deletes within exmh do not
    invalidate the cache, and background incs that add new messages
    are handled by merging them into the scan listing.  The
    scan cache is compatible with xmh.

    Facesaver bitmap display.  If you have a facesaver database
    on your system, exmh displays the bitmap face of the person
    that sent the current message (or their organization).
    Otherwise, it just displays a boring EXMH logo.

    Background inc.  You can set exmh to run inc periodically,
    or just to periodically count up the messages in your mail spool file.

    Various inc styles.  Exmh knows about three styles of inc usage:
    Inc from your spool file to your inbox folder.
    Inc from your spool file or POP host to a set of dropboxes as specified
    by your ~/.xmhcheck file.
    Inc from your spool file directly into folders.  Exmh can run the MH
    filtering program (slocal) for you, or you can let an external agent
    presort mail into folders for you.

    Searching over folder listing and message body.

    A dialog-box interface to MH pick.

    A simple editor with emacs-like bindings is provided by default.
    It has an interface that lets you tweak key bindings.

    Editor interface.  You can hook up exmh to TCL based-editors
    like mxedit quite easily.  A script is also provided, exmh-async,
    for using terminal based editors like vi.  The emacsclient.README
    file has hand-wavy instructions for using emacsclient to talk
    to an emacs server.

    User preferences.  You can tune exmh through a dialog box.  The settings
    are saved in an Xresource-style file named .exmh-defaults.  You can
    also put font and color resource specifications in this file, plus
    there are a few random parameters not exposed via preferences.

    User hacking support.  A user library of TCL routines is supported.
    The main implementation is chopped up into many smallish modules.
    So, you can modify a copy of some module to put your favorite mail
    reader hack in without affecting others (or convincing me to put
    it into the main line).  There are also a number of places where
    hook procedures are used so you can refine the behavior of things
    like composing a reply message.  Details in the man page.

Installation is done via the exmh.install script.  Invoke it as:

    wish -f exmh.install

This puts up a dialog box that lets you patch various file system
specific pathnames and enable or disable features that your
system cannot support (e.g., facesaver, sound).  You can test
out exmh via this dialog before installing it.

In the install dialog, the "Script Library" and the "Install lib directory"
are usually the same place.  The script library is the run-time value
of the library directory, while the install lib directory is the
install-time value.  To test exmh before installing, set the Script
library to "./lib".  Remember to change the Script library back to
the Install library before patching and installing.  When you hit
the Patch button, some consistency checks are done and a relative
pathname will trigger a warning.  You can ignore this when you are
testing, but you should install a working copy that only references
absolute pathnames.

Remember to choose a script library directory that exmh can take up
all for itself.  The install is *not* smart enough to make an exmh
subdirectory in a common lib dir (e.g., /usr/local/lib).

After you set things up in the dialog box, then hit some buttons:

1. Patch - apply site-dependent patches to exmh.
2. TclIndex - compute the auto-load library index.
3. Test - run the patched script.

4. If this works ok, then change the Script library pathname
to match the Install library directory and:

5. Patch again.
6. Save - save the settings into .exmhinstall.
7. Verify - see what the Install will do.
8. Install - install exmh.

If the install fails to work gracefully on your system, let me know!
One common error is to get a complaint about the procedure "Exmh" not
being defined.  This happens when the value of the script library
is not correct.  Its a bit of a pain to first do Test with the script
library set to ./lib, and then remember to change it to be the same
as the install library (modulo AFS wierdness) before installing, but
perhaps you can beef up install.tcl for us all.

exmh depends on the TK send facility for its background processing.
With TK 3.3, send now uses xauthority mechanisms by default, unless
you compile TK with -DNO_SECURITY.  A manifestation of problems are
that background inc'ing appears not to work.  If you cannot recompile
wish, then the trick is to get your X server process started with
the right incantation.  No amount of dinking with xauth will help,
and in fact under normal circumstances you never run xauth.  Again,
its all in starting up your X server properly (or -DNO_SECURITY).

If you end up using exmh on a regular basis, also let me know!
If I can tell my managers that there are N users of my mail
reader, there is a greater chance I'll have time to hack up
more tools in the future (and still get paid).

Finally, please take time to read the man page before asking too many
questions.  If exmh gets an internal error it will display a dialog
box with a TCL trace back and a User Input: area.  You can type short
note into that area, and then hit the "send to exmhbugs" button in
order to file a bug report.  I'll consider feature requests, but
basically I'd appreciate it if you'd code up your feature and
send me some diffs or just the whole file that is affected.
----------------------------------
	Brent Welch	Xerox-PARC