<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN">

<book lang="en">
<bookinfo>
<title>The KFax Handbook</title>
<authorgroup>
<author>
<firstname>Bernd Johannes</firstname>
<surname>Wuebben</surname>
<affiliation><address><email>wuebben@kde.org</email></address></affiliation>
</author>
</authorgroup>
<date>05/10/1997</date>
<releaseinfo>0.03.00</releaseinfo>
<abstract>
<para>This Handbook describes KFax Version 0.3</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>fax</keyword>
<keyword>viewer</keyword>
<keyword>graphics</keyword>
</keywordset>
</bookinfo>

<chapter id="Introduction">
<title>Introduction</title>

<para>KFax is a Fax file viewer capable of displaying and printing all common fax file formats.
In particular the fax files used by popular the mgetty/sendfax and hylafx fax send and
receive packages can be displayed. The first (or only) page of a "PC-Research"-style 
(DigiFAX) files produced  by  the ghostscript dfaxhigh or dfaxlow drivers can
also be displayed. (who is still using this format?) Input files using any 
common fax encoding such as group  3 (1 and 2 dimensional) 
and group 4 can be displayed. KFax has built in native postscript printing
capabilities.</para>

<para>I hope you will enjoy this Fax viewer,</para>

<para><literal remap="tt">Bernd Johannes Wuebben</literal></para>

<para><ulink url="mailto:wuebben@kde.org">wuebben@kde.org</ulink></para>
</chapter>

<chapter id="Installation">
<title>Installation</title>

<sect1 id="how-to-obtain-kfax">
<title>How to obtain KFax</title>

<para>KFax is part of the KDE project <ulink url="http://www.kde.org">http://www.kde.org</ulink>.
KFax can be found on <ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the main ftp site
of the KDE project.</para>
</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>In order to successfully compile KFax, you need the latest versions of 
<literal remap="tt"> libkdecore</literal>,<literal remap="tt"> libkfm</literal> and <literal remap="tt"> libkdeui</literal>. All 
required libraries as well as KFax itself can be found on 
<ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>. </para>
</sect1>

<sect1 id="compilation-and-installation">
<title>Compilation and installation</title>

<para>In order to compile and install KFax on your system, execute the following commands
in the base  directory of the KFax distribution:
<screen>% ./configure
% make
% make install
</screen>
</para>

<para>Since KFax uses <literal remap="tt">autoconf</literal> you should have not trouble compiling it.
Should you run into problems please report them to the <emphasis remap="sf">KDE</emphasis> mailing lists.</para>
</sect1>
</chapter>

<chapter id="Fundamentals">
<title>Fundamentals</title>

<para>KFax can not (yet) send or receive Fax files. For this I wholeheartedly
recommend the mgetty/sendfax 
<ulink url="ftp://ftp.leo.org/pub/comp/networking/communication/modem/mgetty">ftp://ftp.leo.org/pub/comp/networking/communication/modem/mgetty</ulink>
and hylafax fax
<ulink url="ftp://sgi.com/sgi/fax">ftp://sgi.com/sgi/fax</ulink>
send/receive packages which are
available for free.</para>

<para>HylaFAX:
<ulink url="http://info-sys.home.vix.com/flexfax/toc.html">http://info-sys.home.vix.com/flexfax/toc.html</ulink></para>

<para>sendfax/mgetty:
<ulink url="http://www.leo.org/~doering/mgetty/">http://www.leo.org/~doering/mgetty/</ulink></para>

<para>A "zoomed-in" document can be moved within the KFax view, by clicking and holding
down the first mouse button down while moving the pointer.</para>

<para>KFax can not display image file formats which are not related to 
faxing, such as an arbitrary tiff or gif file.</para>

<para>By default raw fax files are interpreted as g3 files. If you want
to display faxg3-2d and faxg4 files you have to specifiy this on
the Fax Options dialog. In the case of raw g4 files you might also 
need to specify the height in scan lines of the fax if it differs 
from the default 2155.</para>

<sect1 id="drag-and-drop">
<title>Drag and Drop</title>

<para>KFax makes use of the KDE Drag and Drop protocol. This means that you can drag
and drop files form the Desktop or kfm or some remote ftp site that you have
open in one of kfm's windows onto KFax. </para>
</sect1>

<sect1 id="dealing-with-files-on-the-internet">
<title>Dealing with files on the internet</title>

<para>You can open and save files transparently on the internet.</para>
</sect1>

<sect1 id="printing">
<title>Printing</title>

<para>KFax supports PostScript printing natively. 
supported. </para>

<para>Make sure your system is set up for printing PostScript documents. If you
don't have a native PostScript printer get yourself
ghostscript/ghostview version 5 or newer  from
<ulink url="http://www.cs.wisc.edu/%7Eghost/">http://www.cs.wisc.edu/%7Eghost/</ulink>.</para>
</sect1>

<sect1 id="fax-options">
<title>Fax Options</title>

<para>KFax supports a number of options in order to allow you an optimal configuration
for your specific usage.
<variablelist>
<varlistentry>
<term>Display Options.</term>
<listitem>
<para><itemizedlist>
<listitem>
<para>Landscape: Show the fax pages by default rotated by 90 degrees.</para>
</listitem>
<listitem>
<para>Upside Down: Display the fax pages by default upside-down.</para>
</listitem>
<listitem>
<para>Invert: Display the Fax as white on black background</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Raw Fax Resolution.</term>
<listitem>
<para><itemizedlist>
<listitem>
<para>Auto: Some fax transmission programs set the first letter of the 
name of a fax of "fine" resolution to an f and to an n for a 
fax of "normal" resolution. If "Auto" is checked
KFax will observe this convention. This options has no effect
on Tiff and "PC-Research (DIGIFAX) facsimili. Those facsimili
are self-specifying.</para>
</listitem>
<listitem>
<para>Fine: Assume raw fax files (g3-g32d-g4) are fine resolution facsimili
(7.7 lines/mm). Tiff  and "PC-Research" (DigiFAX) files are self-specifying. </para>
</listitem>
<listitem>
<para>Normal: Assume raw fax files (g3/g32d/g4) are of normal resolution
(3.85  lines/mm).   Each  fax  line is
duplicated in the displayed image to give  approximately 
equal vertical and horizontal scales. 
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Raw Fax Data:</term>
<listitem>
<para>Checking LS-Bit first will lead KFax to assume that the
bit order of the fax data bytes is reversed. The official fax specification deals only
with serial data transmission. Modem manufacturers have to decide whether the first
bit received should be placed in the most significant or the least significant position
in a byte. The consensus is to pack most significant first, but the options is
available to deal with the opposite order.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Raw Faxsimili Format:</term>
<listitem>
<para><itemizedlist>
<listitem>
<para>g3: Assume the raw input files use group 3, 1-dimensional coding.</para>
</listitem>
<listitem>
<para>g32d: Assume the raw input files use group 3, 2-dimensional coding.</para>
</listitem>
<listitem>
<para>g4: Assume the raw input files use group 4 coding.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Raw Fax Data default height-width:</term>
<listitem>
<para><itemizedlist>
<listitem>
<para>height: specify the default number of line for raw fax data</para>
</listitem>
<listitem>
<para>width: specify the default number of pixels in each scan line for raw fax data
The default value is 1728.</para>
</listitem>
<listitem>
<para>auto: this option is the recommended setting for g3 raw fax data. g3-2d and g4 need
explicit dimensions.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="command-line-options">
<title>Command Line Options</title>

<para>KFax supports the following command line options:
<screen>wuebben: ../kfax -h
usage: KFax &lt;flags&gt; file ...
        -f      fine resolution
        -n      normal resolution
        -h      height (number of fax lines)
        -w      width (dots per fax line)
        -l      turn image 90 degrees (landscape mode)
        -u      turn image upside down
        -i      invert (black/white)
        -m      memory usage limit in bytes (M m mega, K k kilo) default:8 megs
        -r      fax data is packed ls-bit first in input bytes
        -v      version information
        -2      raw files are g3-2d
        -4      raw files are g4    

</screen>
</para>
</sect1>

<sect1 id="kfax-key-bindings">
<title>KFax Key Bindings</title>

<para>KFax honors the following key bindings when the pointer is place on an open
fax document view.</para>

<para><itemizedlist>
<listitem>
<para><literal remap="tt">h</literal> Show help page displaying the available keyboard-shortcuts</para>
</listitem>
<listitem>
<para><literal remap="tt">q</literal> Return to the original document.</para>
</listitem>
<listitem>
<para><literal remap="tt">n + Next PgDn Space</literal> Display the next page</para>
</listitem>
<listitem>
<para><literal remap="tt">p - Prior PgUp Backspace</literal> Display the previous page</para>
</listitem>
<listitem>
<para><literal remap="tt">Shift Home</literal> First Page</para>
</listitem>
<listitem>
<para><literal remap="tt">Shift End</literal> Last Page</para>
</listitem>
<listitem>
<para><literal remap="tt">u</literal> Turn Page upside down</para>
</listitem>
<listitem>
<para><literal remap="tt">l</literal> Turn page 90 degrees</para>
</listitem>
<listitem>
<para><literal remap="tt">m</literal> Show a mirror image of the current fax page</para>
</listitem>
<listitem>
<para><literal remap="tt">i</literal> zoom in</para>
</listitem>
<listitem>
<para><literal remap="tt">o</literal> zoom out
</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="how-to-create-fax-files">
<title>How to create fax files</title>

<para>Perhaps the easiest way to create fax files is by first creating
PostScript file from you document that you wish to fax and then 
to use the ghostscript PostScript interpreter to transform the PostScript
file into one of several fax file, conforming to one of several different
fax file format.</para>

<para>In order to create fax files from ps documents you will need ghostscript.
KFax can display all fax output modes of ghostscript:</para>

<para><itemizedlist>
<listitem>
<para>raw:  fag3 faxg32d faxg4  </para>
</listitem>
<listitem>
<para>tiff: tiffg3 tiffg32d tiffg4</para>
</listitem>
</itemizedlist>
</para>

<para>A raw file will have no pagination information and will be displayed
as a whole in the fax window. 
Tiff files contain pagination information can be paged through in the
fax window.</para>

<sect2>
<title>Example</title>

<para>How to create a fax file that sendfax/mgetty can accept and send:</para>

<para><screen>gs -sDEVICE=faxg3 -sOutputFile=/tmp/fax.g3.%d yourdocument.ps
</screen>
</para>

<para>Assuming that your ps document <literal remap="tt">yourdocumnet.ps</literal> contains three pages,
this will result in the creation of  fax.g3.1 fax.g3.2 fax.g3.3</para>
</sect2>
</sect1>
</chapter>

<chapter id="TheMenuEntries">
<title>The Menu Entries</title>

<sect1 id="file">
<title>File</title>

<sect2>
<title>New</title>

<para>Opens a new Document in the editor</para>
</sect2>

<sect2>
<title>Open</title>

<para>Allows the user to open a fax</para>
</sect2>

<sect2>
<title>Add</title>

<para>Allows the user to add a fax file. This is particularly useful for raw g3/g32d/g4
fax files. The user can add all pages of a fax transmission and print all of the
out in one printing session.</para>
</sect2>

<sect2>
<title>Close Fax</title>

<para>Closes all currently open fax files</para>
</sect2>

<sect2>
<title>Open URL</title>

<para>Allows the user to open a fax file on the internet.</para>
</sect2>

<sect2>
<title>Save to URL</title>

<para>Allows the user to save to a fax file on the internet.</para>
</sect2>

<sect2>
<title>Print</title>

<para>Open the print dialog and lets the user print the currently open fax file pages.</para>
</sect2>

<sect2>
<title>Exit</title>

<para>Exit the fax viewer.</para>
</sect2>
</sect1>

<sect1 id="view">
<title>View</title>

<sect2>
<title>Next</title>

<para>Display the next fax page</para>
</sect2>

<sect2>
<title>Previous</title>

<para>Display the previous fax page</para>
</sect2>

<sect2>
<title>First</title>

<para>Display the first fax page</para>
</sect2>

<sect2>
<title>Last</title>

<para>Display the last fax page</para>
</sect2>

<sect2>
<title>Rotate</title>

<para>Rotate the fax counter-clockwise</para>
</sect2>

<sect2>
<title>Mirror</title>

<para>Display a mirror image of the current fax page</para>
</sect2>

<sect2>
<title>Flip</title>

<para>Display the current fax page upside Down</para>
</sect2>

<sect2>
<title>Zoom in</title>

<para>Zoom in -- that is magnify the current view.</para>
</sect2>

<sect2>
<title>Zoom out --that is reduce the current view.</title>
<para>
</para>
</sect2>
</sect1>

<sect1 id="options">
<title>Options</title>

<sect2>
<title>Fax Options</title>

<para>Brings up the Fax Options Dialog.</para>
</sect2>

<sect2>
<title>Hide/Show Tool-Bar</title>

<para>Allows the user to have the tool bar displayed or hidden.</para>
</sect2>

<sect2>
<title>Hide/Show Status-Bar</title>

<para>Allows the user to have the status bar displayed or hidden.</para>
</sect2>
</sect1>

<sect1 id="help">
<title>Help</title>

<sect2>
<title>Help</title>

<para>Invokes the KDE help system with the KFax help pages displayed.</para>
</sect2>

<sect2>
<title>About </title>

<para>Displays essential information about KFax.</para>
</sect2>
</sect1>
</chapter>

<chapter id="Questionsandanswers">
<title>Questions and answers</title>
<para>
</para>

</chapter>

<chapter id="Copyright">
<title>Copyright</title>

<para><screen>KFax is Copyright 1997 by Bernd Johannes Wuebben,
                          wuebben@math.cornell.edu
                          wuebben@kde.org

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.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.     

</screen>
</para>

<sect1 id="thanks">
<title>Thanks</title>

<para><screen>As always I am resting on the shoulders of giants. I am deeply indebted to 
Frank D. Cringle who wrote the excellent fax viewer viewfax on which 
KFax is partially based:

viewfax version 2.3, Copyright (C) 1990, 1995 Frank D. Cringle.

As well as the wonderful libtiff library version 2.3 beta:

Copyright (c) 1988-1995 Sam Leffler
Copyright (c) 1991-1995 Silicon Graphics, Inc.

And last but not least: Thanks to the Trolls for Qt. http://www.troll.no               

</screen>
</para>
</sect1>
</chapter>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
