Provided by: efax-gtk_3.2.8-2_amd64 bug

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                             EFAX-GTK(1)