Copyright (C) 2001 Chris Vine

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    A copy of the GNU General Public License version 2 is set out
    in the file COPYRIGHT accompanying this distribution.  You can
    also obtain a written copy from the Free Software  Foundation,
    Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

    Note that the copyright of the efax program, to which this is a
    front end, belongs to Ed Casas.

                            OVERVIEW

This program is a Gtk+/Gtk-- front end for the efax program for
receiving and sending faxes with a fax modem.  To use it you must have
efax and ghostscript installed, and the executables (efax, efix and
gs) must be situated in the default system path (such as /usr/bin or
/usr/local/bin).

Any files to be faxed must be in postscript format, which is the
generic printer format for Unix/Linux systems.  The program will use
ghostscript to convert these into the Group 3 fax format which the fax
modem will understand.

		INSTALLATION: FROM SOURCE FILES

Compiling from source
---------------------

To compile from source, place the distribution file in a local source
directory (eg ~/src).  Untarring/unzipping it will create a
sub-directory 'efax-gtk' where the source code can be found.  You can
now edit the file efax-gtkrc (which by default will be placed by "make
install" in /etc) to provide global settings which match your serial
port, name, telephone number and other particulars.  efax-gtkrc
specifies run-time not compile-time options, but you can edit it now
so that the version installed by "make install" is correct.
Alternatively, you can start up the program and enter any settings by
bringing up the `Settings' dialog from the `File/Settings' pull-down
menu once the program has started.  (See below).

Then enter the command `./configure'.  This will set up the Makefile
so that it matches your system.  This can be done as user (you do not
need to be root).  Then type "make", and then "make install".  "make
install" must be run as root, but "make" can be run as user.  The
program will by default be installed in /usr/local/bin.  The name of
the executable is "efax-gtk".

You can change the install directory by running `./configure' with the
--prefix=[dir] option.  Thus -

  ./configure --prefix=/usr

will install the executables in /usr/bin, as will -

  ./configure --bindir=/usr/bin.

The configuration file efax-gtkrc (see above) is by default installed
in /etc.  This can be changed by running ./configure with the
--datadir=[dir] or --sysconfdir=[dir] options.  Thus -

  ./configure --sysconfdir=/usr/local/etc

will install the file in /usr/local/etc.

The man file will by default be installed in /usr/local/man/man1.  If
the --prefix=[dir] option is used, the base directory will be taken
from that.  So - 

  ./configure --prefix=/usr

will install the man file in the /usr/man/man1 directory, as will -

  ./configure --mandir=/usr/man

In addition, a fax filter file `efax-gtk-faxfilter' is by default
installed in /var/spool/fax (see below to see what this file does).  A
different directory can be chosen by running `./configure' with the
--with-spooldir=[dir] option.

To compile and use the program, gtk+-1.2.*, libsigc++-1.0.* and
gtkmm-1.2.* must be installed.  You must have these and (to compile
the program) the respective gtk+-devel-1.2.*, libsigc++-devel-1.0.*
and gtkmm-devel-1.2.* RPM packages installed if you use the Red Hat
RPMs.

efax-0.9 or higher is recommended, although it will work with older
versions of efax (with older versions, some automatic configuration
options will not be available and the different lock file semantics
means that a binary and not UUCP lock file will be created, which may
confuse some other programs trying to access the same serial port).

Making RPM binaries
-------------------

A RPM spec file is included in the distribution.  If rpm is installed,
entering `rpm -tb efax-gtk-[version].src.tgz' as root will create a
standard RPM binary file efax-gtk-[version]-1.[i386].rpm.  This will
be found in the RPM binary directory that your RPM-build configuration
specifies (normally /usr/src/redhat/RPMS/i386 for Redhat i86 systems,
and /usr/src/packages/RPMS/i386 for SuSE i86 systems).

To install the rpm binary once made, use the normal command
`rpm -i [rpm filename]'.

To make the binary RPM file you must have the gtk+, libsigc++ and
gtkmm packages installed (and if you are using Redhat you must also
have the gtk+-devel, gtkmm-devel and libsigc++-devel packages
installed).  Once the rpm file is made, to install it you must also
have the efax and ghostscript packages installed, as efax-gtk.spec
file causes rpm to check for these dependencies when efax-gtk is being
installed.  This can give rise to problems of portability, because
different distributions package things under different names.  The
efax-gtk.spec provided is known to work with Redhat and with Suse-7.3.
If the rpm binary won't install on your system because of these
dependencies, but you are sure that you have gtk+, libsigc++, gtkmm,
ghostscript and efax installed, there are two choices -- to install
the binary file using `rpm -i --nodeps [rpm filename]', or to:

- unzip efax-gtk-[version].src.tgz,

- amend the `Requires:' line in the efax-gtk.spec file to provide the
correct dependency package names for your distribution

- copy efax-gtk-[version].src.tgz to /usr/src/[packages]/SOURCES

- enter `rpm -bb efax-gtk.spec'.

If you install via binary RPMs, then you will either have to use the
File/Settings dialog to configure the program when you first use it,
or before using it have to amend /etc/efax-gtkrc by hand after
installation (see further below).

                             USE

The first time you use the program, you will be asked if you accept
the terms of the General Public Licence, version 2.

Files to be sent should be saved as postscript files.  If the program
is started with a filename as the last argument, then it will begin
with that file already inserted in the program's "file to be sent"
box.  Otherwise once the program has started you can use the standard
file open dialog, or enter it directly into the box via the keyboard.

If sending from a wordprocessor, you can automate this to some extent
if your /etc/printcap file has an entry called "fax", which you can
add to the end of /etc/printcap as follows --

fax:\
	:sd=/var/spool/fax:\
	:mx#0:\
	:sh:\
	:lp=/dev/null:\
	:if=/var/spool/fax/efax-gtk-faxfilter:

(Don't forget to restart the lpd printer daemon after amending
/etc/printcap).

Alternatively, use the printer configuration tool with your
distribution, choose a printer name of `fax' (or whatever other name
you want), choose a printer device of `/dev/null', a spool directory
of `/var/spool/fax' and an input filter of
`/var/spool/fax/efax-gtk-faxfilter'.

This will cause a printer called "fax" to be available to any programs
having postscript output (which includes every Linux/Unix
wordprocessor known to man) and using the standard printer spooler.
Running `make install' will save the accompanying file
"efax-gtk-faxfilter" in /var/spool/fax, which will cause the file sent
to the "fax" printer to be saved in postscript format as
/tmp/faxfile.ps.  You can then invoke the attached "efax-gtk-send"
executable script (which `make install' will place in the same
directory as efax-gtk), and which will start efax-gtk with the file
entered in the "file to be sent" box ready to be faxed (on closing it
will be moved to /tmp/faxfile.ps.backup, but /tmp/faxfile.ps.backup
will be overwritten by a subsequent start of efax-gtk-send, so keep a
separate copy).

If the efax-gtk-faxfilter script is amended to set the DISPLAY
environmental variable, and X has been set up so that connections are
allowed to the X server from the relevant IP address (e.g xhost
+localhost), it should be possible to start efax-gtk in the filter
script itself (making it unnecessary to invoke efax-gtk-send) by
inserting a line in the script such as `efax-gtk $TMP_FILE'.  (I don't
like this though, as it is not really suitable for a program intended
to manage as well as send faxes, and it can be a real fiddle to set
up).

Ordinary ascii text files can be converted into postscript if required
using a number of programs, of which probably the easiest to use are
nenscript or GNU enscript (`man enscript').

Sending faxes
-------------

Before sending a fax, the name of the file to be sent must be
specified in the "File to fax" box.  The file specified must be in
postscript format, and will be converted by the program into the
correct tiffg3 fax format.

The file can be entered into the "File to fax" box by pressing the
"File to fax" button (or from the `File/Find file' pull down menu
item), by starting the program with the filename as the last
parameter, or by entering it by hand into the box.  Files can be more
easily found with the Find file dialog if they are placed in the
$HOME/faxout directory.

In addition, the telephone number to which the fax is to be sent must
be entered into the "Tel number" box.  This can be entered directly
into the box, or by using the built-in addressbook.  The addressbook
can be invoked by pressing the "Tel number" button, or from the
`File/Address book' pull-down menu item.  See "Using the address book"
further below.

To make the sending of faxes direct from a word processor program more
easy, see above.

Successfully sent faxes are copied to a directory in the $HOME/faxsent
directory, which has a name derived from the year, month, day, hour
and seconds when the sending of the fax was completed, and will appear
in the faxes sent list.  They are only included in that list if they
have been sent without error.  The efax message display box will
report on the progress of a fax being sent.  The fax list can be
brought up from the `File/List sent faxes' pull down menu item.  See
"Using the fax lists" further below.

Receiving faxes
---------------

Three ways of receiving faxes are provided for.

First, the program can be set to answer a fax call which is ringing
but has not been answered, by pressing the "Answer call" button.

Secondly, the program can take over a call which has already been
answered (say, by a telephone hand set) by pressing the "Take over
call" button.

Thirdly, the program can be placed in standby mode by pressing the
"Standby" button.  This will automatically answer any call after the
number of rings specified in the efax-gtkrc file, and receive the fax.
The program will keep on receiving faxes until the "Stop" button is
pressed.

Received faxes in tiffg3 format (one file for each page) are placed in
a directory in the $HOME/faxin directory, which has a name derived
from the year, month, day, hour and seconds when the relevant "Answer
call", "Take over call" or "Standy" button was pressed.  (Where in
standby mode after a fax has been received, any further fax will
derive its name from the time when receipt of the last received fax
has been completed and the program goes back into standby mode.)

Received faxes can be printed, viewed, described and managed using the
built in fax list facility.  This can be brought up from the
`File/List received faxes' pull down menu item.  See "Using the fax
lists" further below.

Using the address book
----------------------

To pick a telephone number from the address book, highlight the
relevant address by pressing the left mouse button over it, and then
press the "OK" button.

Addresses can be added to the address book by pressing the add button,
and then completing the relevant dialog which will appear.  To delete
an address from the address book, highlight the relevant address and
press the delete (trashcan) button.  The addressbook can be sorted by
using the up and down arrow buttons on a highlighted address.

Addresses are stored in file `$HOME/.efax-gtk_addressbook'.

Using the fax lists
-------------------

To bring up the fax lists, go to the the `File' menu and pick the
`List received faxes' or `List sent faxes' menu item.  Highlight the
fax to printed or viewed by pressing the left mouse button.  The
programs to be used to print and view the fax are specifed in the
efax-gtkrc configuration file, or if none are specified, the program
will print using lpr (which will work for most Unix systems) and view
with xloadimage.

Prepend `$' to the program name in the efax-gtkrc file for viewing the
fax if the fax viewing program can take multiple file names as its
starting arguments, in which case all the pages of the fax to be
viewed will be passed as file names to the viewing program when first
invoked (eg `$kview' will use the KDE image viewer) -- see the
efax-gtkrc configuration file for further details.  Alternatively this
can be set from the `Settings' dialog by entering it in the
`View/View' Program box.

The resolution of the fax to be viewed is specified with the VIEW_RES
parameter in the efax-gtkrc file.  The default is 200 dpi, which will
be fine with xloadimage or xv, but with a fax viewing program like
kview, 400 would give better results.  This can be changed while the
program is running by bringing up the `Settings' dialog and entering
it into the `View/View Resolution' box.

To print faxes, a PRINT_SHRINK parameter can be specifed in efax-gtkrc
to enable the fax page to fit within the printer margins.  A parameter
of 98 will work with most printers.  This can be changed while the
program is running by bringing up the `Settings' dialog and entering
it into the `Print/Print Shrink' box.

A fax can be deleted from a fax list by pressing the delete (trashcan)
button.  This will place the deleted fax in the $HOME/faxin/oldfax
or $HOME/faxsent/oldfax directory.

NB: link()/unlink() are used to move a fax, so $HOME/faxin/oldfax must
be on the same file system as $HOME/faxin, and $HOME/faxsent/oldfax
must be on the same file system as $HOME/faxsent.  If they are not,
the fax will remain in $HOME/faxin or $HOME/faxsent.

A description can be added to a received fax when appearing in a fax
list (or subsequently amended) by pressing the relevant button -- this
will enable faxes to be more easily identified.

To refresh a fax list (say, to update with any faxes received or sent
since the fax list was brought up), press the refresh button.

Settings
--------

The program settings can be changed by manually editing the efax-gtk
configuration file comprising $HOME/.efax-gtkrc,
/usr/local/etc/efax-gtkrc or /etc/efax-gtkrc.  The file is searched
for in that order, so $HOME/.efax-gtkrc takes precedence over the
other two.

The configuration file can also be set by using the Settings dialog
launched from the `File/Settings' pull down menu item.  The settings
entered using this dialog are always stored as $HOME/.efax-gtkrc.
Accordingly, if the Settings dialog has been used, and you want to
revert to the global settings, this can be done either by deleting the
$HOME/.efax-gtkrc file, or by pressing the `Reset' button in the
Settings dialog, which will reload the Settings dialog from
/etc/efax-gtkrc or /usr/local/etc/efax-gtkrc.

Help can be obtained when filling out the Settings dialog by holding
the mouse over the relevant help (?) button, which will bring up a
"Tips" display, or by pressing the button, which will bring up an
information display.

                                LOGGING

Errors and warnings from efax are displayed in red in the application
text window, and information messages and reports on the progress of
negotiations and on fax status are displayed in black in the window.
In addition, these messages are sent to stderr and stdout
respectively.  Accordingly, fax status can be logged by redirecting
stderr and stdout to a log file.

As an alternative, a log file can also be maintained by setting the
LOG_FILE parameter in the efax-gtkrc configuration file, or by
entering a log file name via the Settings dialog.  If no log file is
specified, no log file will be maintained.

                          CONTACTING THE AUTHOR

My e-mail address is chris@cvine.freeserve.co.uk.

Updates can be obtained from http://www.cvine.freeserve.co.uk/efax-gtk/

Chris Vine.
