xfaces - mail image display for X

Acknowledgements

       Special thanks to Rich Burridge.  A lot of the concepts that now exist in XFaces came from faces first.

       Thanks also go to James Ashton for the X-Faces header face compression / decompression code.

                                                                                                      XFACES(1x)

Author

       Christopher B. Liebman (liebman@zod.clark.net)

Description

XFaces  version 3.0 is a program that will display an image and optionally play a sound for each piece of
       mail in your mail box. Additionaly, you can have a shell command executed. This lets you know at a glance
       (or a listen, or a whatever) 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 (or a number of columns) of mail icons.

       XFaces can also be used to monitor other lists using the -e option or the listCommand resource.

Name

       xfaces - mail image display for X

Options

Xfaces accepts all of the standard X Toolkit command line options as well as the following options
designed to be compatible with Rich Burridge's faces program:

-c<columns>
Specify the number of images that faces will allow before starting a new row. This is also
available as resource XFaces.frame.maxWidth.

-e<command>
Run <command> and use output for faces list. This is also available as XFaces.listCommand.

-f<facedbpath>
This option set the default facedb search path to the colon separated list of directories
specified in <facedbpath>. Also available as resource XFaces.facedbPath.

-h<imageheight>
This option sets the height used internally by XFaces to layout images in a tiled fashion. This
is also available as the resource XFaces.frame.tileHeight.

-p<updatetime>
Specify the amount of time to wait between checks for new mail. Also available as resource
XFaces.update.

-s<spoolfile>
This option specifies an alternate mail spool file to watch. Also available as XFaces.spoolFile.

-w<imagewidth>
This option sets the width used internally by XFaces to layout images in a tiled fashion. This
is also available as the resource XFaces.frame.tileWidth.

-C This option disables image compression. Image compression is used to only show a particular
image only once in the display. Also available as resource XFaces.compressImages.

-K This option insists that the order of the images in the display reflect the order of the images
in the spool file or those returned by a <command>. Also available as resource XFaces.keepOrder.

-S This option says not to shape extra space added to images that are smaller than the tile size.

-pop<hostname>
This option specifies the host name to use for a POP3 mailbox. Also available as XFaces.popHost.

-top For backwards compatibility, use the RETR POP3 command instead of TOP to check for new messages
on the POP3 server.

Synopsis

xfaces [-toolkitoption ...] [-option ...]

User Commands

       These commands add a very powerful feature to XFaces. They allow almost anything to be monitored visually
       and audibly.  When a value is specified for the listCommand resource XFaces will run the command and read
       the commands standard output.  The following is expected.

              The first line consists of two tokens.  The first is expected to be a user name and the  second  a
              host  name.   They  are  intended  to  describe the image that should be displayed by XFaces in an
              iconic state. Note:Thisiscurrentlynotimplementedthoughthelineisstillexpected.

              The second line is expected as
              Cols=<columns> Rows=<rows>
       where <columns> is the number of columns and <rows> that faces should display.  These values are used  to
       set the setWidth and setHeight resources on the Tiled layout widget.

              Each  line following is expected to contain two to six TAB separated fields. The fields are: user,
              host, annotation1, annotation2, annotation3, annotation4. See the annotationCount resource to  see
              how to specify how and where each of the annotations are displayed.

       Steve  Kinzler  maintains  a  distribution  of  scripts  that  can  be  used  to  generate faces lists in
       cs.indiana.edu:pub/faces/scripts.tar.Z.

X Defaults

The application class name is XFaces. For best results the following Shell resource is suggested:

XFaces.allowShellResize:True
This will allow the XFaces window to resize to be the exact size that is required for the current
images.

This program uses a very simple tiled layout widget to layout the images. Each image is displayed in an
Athena Label widget. The name of the layout widget is frame and the following resources are available:

XFaces.frame.tileWidth:<tilewidth>
This resource specifies the width of the children that the Tiled widget is to manage. This size
is enforced. The default is 64

XFaces.frame.tileHeight:<tileheight>
This resource specifies the height of the children that the Tiled widget is to manage. This size
is enforced. The default is 64.

XFaces.frame.setWidth:<forcewidth>
This resource forces the width of the Tiled widget to be <width> tiles wide. If the value is
zero then no width is forced. The default is 0.

XFaces.frame.setHeight:<forceheight>
This resource forces the height of the Tiled widget to be <height> tiles wide. If the value is
zero then no height is forced. The default is 0.

XFaces.frame.minWidth:<minimumwidth>
This resource specifies the minimum width in tiles that the Tiled widget is allowed. If the
value is zero then there is no minimum. The default is 0.

XFaces.frame.minHeight:<minimumheight>
This resource specifies the minimum height in tiles that the Tiled widget is allowed. If the
value is zero then there is no minimum. The default is 0.

XFaces.frame.maxWidth:<maximumwidth>
This resource specifies the maximum width in tiles that the Tiled widget is allowed. If the
value is zero then there is no maximum. The default is 0. Note that since the Tiled widget lays
out its children in row major order a value of 0 creates a horizontal list of images. If the
value is specified as 1 a vertical list is created.

XFaces.frame.maxHeight:<maximumheight>
This resource specifies the maximum height in tiles that the Tiled widget is allowed. If the
value is zero then there is no maximum. The default is 0.

XFaces.frame.vertSpacing:<spacing>
This resource specifies the spacing in pixels that the Tiled widget places vertically between
children.

XFaces.frame.horizSpacing
This resource specifies the spacing in pixels that the Tiled widget places horizontally between
children.

XFaces.frame.internalWidth
This resource specifies the spacing in pixels that the Tiled widget places horizontally between
its borders and its children.

XFaces.frame.internalHeight
This resource specifies the spacing in pixels that the Tiled widget places vertically between its
borders and its children.

Note:IfyouhavespecifiedaborderwidthforthechildrenoftheTiledwidgetthatisnonzerothenyoushouldspecifythefollowingresourcevaluestobeatleasttwotimestheborderwidthspecifiedforthechildren:
• vertSpacing
• horizSpacing
• internalWidth
• internalHeight

XFaces also introduces the following application resources:

XFaces.spoolFile:<mailspoolfile>
This can be used to specify the mail spool file to watch. The default is to append the users
name onto the spoolDir resource.

XFaces.spoolDir:<mailspooldirectory>
This resource specifies the directory that contains user mail spool files. The default is
/usr/spool/mail. On some machines (SVR4?) you may want to set this to /usr/mail.

XFaces.popHost:<hostname>
This resource specifies the name of a host to contact for a POP3 mailbox. Note that in order for
this to work you need to create a file called .popauth in your home directory. The file needs to
contain one line that contains your pop host login id followed by white space followed by your
pop host password. Since this file contains a clear text password it is not the most secure
method. I currently do not have access to a pop server that supports any other type of
authentication.

XFaces.popPort:<portnumber>
This specifies what portnumber to use for POP. The default is the standard POP3 port 110.

XFaces.popTop:<flag>
Specify whether or not to use the newer TOP POP3 command, rather than the RETR command (which may
have the side-effect of marking the mail read on the POP3 server). This also reduces the amount
of network traffic to the POP3 server, so is enabled by default.

XFaces.listCommand:<usercommand>
This resource specifies a user command that will be executed instead of looking at the spool
file. If this resource is specified then value specified in the spoolFile is ignored. See the
USERCOMMANDS section for a description of the data format that XFaces expects from user
commands.

XFaces.imagePath:<imagepath>
This resource specifies a colon-separated list of directories that specify the default
directories to use for image files. The default is /usr/images.

XFaces.soundPath:<soundpath>
This resource specifies a colon-separated list of directories that specify the default
directories to use for sound files. The default is /usr/sounds.

XFaces.facedbPath:<facedbpath>
This is a list of directories that contain a multi-level directory hierarchy. The first few
levels are the host name where each part of the host name is a new directory level. Inside this
is another directory using the users name. And finally, inside of this directory are the actual
image and sound files for this user. The root of the face (for images and for sounds) is face.
This file can be in any of the supported image/sound formats. See the description of the facedb
search type under the imageSearch resource.

XFaces.machine:<machinefile>
This resource specifies the name of a file that is used to alias machine names. Each facedb tree
is allowed to contain one of these. The default is machine.tab. Any blank lines and lines
starting with the # character are ignored. All other lines are expected to look like:

old.host.name=new.name

XFaces.people:<peoplefile>
This resource specifies the name of a file that is used to alias user names for specific hosts.
Each facedb tree is allowed to contain
one of these. The default is people.tab. Any blank lines and lines starting with the #
character are ignored. All other lines are expected to look like:

host.name/olduser=newuser

XFaces.update:<updatetime>
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 33.

XFaces.fromField:
This resource specifies which mail header to use as the from header. The default is the old uucp
"From_" header. (the _ is really a space character)

XFaces.noMailImage:<emptyimage>
The image to use when you have no mail. The default is "nomail". The imagePathisusedtolocatethisfile.XFaces.noMailSound:<emptysound>
The sound to use when you have no mail. The default not to play a sound with no mail. The
soundPath is used to locate this sound.

XFaces.lookupHostname:<flag>
If this resource is True then the host name part of the from address will be looked up and
translated to the real hostname. The default value is False.

XFaces.keepOrder:<flag>
This boolean resource controls the image ordering in faces. For performance reasons the default
is False. When scripts are being run you will usually want to specify this as True.

XFaces.compressImages:<flag>
Only show each image once in the image display. The default is True. When scripts are being run
you will usually want to specify this as False.

XFaces.useSound:<flag>
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:<flag>
Use shaped images if available. This will also cause the background of the XFaces main window to
become transparent where there is no image. This defaults to True.

XFaces.useCommands:<flag>
This resource tells XFaces if it needs to search for shell commands to run in addition to image
and sounds. The default is False.

XFaces.useContentLength:<flag>
This resource enable code to use a Content-Length: mail header to specify how large the mail body
is. After the headers this many bytes are skiped.

XFaces.shapeBorders:<flag>
This resource, when set to True will cause the borders of the Label widgets to be shapedout.
The default is True.

XFaces.shapeInternal:<flag>
This resource when set to True will cause the internal width and height margins of the Label
widgets to be shapedout. The default is True.

XFaces.closeness:<closenessvalue>
This resource controls how close a color must come to the actual color for the XPM library to
accept it. The default is 40000.

XFaces.imageTypes:<imagetypelist>
This resource specifies the default image types that are used to attempt to load an image file.
The list also specifies the order the types are attempted. Valid types are:

xpm-shaped
This is a shaped color image. Shaped xpm files should be named face-shape.xpm.

xpm This is a non shaped color image. These files should be named face.xpm.

xbm-shaped
This a an monochrome shaped image. The image file and mask are stored in separate files
called face-shape.xbm for the image data and face-shape.xbm-mask for the shape mask.

xbm This is a non shaped monochrome image. These files should be called face.xbm.
the default value for this resource is:

xpm-shape:xpm:xbm-shape:xbmXFaces.imageSearch:<searchspecs>XFaces.soundSearch:<searchspecs>XFaces.commandSearch:<searchspecs>
These resources have complete control of the search type , image types for images and path
arguments for locating images, sounds and commands. The search spec is a multi line resource.
Each line represents a new search. Each line is constructed as follows:

<search type> [<format list> [<search path>]]

The <formatlist> is currently ignored for the soundSearch resource. Both the <formatlist> and
the <search path> are (except if you use the facedb search) for the commandSearch resource. If
the <formatlist> is empty then the list in the imageFormats resource is used. If the <searchpath> is empty then the facedbPath is used for facedb searches for both sounds and images and one
of the soundPath or imagePath is used for the other search types.

The valid search types are:

beforeImage
The beforeImageBindings resource is used as a set of regular expression to match lines in
the mail header. beforeSound The beforeSoundBindings resource is used as a set of
regular expression to match lines in the mail header. beforeCommand The
beforeCommandBindings resource is used as a set of regular expression to match lines in
the mail header.

resource
The user name and host name are looked up in the X resources for a match. The resources
attempted are:

XFaces.<type>.user@host
XFaces.<type>.user
XFaces.<type>.host
Where type is one of: image, sound, command.

u@h The user name and host name is combined and looked for as a file name. The names
attempted are:

[path]user@host
[path]user
[path]host

facedb This is the search that is used in Rich Burridge's faces program. The search attempts
the following for the address liebman@zod.clark.net:

[path]/net/clark/zod/liebman
[path]/net/clark/zod/liebman/face
[path]/net/clark/liebman
[path]/net/clark/liebman/face
[path]/net/liebman
[path]/net/liebman/face
[path]/MISC/liebman
[path]/MISC/liebman/face
[path]/net/clark/zod/unknown
[path]/net/clark/zod/unknown/face
[path]/net/clark/unknown
[path]/net/clark/unknown/face
[path]/net/unknown
[path]/net/unknown/face
[path]/MISC/unknown
[path]/MISC/unknown/face

x-face This looks for an X-Face: header and extracts a 48 pixel by 48 pixel monochrome image.

afterImage
The afterImageBindings resource is used as a set of regular expression to match lines in
the mail header.

afterSound
The afterSoundBindings resource is used as a set of regular expression to match lines in
the mail header.

afterImage
The afterCommandBindings resource is used as a set of regular expression to match lines
in the mail header.

The default value of the imageSearch resource is:
beforeImage\n\
resource\n\
facedb\n\
x-face\n\
afterImage
The default value of the soundSearch resource is:
beforeImage\n\
resource\n\
facedb\n\
afterImage
The default value of the commandSearch resource is:
beforeImage\n\
resource\n\
afterImageXFaces.beforeImageBindings:<spec>XFaces.afterImageBindings:<spec>XFaces.beforeSoundBindings:<spec>XFaces.afterSoundBindings:<spec>XFaces.beforeCommandBindings:<spec>XFaces.afterCommandBindings:<spec>
These resources specify regular expressions that can be matched against the mail headers to
locate an image or sound. These are multi-line resources. Each line is constructed as:

<fieldname><regexp><:><file><label><:><anno>
If the <fieldname> is specified as * then all headers are tested. If the <fieldname> begins with a
(like Subject: or *) then the search is case insensitive. The <label> field is only used for image and
if specified, it will be used in the annotations at position <anno> if <anno> is not supplied then it
defaults to 1.

XFaces.ignoreMessageBindings:
These resources specify regular expressions that can be matched against the mail headers to
locate an image or sound. These are multi-line resources. Each line is constructed as:

<fieldname><regexp>
If the field name is specified as * then all headers are tested. Any match found will cause the message
to be ignored, no sound, no image, no nothing!

XFaces.annotationCount:<numberofannotations>XFaces.unknownAnnotationCount:<numberofannotations>
This resource specifies the number of annotations that the user is specifing. The unknown
annotations are applied on faces that were located via the facedb search when substituting
"unknown" for the user name. For each annotation the following resources will be retrieved where
N runs from 1 to annotationCount (or unknownAnnotationCount)

XFaces.annotationN.x:<x>XFaces.unknownAnnotationN.x:<x>
If <x> is a positive number then it is the offset from the left side of the image to the
left side of the text. If <x>Pisanegativenumberthenitistheoffsetfromtherightsideoftheimagetotherightsideofthetext.XFaces.annotationN.y:<y>XFaces.unknownAnnotationN.y:<y>
If <y> is a positive number then it is the offset from the top of the image to the top of
the text. If <y>Pisanegativenumberthenitistheoffsetfromthebottomoftheimagetothebottomofthetext.XFaces.annotationN.maxWidth:<width>XFaces.unknownAnnotationN.maxWidth:<width>
This specifies the maximum width in pixels the text is allowed to be.

XFaces.annotationN.font:<fontname>XFaces.unknownAnnotationN.font:<fontname>
This is the font to use to render the annotation.

XFaces.annotationN.foreground:<Xcolorspec>XFaces.unknownAnnotationN.foreground:<Xcolorspec>
This is the foreground color for the annotation.

XFaces.annotationN.background:<Xcolorspec>XFaces.unknownAnnotationN.background:<Xcolorspec>
This is the background color for the annotation.

XFaces.annotationN.shapeText:<flag>XFaces.unknownAnnotationN.shapeText:<flag>
If true then the text itself is used as the shape mask, if false then the shape mask is a
filled rectangle with extents matching those of the text. The default is False.

XFaces.annotationN.opaqueText:<flag>XFaces.unknownAnnotationN.opaqueText:<flag>
If true then the text background is drawn too (the background is the bounding filled
rectangle, when false only the text is drawn. The default is True.

XFaces.mail.annotationN:<type>XFaces.mail.unknownAnnotationN:<type>
This specifies what is to be placed into this annotation position for mail items. The values for
type are:

none An empty string.

user The user part of the From address.

host The host part of the From address.

user@host The user and host parts of the From address.

count The number of messages represented by this face.

*<header> Any value beginning with a '*' is expected to be a header name and the contents of that
header will be displayed. For instance "*subject:" will display the subject line.

XFaces.annotationAbove:<flag>
This really should be called something else! Anyway, when this resource is true and the image
found is smaller than the tile size the extra space allocated will be placed on teh top instead
of the bottom. The default value is False.

XFaces.background:<color>
This is the color of any extra image space allocated.

XFaces.shapeExtra:<flag>
This, if true, will cause any extra image space allocated to be shaped out.

XFaces.xbm.foreground:<color>
This is the foreground color for loaded X bitmaps.

XFaces.xbm.background:<color>
This is the background color for loaded X bitmaps.

XFaces.xpm.noneColor:<color>
This is the color used to represent the transparent pixels when the overrideNoneColor is True.

XFaces.xpm.overrideNoneColor:<flag>
When this value is set to true the transparent pixels in a Xpm image are replaced bu the color
specified in the noneColor resource. The default value is False.

XFaces.xpm.filterCount:<count>
This resource specifies the number of external filters to look for. The filters are specified
with the following resources:

XFaces.xpmFilterN.name:<name>
This is the image type name used to refer to this filter. It can be used in the
imageType resource and anywhere else an image type name is expected.

XFaces.xpmFilterN.filter:<command>
This is the command that will produce an xpm file on stdout. This could be something
like: "giftopnm %s | ppmtoxpm". A single %s will be replaced by the file name of the
image to be loaded.

XFaces.xpmFilterN.extension:<entension>
This is the file extension that the image file is expected to have.