# YajHFC FAQ

## Contents

- Installation
  - Where do I get a fax viewer for Windows?
  - Where do I get a fax viewer for Linux/*BSD/... ?
  - What should I use as a fax viewer on Mac OS X?
  - Where do I get a PostScript viewer?
  - Where can I get GhostScript from?
  - Where can I get TIFF2PDF from?
  - How can I supply already downloaded versions of tiff2pdf and GhostScript to the Windows setup?
- Usage of the program
  - How can I edit PostScript cover page templates?
  - Which fields are recognized in a HTML cover page?
  - Where can I find the old default cover page used before version 0.4.2?
  - I liked the old send dialog better. Can I have it back?
  - 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.
  - What can I enter as a value for the matches Operator in the custom filter dialog?
  - Which command line arguments does YajHFC understand?
  - How can I give cover page information using the -recipient switch?
  - What does the column XYZ mean?
  - How can I specify some default settings?
  - How can I display the HylaFAX archive folder in YajHFC?
  - What do the different options under Paths & Viewers -> View and send settings do (0.4 and up)?
  - Which characters are recognized as date/time format?
  - What does the Answer call feature do?
  - Why are there so many text extraction methods?
- Problems/Known bugs
  - I created a HTML document/cover page, but the formatting in YajHFC looks wrong!
  - 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.
  - I often get an error when I am sending two or more faxes in a row. What can I do about it?
  - YajHFC running under Windows sometimes saves its configuration in C:\.yajhfc instead of C:\Documents and Settings\USERNAME\.yajhfc
  - The tray icon is not shown!
- Miscellaneous
  - Why are passwords stored in clear text? (before 0.4)
  - Why did you choose that stupid name?

# 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:
  Download it from `http://www.cs.wisc.edu/~ghost/`
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:
  Download it from `http://gnuwin32.sourceforge.net/downlinks/tiff.php`
  If this link does not work, please see `http://gnuwin32.sourceforge.net/packages/tiff.htm` or `http://www.libtiff.org/`.
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`).

## How can I supply already downloaded versions of tiff2pdf and GhostScript to the Windows setup?

Starting with version 0.4.2 the Windows setup optionally downloads and installs tiff2pdf and GhostScript. Before starting a download the setup program searches in the following places for already downloaded versions:

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
`@@FromEMail@@` | The sender's e-mail address
`@@Subject@@` | The fax's subject
`@@Date@@` | Today's date
`@@PageCount@@` | The number of pages excluding the cover page
`@@Comments@@` | The comments entered for this fax

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
`@@EMail@@` | The recipient's e-mail address
`@@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
`@@FromEMail@@` | The sender's e-mail address
`@@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@@`.

## Where can I find the old default cover page used before version 0.4.2?

You can find it in the “Coverpage examples” archive at `http://download.yajhfc.de/misc/coverpages.zip`

## 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".
    -A, --admin                      Start up in admin mode.
    -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
                                     load.
        --loaddriver=JARFILE         Specifies the location of a JDBC driver JAR
                                     file to load.
        --override-setting=KEY=VALUE Overrides the value of the specified setting
                                     for this session. The overridden setting is
                                     not saved.
        --no-plugins                 Disables loading plugins from the plugin.lst
                                     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
                                     instead of ~/.yajhfc
    -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
`email` | The recipient's e-mail address
`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”.

# About this document ...

YajHFC FAQ

This document was generated using the LaTeX2`HTML` 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`.