exmh.README
Last modified: Wed Dec 28 19:58:32 PST 1994
exmh version: 1.5.3
Brent Welch, welch@parc.xerox.com

exmh is a TCL/TK based interface to the MH mail system.
You need wish (3.6 is best, >= 3.3 should work) and MH (6.7 or 6.8).

This version of exmh is *not* ready for Tk 4.0

Experienced EXMH installers should check FLASHES below and
the exmh.CHANGES file.

**************************************************

Please read through *all* of this, thanks, especially
the part at the end about the TK send command.

**************************************************

Please encourage your exmh users to REGISTER via the
Register menu entry under the Help... menu.  This let's
me track exmh usage and get user feedback.  I won't
abuse this registration - there is no obligation associated
with registration, but I would like all exmh users to do it.

All this does is send me a mail message.  You get to add your
comments, pro and con, about exmh.  I've learned a lot from
the registrations I have received so far.  Thanks!

**************************************************

RELATED PACKAGES
Find TCL and TK on
    ftp.aud.alcatel.com:/tcl
    ftp.cs.berkeley.edu:/ucb/tcl
Find MH on
    ftp.ics.uci.edu:/pub/mh
(optionally)
Find Metamail (for MIME support) on
    thumper.bellcore.com:/pub/nsb
Find Faces on
    cs.indiana.edu:/pub/faces
Expect is available as
    pub/expect/expect.tar.Z from ftp.cme.nist.gov
Japanization patch for Tcl and Tk
    srawgw.sra.co.jp:/pub/lang/tcl/jp
    tcl7.3jp-patch.gz, tcl7.3jp-update1.gz, tcl7.3jp-update2.gz,
    tk3.6jp-patch.gz, tk3.6jp-update1.gz, tk3.6jp-update2.gz.
    It seems that they will move the archives to ftp.sra.co.jp near future.


-----------------------------------------------
TK 3.6 BUG that causes core dump when iconified
-----------------------------------------------
There is a bug in TK >= 3.3 in the text widget that exmh manages to tickle.
It occurs when the exmh window is iconified, and it causes a core dump.
However, there is a patch that fixes this in the misc/tkText.patch file.
If you have TK 3.6 and
have applied Ousterhout's first patch, then you are ok.

--------------------------------------------
AIX BUG that results in no buttons or menus
--------------------------------------------
The Aix 3.2 compiler does not compile tkOption.c correctly when
optimization is turned on.  The symptom of this is a message like
exmh: Error in ./lib/app-defaults: missing colon on line 2
and there are no buttons or menus in the interface.
----------------------------------------------------------------------------

See exmh.FAQ for answers to some frequently asked questions.
This information is now available via the FAQ button in exmh.

FLASHES

1.6 will be compatible with tk 4.0, 1.5.3 is not.

1.5.3 has three bug fixes over 1.5.2, including the
    disabled buttons problem.

1.5.2 is has several minor patches over 1.5.1
Most notable is that it attempts to preallocate all needed colors.

1.5.1 is a stable release.
There are several bug fixes over 1.5, notably with 8-bit input and
    text/enriched processing.
3 new features crept in:
    <Button-2> pastes the selection, unless you drag the mouse for scrolling.
    Highlight URI - scan a message for URL and URN references.
    Mime Preview - in sedit you can "clip" the message to view it
	as it will appear to an exmh reader.

The man page has been chopped into 4 documents:
exmh.l - a tutorial
exmh-use.l - a more comprehensive user guide
exmh-custom.l - a guide to exmh customization
exmh-ref.l - a terse description of all buttons and menu entries.

8-bit character input is now supported by Sedit.

PGP is cleaned up even more.

Focus handling is cleaned up.

Help... has a bug report entry and a way to unofficially
register exmh users.

The Import facility converts mailbox folders into MH folders.
This will not work on all folder formats, just vanilla Berkeley mail.

There is an updated interface to Msg_Reply and friends that make it even
easier to define new variations on repl.  The two existing reply
functions have been moved into a Reply... menu.

Performance Hints:
Squeeze the last drop out of message display by disabling the
separator bars in message display. (Show Graphic Part Separator under MIME)

Really large folders make exmh run slowly.  Take this as a hint to
reorganize things into sub-folders if you have more than 500 or so
messages in a folder.

Bound the unseen folder search by defining the .mh_profile
Folder-Unseen: pattern pattern pattern
entry to name the folders to search under.  The default is *, so
all folders are searched.

Reverse Video:
It takes just a few resource settings in your ~/.exmh-defaults-mono
file to get reverse video on a black and white display:

! For widgets
*Background: black
*Foreground: white
! For highlights
*c_background: black
*c_foreground: white

Colorized headers:
Did you know you can colorize rfc822 headers in the message display
by setting *m_tagnames and related X resources?  This feature has been
around for some time, but seems to be little-known.  Here's what I
have in my ~/.exmh-defaults-color file.

*m_tagnames:    hidden subject from x-filters-matched content-type x-mailer repl
ied replied-to
*m_hidden:      -font 6x10
*m_subject:     -foreground blue
*m_x-filters-matched:   -foreground "medium sea green"
*m_content-type:        -foreground "medium sea green"
*m_x-mailer:    -foreground "medium sea green"
*m_from:        -foreground blue
*m_replied:     -foreground "violet red"

The *c_ family of resources has expanded a bit to allow control of
both foreground and background colors for current, unseen, moved, and
delete messages.

Starting with Exmh 1.3, TK 3.2 is no longer supported.

New goodies in misc - check misc/README
    (flist C program)
    (Xauthority hints)

MAILING LISTS
There are now three exmh-related mailing lists.
YOU ONLY NEED TO PICK ONE LIST.
Send your subscription requests to:
exmh-announce-request - to receive release notices
exmh-users-request - to get exmh-announce + user discussion
exmh-workers-request - to get all of the above plus exmh hacker discussion
The mailing lists have the following addresses, but please send
your subscription requests to the -request aliases.
exmh-users@parc.xerox.com
exmh-workers@parc.xerox.com


ACKKNOWLEDGMENTS

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.

Thanks to Xerox/PARC for tolerating my work on exmh.

Honorable mentions:
John LoVerso (loverso@osf.org) who contributed the popup nested folder display.
Chris Garrigues (cwg@mcc.com) who rewrote the mime display code.
Marc VanHeyningen (mvanheyn@cs.indiana.edu) who wrote the mailcap parsing code.
Allen Downey, downey@cs.berkeley.edu who provided PGP support.
Scott Stanton, sstanton@eng.sun.com who contributed the alias browser.
Stefan Monnier, monnier@di.epfl.ch updated the PGP code
Anders Klments, klements@it.kth.se also updated the PGP code, and more

FEATURES

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

    MIME support!  Displays richtext and enriched directly.  Parses
    multipart messages.  A popup menu under the right button can invoke
    external viewers (metamail) for things not directly supported.
    Built-in editor allows simple composition of text/enriched format
    and multipart messages (via Insert Part).

    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.
    (Depends on proper TK send functioning.  See notes below.)

    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

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.

Upon startup, exmh.install looks around for .exmhinstall files from
previous installations.  It will ask you which one you want to use,
unless there is already one in the current directory.  You can also
use the Conf button to look for config files.  This lets you maintain
a set of config files, .exmhinstall.* if you need this for multiple
architectures, for example.

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.  The Test button now automatically changes the
run-time value to "./lib" in order to test before installing.  So,
the only reason for the distinction between install-time and run-time
is for AFS environments where writable and read-only volumes might
have different names.

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).

WARNING: you need to specify an alternate location - the
install is *not yet* smart enough to handle leaving the script
library where you unpacked the tar file.

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

1. Patch - to apply site-dependent patches to exmh.
    The configuration is saved into a .exmhinstall file.
2. TclIndex - to compute the auto-load library index.
3. Test - to run the patched script.
4. Verify - to see what the Install will do.
5. Install - to 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.

VERY IMPORTANT. PLEASE READ. SOURCE OF MANY PROBLEMS. READ THIS HERE :-)

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 -DTK_NO_SECURITY.  A manifestation of problems are
that background processing doesn't work: new messages are not scanned
into the current folder, the flag icon doesn't behave, and so on.
Similarly, use of the exmh-async wrapper script also fails.
If you cannot recompile wish, then the trick is to get your X server process
started with the right incantation.

You can easily test send (and my installation process should have...)
Just run wish, and type in the following command to it:

send exmh {Exmh_Status "Hello world"}

Obviously, make sure exmh is running first.

If you get an error, you need to recompile the TK library, or learn how
to start up the X server so it does the right Xauthentication stuff.

Here is one example, for SunOS openwindows.  This is an excerpt from
a .xerverrc file:

    if [ ! \( -d $HOME -a -w $HOME \) ]; then
      echo "Warning: Can't write X authority file" 1>&2 ;
      auth_args=""
    else
      authfname=$HOME/.xnews.`uname -n`$DISPLAY
      ${OPENWINHOME}/lib/mkcookie $authfname -auth magic-cookie
      auth_args="-auth $authfname"
    fi ;
    ${OPENWINHOME}/bin/xnews $auth_args $server_args $xnews_config_args ;;

The general picture of whats going on is this:
1) some program generates a magic cookie (arbitrary string) and writes
this to a file.
2) The name of this file is passed to the X server
3) The X server writes an entry for the DISPLAY into your ~/.Xauthority
file.
4) Xlib reads ~/.Xauthority when you create a window, and passes the
cookie value back to the X server.

If you have the xauth program and your server doesn't like to be told about
the intermediate file, then you can use xauth to write into the
~/.Xauthority file for you, and apparenty the right thing will happen.
If this sounds vague, it is.  For precise details, do some experimentation
or ask your local X guru.  If you come up with particular solutions,
feel free to post them to comp.lang.tcl so other folks with similar
configurations can learn how to do the right thing as well.

See also misc/Xauthority for similar info.

CONCLUDING REMARKS

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).  There is a
Register User menu entry under the Help... menu that you
can use for this purpose.  Encourage your users to do this
if you are an administrator at a large site.

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 What Happened: 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
	welch@parc.xerox.com

