                      -*- Mode: Indented-Text -*-


			     XFaces 2.1
			Christopher B. Liebman
			liebman@zod.clark.net
			   January 11, 1994

What is XFaces?

       XFaces is a program that will display an image for each
    piece of mail in your mail box.  This lets you know at a
    glance who you have mail from.  XFaces starts out (when you
    have no mail) looking like a color xbiff.  As you receive
    mail XFaces becomes a column of mail images.  Some of XFaces
    features:

      - Both mono and color images.

      - Optional Shaped window support with both xpm and xbm.

      - Sound support using the NetAudio protocol. The NetAudio server 
        currently supports Sun's SparcStation (SunOS 4.1.X and Solaris 2.2),
	SGI's Indigo and NCD MCX X terminals running NCDware 3.1 or later.

      - Face images can be "compressed" so that each image will only
        show up once on your display.  This way, if you receive 30 messages
        from one user, list or whatever the image will only show up once.

      - Sounds can also be compressed so that they will only play once
        each.

      - You can use regular expressions to search the To, Cc, Subject,
	and From lines to choose images and sounds. This lets you
	specify an image/sound for mail that comes from a mailing list.

       XFaces is based on the Xt Intrinsics (-lXt) and the Athena
    Widget set (-lXaw).  To build in Xpm support you need the
    xpm library (-lxpm) version 3.2 or later.  To build in the
    sound support you will need NetAudio 1.1 or later.
    Both the xpm and the NetAudio distributions and publicly
    available with anon ftp from ftp.x.org in the contrib
    directory.

What machines will XFaces run on?

       XFaces as been compiled and tested on the following
    machines/OS':

    	Sun Sparc 10	SunOS 4.1.3	(MIT X11R5)
	Sun Sparc IPC	SunOS 4.1.1	(MIT X11R5)

       Please help me add to this list.  I am really interested to
    find out how well this works on other machines.  Currently the
    above machines are the only ones that I have access to.

Building and Installing XFaces

       You need Imake. You need to look at the Imakefile in this directory
    to see the definitions for XPM,SOUND,SHAPE are what you want.  By default
    All three are compiled in.  If you do not want one of them, just comment
    out or delete the #define. Sound support has another option USE_BUCKETS. 
    If this is defined then XFaces will store the sounds for all active sounds
    in the audio server.  If you are using NetAudio 1.1 on a sparc then you
    will either neet to disable the BUCKET support or apply the included patch
    to ausun (the patch is in ausun.patch).  The bug in the sun NetAudio server
    causes a weird audio "glitch" that I noticed when playing from buckets.

       Next to build the Makefile run:
	    xmkmf

       Then to build XFaces run:
    	    make
    
       To install XFaces type:
	    make install

How to set up XFaces

       I currently am not using the path bases search
    mechanism so the enclosed XFaces app defaults file does
    not have any good examples of that.  My current
    configuration is image files in /usr/images and sound
    files in /usr/sounds and all mapping done in the XFaces
    app defaults file and in users local defaults.

       Included in this release are a number of sample icons
    that I use.  Also the sample XFaces app defaults file
    contains examples of using the before bindings to show a
    particular image/sound for items from a mailing list.

       I will be glad to help anyone who is having problems
    setting up XFaces or anyone who has any questions about
    XFaces.

How does XFaces decide what image?

       First the resource "XFaces.beforeImageBindings" is
    retrieved. This resource contains a list of pattern/image
    name pairs.  Each pattern is applied to the To, Cc, From and
    Subject lines from the mail message.  If a match is found
    the image name is used to locate the actual image file. See
    image name mapping for how the files are located and the
    various extensions and what they mean.

       Next if there was no match from the beforeBindings the
    the resource "XFaces.image.user@host" is looked up where
    user is the user name from the From field and host is the
    users host from the From field.  If this lookup succeeds then
    the string value retrieved is used as an image name. If that
    fails then the resource "XFaces.image.user" and
    "XFaces.image.host" are tried.

       If there still is no image then a path based search is
    tried.  First a new image name is constructed using the
    "XFaces.faceImagePath" + "/user@host". Then
    "XFaces.faceImagePath" + "/user" and finally
    "XFaces.faceImagePath" + "/host".  In other words the
    directory given by the string value of the
    "XFaces.faceImagePath" resource contains image files named
    things like: user@host, user@host.xpm, user.xpm, host.xbm,
    etc.

       If that fails to produce then the resource
    "XFaces.afterImageBindings" is looked up.  This works just
    as the "before" bindings did.

       Finally, if there is still no image then the string
    "user@host" will appear as the image.

How does XFaces decide which sound?

       First there is a "XFaces.beforeSoundBindings" just like the
    the images, except that we use the values as sounds.

       If the before bindings had no match then the resource
    "XFaces.sound.user@host" and then follows the same pattern
    as the images.

       Then there is a path based search using
    "XFaces.faceSoundPath" as the base and proceeding like the
    images.

       Finally there is an after binding, just like the images.  If
    nothing is matched here then no sound is played for the
    face.

Image Name Mapping

       If the image file name does not begin with "/", "./", or
    "../" then the resource "XFaces.imagePath" is prepended.
    The following are attempted:

	file		(as an xpm file, loading shape mask is present)
	file-shape.xpm	(same as previous)
	file		(as shaped xbm file, must have matching -mask file)
	file-shape.xbm	(same as previous)
	file		(as xbm file)
	file.xbm	(as xbm file)

       Here is an example XFaces.imagePath is /usr/images and the
    image name is liebman the the following files will be tried:
    (I hope that I got this right! :^)

	/usr/images/planet		(as shaped xpm)
	/usr/images/planet-shape.xpm	(as shaped xpm)
	/usr/images/planet		(as xpm)
	/usr/images/planet.xpm		(as xpm)
	/usr/images/planet		(as shaped xbm with
					    /usr/images/planet-mask)
	/usr/images/planet-shape.xbm	(as shaped xbm with 
					    /usr/images/planet-shape.xbm-mask)
	/usr/images/planet		(as xbm)
	/usr/images/planet.xbm		(as xbm)


Sound Name Mapping

       If the sound file name does not begin with "/", "./", or
    "../" then the resource "XFaces.soundPath" is prepended.
    The following are attempted:

	file
	file.au
	file.snd
	file.voc
	file.wav
	file.wave

       Here is an example XFaces.soundPath is /usr/sounds and the
    sound name is crash the the following files will be tried:

	/usr/sounds/crash
	/usr/sounds/crash.au
	/usr/sounds/crash.snd
	/usr/sounds/crash.voc
	/usr/sounds/crash.wav
	/usr/sounds/crash.wave

Sample face images

       I have placed a number if images that we use for 
    XFaces in the images subdirectory.  You will want to copy
    them to your images directory.

Resources

       Here is a list of application resources that XFaces
    uses:

    XFaces.spoolFile
    	This can be used to specify your mailbox.

    XFaces.spoolDir
        This can be used to specify the directory your
	mailbox is in.

    XFaces.imagePath:
    	The directory that contains the image files.

    XFaces.soundPath:
    	The directory that contains the sound files.

    XFaces.faceImagePath:
    	The directory that contains the image files named
	with mail address format (liebman@zod.clark.net.xpm,
	etc).

    XFaces.faceSoundPath:
    	The directory that contains the sound files named
	with mail address format (liebman@zod.clark.net.snd,
	etc).

    XFaces.update:
    	How often to check for new mail in seconds. The
	default is 60.

    XFaces.volume:
    	The volume at which to play sounds. The default is
	60.

    XFaces.fromField:
    	This resource specifies which mail header to use as
	the from header.  The default is the old "From "
	header.

    XFaces.noMailImage:
    	The image to use when you have no mail. The default
	is "nomail".

    XFaces.noMailSound:
    	The sound to use when you have no mail. The default
	not to play a sound with no mail.

    XFaces.compressImages:
    	Only show each image once in the image display. The
	default is True.

    XFaces.compressSounds:
    	Only play a sound once. The default is True.

    XFaces.useSound:
        Play sounds.  The default is True.  A user can
	disable sounds for his XFaces by setting this
	resource to False in his resources.

    XFaces.useShape:
    	Use shaped images if available.  This defaults to
	true.

    XFaces.beforeImageBindings:
    XFaces.afterImageBindings:
    XFaces.beforeSoundBindings:
    XFaces.afterSoundBindings:
    	This resources specify patterns and associate an
	image or sound with any mail that matches the
	patterns. The patterns are applied to the From, To,
	Cc and Subject headers from the mail.


Bugs (bugs? never! :^), Fixes and Enhancements

       If you find any bugs or have fixes for bugs or have
    suggestions for enhancements or have patches for enhancements
    please send them to me at:

	liebman@zod.clark.net

    I will welcome *any* improvements to the documentation!

-------------------------------------------------------------------------------
 
		 Copyright 1994 Christopher B. Liebman

     Permission to use, copy, modify, distribute, and sell this software
     and its documentation for any purpose is hereby granted without fee,
     provided that the above copyright notice appear in all copies and that
     both that copyright notice and this permission notice appear in
     supporting documentation, and that the name Christopher B. Liebman not
     be used in advertising or publicity pertaining to distribution of this
     software without specific, written prior permission.

    THIS SOFTWARE IS PROVIDED `AS-IS'.  CHRISTOPHER B. LIEBMAN, DISCLAIMS
    ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING WITHOUT
    LIMITATION ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
    PARTICULAR PURPOSE, OR NONINFRINGEMENT.  IN NO EVENT SHALL CHRISTOPHER
    B. LIEBMAN, BE LIABLE FOR ANY DAMAGES WHATSOEVER, INCLUDING SPECIAL,
    INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING LOSS OF USE, DATA, OR
    PROFITS, EVEN IF ADVISED OF THE POSSIBILITY THEREOF, AND REGARDLESS OF
    WHETHER IN AN ACTION IN CONTRACT, TORT OR NEGLIGENCE, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

