Provided by: xfaces_3.3-29ubuntu1_amd64 bug

NAME

       xfaces - mail image display for X

SYNOPSIS

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

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.

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 <facedb path>
               This  option  set  the  default  facedb search path to the colon separated list of
               directories  specified   in   <facedb   path>.    Also   available   as   resource
               XFaces.facedbPath.

       -h <image height>
               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 <update time>
               Specify the amount of time to wait between checks for new mail.  Also available as
               resource XFaces.update.

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

       -w <image width>
               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.

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: <tile width>
               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: <tile height>
               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: <force width>
               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: <force height>
               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: <minimum width>
               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: <minimum height>
               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: <maximum width>
               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: <maximum height>
               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:  If  you  have  specified a border width for the children of the Tiled widget
              that is non zero then you should specify the following resource  values  to  be  at
              least two times the border width specified for the children:
                     · vertSpacing
                     · horizSpacing
                     · internalWidth
                     · internalHeight

       XFaces also introduces the following application resources:

       XFaces.spoolFile: <mail spool file>
               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: <mail spool directory>
               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: <port number>
               This  specifies what port number 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 USER COMMANDS section for a description of the data
               format that XFaces expects from user commands.

       XFaces.imagePath: <image path>
               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: <sound path>
               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: <facedb path>
               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: <machine file>
               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: <people file>
               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: <update time>
               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: <empty image>
               The image to use when you have no mail. The default is "nomail".  The imagePath is
               used to locate this file.

       XFaces.noMailSound: <empty sound>
               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
               shaped out.  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 shaped out.  The default is True.

       XFaces.closeness: <closeness value>
               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: <image type list>
               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:xbm

       XFaces.imageSearch: <search specs>

       XFaces.soundSearch: <search specs>

       XFaces.commandSearch: <search specs>
               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 <format list> is currently ignored for  the  soundSearch  resource.  Both  the
               <format  list> and the <search path> are (except if you use the facedb search) for
               the commandSearch resource.  If the <format list> is empty then the  list  in  the
               imageFormats  resource is used.  If the <search path> 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\
                           afterImage

       XFaces.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:

                   <field name> <regexp><:> <file> <label><:><anno>
       If the <field name> is specified as * then all headers are tested.  If  the  <field  name>
       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:

                   <field name> <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: <number of annotations>

       XFaces.unknownAnnotationCount: <number of annotations>
               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>P is a negative number then
                       it is the offset from the right side of the image to the right side of the
                       text.

               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>P is a negative number then it is  the
                       offset from the bottom of the image to the bottom of the text.

               XFaces.annotationN.maxWidth: <width>

               XFaces.unknownAnnotationN.maxWidth: <width>
                       This specifies the maximum width in pixels the text is allowed to be.

               XFaces.annotationN.font: <font name>

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

               XFaces.annotationN.foreground: <X color spec>

               XFaces.unknownAnnotationN.foreground: <X color spec>
                       This is the foreground color for the annotation.

               XFaces.annotationN.background: <X color spec>

               XFaces.unknownAnnotationN.background: <X color spec>
                       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.

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: This  is  currently  not  implemented
              though the line is still expected.

              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.

SEE ALSO

       mail(1), sendmail(8)

AUTHOR

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

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)