# Installation

## Where do I get a fax viewer for Windows?

Generally you can use any program that can display TIFF files, although some of them display faxes in low resolution with an incorrect (half) height.

Luckily, all recent Windows versions come with program that does this correctly:

Windows 95/98/ME/2000:
You can use the Accessories/Imaging application. To use it with YajHFC, use the browse button of the Command line for fax viewer box to browse for kodakimg.exe on your hard drive.
This file usually resides either in the Windows directory (Win 98/ME) or
in Program Files\Windows NT\Accessories\ImageVue (Win 2k).

Windows XP/Vista:
You can use the integrated “picture and fax viewer”. To use it, enter the following text into the Command line for fax viewer box:
rundll32.exe shimgvw.dll,ImageView_Fullscreen %s

## Where do I get a fax viewer for Linux/*BSD/... ?

kfax works very well for me, but just as with Windows, you may use any program that can display TIFF files, just search your distribution's package database (xloadimage does not work for me, however).

## What should I use as a fax viewer on Mac OS X?

Just enter open %s into the Command line for fax viewer box. The faxes should open in the default application now. Thanks to Scott Harris for figuring this out.

## Where do I get a PostScript viewer?

Windows:
Use Ghostview from http://www.cs.wisc.edu/~ghost/
Linux/*BSD/...:
Just install one of the Postscript viewer packages (e.g. gv, kghostview, gnome-gv, ...)

## Where can I get GhostScript from?

Windows:
Linux/*BSD/...:
Install the GhostScript package for your distribution (on most installations this package will already be installed; if not: the package name usually begins with ghostscript or gs)

## Where can I get TIFF2PDF from?

Windows:
Linux/*BSD/...:
Install the “libtiff tools” package for your distribution. Usually this package will have the word tiff in its name (on Debian/Ubuntu it is called libtiff-tools and on SUSE tiff).

1. The directory where the setup.exe resides
2. The user's desktop (where the files are saved if you choose to preserve downloaded files)

Please note that the file names must exactly match the ones of the downloaded files (i.e. gs864w32.exe (32 bit) or gs864w64.exe (64 bit) and tiff-3.8.2-1.exe).

# Usage of the program

## How can I edit PostScript cover page templates?

Those templates have to be in the same special PostScript format the HylaFAX faxcover program uses. See the following pages for hints how to create/edit such files:
http://www.hylafax.org/HylaFAQ/Q202.html
http://www.hylafax.org/howto/tweaking.html

Alternatively, starting with YajHFC 0.3.7, you can use Cover pages in HTML or, with a plugin, in XSL:FO or ODT (OpenDocument Text) format.

YajHFC 0.5.2 adds the option use PDF documents as cover pages.

## Which fields are recognized in a HTML cover page?

The following “words” are replaced (case insensitively) with the corresponding values when a HTML file is used as a cover page:

Word Meaning
@@Name@@ The recipient's name
@@Company@@ The recipient's company
@@Location@@ The recipient's location
@@Faxnumber@@ The recipient's fax number
@@Voicenumber@@ The recipient's voice number
@@FromName@@ The sender's name
@@FromCompany@@ The sender's company
@@FromLocation@@ The sender's location
@@FromFaxnumber@@ The sender's fax number
@@FromVoicenumber@@ The sender's voice number
@@Subject@@ The fax's subject
@@Date@@ Today's date
@@PageCount@@ The number of pages excluding the cover page

Starting with version 0.4.0 the following additional fields are available (note that the italic fields will be empty when you use “Resend fax”):

Word Meaning
@@Surname@@ The recipient's surname (resent faxes: the same as @@Name@@)
@@GivenName@@ The recipient's given name
@@Title@@ The recipient's title
@@Position@@ The recipient's position
@@Department@@ The recipient's department
@@CompanyName@@ The recipient's company name (without department) (resent faxes: the same as @@Company@@)
@@Street@@ The recipient's street name
@@Place@@ The recipient's location (without street or ZIP code) (resent faxes: the same as @@Location@@)
@@ZIPCode@@ The recipient's ZIP Code
@@State@@ The recipient's state
@@Country@@ The recipient's country
@@WebSite@@ The recipient's website
@@FromSurname@@ The sender's surname
@@FromGivenName@@ The sender's given name
@@FromTitle@@ The sender's title
@@FromPosition@@ The sender's position
@@FromDepartment@@ The sender's department
@@FromCompanyName@@ The sender's company name (without department)
@@FromStreet@@ The sender's street name
@@FromPlace@@ The sender's location (without street or ZIP code)
@@FromZIPCode@@ The sender's ZIP Code
@@FromState@@ The sender's state
@@FromCountry@@ The sender's country
@@FromWebSite@@ The sender's website
@@TotalPageCount@@ The number of pages including the cover page
@@CCNameAndFax@@ The names and fax numbers of the other recipients of this fax in the format Name1 <faxnumber1>; Name2 <faxnumber2>; ... (versions > 0.4.4 only)

This replacement is done at the source code level, so those words will not be recognized if the formatting changes inside one of it (e.g. @@subject@@).

Starting with version 0.4.2 some simple conditional statements are supported. These are implemented using HTML comments, so please make sure that the text enclosed in a conditional statement does not contain any comments.

Word Meaning
@@IfSomeFilled:field1,field2,...@@ Include the following text only if at least one of the given fields is filled (i.e. has a value with a length > 0).
@@IfAllFilled:field1,field2,...@@ Include the following text only if all of the given fields are filled (i.e. have a value with a length > 0).
@@IfSomeEmpty:field1,field2,...@@ Include the following text only if at least one of the given fields is empty (i.e. has a value with a length = 0).
@@IfAllEmpty:field1,field2,...@@ Include the following text only if all of the given fields are empty (i.e. have a value with a length = 0).
@@Else@@ Include the following text only if the last @@If...@@-Statement did not match.
@@EndIf@@ Marks the end of the area influenced by the last if. Every @@If...@@ must have exactly one corresponding @@EndIf@@.

## I liked the old send dialog better. Can I have it back?

Just open the Options dialog and select Traditional as “Style of send dialog”.

## I want to access a phone book over JDBC, but YajHFC won't find the driver even if I specify a correct class path when invoking java.

If you use the -jar command line argument, java ignores a user defined class path. So, please start YajHFC using the following commands (replace /path/to/dbdriver.jar and /path/to/yajhfc.jar with the respective real paths and file names of course):

Linux/Unix:
java -classpath /path/to/dbdriver.jar:/path/to/yajhfc.jar yajhfc.Launcher
Windows:
java -classpath c:\path\to\dbdriver.jar;c:\path\to\yajhfc.jar yajhfc.Launcher

In recent YajHFC versions you can also simply add the driver using the Plugins & JDBC panel in the Options dialog.

## What can I enter as a value for the matches Operator in the custom filter dialog?

Regular Expressions. A short reference about the accepted syntax can be found at: http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html

Please note that Regular Expressions are not the same as wildcards: For example, to get the effect of the * wildcard, you have to use .* and for the effect of the wildcard ? use ..

## Which command line arguments does YajHFC understand?

Output from java -jar yajhfc.jar --help (version 0.5.1):

Usage:
java -jar yajhfc.jar [OPTIONS]... [FILES TO SEND]...

Argument description:
-r, --recipient=RECIPIENT        Specifies a recipient to send the fax to. You
may specify either a fax number or detailed
cover page information (see the FAQ for the
format in the latter case). You may specify
--recipient multiple times for multiple
recipients.
-C, --use-cover[=yes|no]         Use a cover page for sending a fax.
-s, --subject=SUBJECT            The fax subject for the cover page.
--comment=COMMENT            The comment for the cover page.
-M, --modem=MODEM                Sets the modem to send the fax. Specify either
the modem's name (e.g. ttyS0) or "any" to use
any modem.
-S, --server=SERVER              Sets the server to send the fax over. Specify
either the server's name (e.g. "My server"),
the server's list index (0 is the first
element) or the ID in the form "#ID".
-I, --identity=IDENTITY          Sets the sender identity to use when sending
the fax. Specify either the identity's name
(e.g. "My identity"), the identity's list
index (0 is the first element) or the ID in
the form "#ID".
--stdin                      Read the file to send from standard input.
--print-jobids[=FILE]        Prints the job IDs of newly sent faxes to
stdout or to the specified file. One job per
line is printed, in the format "yyyy-mm-dd
hh:mm:ss NEW_FAXJOB jobid".
-d, --debug                      Output some debugging information.
-l, --logfile=LOGFILE            The log file to log debug information to (if
not specified, use stdout).
--appendlogfile=LOGFILE      Append debug information to the given log
file.
--background                 If there is no already running instance of
YajHFC, launch a new instance and terminate
this instance (after submitting the fax to
send).
--noclose                    Do not close YajHFC after submitting the fax.
--no-wait                    Do not wait for the send window to be closed
by the user. If YajHFC is invoked multiple
times before the user closes the send window,
the specified documents are added to the list
of files there. This option implies
--background.
-T, --showtab=0|R|1|S|2|T        Sets the tab to display on startup. Specify 0
or R for the "Received", 1 or S for the "Sent"
or 2 or T for the "Transmitting" tab.
--windowstate=N|M|I|T        Sets the initial window state of the main
window to _N_ormal, _M_aximized, _I_conified
(minimized) or minimized to _T_ray.
--loadplugin=JARFILE         Specifies a jar file of a YajHFC plugin to
--loaddriver=JARFILE         Specifies the location of a JDBC driver JAR
--override-setting=KEY=VALUE Overrides the value of the specified setting
for this session. The overridden setting is
not saved.
file.
--no-gui                     Sends a fax with only a minimal GUI.
--no-check                   Suppresses the check for the Java version at
startup.
-c, --configdir=DIRECTORY        Sets the configuration directory to use
-h, --help[=COLUMNS]             Displays this text (formatted for COLUMNS
columns if given).


## How can I give cover page information using the -recipient switch?

Starting with version 0.4.0, you can give that information using name:value pairs, separated by semicolons. For example, to send a fax to “John Doe” in “Example town” with the fax number 0123456, use the following command line:

java -jar yajhfc.jar [...] -recipient="givenname:John;surname:Doe;location:Example Town;faxnumber:0123456" [...]

The following field names are recognized:

Field name Meaning
surname The recipient's surname
givenname The recipient's given name
title The recipient's title
position The recipient's position
department The recipient's department
company The recipient's company name
street The recipient's street name
location The recipient's location
zipcode The recipient's ZIP Code
state The recipient's state
country The recipient's country
faxnumber The recipient's fax number
voicenumber The recipient's voice number
website The recipient's website

Starting with version 0.4.2 you can also specify an input textfile with recipients using -recipient=@filename or the respective button in the send dialog. It is assumed that the text file contains one recipient per line (either a fax number or a data set using the above format).

## What does the column XYZ mean?

Most likely, I don't know exactly either, because the column descriptions are simply copied from the faxstat(1) man page (JobFmt/RcvFmt) and abbreviated/translated.

## How can I specify some default settings?

Starting with version 0.4.0 the following files (if they exist) are loaded in order to retrieve the saved settings:

1. [Directory where yajhfc.jar resides]/settings.default
2. the user settings from {user.home}/.yajhfc/settings (if you specified -configdir=DIR, DIR/settings is used instead)
3. [Directory where yajhfc.jar resides]/settings.override

Settings from files loaded later override the settings specified in the files loaded earlier, i.e. the settings from settings.override take precedence over those in the user settings and settings.default.

This logic can be used to specify default settings (e.g. in a networked environment):
Simply configure one YajHFC installation as you like, then copy {user.home}/.yajhfc/settings to the directory where yajhfc.jar is and rename it to settings.default.

Overrides can be specified in a similar fashion. In this case, you are encouraged to edit the settings file (it is a plain text file), and remove any lines that specify settings you wish not to override (usually you will want to remove at least user and pass-obfuscated (user name and password used to connect to the HylaFAX server), FromName, *ColState (the widths of the table columns), *Bounds (the position of the different windows) and mainwinLastTab).

Note, however that the user can still set these settings to a different value for a running YajHFC instance. They are reset to the override values only when YajHFC is started again (in other words: the user can set these settings, but they are not saved between different runs of YajHFC).

## How can I display the HylaFAX archive folder in YajHFC?

With version 0.4.0 support for the HylaFAX archive folder has been implemented.

This directory cannot be accessed using the “normal” HylaFAX connection like the other folders, however, because HylaFAX does only allow to get the list of subfolders in the archive directory, but not to get any information (except the ID) about the archived jobs or the attached documents (if you know a HylaFAX version where this is different, please let me know).

For this reason the directory has to be accessed by other methods. Currently (0.4.0) YajHFC only supports access using the file system. This means you have to export the archive directory on the server using Samba, NFS or any other network file system, mount it on the client (if you use Unix; on Windows, you can just use UNC paths) and tell YajHFC in the options under which path the archive directory can be found.

When you have done that, the archive table should work just like the other tables do.

## What do the different options under Paths & Viewers -> View and send settings do (0.4 and up)?

For the impatient: The recommended settings are (they are not the default, because they require gs and tiff2pdf):

• Format: PDF or TIFF
• Send multiple files as: Single file except cover
• View as single file: Yes
• Always view/send in this format: Yes

### Format for viewing/sending

The format to which the documents should be converted if necessary. Generally PDF and TIFF give better results than PostScript here (as the latter uses GhostScript's pswrite device).

### Send multiple files as

Multiple files:
Same behaviour as pre-0.4.0 versions. If you attach multiple documents to a single fax job, these documents are converted to PS or PDF, but kept as separate files (e.g. if you send a fax with files doc.ps and picture.jpg, two separate files are uploaded)

Single file except for cover:
One file is created for the whole fax, but the cover page is kept as a separate file (e.g. if you send a fax with doc.ps and picture.jpg, a single PDF/PS/TIFF file is created and uploaded).
Advantage: The resolution is reduced to 196 dpi (-> smaller files/upload) and a single document file can be used when sending a fax to multiple destinations.

Complete fax as single file:
One file is created for the whole fax including the cover page. If the fax has no cover this behaves identical to the above case.
Advantage: No conversions on the client are necessary when viewing the sent fax.
Disadvantage: When sending a fax to multiple recipients one file per recipient has to be created and uploaded.

### View faxes as single file

If this option is checked and a fax on the server consists of multiple files, a single file is created (on the client) for viewing.

### View/send faxes always in this format

This option modifies the behaviour of “Send multiple files as” and “View faxes as single file”.
When this option is unchecked, a fax is only converted if it consists of multiple files. If it consists of only a single file, the format is left as it is.
When this option is checked, a fax consisting of a single file is also converted when that single file has a different format than the one selected at “Format for sending/viewing”.
Advantage: A single viewer is used for both sent and received faxes (e.g. to view received faxes as PDF).
Disadvantage: Usually more format conversions are necessary on the client.

## Which characters are recognized as date/time format?

The date is formatted using a Java SimpleDateFormat. A description of the characters recognized can be found at http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html.

## What does the Answer call feature do?

The same as the HylaFAX faxanswer command: It instructs the HylaFAX server to try answering an incoming call on the given modem even if the modem normally ignores inbound calls. This can be useful for testing or for small installations where a modem shares the line with a normal telephone.

## Why are there so many text extraction methods?

Because in my experience no method works 100% perfect. For some documents none may work correctly.

In Windows, using iText usually works just fine.

Especially in Linux where every application produces PostScript for itself, it is not uncommon to come across documents that cannot be converted to text, however. In that case typically there is nothing you can do about it. The reason for that is that PostScript (and PDF) are actually not really text oriented formats. Any application is free to encode the text as it wants, for example it can encode it so that 1 maps to the glyph (i.e. the picture) of the character e, 2 to h, and so on. So the text hello might be extracted as something like 21334 although it displays correctly.

If you have problems, the Test button in the options dialog (under Recipient extraction) can be very handy, so you can see how a document comes out when converted to text and try out different conversion methods. In my experience, the iText method often works best, ps2ascii works worst, while pstotext and pdftotext are somewhere in the middle. This heavily depends on the document, however.

# Problems/Known bugs

## I created a HTML document/cover page, but the formatting in YajHFC looks wrong!

YajHFC uses the HTML support integrated in Java (HTMLEditorKit / HTMLDocument) to convert HTML to PostScript. This support is quite limited, however; it only supports HTML 3.2.
This means that complex layouts often won't render correctly in YajHFC. To achieve the layout you want, you will basically have the following alternatives:

• Do some “trial & error” until the layout looks right (the preview button in the send dialog will show the layout of the converted HTML).
• Use a HTML editor like Ekit (http://www.hexidec.com/ekit.php) that also uses the Java HTML support, so it will render similarily in YajHFC.
• Use another format for the cover page (such as XSL:FO or ODT with the FOP Plugin).

## When trying to view sent faxes I always get an error message saying File format PCL not supported, although all the documents are PostScript/PDF.

Check the Use PCL file type bugfix checkbox in the Options dialog and try again.

Some HylaFAX versions incorrectly report a file type of “PCL” for all documents associated with a job. If this checkbox is checked, YajHFC tries to guess the file type if PCL is reported (which usually works pretty well).

## I often get an error when I am sending two or more faxes in a row. What can I do about it?

Some versions of the HylaFAX server seem to have problems when more than one fax is submitted per session.

To work around that problem, go to the Server tab in the Options dialog, check the Create new session for every action box and try if the problem persists. If this does not help, please mail me a bug report.

## YajHFC running under Windows sometimes saves its configuration in C:\.yajhfc instead of C:\Documents and Settings\USERNAME\.yajhfc

As a default YajHFC saves its configuration information in the subdirectory .yajhfc of the directory returned by the Java system property user.home. Sometimes some Java versions seem to not set this property correctly leading to the misbehaviour described above.

As a workaround, you can set this property explicitely when starting YajHFC by using java's -D command line switch, for example:
java -Duser.home=%USERPROFILE% -jar "C:\Program Files\yajhfc.jar"

## The tray icon is not shown!

Starting with version 0.4.0 YajHFC supports a tray icon which will be shown when you run YajHFC under Java 1.6 (“Java 6”). If you use Java 1.5 (“Java 5”), a tray icon is not supported.

So, please make sure you have Java 1.6 installed. If you are absolutely sure you have Java 1.6 installed and the tray icon is still not shown, please mail me a bug report.

# Miscellaneous

## Why are passwords stored in clear text? (before 0.4)

Simply put: Because there isn't any method that is much better.

YajHFC could encode/“encrypt” them somehow before storing, but if it did, you could always look at the source code to find out how to decrypt them (even if YajHFC was closed source software you could still disassemble it or experiment a bit to find that out).

The only secure method would require you to enter a master password every time you start YajHFC, but in my opinion that would not provide an improvement over entering the “real” password.

Because of many requests passwords are obfuscated using a simple algorithm in version 0.4.0 and up. The statement above still holds true, however, i.e. once you read the source code, the password can be decrypted easily.

## Why did you choose that stupid name?

YajHFC started out as a test project for Java and the gnu.hylafax library and so it didn't have a “nice” name. After working at it for a while, I noticed that it turned out to be actually useable, so I chose to give it a name. Because I was also playing around with SuSE's yast at that point of time and I knew there were/are already a lot of other java hylafax clients out there, I simply called it “yet another Java HylaFAX client”.

YajHFC FAQ

This document was generated using the LaTeX2HTML translator Version 2008 (1.71)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_subdir -split 0 -html_version 3.2,latin1,unicode,utf8 -no_navigation -prefix faq faq.tex

The translation was initiated by Jonas Wolz on 2012-01-03

#### Footnotes

...\{user.home\}
In Windows user.home usually is C:\Documents and Settings\USERNAME.

Jonas Wolz 2012-01-03