XFACES(1x)

📦 version 3.3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

xfaces(1x) — mail image display for X. periodt, that's the whole vibe. 💖

🦋 SYNOPSIS 🦋

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

💖 DESCRIPTION 💖

Okay bestie, so XFaces version 3.0 is literally a program that will display an image and optionally play a sound for each piece of mail in your mail box. Not me being obsessed with visual mail notifications 💅 Plus, 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. iconic behavior ✨

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

👑 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. ngl, clear text password is giving risky 💀
  • 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 lil sound to play when you've got no mail. The default is to not play a sound when there's no mail. soundPath is what goes looking for this sound. 🔇
  • XFaces.lookupHostname: <flag> — if this one's True, the host name part of the from address gets looked up and translated into the actual real hostname. Default is False. 🌐
  • XFaces.keepOrder: <flag> — this boolean resource is the one in charge of image ordering in faces. For performance reasons the default is False. When you're running scripts you'll usually wanna set this to True. 🔢
  • XFaces.compressImages: <flag> — only shows each image once in the image display. Default is True. When you're running scripts you'll usually wanna set this to False. 🖼️
  • XFaces.useSound: <flag> — plays sounds. Default is True. A user can turn sounds off for their own XFaces by setting this resource to False in their resources. 🔊
  • XFaces.useShape: <flag> — uses shaped images if they're available. This also makes the background of the XFaces main window go transparent wherever there's no image. Defaults to True. ✨
  • XFaces.useCommands: <flag> — tells XFaces whether it needs to go searching for shell commands to run, on top of images and sounds. Default is False. 💻
  • XFaces.useContentLength: <flag> — this one switches on code that uses a Content-Length: mail header to figure out how big the mail body is. After the headers, that many bytes get skipped. 📏
  • XFaces.shapeBorders: <flag> — when set to True, this makes the borders of the Label widgets get shaped out. Default is True. 🎀
  • XFaces.shapeInternal: <flag> — when set to True, this makes the internal width and height margins of the Label widgets get shaped out. Default is True. 🎀
  • XFaces.closeness: <closeness value> — controls how close a colour has to come to the actual colour before the XPM library will accept it. Default is 40000. 🎨
  • XFaces.imageTypes: <image type list> — this one names the default image types that get used when trying to load an image file, and it also sets the order they get attempted in. Valid types are:
    • xpm-shaped — this is a shaped colour image. Shaped xpm files should be named face-shape.xpm.
    • xpm — this is a non shaped colour image. These files should be named face.xpm.
    • xbm-shaped — this is a monochrome shaped image. The image file and mask live 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 three have complete control over the search type, the image types for images, and the path arguments for locating images, sounds and commands. The search spec is a multi line resource — every line is a whole new search. Each line gets built like this:

<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 instead. If the <search path> is empty then 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 expressions to match lines in the mail header.
  • beforeSound — the beforeSoundBindings resource is used as a set of regular expressions to match lines in the mail header.
  • beforeCommand — the beforeCommandBindings resource is used as a set of regular expressions to match lines in the mail header.
  • resource — the user name and host name get 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 get combined and then looked for as a file name. The names attempted are:
[path]user@host
[path]user
[path]host
  • facedb — this is the search that gets used in Rich Burridge's faces program. For the address liebman@zod.clark.net it attempts the following:
[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 pulls a 48 pixel by 48 pixel monochrome image out of it.
  • afterImage — the afterImageBindings resource is used as a set of regular expressions to match lines in the mail header.
  • afterSound — the afterSoundBindings resource is used as a set of regular expressions to match lines in the mail header.
  • afterImage — the afterCommandBindings resource is used as a set of regular expressions to match lines in the mail header. (yep, the page says afterImage here a second time, bestie — we're keeping it exactly as written 💀)

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 hold regular expressions that get matched against the mail headers to hunt down an image or a sound. They're multi-line resources, and each line is built like:

<field name> <regexp><:> <file> <label><:><anno>

If the <field name> is given as * then all headers get tested. If the <field name> begins with a (like Subject: or *) then the search is case insensitive. (the original page drops a character right there — not our typo, iykyk 🙈) The <label> field is only used for image, and if you supply it, it gets used in the annotations at position <anno>; if <anno> isn't supplied then it defaults to 1. 🏷️

  • XFaces.ignoreMessageBindings: — these resources hold regular expressions that can be matched against the mail headers to locate an image or sound. They're multi-line resources, and each line is built like:
<field name> <regexp>

If the field name is given as * then all headers get tested. Any match found makes the whole message get ignored — no sound, no image, no nothing! 🚫🔕

  • XFaces.annotationCount: <number of annotations>
  • XFaces.unknownAnnotationCount: <number of annotations>

This resource says how many annotations the user is specifying. The unknown annotations get applied to faces that were located via the facedb search by substituting "unknown" in for the user name. For each annotation, the following resources get 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's 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's 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's the offset from the top of the image to the top of the text. If <y>P is a negative number then it's the offset from the bottom of the image to the bottom of the text. ⬆️⬇️

  • XFaces.annotationN.maxWidth: <width>
  • XFaces.unknownAnnotationN.maxWidth: <width>

This sets the maximum width, in pixels, that the text is allowed to be. 📐

  • XFaces.annotationN.font: <font name>
  • XFaces.unknownAnnotationN.font: <font name>

This is the font used to render the annotation. ✍️

  • XFaces.annotationN.foreground: <X color spec>
  • XFaces.unknownAnnotationN.foreground: <X color spec>

This is the foreground colour for the annotation. 🎨

  • XFaces.annotationN.background: <X color spec>
  • XFaces.unknownAnnotationN.background: <X color spec>

This is the background colour for the annotation. 🖌️

  • XFaces.annotationN.shapeText: <flag>
  • XFaces.unknownAnnotationN.shapeText: <flag> — okay so when this one's true, the text itself gets used as the shape mask, like the actual letters are the mask, iconic. When it's false, the shape mask is just a filled rectangle whose extents match the text's extents. Default is False.
  • XFaces.annotationN.opaqueText: <flag>
  • XFaces.unknownAnnotationN.opaqueText: <flag> — true means the text background gets drawn too (and that background is the bounding filled rectangle, fyi), false means only the text is drawn, nothing behind it. Default is True. 🎀
  • XFaces.mail.annotationN: <type>
  • XFaces.mail.unknownAnnotationN: <type> — this is the one that says what goes into this annotation position for mail items. The values for type are:
    • none — an empty string. literally nothing. the void. 💀
    • 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 that starts with a * is expected to be a header name, and the contents of that header get displayed. Like, for instance, "*subject:" will display the subject line. 🦋
  • XFaces.annotationAbove: <flag> — bestie the manpage itself says 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 gets placed on the 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> — if true, this causes any extra image space allocated to be shaped out.
  • XFaces.xbm.foreground: <color> — the foreground color for loaded X bitmaps.
  • XFaces.xbm.background: <color> — the background color for loaded X bitmaps.
  • XFaces.xpm.noneColor: <color> — the color used to represent the transparent pixels when overrideNoneColor is True.
  • XFaces.xpm.overrideNoneColor: <flag> — when this value is set to true, the transparent pixels in a Xpm image get replaced by the color specified in the noneColor resource. Default value is False.
  • XFaces.xpm.filterCount: <count> — this resource specifies the number of external filters to look for. The filters themselves are specified with the following resources:
    • XFaces.xpmFilterN.name: <name> — the image type name used to refer to this filter. It can be used in the imageType resource and literally anywhere else an image type name is expected.
    • XFaces.xpmFilterN.filter: <command> — the command that will produce an xpm file on stdout. 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> — the file extension that the image file is expected to have.

🫶 USER COMMANDS 🫶

These commands add a very powerful feature to XFaces, no cap. They let you monitor almost anything, visually and audibly. When a value is specified for the listCommand resource, XFaces will run the command and read the command's standard output. Here's what it expects:

  • The first line consists of two tokens. The first is expected to be a user name and the second a host name. They're intended to describe the image that should be displayed by XFaces in an iconic state.
Heads up: 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.

And that's the whole page, bestie, we did it 💅 the footer on this one is the XFACES(1x) line — that's the source/version stamp and the date living right there at the bottom, so go forth and face, fr fr 🌈⭐

📦 where this page comes from