NAME
efax-gtk - GUI front end for efax program
SYNOPSIS
efax-gtk [options] [ file ]
Options: [-rs]
-r Start the program in receive standby mode
-s Start the program hidden in the system tray
COPYRIGHT
Efax-gtk is Copyright (C) Chris Vine, 2001 - 2008. It is released
under the General Public License, version 2.
DESCRIPTION
efax-gtk is a GTK+ front end for the efax program. It can be used to
send and receive faxes with a fax modem, and to view, print and manage
faxes received. It also provides a socket interface to provide a
"virtual printer" for sending faxes from word processors and similar
programs, and can automatically e-mail a received fax to a designated
user.
The efax-gtk distribution compiles and installs a patched version of
efax-0.9a-001114, so you do not need to separately build and install
efax. In particular, the version of efax supplied with efax-gtk
provides internationalization support, and resolves certain
difficulties with locales in the standard distribution.
To avoid name conflicts the patched versions of efax and efix are
installed as efax-0.9a and efix-0.9a. If you want to use the standard
distributions of efax, delete efax-0.9a and efix-0.9a, and then make a
symbolic link from efax to efax-0.9a and from efix to efix-0.9a so that
efax-gtk can find them. efax-0.9 or higher is recommended, although
the program 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.
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.
ARGUMENTS
A file may be passed as an argument to the program, in which case that
file will automatically appear in the "File to send" box when the
program starts.
USE
The first time you use the program, you will be asked if you accept the
terms of the General Public Licence, version 2.
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. It can be entered manually in the "Fax to send" box, or
entered by means of the file selection dialog. If the file comprises a
single postscript file, then you can find it by pressing the "Single
File" button. It can be more easily found with this dialog if it is
placed in the $HOME/faxout directory.
Where more than one file is specified in the "Fax to send" box, they
will be sent as a single fax appended in the order in which they are
entered in the box. Such multiple files can be more easily selected
using the file list brought up by pressing the "Multiple Files" button.
Pressing the "Multiple Files" button enables files to be found and
added to the file list, and they can be reordered by using the Up or
Down arrow buttons, or by dragging and dropping with the mouse. (If
entering multiple files manually rather than by means of the "Multiple
Files" dialog, use a `,' or a `;' as the file name separator.)
The telephone number to which the fax is to be sent is 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. However,
if a telephone connection has already been established with the remote
fax receiver, then the fax can be sent without dialing by leaving the
"Tel number" box blank (a dialog will come up asking if you would like
to send the fax without dialing - this does the same thing as `fax send
-m ...' using the efax `fax' script from the command line).
When a fax is received from the print system via the socket server, the
program settings can be configured to bring up a dialog automatically.
If the program is inactive or is standing-by to receive faxes the fax
can be sent directly from this dialog without the need to invoke the
list of queued faxes received from the socket.
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.
The program can send a fax when it is in receive standby mode. If
sending a fax from receive standby mode, when the fax has been sent (or
there is an error in sending the fax), the program will return to
receive standby mode.
To make sending faxes from word processors easy, a socket server is
provided interfacing directly with the print system. See below for
further details.
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').
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. A fax can also be sent when the program is in receive standby
mode.
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 "Standby" 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.
When a fax is received, a pop-up dialog can also be set to appear (go
to the Settings dialog to do this).
In the settings dialog you can also specify a program to be executed
whenever a fax is received. The fax ID number is passed as the first
(and only) argument to the program, which enables the program to find
the fax in $HOME/faxin. The distribution contains two executable
scripts, mail_fax and print_fax, which can be used to e-mail a fax to a
user or print a fax automatically when it is received. (These scripts
are not installed by `make install' - if you want to use them, make
them executable with `chmod +x' and copy them to a directory which is
in the system path, such as /usr/local/bin, and then specify the script
name in the settings dialog).
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 gv.
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 `Trash' folder. If the
delete (trashcan) button is pressed in relation to a fax in the `Trash'
folder, it will be deleted from the file system.
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.
The received faxes list will show, at the far right of the tool bar,
the number of faxes received since the program was last started. If
efax-gtk is in receive standby mode, the "tooltips" for the program's
icon in the system tray will also indicate this number. The count can
be reset to 0 without restarting the program by pressing the reset
button in the received faxes list.
Settings
The program settings can be changed by manually editing the efax-gtk
configuration file comprising $HOME/.efax-gtkrc, $sysconfdir/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 the global
configuration file ($sysconfdir/efax-gtkrc or /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. If a log file is specified, then it
can be viewed from the "Log" pull-down menu, and if efax-gtk is
compiled against GTK+-2.10 or greater, the log file can also be printed
from the pull-down menu.
USING WITH A WORD PROCESSOR
Printing to file from the program itself
Probably the simplest way of using the program with a word processor is
to print to file from the print dialog of the word processor program
concerned, and choosing a file name in the $HOME/faxout directory which
can then be selected with the file selector dialog in efax-gtk. All
Unix/Linux word and document processing programs will print to file in
Postscript format, ready to be faxed by efax-gtk. (At least, if there
is one which does not, I do not know of it).
Printing via CUPS
Efax-gtk can run a socket server, which CUPS can connect to. When the
socket server is running, fax files received from CUPS will
automatically be displayed in a "Queued faxes from socket" list
maintained by efax-gtk. From this list, a fax can be selected for
sending by efax-gtk, so there is no need to print to file from the word
processor and then select the file with the file selection dialog in
efax-gtk.
When a fax is received in this way from the print system via the
socket, the program settings can also be configured to bring up a
dialog automatically. If the program is inactive or is standing-by to
receive faxes, the fax can be sent directly from this dialog without
the need to invoke the list of queued faxes received from the socket.
If you are using CUPS and you want to connect it directly to efax-gtk
as mentioned above, you can do so by bringing up the fax administration
page for CUPS in a web browser, installing a new printer with a name of
"fax" (or whatever other name you want), choose the IPP protocol, pick
a URI of "socket://[hostname]:[port]", and choose the "Raw" CUPS
printer driver.
The port number can be any port number less than 65536 and more than
1023 which is not used by any other service on your machine/network
(this can be checked out by using nmap, but it is best to avoid any
listed in /etc/services). For example, as you will usually be printing
from a local computer, if you choose a port number of 9900 (which would
be quite reasonable) the URI would be:
socket://localhost:9900
As an alternative, rather easier than the web interface is adding a new
CUPS virtual printer for efax-gtk by using lpadmin. To do this, log in
as whatever user has appropriate permissions (usually root) and do it
from the command line with:
/usr/sbin/lpadmin -p FaxPrinter -E -v socket://localhost:9900
That will create a printer name for efax-gtk called FaxPrinter for a
case where efax-gtk is listening on port 9900.
You should then start efax-gtk, go to the Socket tab in the settings
dialog, check the "Run socket server" box, and enter 9900 in the "Port
to which faxes to be sent" box.
To send a fax from the "Queued faxes from socket" dialog, highlight the
one to be sent, press the "Enter selected fax to send" button in the
dialog (the one with an icon representing a fax machine) which will
enter the fax in the "File to fax" box in efax-gtk, and then choose a
telephone number to send it to and press the "Send fax" button in the
ordinary way.
If efax-gtk isn't running when you attempt to send a file via CUPS to
efax-gtk don't worry. CUPS will queue the fax until it detects that
the efax-gtk socket server is running, and then send it to efax-gtk.
Where a fax is queued for sending in the socket list, a small red
circle will appear in the main program window on the right hand side of
the "Fax to send" box.
Printing via lpd/lprng
The socket server can also be used in the same way with lpd/lprng. The
files efax-gtk-faxfilter and efax-gtk-socket-client are installed in
/var/spool/fax, when you run `make install' (the installation directory
can be changed at the ./configure stage using the "./configure
--spooldir=[dir]" parameter. You should add at the end of
/etc/printcap the following -
fax:\
:sd=/var/spool/fax:\
:mx#0:\
:sh:\
:lp=/dev/null:\
:if=/var/spool/fax/efax-gtk-faxfilter:
This will cause a printer by the name of "fax" to be available, which
(if printed to) will send the file to the efax-gtk socket server. If
you set efax-gtk to listen on a port other than port 9900, you will
need to amend the file /var/spool/fax/efax-gtk-faxfilter by hand to
specify the correct port number on which efax-gtk is listening.
Don't forget to restart the lpd printer daemon after amending
/etc/printcap. (An equivalent addition to /etc/printcap can also be
made by using the printer configuration tool with your distribution,
choosing a printer name of "fax" (or whatever other name you want),
choosing a printer device of "/dev/null", a spool directory of
"/var/spool/fax" and an input filter of "/var/spool/fax/efax-gtk-
faxfilter".)
SYSTEM TRAY
Efax-gtk has been written so that it will sit in the system tray in
GNOME and KDE when the program is running.
From the system tray, the program can be hidden and raised again by
left-clicking with the mouse on the icon, and right-clicking on it will
bring up a menu from which certain program operations can be performed.
A `tips' display will also indicate the program state if the mouse is
left hovering over the efax-gtk icon.
Clicking on the top right (delete) button of the window frame will not
cause the program to terminate if the program is embedded in the system
tray. Instead it will hide it in the tray. If you want to close the
program when it is embedded in the tray, either select the "Quit" menu
item in the system tray efax-gtk menu, or select the "Quit" menu item
in the "File" pull-down menu in the program toolbar.
Recent versions of GNOME call the system tray a "Notification Area".
If your desktop panel does not have a Notification Area installed, it
can be placed on the panel by right clicking on the panel, and going to
Add to Panel -> Utility -> Notification Area.
WORKING DIRECTORY
A working sub-directory for the storage of .efax-gtk_addressbook,
.efax-gtk_mainwin_save and .efax-gtk_queued_server_files and the
faxin, faxout, faxsent and efax-gtk-server directories can be specified
in the efax-gtkrc configuration file with the WORK_SUBDIR: parameter.
This working subdirectory will appear as a subdirectory of $HOME (so if
WORK_SUBDIR: is specified as efax-gtk, $HOME/efax-gtk will be the
working directory). If none is specified, which is the default, then
these files/directories will be stored directly in $HOME (which was
what happened before the option was available, so past efax-gtk
installations will not be broken if this option is left unset). The
WORK_SUBDIR: parameter enables these files and folders to be kept
together in a separate directory if wanted. If a WORK_SUBDIR:
parameter is specified, only .efax-gtkrc will appear directly in $HOME.
Note that if you specify a value for WORK_SUBDIR: in the efax-gtkrc
configuration file, you will need to shift old versions of the files
and directories mentioned above into the new working directory or efax-
gtk will not be able to find them, so use this option with caution. In
addition, if you wish to use the "print_fax" or "mail_fax" scripts, you
will need to set the WORK_SUBDIR option in the relevant script.
FILES
efax-gtk
The efax-gtk executable.
efax-gtk-faxfilter
A filter script for lpd/lprng which will send files to the efax-
gtk socket server
efax-gtk-socket-client
The companion socket client for efax-gtk-faxfilter
efax-gtkrc
The efax-gtk configuration file.
efax-gtk.po
Various translation files for different locales.
efax-gtk.1
Efax-gtk manual file
In addition some files from efax itself are installed, as follows:
efax-0.9a
The efax executable
efix-0.9a
The efix executable
efax.1 efix.1
Efax manual files
SEE ALSO
efax(1)
AUTHOR
Chris Vine
cvine@users.sourceforge.net
9 September 2008