HP UX Archive Centre

README for faces, the visual list monitor.

Version 1.6.1 - November 1991.

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.

Audio capabilities are also provided as a conditional compilation option.

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.

----------

The latest version of faces, a selection of faces databases and various
other goodies are available via anonymous ftp from cs.indiana.edu in the
pub/faces directory.

You may send copies of your local database and/or any logo bitmaps you
may have to kinzler@cs.indiana.edu for inclusion in the facedir or logos
databases. Logo bitmaps of any size or format are welcome.

Thanks to Steve Kinzler (kinzler@cs.indiana.edu) for providing this
service.

----------

There is a mailing list for people interested in faces. It is:

faces@cs.indiana.edu

To get added to the list, send a request to:

faces-request@cs.indiana.edu

Early patches are sent to the mailing list, plus active discussion on
ideas for enhancements to faces.

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

Initially there is no Makefile file present in the reve source directory.
You will need to copy Makefile.dist to Makefile, then adjust accordingly.

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.

You might need to be super user to do some of the next steps.

The very first time you are installing faces, you will need to do a "make
tables". This will create your face directory and copy default machine and
people tables into this directory. You should then create hostname and
username sub-directories under this face directory, and setup with the
appropriate ikons/icons. You can also customise your machine.tab and
people.tab files. The manual pages describe this in more detail. A small
sample face directory has been included with this distribution.

This should then be followed by a "make install".

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:

AUDIO_SUPPORT - uncomment to enable audio support
AUDIO_CMD - alternative command to use to play the sound files.
BACKNAME - alternate background icon pattern file name.
BACKGROUND - alternate background icon pattern definition.
DNSLOOKUP - use DNS (Domain Name Service) to try to convert hostnames.
DNSLIB - name of the library to use to resolve DNS calls.
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.
CFACEDIR - alternate face database directory definition.
FMONTYPE - default monitoring type.
HASPOLL - uncomment if you have the poll(2) call (rather than select(2))
INVERT - inverse video.
NAMEUNKNOWN - clump all unknown users together per community.
NEWSINCDIR - NeWS only: location of the NeWS #include files.
NEWSLIBDIR - NeWS only: location of the NeWS libraries.
NISLOOKUP - uncomment to use Sun NIS (formerly YP) to look for hosts.
NODOMAINS - uncomment if you don't want full host domain names.
NOGETHOSTNAME - uncomment if you don't have the gethostname() call.
NOINDEX - uncomment if you don't have the index() function.
NOMAXPATHLEN - uncomment if your system doesn't define MAXPATHLEN.
NOSELECT - uncomment if your machine doesn't have the select() call.
NOUTIME - uncomment if your system doesn't have a utime() library call.
PERIOD - alternate period in seconds before recheck.
PLP - uncomment if you are running PLP and monitoring printers.
RAND - uncomment if you are using the RAND mailer.
REVORDER - byte reversal for little-endian machines.
SELTYPE - uncomment for old select(2) calls.
SGIDEF - uncomment if you are using a Silicon Graphics machine.
SGILIBS - uncomment if you are using a Silicon Graphics machine.
SPOOLDIR - alternate directory for spoolfiles.
SPOOLFILE - alternate default spoolfile to monitor.
SVR4LIBS - uncomment and set if building under SVR4.
SYSV - uncomment if you are running Unix System V.
TOPIX - uncomment if building under Sequoia's operating system.
TTEXT - SunView only: uncomment on SunOS v3.x systems.
UPDATE - alternate mail alias for faces database updating.
USE_BZERO - uncomment if your system has bzero instead of memset.
USE_GETWD - uncomment if your system doesn't have the getcwd library call.
X11R3 - uncomment if you are building the X11 version under X11R3.
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.
-------------------------------------------------------

As of patch #10 to v1.4, faces is capable of recognising the compressed face
image only in the mail message header. Previous to this, it was also
recognised in the body of the message. The latter case causes problems when
a mail message includes other messages with X-Face: lines.

The following method works for Berkeley Mail (aka /usr/ucb/mail), Open
Windows mailtool and mush. It probably works for others too. Note that the
special patch to the mush mail source is no longer needed. It fact, if you
are using a version of mush which has this patch applied, you should un-apply
it before making the changes listed below, otherwise you will have two sets
of X-Face lines in your mail headers. The file mush.xface.patch can be
removed from this faces distribution.

It is suggested that each user store the compressed image (generated by
compface) in a file called .face in their home directory. Second and
subsequent lines should have a preceding tab. For example, my .face file
contains:

------CUT HERE------START------CUT HERE------
*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
------CUT HERE-------END-------CUT HERE------

Each user should add the line:

set sendmail=/usr/local/bin/faces.sendmail

to their ~/.mailrc file, where /usr/local/bin is equivalent to the BINDIR
definition in the Makefile. This small shell script will be installed when
you do a "make install".

----------

A similar method exists with the Elm mailer. The user's compressed face
image should be setup in a ~/.face file as detailed above.

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`

-----------

For straight SVR4, the solution is to use mailx(1) and place in one's
individual .mailrc the line:

sendmail=/path/to/faces.binmail

where "faces.binmail" is the "faces.sendmail" script with "/usr/bin/rmail" in
place of the sendmail invocation.

-----------

Here's a way of doing it from within GNU Emacs.

Put the following in your ~/.emacs file:

; Add my face image to the header of all mail messages
(setq mail-setup-hook
'(lambda ()
(save-excursion
(goto-char (point-min))
(search-forward mail-header-separator)
(beginning-of-line nil)
(insert "X-Face: ")
(insert-file "~/.face"))))

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.

John Mackin for the routines to do RFC822 parsing, and for the
faces.sendmail shell script, which is used to automatically put the
compressed X-Face: image lines in your mail headers.

Pat Lashley for fixing up the NeWS version; modifying it to use cps, and
improving the quality of the NeWS code. Pat also added the ability to use
the Sun NIS, to look for hosts not found in the machines.tab file.

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 suggesting what should be in the unofficial
patch to mush v7.1.2 to support X-Face lines. Note that this is no longer
needed.

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 previous
X11 version.

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

Ken Wood for the details of how to generate X-Face: lines from within GNU
Emacs.

Steve Kinzler for collecting and maintaining a variety of faces databases,
including converting the complete Usenix FaceSaver database to XBM format,
for writing a set of filters for converting between various formats and a
set of faces -e scripts.

Rex Di Bona for the face icon lookup algorithm used in v1.6.

Also thanks to the following for various bug reports, fixes and suggestions
for improvement:

Robert Adams,
Mark Andrews,
Brent Browning,
Tim Chown,
Dave Cohrs,
Philip Colmer,
Jeremy Cook,
Dirk Craeynest,
Neil Crellin,
Ian Darwin,
Graham Dumpleton,
John Fong,
Philip Gladstone,
Dave Glowacki,
Peter Gray,
Rick Gunderson,
Cameron Humphries,
Amir J. Katz,
Dick Keene,
Steve Kinzler,
Mike Khaw,
Tony Landells,
Pat Lashley,
Hugues Leroy,
Hakon Lie,
Rich McAllister,
Chris Mackerell,
John Mackin,
Chris Maltby,
Lindsay F. Marshall,
Stephen Martin,
John B. Melby,
Steven M. Miller,
Kate Morris,
Sjoerd Mullender,
Dan Nydick,
Jim R. Oldroyd,
Paolo Petta,
Howard Pelling,
Bruno Pillard,
Bob Posert,
Darryl K. Ramm,
Greg Rose,
Steve Piette,
Philippe-Andre Prindeville,
Michael Schmidt,
Glenn Satchell,
Mark Shand,
Alan Skea,
Ignatios Souvatzis,
Chris Steinbroner,
Michael Urban,
Johan Vromans,
Rod Whitby,
Ken Wood,

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

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

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