
/*  $Header: /cvsroot/faces/faces/README,v 1.1.1.1 2002/04/15 20:20:47 richburridge Exp $
 *
 *  Copyright (C) 1990-2002  Rich Burridge, Sun Microsystems Inc.
 *  All rights reserved.
 *
 *  Permission is given to distribute these sources, as long as the
 *  copyright messages are not removed, and no monies are exchanged.
 *
 *  No responsibility is taken for any errors on inaccuracies inherent
 *  either to the comments or the code of this program, but if reported
 *  to me, then an attempt will be made to fix them.
 */

Faces  -  README  -  April 2002.

-------------------------------------------------------------------------
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. Acknowledgements.
------------------------------------------------------------------------


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

This is the fourth general release of a "faces" server for monitoring a
list visually. Typically this is a list of incoming mail messages.

Faces has three 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) 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.

     There are lots of good examples that have already been written and
     these can be downloaded from:
     ftp://ftp.cs.indiana.edu/pub/faces/picons/src/

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.

Audio capabilities are also provided as a conditional compilation option.

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

This release contains only a graphical interface for Gtk.

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 can always be found at:

    ftp://ftp.cs.indiana.edu/pub/faces/faces/

A selection of faces databases can be found at:

    ftp://ftp.cs.indiana.edu/pub/faces/picons/db/

and various other goodies are available for download from :

    http://www.cs.indiana.edu/ftp/faces/

Thanks to Steve Kinzler (kinzler@iuvax.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.
-------------------

See the file 'INSTALL'


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. Two types of faces images are currently recognized:

  (1)   PBM (Portable bitmap format) called face.pbm
  (2)   X11 xbm format, called face.xbm

Faces also 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 if you wish 
to use it as an X-Face: or to the XBM or PBM formats if you wish to store 
it in a faces database.  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.

See also various programs available from:

    ftp://ftp.cs.indiana.edu/pub/faces/picons/src/

that will help you manipulate your faces image.

When you have a 48x48x1 ikon, you then need to run the compface program
on it, to convert it to an X-Face: representation. 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 in the mail headers
or 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 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"))))


; Hide compressed faces when reading mail messages
(setq rmail-ignored-headers
      "^via:\\|^mail-from:\\|^origin:\\|^status:\\|^received:\\|^[a-z-]*message-id:\\|^summary-line:\\|^errors-to:\\|^X-Face:")


6. Acknowledgements.
--------------------
 
See the AUTHORS file.

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

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

Rich Burridge,          rich.burridge@Sun.COM
