***************************************************************************
*****                                                                 *****
*****        XFAX : an X-windows faxprogram build with Xforms,        *****
*****  using 'efax' by Ed Casas to actually convert and send faxes.   *****
*****    Kees Lemmens; August 1996. Fac. TWI TU Delft Netherlands     *****
***************************************************************************

Modified in Oct 1997 (v 1.10), small bugfixes and printer support.
See the CHANGES file for details.

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

If you start the xfax program (after having compiled the program !) you'll
see a window with a number of gadgets. The layout of this fax window was
loosely inspired by our old HP Fax program, to avoid large adaptation
problems with our less "computerized" users.

We have been using the HP Fax program for the last 2 years, but it was so
unreliable and so critical about the used modem (only a very expense
Multitech modem worked, but we already tried 2 other modems before we found
out this !) and it also was so badly supported by HP that we decided to drop
it and build our own, based on some more reliable PD sources.

Xfax is an X-windows faxprogram, that was built with the fantastic Xforms
libraries by T.C. Zhao and M. Overmars. Xfax relies currently on 2 simple
commandline oriented faxtools "efax and efix" written by Ed Casas, but as
all external commands can be preset from within in program, it is easy to
adapt it to use any other commandline oriented faxprogram. (i.e. hylafax or
netfax).

For G3 viewing it now uses (v 1.04) the "efix" program in combination with
ppmtoxpm, while the xpm output is being viewed through a builtin viewer with
paging support, pagenumber indicator etc.

HOW TO USE:
==========

Start the program with xfax. Currently there is one commandline option
supported: -v 1,2 or 3 to use the Large, Medium or Small size Fax Previewer.
After startup you'll see a number of buttons, windows and pulldown menu's
I'll explain shortly hereafter:

File menu:
----------

<FROM INFO> Can be used to preset your personal information: i.e. Name,
Emailaddress, Telephone and Faxnumber and so on. Don;t forget to set this
when you start the program for the first time or else the frontpage won't
contain information about the sender !!

<SET HEADER> The frontpage puts a little ASCII file on top with i.e. general
information about your organisation. The default is "/opt/lib/xfax/faxheader"
but you can change it with this option to set your own private (ASCII) header.

<LOAD & SAVE MESSAGE> with this options you can import/export a message
to/from the "Message" window. Alternatively you can of course type it
manually into the "Message" window. 

NOTE: The message window is only supposed to contain a few lines of text !
All files and messages will be truncated to approx. 500 characters !
Use an "Attachment" for longer messages: i.e. click on the Editor button.

<EXIT>  This must be clear, if not then you better use a normal fax instead
and stay away from computers for the rest of your life !

Options menu:
-------------

<SEND EMAIL> This sets the "EmailFlag" to "True" and thus requests either
the faxserver or the direct faxprogram to send you information about the
fax transmission.
Remember to set your email address in the "From" window first, or the
faxsend program won't be able to send you any email !

Note that if you use any other program for sending faxes than either
the faxserver or faxdirect, you'll have to provide for the "Send email"
option yourself !!
This option is a toggle: i.e. clicking it will change from "No email" to
"Send Email" or vice versa.

<SHOW FRONTPAGE> If you don't want to use the system frontpage (i.e. you
cretaed a nice Postscript frontpage yourself and want to send it as the
first attachment) you can use this option to disable the creation of a
frontpage. The yellow "frontpage" light on the main window will be cleared
then to indicate that you are sending without a frontpage.
Also this option is a toggle.

<SYSTEM PARAMETERS> All commands that are used for converting, viewing or
sending the fax are preset to reasonable defaults, but you can use this to
change them to your personal preferences. However, you should know what
you're doing or else the program may fail to work properly !

Especially the conversion commands are nasty and should be inspected from
the defaults first, as they should be able to produce more than 1 fax page
for each attachment if the file doesn't fit on one page.

Presets (assuming you compiled with FAXBASE=/opt/lib/xfax) :

G3ToXpm  : /opt/lib/xfax/g3toxpm
FaxSend  : /opt/lib/xfax/faxsend
FaxPrint : /opt/lib/xfax/faxprint
AsciiCmd : /opt/lib/xfax/efix -ve -itext -p21x29.7cm -d0.3,0.3 -l56 -s2.5x2.5
           -n %s.%%03d %s
PSCmd    : gs -q -sDEVICE=faxg3 -dNOPAUSE -sOutputFile=%s.%%03d %s quit.ps
GifCmd   : /opt/lib/xfax/giftog3 %s.001 %s
SpoolDir : /tmp
FaxHeader: /opt/lib/xfax/faxheader
Editor   : xterm -e vi (the nicer nedit on HP)

Note that all user information (also the Header and From info) is stored in
a file $HOME/.xfaxrc.

Faxnumber:
----------
Here you have to specify the faxnumber of the recipient. Of course no fax
can be send 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(i.e. 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)

This is fixed in v1.06: all spaces will be converted into dashes so these are
allowed now.

Recipient:
----------
Name of the person who 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
faxes for many employers.

Add alias:
----------
Add the current faxnumber and recipientname to an aliasdatabase, so you can
fetch it from the database next time.

Read alias:
-----------
Use this to browse the alias database and to paste 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 "Paste"
button.

Aliases can be removed again by selecting them and clicking the "Remove"
button.

Message:
--------
A window to supply a SHORT message on the frontpage. Either type it manually
or use "Load Message". 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 I think a
frontpage shouldn't contain too much information. You'd better use an
attachment instead if you need to send longer messages.

Attachments:
------------
<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.

<REMOVE FILE> By first selection a file in the "Attachments" window and then
pressing "Remove File", you can drop a file again from your attachments.

<EDITOR> Allows you to start your favorite editor to produce a message and
to add it to the attachments list afterwards.

Buttons at bottom row:
----------------------

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

Note: the first 2 pages are converted in the foreground, so the system will
wait until these are finished before starting the viewer. All other pages
will be processed in the background, to make things (seem) a little faster.
However, if you jump immediately to page 3 .... there is a change it isn't
yet finished. In that case: just retry a few times until the conversion
process has finished it's work and the viewer comes up with the page.

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 /opt/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 i.e. to see
if your fax has been succesfully sent (if using a direct faxprogram) or use
it for debugging the various scripts.

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

<EXIT> Obvious, if not, see the "Exit" explanation above.

RECEIVING FAXES:
================

There used to be a Receive Fax button in xfax but it wasn't very useful, so
I dropped it from the program in version 1.10. The problem is that receiving
faxes is actually more a job for a daemon than a job for a graphical user
interface. This daemon should monitor the faxline permanently for incoming
faxes and should be started through i.e. /etc/inittab or rc.local.
In a multiuser environment then someone has to read all the faxes to determine
the actual recipient, as this cannot be done automatically (yet ?).

There are also too many different possibilities for a receive button, like :

- Pick up all incoming faxes for the current user from a certain directory
  (where they were previously stored by i.e. a secretary)
- Answer the telephone using 'efax receive' when you know there is a fax
  calling on the other side. (user at home)
- Start the daemon process that monitors the line permanently. (this can 
  cause problems for outgoing modemcalls) 

SUPPORTED FILEFORMATS:
======================

Only support for Postscript, GIF and of course ASCII is currently build in.
The rest should first be converted to one of these formats before it can be
faxed with xfax. However, you can change virtually everything into
PostScript, so this shouldn't be a real problem.

Note that the detection is quite simple:

Every file starting with "%!" is considered to be a Postscript file and
every file starting with "GIF8" is supposed to be a GIF picture (This is to
support both GIF87a and GIF89a versions). All other files will be treated
as if they were ASCII.

SUPPLIED SCRIPTFILES:
=====================

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

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

to run it every 10 minutes between 8 and 19 on weekdays.

FAXQUEUE: Only moves the complete faxdirectory with all G3 files, frontpage
and faxinfo to the spool directory and leaves the actual sending to the
separate spooler (i.e. faxserver). Of course the spooler 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 'ppmtoxpm' 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 !!

Note that there are 3 options: a Low Res, Medium Res and High Res one. Use the
one that corresponds with the viewfax window you choose at compile time or
the one that you supplied on the commandline or else the rendered image
won't fit into the faxviewer !

Sometimes the ppmtoxpm program hangs due to a parse problem with a
commentline in /usr/lib/X11/rgb.txt starting with a '!' sign. In that case
you can remove the commentline from the rgb.txt file and everything will
work fine.

*** NOTE for HPUX 10 users *** : efix08 doesn't produce valid pgm files, no
matter if compiled with gcc or the native compiler. As this is necessary for
the viewer I decided to use efix07 - that works fine - instead.

GIFTOG3: A simple script based on the pbm tools to convert a GIF file into a
G3 file. Of course you can use any other script if you like. The script will
- unlike the PSToG3 and AsciiToG3 commands - only produce one G3 file for
each GIF picture.

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:

 /opt/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 it has a builtin viewer now it
isn't very useful anymore, unless you want to view pages manually.

OTHER REQUIRED SOFTWARE:
========================

- Efax and efix, both by Ed Casas (I used the efax07a.tar.gz distribution)
  You won't need the 'fax' script that was supplied, but of course you may 
  write a wrapper around it to make it read all files in the fax directory
  (frontpage and g3files) and to send email if requested.
  I have precompiled versions for both Linux and HPUX, so if you want to use
  mine: just let me know.

- ghostscript (gs) with fax g3 support to convert Postscript files to G3.
  Note that the Aladdin version uses -sDEVICE=faxg3 while the GNU version uses
  -sDEVICE=dfaxhigh to produce fax format !!

- some pnm, pbm etc. tools to convert Gif files to G3 and to convert g3
  files into xpm format. (i.e. ppmtoxpm for viewer)
  The are all part of the "netpbm" or "pbmplus" toolkits and are widely
  available on the net, either precompiled or in source.

HOW TO COMPILE/INSTALL:
=======================

If you don't have the xforms library and headerfile: get one from the Xforms
webpages: http://bragg.phys.uwm.edu/xforms

- Check for the right compiler, compilerflags (include paths for X11 !) and
  libraryflags (libraries for X11 !) in the Makefile and check if you can
  agree with the presets in xfaxdefs.h . Note that if you change the FAXBASE
  directory /opt/lib/xfax , you'll also have to check the supplied scripts
  and alter the basepath where necessary.

- Check if you can agree with the default HighRes FaxViewer (which doesn't
  fit completely on a 1024x768 screen) or else choose a lower one by
  changing the VIEWERSIZE macro in the xfaxdefs.h headerfile (HR,MR or LR).
  Note that it can also be changed from the commandline now.

- After that you can type "make". If everything went well, you should have a
  working xfax now.

- After this you may obtain the efax package and build efax and efix. Without
  these programs you won't be able to send your faxes !

- Install the scripts, efix and efax in the FAXBASE path (/opt/lib/xfax) and
  set a softlink from either 'faxqueue' or 'faxdirect' to 'faxsend',
  depending on how you want to send your faxes.

- Check the search paths in the various scripts and also check if you have
  the necessary programs (conversion programs from the 'netpbm' or 'pbmplus'
  tools and the ghostscript program if you want to process postscript
  files).

- Check the 'faxdirect' and 'faxserver' commands for the modem port, dial
  prefixes and so on and set the DEV, FROM and HDR info with your local
  information. You may also check the BUSYRETRIES settings.

- Check also the PRINTCMD in the 'faxprint' script. Note it should be
  capable of printing Postscript, so if you don't have a Postscript printer
  you'll need a filter with ghostscript to produce output for i.e. a
  Deskjet.

If you are going to use the faxserver and a faxqueue :

- Install the faxserver by setting the crontab entry and creating the
  /var/spool/fax directory. Either you can make this worldwritable (i.e.
  with a -t bit) or use a guid bit on the 'faxqueue' command if your OS
  supports it for scriptfiles.

  Remote queuing can be achieved with an NFS export of the /var/spool/fax
  directory on the faxserver and the use of i.e. the automounter.

Alternatively you may use 'rcp' or a TCP/IP connection to queue your faxes
or you may try to use the printqueue for this trick. I did it myself with
the BSD printer spooler once and that wasn't too difficult.

Comments:
=========

If you have any comments, found any bugs or just want some extra features
to be added: write email to lemmens@dv.twi.tudelft.nl and I'll see what I
can do.

