# The KFax Handbook

Bernd Johannes
Wuebben

    wuebben@kde.org

05/10/1997
0.03.00

This Handbook describes KFax Version 0.3

KDE
fax
viewer
graphics

## Introduction

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.

I hope you will enjoy this Fax viewer,

`Bernd Johannes Wuebben`

wuebben@kde.org

## Installation

### How to obtain KFax

KFax is part of the KDE project http://www.kde.org. KFax can be found on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### Requirements

In order to successfully compile KFax, you need the latest versions of `libkdecore`,`libkfm` and `libkdeui`. All required libraries as well as KFax itself can be found on ftp://ftp.kde.org/pub/kde/.

### Compilation and installation

In order to compile and install KFax on your system, execute the following commands in the base directory of the KFax distribution:

    % ./configure
    % make
    % make install

Since KFax uses `autoconf` you should have not trouble compiling it. Should you run into problems please report them to the KDE mailing lists.

## Fundamentals

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

HylaFAX: http://info-sys.home.vix.com/flexfax/toc.html

sendfax/mgetty: http://www.leo.org/~doering/mgetty/

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.

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

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.

### Drag and Drop

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.

### Dealing with files on the internet

You can open and save files transparently on the internet.

### Printing

KFax supports PostScript printing natively. supported.

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 http://www.cs.wisc.edu/%7Eghost/.

### Fax Options

KFax supports a number of options in order to allow you an optimal configuration for your specific usage.

Display Options.

  - Landscape: Show the fax pages by default rotated by 90 degrees.

  - Upside Down: Display the fax pages by default upside-down.

  - Invert: Display the Fax as white on black background

Raw Fax Resolution.

  - 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.

  - 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.

  - 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.

Raw Fax Data:

  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.

Raw Faxsimili Format:

  - g3: Assume the raw input files use group 3, 1-dimensional coding.

  - g32d: Assume the raw input files use group 3, 2-dimensional coding.

  - g4: Assume the raw input files use group 4 coding.

Raw Fax Data default height-width:

  - height: specify the default number of line for raw fax data

  - width: specify the default number of pixels in each scan line for raw fax data The default value is 1728.

  - auto: this option is the recommended setting for g3 raw fax data. g3-2d and g4 need explicit dimensions.

### Command Line Options

KFax supports the following command line options:

    wuebben: ../kfax -h
    usage: KFax <flags> 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

### KFax Key Bindings

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

- `h` Show help page displaying the available keyboard-shortcuts

- `q` Return to the original document.

- `n + Next PgDn Space` Display the next page

- `p - Prior PgUp Backspace` Display the previous page

- `Shift Home` First Page

- `Shift End` Last Page

- `u` Turn Page upside down

- `l` Turn page 90 degrees

- `m` Show a mirror image of the current fax page

- `i` zoom in

- `o` zoom out

### How to create fax files

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.

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

- raw: fag3 faxg32d faxg4

- tiff: tiffg3 tiffg32d tiffg4

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.

#### Example

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

    gs -sDEVICE=faxg3 -sOutputFile=/tmp/fax.g3.%d yourdocument.ps

Assuming that your ps document `yourdocumnet.ps` contains three pages, this will result in the creation of fax.g3.1 fax.g3.2 fax.g3.3

## The Menu Entries

### File

#### New

Opens a new Document in the editor

#### Open

Allows the user to open a fax

#### Add

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.

#### Close Fax

Closes all currently open fax files

#### Open URL

Allows the user to open a fax file on the internet.

#### Save to URL

Allows the user to save to a fax file on the internet.

#### Print

Open the print dialog and lets the user print the currently open fax file pages.

#### Exit

Exit the fax viewer.

### View

#### Next

Display the next fax page

#### Previous

Display the previous fax page

#### First

Display the first fax page

#### Last

Display the last fax page

#### Rotate

Rotate the fax counter-clockwise

#### Mirror

Display a mirror image of the current fax page

#### Flip

Display the current fax page upside Down

#### Zoom in

Zoom in -- that is magnify the current view.

#### Zoom out --that is reduce the current view.

### Options

#### Fax Options

Brings up the Fax Options Dialog.

#### Hide/Show Tool-Bar

Allows the user to have the tool bar displayed or hidden.

#### Hide/Show Status-Bar

Allows the user to have the status bar displayed or hidden.

### Help

#### Help

Invokes the KDE help system with the KFax help pages displayed.

#### About

Displays essential information about KFax.

## Questions and answers

## Copyright

    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.

### Thanks

    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