
README for faces, the visual list monitor.

Version 1.4 June 1990.

Permission is given to distribute these sources, as long as the
copyright messages are not removed, and no monies are exchanged. 

-------------------------------------------------------------------------
CONTENTS:

1. What is faces?
2. Getting started.
3. Face formats.
4. How do I get a face image icon?
5. How to include your compressed face image with mail.
6. Automatically updating the faces database.
7. Acknowledgements.
------------------------------------------------------------------------


1. What is faces?
-----------------

This is the third general release of a "faces" server for monitoring a
list visually. Typically this is a list of incoming mail messages, jobs
in the print queue or users on a system.

Faces has five different modes of operation:             
                                                         
 (a) The default will monitor for new mail. By default, only the last ten
     messages are displayed. Using the left mouse button it is possible to
     toggle the text in the faces window. This will either be the username
     or the time the mail message arrived. The icon shows the image of the
     last message to arrive.
                                                         
 (b) You can monitor the whole of a mail file. The open window will
     automatically adjust it's size to correctly show the face icons. The
     open window options are the username or the timestamp and number of
     message from that user. The icon will display the image of the last
     message, and a count of the total number of messages in the spool
     file or mail folder.
 
 (c) Monitoring a given print queue. This will generate a single face icon
     showing the job at the top of the print queue, and the text message
     will display the printer name plus the number of jobs to be printed.
     Opening the window will show images of all the jobs in the queue. The
     text on each image can be toggled, choices being the owners' name and
     the size of the job in bytes.
 
 (d) Monitoring users on a machine. For each user, a face image is displayed.
     Text can be either the username or the time they logged on. The iconic
     form displays the total number of users.
 
 (e) Custom monitoring. You can specify a program or shell script to run.
     The standard output from this program will be read by the faces program,
     and the appropriate faces displayed using the information provided. The
     format of this face information is given in the faces manual page.

Included with this release, is the ability to include a face image with
your mail message using an X-Face header line (plus continuation lines).
Faces expects this line to be in a certain compressed format, and
uncompresses it, and displays that image on-the-fly. There is also an
option to automatically update the faces database with this new image.

By default, after every sixty seconds, faces will recheck the mail file or
the print queue. If the mail spool file has changed size, it will produce a
chain of records for which it has face icons.

This release contains graphical interfaces for NeWS, SunView, X11 and XView.

Faces is based on the AT&T v8 face server called vismon, but is not derived
from vismon sources. With the previous version came vismon compatibility.
Note that that resulted in a few changes from the way faces v1.1 worked.
See the manual pages for more details.


2. Getting started.
-------------------

You need to specify one of the following four options to compile faces:

 1/     make sunview      - to make the SunView version.
 2/     make news         - to make the NeWS version.
 3/     make x11          - to make the X11 version.
 4/     make xview        - to make the XView version.

This should then be followed by a make install. You might need super-user
permission to do this successfully. Create your face directory, hostname
and username sub-directories and appropriate ikons/icons, machine and
people tables, and you're set. The manual pages describe this in more
detail. A small sample face directory and alias files have been included
with this distribution.

The Makefile compilation details are setup to default to compiling the
SunView version of faces on a Sun4 running SunOS v4.1. Note that there are
various compilation definitions that might need uncommenting if you are
trying to compile and run it on any other machine or graphics environment
or operating system.

These are:

BACKGROUND    - alternate background icon pattern.
DONTSHOWNO    - don't show number of message on face image.
DONTSHOWTIME  - don't show timestamp on face image.
DONTSHOWUSER  - don't show username on face image.
FACEDIR       - alternate face database directory.
FMONTYPE      - default monitoring type.
INVERT        - inverse video.
NEWSINCDIR    - NeWS only: location of the NeWS #include files.
NEWSLIBDIR    - NeWS only: location of the NeWS libraries.
NODOMAINS     - uncomment if you don't want full host domain names.
NOINDEX       - uncomment if you don't have the index() function.
PERIOD        - alternate period in seconds before recheck.
REVORDER      - byte reversal for little-endian machines.
SELTYPE       - uncomment for old select(2) calls.
SPOOLFILE     - alternate default spoolfile to monitor.
TTEXT         - SunView only: uncomment on SunOS v3.x systems.
UPDATE        - alternate mail alias for faces database updating.
X11INCDIR     - X11 only: location of the X11 #include files.
X11LIBDIR     - X11 only: location of the X11 libraries.
XVIEWINCDIR   - XView only: location of the XView #include files.
XVIEWLIBDIR   - XView only: location of the XView libraries.

See the Makefile for a detailed description of each of these definitions.

If you need to make other changes in order to get faces to compile and run
on your system, please let me know the details (see email address below),
and I will try to include them into a future version.


3. Face formats.
----------------

Typically, there is a face directory, and under that are directories which are
hostnames.  Under that are username directories, and this is where the face
images are placed. The face images are currently stored in one of four ways:

  (a)   NeWS .ps format, called face.ps.
  (b)   Sun icon format, called sun.icon.
  (c)   Blit ikon format, called 48x48x1.
  (d)   X11 xbm format, called face.xbm

The NeWS .ps allow for animation with the users' face. These files are
drawn when the rest of the static faces have been displayed. They will be
redrawn every time the mail or print queue is recheck or when the faces
window or icon is damaged. See the manual page for details on the
conditions imposed on these NeWS .ps files.

With this release, faces has support for reading a compressed face image
included with the users mail message. This compressed face image consists
of a line starting with "X-Face: " followed by compressed face data. This
compressed data will be continued over subsequent lines. This X-Face image
will have been created by running the compface program on a Blit ikon
(48x48x1 format). The X-Face line and it's continuation records should
be part of the mail header, but it is recognised that not many mailers can
generate these records at the moment, so faces looks for the X-Face in
both the mail header and message body. It is initially expected that the
X-Face will become part of the users signature file. See the compface manual
page for more details, on how to create you compressed image, and section 5
below, on how to get it included with your mail.


4. How do I get a face image icon?
----------------------------------

In order to get a real representation of your face, you will have had to
have sat down in front of a video camera attached to some kind of scanning
system. These facilities have been available at recent Usenix conferences
in the US (the FaceSaver project), and at the last couple of Australian
Unix User Group conferences. I expect EUUG has done something similar.

This face image then needs to be converted into a 48x48x1 ikon. In the
filters sub-directory of the faces distribution is a shell script that
uses several utilities from the PBM toolkit to achieve this. The PBM
(Portable BitMap) toolkit is an excellent set of programs to convert from
one graphics format to another, and manipulate the resulting images.
PBM was written by Jef Poskanzer, and is available from the sources
archives on uunet, and other places. It was also distributed on the X11R4
contribution tape.

When you have a 48x48x1 ikon, you then need to run the compface program
on it. See the compface/compface.1 manual page for more details.


5. How to include your compressed face image with mail.
-------------------------------------------------------

Faces is capable of recognising the compressed face image anywhere in the
mail message (header or body), but the best place to put it is in the mail
header (out of the way).

It is suggested that each user store the compressed image (generated by
compface) in a file called .face in their home directory. For example, my
.face file contains:

*7O.<19S{MCsaxxe=iCc*y5!i:>e,K40m^btp"<`~gNx5>o?eJMzUng=j]%KybY
\/VaZ/3a4pD%#rGu7D<M$.TDpaDN8#8eJC&^^&Mr]@~}Pa,*F-ePrMg5.}e,,bu
qROdT{Vzn{!ouXy.&*#V#Q&Zf7a8lX2Kb}"$UT^VhnsJ?){wFU5r+,duO>4@L

Note that there is no initial "X-Face:" and leading spaces have been
removed from each line.

To automatically include this into a header into an Elm mail message, just
add the following line to your .elm/elmheaders file:

    X-Face: `cat $HOME/.face`

In v7.1.2 (version 7.1 - patchlevel #2), the Mush mail program will look for
the existence of a .face file (in the above format) in the users home
directory, and generate a similar header.

For users of other mailers, it is suggested that the X-Face: line[s] be
added to your .signature file. Note that in this case, the initial line
should have "X-Face: " prepended, and second and subsequent lines should
start with at least one whitespace character.


6. Automatically updating the faces database.
---------------------------------------------

The -U command line option to the faces program allows you to automatically
update your faces database with these "on-the-fly" X-Face: images. Note, that
this alias is not automatically installed for you as this might be a security
risk on your system.

If the -U option is given, then every time a new X-Face: image is found,
a copy of the converted blit ikon format data is sent to a certain mail
address. The subject line for this mail message is the name of the file
that should be created (or overwritten) in the faces database.

By default this mail alias is called "facemaker" but can be altered in the
Makefile. You would then need to add the following alias to your
/etc/aliases (usr/lib/aliases) file:

facemaker:      "|/usr/local/bin/face_update"

This face_update program is a shell script, and is included with this
distributions. For it to work correctly, the faces directory should be
owned by 'daemon' (with read/write permissions), and readable by the
rest of the world.


7. Acknowledgements.
--------------------
 
Special thanks go to:

James Ashton for the mail header face compression / uncompression code.

Pat Lashley for fixing up the NeWS version; modifying it to use cps, and
improving the quality of the NeWS code.

Chris Maltby for the parsefrom routine used to extract the username and
hostname from the "From " and "From:"lines. Chris also supplied a shell
script to convert Usenix FaceSaver images to 48x48x1 ikons, and a rewrite
of the faces manual page..

Hal Stern for the face_update shell script.

Dan Heller and Bart Schaefer for adding support for .face files in
their latest patch to v7.1 of the mush mailer.

Guy Harris for the basis of the previous manual page.

Dave Lemke for many excellent suggestions and help with the original
version of the X11 code.

Heather Rose for suggesting the animated NeWS faces.

Andrew Nicholson for help with some of the trickier NeWS code in the
previous version.

Rob Pike for sending me a copy of the Pike/Presotto paper "Face the Nation",
which I used to get vismon compatibility.

Jonathan Bowen for suggesting the rusers monitoring addition.

C.P. Lai for the Sun386i icon code plus numerous bug reports.

Jim Knutson for improving the previous version of the hostname and username
parsing.

Dave Cohrs for several fixes and enhancements, the addition of X11 bitmap
support, and generally sorting out most of the problems with the X11 version.

Greg Dudek for an alternative version of "on-the-fly" X-Face imaging which
hasn't been used.

Also thanks to Jeremy Cook, John Machin, Neil Crellin, Mark Andrews, Sjoerd
Mullender, Cameron Humphries, Rick Gunderson, Rich McAllister, Hakon Lie,
John Fong, Chris Maltby, Darryl K. Ramm, Steve Piette, Tony Landells and
Pat Lashley for various bug reports, fixes and suggestions for improvement.


----------------------------------------------------------------------------

Suggestions for further improvement would be most welcome, plus bug reports
and comments.

Rich Burridge,          DOMAIN: richb@Aus.Sun.COM
PHONE: +61 2 413 2666   ACSnet: richb@sunaus.sun.oz.au
