*****************************************************************
**  XFAX : an X-windows faxprogram build with Xforms,
**  using 'efax' by Ed Casas to actually convert and send faxes.
**  Kees Lemmens; 1996 - 1999, Fac. TWI TU Delft Netherlands
**  J.-P. Demailly; 1998 - 1999, Universit de Grenoble I, France
*****************************************************************

Xfax, Version 2.11, February 4, 2000


GENERAL DESCRIPTION:
====================

Xfax is a X-Windows fax program, including a faxviewer, a faxprinter
and a faxconverter from various formats to fax G3 format.  It supports
frontpage generation in 3 modes (Ascii, Postscript, TeX/LaTeX), and
enables the user to forward a list of documents of various types
(Ascii files, TeX/LateX files, PostScript or PDF documents, images...). 
Xfax is based on the efix/efax tools by Ed Casas, but it is also
possible (with some minor modifications) to make it work with Hylafax,
Netfax or some other commandline oriented faxprogram. You can get these
packages from
    http://casas.ee.ubc.ca/efax/
    http://www.vix.com/hylafax/    or    ftp://sgi.com/sgi/fax

Xfax should be very user-friendly and rather straightforward to build
and to configure.  It uses the Xforms library by T.C. Zhao and Mark
Overmars as its GUI toolkit.  
The current version of the Xforms library is version 0.88.1. It can be
downloaded from
    ftp://einstein.phys.uwm.edu/pub/xforms
    ftp://ftp.cs.ruu.nl/pub/XFORMS  (Primary mirror site)

Xfax offers the possibility of formatting Ascii text files with the
enscript utility. This, of course, only works if enscript is installed
on your system. If not, Xfax can still convert Ascii text files directly
via efix (you should nevertheless probably install the very useful
enscript package!)

Xfax can also make use of conversion routines for graphic files,
especially "ppmtoxpm" from the netpbm-pbmplus package, and/or
"convert" from the ImageMagick package ("convert" is more powerful
than "ppmtoxpm" and supersedes it entirely). You will definitely need
the ImageMagick package (or some other equivalent graphical tool) 
if you want to be able to process arbitrary image files on the fly,
otherwise ppmtoxpm is quite sufficient.
The ImageMagick package can be downloaded from
    ftp://ftp.wizards.dupont.com:/pub/ImageMagick/

NOTES: 

1) the scripts "anytog3" and "g3toxpm" will have to be slightly
modified if other conversion tools than those described above are used.
They are configured for A4 paper format, but this can of course
be changed by setting the adequate options wherever necessary 
(check the occurrences of enscript, dvips and ghostscript).

2) The xfax package presently only includes dialogs for English
and French. Building dialogs for a new language requires only to 
create the corresponding lang/src.{New_Language} file. If you happen 
to make such a translation to a new language, please send us your
contribution so that we can include it in further releases.


USER CONFIGURATION:
===================

When xfax is used for the first time, the system wide configuration file
is set as the user's private ~/.xfaxrc configuration file. It still misses
the user's private data, which can be set by the "Set User info" Option.
If the user fails to do so, the front page will not contain any data about
the sender.

Xfax is highly configurable. This means that the user can provide his
own scripts to be used for the fax processing routines "faxdirect",
"faxqueue", "faxserver", "faxprint" or the file conversion routines
"anytog3" and "g3toxpm". The latter routines are provided with the
assumption that ppmtoxpm is installed on your system.
If this is not the case, any utility which can achieve image format
conversions pgm->xpm and other_formats -> G3 can be used instead. 
The users's preferred external editor can be set as well, e.g. "emacs" 
or "xterm -e vi".  All this can be accessed on the fly through the
"System parameters" Option (which, however, no longer need be used
once everything is correctly set up).

One of the main configuration choice depends whether "faxserver" is
installed or not. (It should always be installed in case of a
multi-user environment, see FAXSERVER section below). If faxserver is
installed, the "Send fax" command to be used is "faxqueue". Otherwise,
use instead "faxdirect", which directly outputs the faxpages to the
modem without queuing them in the fax spool directory.


EVERYDAY USE:
=============

Xfax can be used to forward a large variety of document types (plain
ascii text, TeX/LateX files, dvi files, pdf files, fax g3 files, image formats
that the image conversion utility can handle). These documents are
listed in the "Attached documents" browser. Ascii or TeX files can be
edited on the fly, and the user can possibly adjust the geometry to
the desired output format, if needed. The documents are then sent
consecutively in the order of their appearance in the browser. The
frontpage is automatically generated from the other input fields
(faxnumber, name, institution, service of the recipient) and from the
message.  Frontpage generation can be disabled with the 
"Show Frontpage" Option in the "Options" menu, or by suppressing 
the <FrontPage> line from the "Attached documents" browser.

The "Add Alias" and "Read Alias" buttons can be used to store and 
retrieve fax numbers of the the fax recipients. These data are
maintained in the file ~/.xfaxaliases in the user's home directory.

All data concerning a fax message session (recipient fields, message,
list of documents, options used) can be stored -- and later retrieved
-- in a record file. These data are retrieved from within xfax
by pressing the "Load Fax" button, or by a direct shell invocation
"xfax record_of_session".


FILE MENU:
==========

Allows you to load, save or edit a record of your fax message (data in
input fields, message, attached documents, options...).  Parts of the
data can be cleared according to the selected clear commands.  The
command "Show message queue" launches a browser showing all 
queued, not yet delivered fax messages.  You can check the contents 
of each of each of the messages you own, and possibly remove them
from the queue.


OPTIONS MENU:
=============

The first 7 options govern the behaviour of xfax:
1. Should a frontpage be generated ?
2. Should email be sent to the user if something goes wrong after a
   "faxqueue" command has been issued ?
3,4,5. Select fields which should be imported to the input fields 
   while retrieving a session record file ("Load Data" button).
6. This option determines whether xpm pages are stored in different 
   files or overwrite themselves. The "View fax" command converts 
   the G3 fax pages into xpm format for the mere purpose of allowing
   them to be viewed in the internal viewer [an external viewer  
   g3view  is also provided]. Since each xpm page takes about 1 Meg,
   large documents could produce and require storing so many data that 
   HD gets filled up. In that case, disabling the "Bookkeep xpm pages"
   Option ensures that only one xpm page is generated at each step, 
   at the expense of taking more time to switch between pages.
7. Shows or hides the digital clock. In addition to showing time,
   the clock is used as a time counter during fax emission with
   "faxdirect".

Option 8 is  "Set User Info". It is used to set information that should
be fixed before the first xfax call.

The last 3 options are:
- Set Dialog file (selection of language used for xfax
- Set Help file (this file!)
- System parameters (an option already discussed).


INPUT FIELDS:
=============

Faxnumber:
----------
Here you have to specify the faxnumber of the recipient. Of course no
fax can be sent if you don't provide a faxnumber ! Also don't forget
the leading "0" or other special prefixes when using a company
telephone system.

Avoid spaces in the faxnumber(e.g. 0 0049 123456), as this may confuse
commandline parsing by the underlying software ! Use dashes if you
really think you have to separate the numbers ! (i.e. 0-0049-123456)

Name (of Recipient):
--------------------
Name of the person whom you address the fax to. Note that it can be
difficult to find out for the other side who the fax is addressed 
to if you don't supply this information, especially at large
organisations with only a few fax machines for many employees.

Institution (of Recipient)
--------------------------
Intitution where works the above mentioned person.

Service (of Recipient)
----------------------
Service where works the above mentioned person.

Message:
--------
A window to supply a SHORT message on the frontpage. Either type it
manually or use "Load Msg" to get it from a previously recorded xfax
session. The number of characters is currently limited to about 1500
and the number of lines to 15.

It is easy to alter these or even make them infinite, but we think a
frontpage shouldn't contain too much information. You'd better use an
attachment instead if you need to send longer messages.


BUTTONS OF THE INPUT FIELD AREA:
================================

<COVER> The cover file is used to generate the front page. It can be
either a plain Ascii file, a PostScript file (in suitable format), or
a TeX/LateX file. System wide cover files of all 3 types are provided
in the system wide lib/xfax/covers directory. Check them to understand
how new cover files can be built. PostScript and TeX/LaTeX files allow
inclusions of pictures or logos in the frontpage.  The second line of
the cover file should carry an indication
%%Language: ******
where ****** is the basename of the dialog file of the language being
used. That name must be given with capital letters if required (e.g. 
English, French...) This indication is necessary to get the date 
spelled in the desired language on the front page.

<LOAD FAX> Load a record file of a previous xfax session.

<SAVE FAX> Save the current xfax session into a record file.

<LIST ALIASES> Use this to browse the alias database and to export a
destination directly into the "faxnumber" and "recipient" fields. You
can either do this by double clicking an entry or by selecting it and
then clicking the "Export" button.

<ADD ALIAS> Add the current faxnumber, recipientname, institution and
service to an aliasdatabase (~/.xfaxrc), so you can retrieve it from
the database next time.
Aliases can be removed again by selecting them and clicking the
"Remove" button.

<EDIT> (yellow button at the lower right corner of the message field)
Starts your favourite text editor so as to edit the frontpage message.
You can select the editor utility with the "System Parameters" option.


ATTACHED DOCUMENTS:
===================

<ADD FILE> Allows you to directly attach files to be faxed after the
frontpage. Note that the file should be in one of the specified
formats (See below). The default is always plain ASCII.

<EDIT> Allows you to start your favorite editor to produce a document
and to add it to the "attached documents" list afterwards.

<INFO> Gives some short information on the attached documents: file size
of source, name and location of the related fax page files.

<MODIFY> Allows you to modify/cancel the file in the selected line.
5 options are available :
   * Remove a line from the browser (this, of course, does not delete
     the file itself!)
   * Change the file name
   * Change the font specification FontType@Size 
     (this is relevant only for Ascii text files). 
     Valid FontType specifications are:
   Courier, Courier-Oblique, Courier-Bold, Courier-Bold-Oblique,
   Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic,
   Helvetica, Helvetica-Oblique,
   Helvetica-Bold, Helvetica-BoldOblique,
   Helvetica-Condensed, Helvetica-Condensed-Oblique,
   Helvetica-Condensed-Bold, Helvetica-Condensed-BoldObl,
   Helvetica-Narrow, Helvetica-Narrow-Oblique,
   Helvetica-Narrow-Bold, Helvetica-Narrow-BoldOblique,
   NewCentury-Schlbk-Roman, NewCentury-Schlbk-Italic, 
   NewCentury-Schlbk-Bold, NewCentury-Schlbk-BoldItalic,
   Palatino-Roman, Palatino-Italic, Palatino-Bold, Palatino-BoldItalic,
   Symbol,
   AvantGarde-Demi, AvantGarde-DemiOblique, 
   AvantGarde-Book, AvantGarde-BookOblique,
   Bookman-Demi, Bookman-DemiItalic, 
   Bookman-Light, Bookman-LightItalic,
   ZapfChancery-MediumItalic, ZapfDingbats

   * Attach a geometry setting to pages of the selected document.
   * Force an update of the document within the Fax Viewer


BUTTONS AT BOTTOM ROW:
======================

<RESOLUTION> This option sets the resolution as High, Medium or Low
to be used for the View Fax command.

<VIEW FAX> This shows all the faxpages in G3 format. Thus, it will
show quite accurately how it will look on the recipient side. The
command that will be called to convert a faxpage into xpm is preset to
'g3toxpm' (which is simply a scriptfile that calls some local
programs.) After that, a builtin viewer allows you to browse through
the faxpages, while indicating the total number and the current page.
The faxpages are generated on the fly, and it takes a few seconds for
each document and an additional couple of seconds to convert the
faxpage into xpm format and load it. The operation is of course much
quicker once faxpages have already been generated.

You can change the G3->Xpm conversion command if necessary in the 
<System Parameters> window.

<SEND FAX> This will call the specified faxprogram to actually
transfer your fax. Default is /var/lib/xfax/faxsend and this is a
softlink to either the "faxdirect" program to send the fax immediately
by the faxmodem on your local system, or the "faxqueue" program that
will only move the directory containing all information about your fax
to a fax spool directory.

(The spool directory can also be of course an NFS directory, which
will enable you to use a remote server without the need for special
TCP/IP protocols.)

<VIEW LOG> This opens a window that shows the standard output and
possible errors of all commands that are called by xfax. You can use
it e.g. to see if your fax has been successfully sent (if using the
faxdirect command) or use it for debugging the various scripts.
The "Abort" button in the ViewLog window can be used to kill the fax
emission by brute force. The AutoRaise option lets the Log Viewer
popup automatically each time the "Send fax" command is issued.

<PRINT FAX> This option will build all G3 fax pages and print them
using the command specified in the FaxPrint field. Default is
/var/lib/xfax/faxprint.

<EXIT> Exits xfax (after checking that all user data have been 
actually saved, whenever needed).


SUPPLIED SCRIPTFILES:
---------------------

FAXSERVER: This is a script that just inspects the spool directory for
faxes and sends all of them in a sequential order, using the "faxinfo"
file in each of the fax directories. One can run it from cron,
i.e. like this:

00,10,20,30,40,50 8-19 * * 2-6 /var/lib/xfax/faxserver >> /var/adm/xfaxlog

to run it every 10 minutes between 8 and 19 on weekdays. The faxserver
procedure should always be used in a multi-user environment, otherwise
faxes forwarded at the same time by different users could get mixed up.

FAXQUEUE: Just has the effect of moving the complete faxdirectory with 
all G3 files, fax contents and faxinfo to the spool directory and leaves 
the actual sending to the separate spooler (i.e. faxserver). Of course
the faxserver should be running or else your faxes will stay there 
forever !

FAXDIRECT: An alternative faxprogram that will try to send your fax
immediately through a fax modem on your local system.

G3TOXPM: A script that uses 'efix' to produce a ppm file from a g3
file and then calls 'convert' to convert it into xpm format, which is
the only useful format supported by Xforms. It is vital if you're
using the view option !!

ANYTOG3: A simple script based on the ImageMagick "convert" tool to
convert eventually any file into a G3 file. You can adapt any other script
if you like.

G3VIEW: Views one G3 page. The program loops through all pages and
calls the ViewG3 commmand for each page separately. Currently set to
the following:

/var/lib/xfax/efix -i fax -o pgm -p29.7x42cm -s1.4x1.4 $1 | \
  xv -geometry +100+50 -

It was used in the older xfax versions, but as there is now a builtin 
viewer, it isn't very useful anymore, unless you want to view pages
manually, without running xfax.


AUTHORS:
========

Copyright:

Kees Lemmens (e-mail: C.W.J.Lemmens@dv.twi.tudelft.nl)
original author of xfax, maintainer till version 1.11s.

Jean-Pierre Demailly (e-mail: demailly@ujf-grenoble.fr)
has contributed all enhancements and new capabilities appeared with 
versions 2.xx.


COPYING-POLICY: 
===============

GPL (General Public Licence from the Free Software Foundation).
Please send your contributions, bug reports, hints etc. to the authors. 
Thanks !
