This is the first draft of the Z-Fax User's manual.
Chapter titles are given in ALL UPPER CASE.
Section headings are given between paragraphs.
Figures are indicated by [notations in square brackets]

------------------------------------------------

SENDING WITH Z-FAX


The Z-Fax Send Window

The Send window is one of the two primary windows in Z-Fax.

       [full view of Send window, bordered by labels for items]

Figure XX shows the Send window.  From this
window, you can choose one or more fax recipients, select the file to
send, and specify whether to include a cover sheet as the first page
of each fax. You may also specify the type of file to send, and Z-Fax
will automatically convert the file to fax format when you press the
Send button.


Setting up a cover sheet

Before you send your first fax, you will need to set up your cover
sheet data.  Selecting "Preferences" from the "Edit" menu on the Send
menu bar will bring up the Send Preferences window:

                      [Send Preferences window]

In this window, enter your name, organization name, and your fax phone
number as you want it to appear on your cover sheets.  Also select
the file to use as your cover sheet.  This may be either an ASCII text
file, or a Postscript file.  Pressing the file cabinet icon will bring
up a file selection window which allows you to select from a list of
current files.  The default cover sheet offered is system-wide default
of /usr/lib/Z-fax/default.cover.

When you have entered the information, press the Save button to save
the information for future Z-Fax sessions.  If you do not save your
selections, the information will be lost when your exit Z-Fax.  Press
the Done button if you wish to close the Send Preferences window without
saving the selections.


Sending a fax

To send a fax, enter the name, organization, and fax number of the person
to which you want to send into the text fields in the left center
of the window.  Press the Add button to add this person to the recipient
list, displayed to the right of the text fields.
If you are not including a cover sheet, you do not need to enter any
data in the Name or Organization fields.

To add additional recipients, enter the new information in the name,
organization, and fax number fields, and press the Add button again.
You can use the scroll bars on the right and bottom of the
recipient list window to display different areas of the list.

To delete a recipient from the list, select the items in the recipient
list, then press the Delete button.  You can also delete all recipients,
as well as clear all the data fields in the Send window by pressing the
Reset button at the bottom center of the window.

In addition to the names and organization names, you can add a subject
line to your fax cover sheets by entering text into the Subject field.

Select a file to transmit by typing the name of the file into the
File Name text field, or press the List button to display a list of
files. You can then select a file directly from the list. Files may be
in ASCII, Postscript, TIFF, PBM, or fax format, and Z-Fax will convert
them automatically into fax format if needed.

You may enter more than one file to send, and the names of the files
will appear in the "Files to send" scrolled list above the File Name
field.  To delete files from the list, select the files to be deleted,
then press the Delete button under the "Files to send" list.

Select a priority by pressing the button next to the desired priority.
If you select "Delayed", the "Delay until" buttons will become active,
allowing you to select a delay time.  Set the delay time by pressing
the clock buttons until the desired time is displayed.  Pressing the
hour, ten-minute, and minute buttons will increment the displayed time.
Pressing the button on the far right will cycle among "AM", "PM, or
"Mil" for 24-hour time.  Pressing the left mouse button will increase
the digits, and the middle mouse button will decrease them.

When you have entered all the information, press the Send button to
begin queueing the faxes for transmission. Z-Fax will convert the files
in your send list to fax format, and create a seperate cover sheet for
each recipient.

Pressing the Reset button at the bottom of the window will clear all
the data fields and delete all recipients.


Using your fax phone directory

In addition to typing in names and fax numbers directly, Z-Fax provides
a fax phone directory in which you can store names and fax number of
people you frequently send faxes to.  To bring up the Fax Directory, press
the Pick button, or select "Fax Directory" from the Edit menu.

                      [Fax Directory window]

The upper half of the window displays a scrolled list of your directory
entries.  The lower half contains text fields in which you can add or
update entries.

To make an entry in your directory, enter a name, organization, and
fax number into the three text fields, and press the Add button
at the bottom of the Fax Directory window.  The entry will be copied
to the list in the upper portion of the window, and added to the
directory.

To update an existing entry, select that entry in the list.  The entry
data will appear in the text fields.  Make the desired changes in the
text fields, then press the Replace button.  The information in the
text fields will then replace the currently-selected entry in the list.

To delete one or more entries, select the entries in the list, then
press the Delete button.

When you are ready to select recipients, select one or more entries
in the list, then press the Fax button.  Z-Fax will copy the selected
entries to the recipients list on the Send window.

Press the Save button to save the directory for future Z-Fax sessions.
The directory will be written to the file ".zfaxdir" in your home
directory.  If you do not save the directory, Z-Fax will give you
the opportunity to save just before you exit Z-Fax.

Pressing the Done button will close the Fax Directory window without
performing any other actions.


Selecting priorities

Z-Fax offers four levels of priority for outgoing faxes:

* Normal priority: used for most transmissions, faxes at this level
    are sent on a first-come-first-served basis.

* High priority: used for urgent documents, high-priority faxes
    are sent before all other faxes.

* Offpeak: for less urgent documents, off-peak faxes are held until
    off-peak hours, as defined by the system administrator.  This
    prevents them from interfering with high and normal priority
    documents, and can be sent during hours of lower telephone rates.

* Delayed: you can select a specific time at which the fax will be sent.


Priorities of faxes are selected on the Send window.


The fax send queue

To allow all the users on a system to use a single or small number of
fax devices, Z-Fax manages outgoing fax documents in a queue, similar
to the queue used by the UNIX print spooler.  When you send a fax from
the Send window, it is sent to a waiting area where your fax waits
its turn based on priority and time entered into the queue.

From the Send window, you can display the list of faxes waiting in
the queue, and cancel your own faxes if desired.  Select the "Fax Queue"
item from the "Queue" menu on the Send window to open the
Fax Queue window.

                          [Fax Queue window]

Each fax in the queue is displayed on one line.  The columns of the
display contain information about the fax.

* column 1 displays the fax ID, a unique identifier given to each fax
  in the queue

* column 2 displays the recipient of the fax.

* column 3 displays the phone number to which the fax will be sent.

* column 4 displays the priority of the fax: High, Normal, Offpeak,
  or Delayed.  This column also shows certain status indicators such
  as SENDING and FAILED.

* column 5 shows the number of pages of the fax

* column 6 shows the time at which the fax was placed in the queue

* column 7 displays the sender of the fax

Depending upon the size of your screen, not all the columns may display
at once.  Use the scroll bar at the bottom of the list to scroll the
list left or right.

You can delete a fax that you submitted in the queue by selecting the
fax in the list and pressing the Delete button.  You cannot delete
faxes sent by anyone else.

If you have the Fax Queue display open for more than a few minutes,
the contents of the queue may change.  Press the Refresh button to
update the list with current information.  The list is automatically
updated each time the Fax Queue window is opened.


Failed transmissions

A fax may not get through for a variety of reasons.  The other fax
may have been busy or not answering, ran out of paper, or the phone
number may have been incorrect.  If Z-Fax cannot transmit a fax,
it will notify you by electronic mail.  The fax document will either
be saved in the outgoing queue directory, or discarded, depending
on how the system administrator has configured Z-Fax.  For more
information, see Z-FAX CONFIGURATION section.


Creating your own cover sheet

You can create your own individual cover sheet and use it in place
of the standard Z-Fax cover sheet.  The cover sheet can be either
ASCII text or Postscript, and must be a single page.

The variable information on the cover sheet, such as the recipient's
name and organization, is represented by variable strings that are
replaced with the corresponding values when the fax is sent.  These
variables are:

$recpient       Name of the recipient of the fax
$recipientorg   Company or organization of the recipient
$sender         Name of the fax sender
$senderorg      Company or organization of the sender
$subject        Subject of the document
$pages          Number of pages, including the cover sheet
$date           The date on which the fax was sent
$time           The time of day at which the fax was sent

Note that because of delays in the fax queue, the date and time
placed on the cover sheet may not correspond to the actual date and
time the fax is transmitted.

When a fax is sent, these strings are removed and replaced by the
corresponding values from Z-Fax.


RECEIVING FAXES WITH Z-FAX


How faxes arrive

Because fax documents arrive as bitmap images, the computer cannot easily
decipher who is the intended recipient.  Therefore, Z-Fax can be configured
to handle incoming faxes in one of two ways.  Received faxes can be stored in
the receive directory (usually /usr/spool/fax/incoming) where everyone
would have access to them, or faxes can be sent by electronic mail to one
person, who distributes them to the intended recipient.  See the section
Z-FAX CONFIGUATION for information on how select which method Z-Fax uses
on your system.


The Z-Fax View window

Viewing received faxes is done in the View window, the second primary
window in Z-Fax.

      [View window with insensitive controls and blank display area]

The View window has three areas: the menu bar, the contol panel, and
the display area.  If you invoke Z-Fax using the "zfax" command with
no file to display, the display area is blank and all the controls
in are turned off, or "insensitive."

To select an image to view, select the "Open" item from the File menu.
This will open the File Finder window.  Select a file from the scrolled
list, or enter the name of a file directly.

Once you have selected a fax file to view, Z-Fax will decode the file
from fax format to viewable form.  While this is happening, Z-Fax
will display a "Working" window

                           [Working window]

You can interrupt the process by pressing the Stop button in the
window.  This will abort the display of the selected fax file.

After Z-Fax has decoded the fax, the first page of the fax will be
displayed in the viewing area.

      [View window with normal controls and fax displayed]

Use the scroll bars on the right side and bottom of the viewing area
to display different areas of the current page.


Paging, scaling, and rotating faxes

The control panel on the View window contains, from left to right, a page
selector, four buttons for rotating the displayed document, four buttons
for resizing, and two buttons for changing the colors used to display the
document.

The page selector is a scale bar that can be moved left and right to select
a specific page of the document. Beneath the scale at either end are the
first and last page numbers. Directly above the bar is the number of
the current page. To select the next or previous page, click once in the
track on the left or right of the bar. To select a specific page,
drag the scale bar left or right until the desired page number appears
above the bar. Note that the displayed page will not change until you
release the bar.

The four orientation buttons are used to rotate the displayed document
to one of for 90-degree positions. The letter F on the buttons indicates
the orientation of the original document as received from the sender.

The four size buttons are used to enlarge or reduce the displayed image.
The button labelled 25% reduces the document to one-quarter of its original
size, the 50% reduces it to one-half . The 200% buttons doubles the size
of the image, and the 100% button displays the document at its original
size.  The default size is 50%, not 100%, since that better reflects a
typical fax on a typical
workstation screen.

The size and orientation functions are also available on the menu bar
at the top of the window, so that you can use keyboard commands as well
as the mouse to rotate and scale the document.


Changing fax colors

In addition to the tranditional white background and black foreground
of paper fax documents, Z-Fax allows you to select the colors used to
display your fax documents.

Pressing the paint button on the Fax View window, or selecting the
Change Colors item on the Options menu will bring up the Color Selection
window. This window displays pushbuttons of different colors, a
color bar to display the currently selected color, and action buttons
to apply the color to the foreground or background.

Pressing one of the colored pushbuttons makes that color the current
color, and changes the color bar to that color. Press the Foreground
or Background button to assign that color to the foreground or background
areas of the currently displayed fax. Pressing the button labeled
Exchange will switch the current foreground and background colors.

Z-Fax will not allow you to assign the same color to both the foreground
and the background, since the document would then be invisible.

Color selections will remain in effect until you exit Z-Fax. Use the
Receive Preferences window to select the colors you want to use when
Z-Fax is started.

There is also a button to swap the foreground and background colors.


Printing received faxes

After a fax document has been displayed in the View window, you
can print the fax to one of your system's printers through the UNIX
print spooler. Select Print from the File menu of the Fax View
window to open the Print window.

                           [Print window]

Enter the name of the printer to print to as defined by your print
spooling system, and select one of the three types of printers
supported: Postscript, HP LaserJet, or Epson dot matrix. Press the
Print button to send the fax to the UNIX print spooler.

Note that by using the Save window, you can also produce output
for a printer, but save the data to a file rather than sending it
directly to the printer.


Converting received faxes to other graphics formats

In addition to printing received faxes, you can also convert fax
documents to other graphics formats in order to use them in other
applications, such as destop publishing or OCR (Optical Character
Recognition).

                          [Save File window]

Select Save File from the File menu of the Fax View window
to open the Save window. Select the desired graphics format,
then enter the name of the output file. Press the Save button, and
Z-Fax will convert the fax to the selected format and write the output
to the new file. The formats that can be created are:

  - TIFF Class F: Tag Image File Format using CCITT Group 3 compression
and storing each page as a TIFF subfile. For general storage and
image interchange, this format is recommended, as it is widely used
by many other applications, such as desktop publishing, drafting and
paint packages, and requires the least amount of disk space.

  - TIFF: Tag Image File Format using no compression, for
interfacing with applications that do not support CCITT Group 3
compression.

  - X Bitmap: an image storage format used by X Windows. This format
is very easy to incorporate directly into C programs.

  - Portable Bitmap (PBM): a format used by the PBMPLUS libraries and
utilities. The PBMPLUS utilities, available from many public UNIX archive
sites, can be used to convert PBM-format files into many other graphics
formats used on UNIX, MS-DOS, and Macintosh computers.

  - Postscript, HP LaserJet, and Epson: these formats are provided
for creating output for printers without actually sending the output
to a printer.

Note: except for TIFF Class F, these formats produce extremely large
files and will require a great deal of disk space.


Setting receive preferences

The Receive Preferences window allows you to select options pertaining
to viewing, printing, and saving received fax documents.  Select
Preferences from the Options menu on the View window to open this window.

                    [Receive Preferences window]

You can specify the initial size, orientation and colors used to display
fax documents. The name and type of your printer, and the default file
save type can also be saved. All of these options are used by Z-Fax as
initial settings. You can modify them after Z-Fax is running. Press
the Save button to store the current settings for future Z-Fax sessions.


COMMAND-LINE INTERFACE

In addition to the X Windows interface, Z-Fax provides several external
utilities accessible from the UNIX command line, or for use from within
other programs or shell scripts.  Utilities are provided to create
and queue fax documents for transmission, examine and manage the fax
queue, and print received documents.


Creating a fax document

The buildfax utility is used to create a fax document, including a
cover sheet.  buildfax can convert ASCII text, Postscript, TIFF
into fax format, or add a cover sheet to and existing fax file.
buildfax requires at least one argument, the name of the input
file to convert.  All instructions to buildfax are given as options
on the command line:

	-o <file>	Write the final output to <file>.  If no
			-o option is given, output is written to
			the standard output.

	-c <file>	Use <file> as the cover sheet.

If the -c option is given, the following options allow you to
customize the cover sheet:

	-r <recipient>	Name of the recipient of the document

	-ro <org>	Recipient's company or organization

	-s <sender>	Name of the sender

	-so <org>	Sender's company or organization

	-S <subject>	Subject line for the cover sheet

If no -c option is given, these options are ignored.  Alternately,
the environment variable ZFAX_COVER_FILE can be set to select the
cover sheet file.  If this variable is set, the -c flag is assumed
by buildfax.  If you have a ZFAX_COVER_FILE set and do not want a
cover sheet, use the -n option.

After the options, list the name of the file you want buildfax to convert.
If you give more than one file, the files will be compiled into one fax
document.  The files will appear in the document in the same order they
appear on the command line.


Sending faxes

The utility "faxit" is an interactive, character-based utility for
building and sending fax documents.  It will prompt you for files to
send, a recipient information either entered directly or selected from
your fax phone directory, and will ask whether to include a cover sheet.
faxit will then build a fax file and cover sheet from the information
given, and submit it on the fax queue.

faxit recognizes two environment variables, "NAME" and "ORGANIZATION"
The value of NAME is offered as the sender's name, and the value of
ORGANIZATION is the initial value of sender' organization.


Printing fax documents

The printfax utility accepts fax documents and converts them for output
to printers.  printfax can also automatically spool the converted fax
through the UNIX print spooler.  printfax is controlled by the following
command-line options:

	-t <printer>	Specifies the type of printer, one of postscript,
			laserjet, or epson.  The abbreviations ps, lj,
			and ep are also accepted.

	-l		Spool the output through the UNIX lp print spooler
			If no -l is given, output is sent to printfax's
			standard output.

	-d <dest>	Tells the UNIX print spooler the destination printer
			(System V compatibility).

	-P <dest>	Tells the UNIX print spooler the destination printer
			(BSD compatibility).

	-s		Supress the printing of the request ID from lp
			(System V only)

The -d, -P, and -s options are ignored if -l is not given.


The fax queue

Z-Fax provides four utilities for managing the fax queue.  queuefax
submits fax documents onto the queue.  It requires at least two arguments,
the name of the file to queue, and the fax number to which it should
be sent.  An optional -p flag can be used to supply a priority of
high, normal, or offpeak.  If no -p is given, normal priority is used.
The -d flag can be used to give a delay time.  -d must be followed by
a 3- or 4-digit integer specifying the time to send.  The first one
or two digits specify the hour, and the last two digits the minute.
The -r flag may be used to specify a recipient name.  This information
is only used for display in a queue listing, and is helpful for tracking
documents in the queue.  Enclose the recipient name in quotes if it
consists of more than one word, or contains any shell special characters
such as "?".  The -s option can be used for "silent mode" where queuefax
does not output the request ID of the queued fax.  This is useful if
queuefax is being run from another program.

Here are some examples of queuefax command lines:


queuefax -s invoice.fax 767-4265

queuefax -p high -r "Mr. VIP" quote.fax 555-1234

queuefax -d 0600 -r "Sales Manager" contract.fax 555-1234


The requeuefax program re-enters a failed fax into the active queue.
It requires one argumemnt, a fax ID.  The flags are the same as for
queuefax except that you can't specify the recipient.

The listqueue utility lists all items currently in the queue, displaying
the fax ID, recipient, fax number, priority, number of pages, time
placed in the queue, and sender.

dequeuefax deletes an item from the fax queue.  It requires one
argument: the fax ID of the item to delete.



Z-FAX CONFIGURATION


Z-Fax Library Directory

The Z-Fax library directory contains files Z-Fax uses in its
operation.  These files include the configuration file for the
queue system, the default cover sheet, and the help file for the
X Windows interface.  This directory is normally /usr/lib/Zfax.
If you move this directory, you can tell the Z-Fax programs the
new location by setting the ZFAXLIB environment variable to be
the full pathname to the new directory.


Z-Fax Configuration File

The file named "config" in the Z-Fax library directory controls the
behavior of Z-Fax for transmitting and receiving fax documents.
Information is stored in the file as variable names and their
values, for example:

FAX_ID=415-479-0448

Each variable must be on a separate line.  There must be no spaces
between the variable name and the '=' character.  If the value begins
with or contains spaces, it must be enclosed in double quote (")
characters.  Blank lines in the file are ignored.  Lines beginning with
the '#' character are also ignored, and can be used to insert comments
into the file.

Variables used by Z-Fax are:

FAX_ID		Your fax ID identifies you to remote fax devices.  Most often,
		your own fax number is used.  Up to 20 digits, letters, and
		punctuation characters may be given

LOG		LOG indicates the name of the file in which the log of fax
		transmissions and receptions will be recorded.  If no file
		name is given, no log will be kept.

NET_HOST	Z-Fax can be configured to send fax documents to another
		computer for queuing and transmission.  This is used where
		a number of workstations use the fax device or devices on
		one of the workstations.  Set this variable to the name of
		the computer where the faxes will actually be transmitted.
		If this variable is not set, Z-Fax assumes the faxes will
		be transmitted from the local computer.

NET_PORT	Set this variable to the TCP/IP network port number on
		which the fax server "netfaxq" will listen for fax queue
		requests.  Choose this number carefully; it must not conflict
		with any other daemons or services on your network.

TRANSMIT_DIR  	Indicates the directory used for the queue of fax documents
		waiting to be transmitted.

OFFPEAK_START	Define the beginning and end of the period during which
OFFPEAK_END	off-peak faxes are transmitted.  Times are given as two
		hour digits and two minutes digits, followed by an optional
		"a" or "p" to indicate A.M. or P.M.  If no "a" or "p" is
		present, A.M is assumed.  If the hour is greater than 12,
		24-hour time is assumed.

TRANSMIT_RETRY	Indicates how many times to retry failed fax transmissions.
		Note that the FIRST attempt is not counted, so a setting of
		2 will # attempt the transmission a total of 3 times.

TRANSMIT_FAIL	Indicates how failed fax transmissions are to be handled.
		A value of "return" will cause the entire failed document
		to be sent via electronic mail back to the sender.  "store"
		will send an error message via electronic mail to the sender
		and the actual document will be stored in the queue directory.
		"discard" will discard the failed document, and return only
		the error message to the sender.

RECEIVE		RECEIVE specifies what to do with received fax documents.
		"store" will store them in the RECEIVE_DIR directory
		(see below), and send an electronic mail notification message
		to the list of users given in RECEIVE_NOTIFY.  A value of
		"forward" will forward received faxes by electronic mail to
		the first person on the RECEIVE_NOTIFY list, and send a
		notification message to the rest of the list.

RECEIVE_NOTIFY	RECEIVE_NOTIFY is the list of users to receive incoming faxes
		and/or be notified when incoming faxes arrive.  Users should
		be listed by login name, separated by commas or spaces.

RECEIVE_DIR	The directory to which received faxes are stored if RECEIVE
		is set to "store".

RECEIVE_FAIL	If RECEIVE_FAIL is set to "no," received fax documents
		which terminate in an error will be discarded.  If RECEIVE_FAIL
		is set to "yes," partially received documents will be received
		in the normal fashion.

Most of these values can be altered using the Configuration window
of Z-Fax.  Anyone may view the configuration, but you must be logged
in as root to save any changes.  Changing settings without saving
will have no effect.

Note: saving changes made in the Configuration window will completely
overwrite the configuration file.  All comments and variables not known
to Z-Fax will be overwritten.


Z-Fax Send and Receive Daemon

The Z-Fax daemon "zfaxd" co-ordinates incoming and outgoing faxes, allows
your computer to use the same fax modem for both sending and receiving,
and support multiple fax modems for high-volume applications.

zfaxd should be started up at boot time by one of your /etc/rc files.
zfaxd requires at least one command-line arguments: the name of the
serial device to which your Class 2 fax modem is connected.  If you
have more than one fax modem, add the additional device names to the
command line.  All device names must be given as full pathnames.  An
example command line to start zfaxd for operation on one fax modem on
/dev/cua0 would be:

/usr/local/bin/zfaxd /dev/cua0 &


Sending faxes over the network

Z-Fax can be configured so that one computer services the fax transmission
needs of many computers on the network.  The utility "netfaxq" will
monitor the network for incoming fax queue requests, and relay information
back to the requesting computer.

Before setting Z-Fax loose on the network, you must first select a host
computer and a network port number where the fax service will be provided.
The host computer will be where the fax modems are connected.  The port
number can be any integer number between 201 and 65535 that is not already
in use on your network.  To find out what port numbers are in use, look
in the /etc/services file, or see your network documentation.

On the fax server computer, start the "netfaxq" daemon.  This should
normally be started at system boot time, in your /etc/rc file, for example.

On the computers to be served by the fax server computer, add to the
Z-Fax configuration files entries for NET_HOST and NET_PORT (see the
Z-Fax Configuation File section).

The zfaxd queue manager should be run only on the server computer, and
should not be run on any of the client computers.


Ghostscript

Z-Fax uses a program called Ghostscript to assist in converting Postscript
files into fax documents.  Ghostscript is licensed under the GNU Public
License.  See the file Ghostscript/COPYING for more information.

The version of Ghostscript included with Z-Fax assumes its support and
font files are located in /usr/local/lib/ghostscript and
/usr/local/lib/ghostscript/fonts.  If you should move the files in
these directories, Z-Fax will not function properly unless you set the
environment variable GS_LIB to the new directories.  For example, if you
moved the files to /v/lib/gs and /v/lib/gs/fonts, you would need to set
GS_LIB to "/v/lib/gs:/v/lib/gs/fonts".
