viewfax(1)

💖 viewfax(1) — Local commands, but make it a vibe 💖

okay bestie, sit down, hydrate, because this one's a whole mood. It's called viewfax and it lives in the local commands section of your manual, iykyk. 🦋

---

✨ NAME ✨

viewfax — display fax files in an X11 window 💅

---

🌸 SYNOPSIS 🌸

viewfax [-fnluirvW24] [-hheight] [-wwidth] [-zzoom] [-ddisplay]
[-gwxh+x+y] [-bbell] [-mmemory] filename...

---

🎀 DESCRIPTION 🎀

So like, viewfax shows you one or more fax files in an X11 window. That's the whole job. It's giving "I do one thing and I slay at it." ✨

The input files can be raw, single-page faxes — the kind a fax modem receives with a program like mgetty(1) — or tiff files, like the ones hylafax uses. And plot twist 👑: the first (or only) page of "PC-Research"-style (DigiFAX) files made by the ghostscript dfaxhigh or dfaxlow drivers can also be displayed. Versatile queen.

Input files using any common fax encoding — like group 3 (1 and 2 dimensional) and group 4 — can be displayed. No cap.

The fax images get rendered at full resolution, then successively scaled down by a linear factor of 2 before display, until they fit on the screen. Like, it keeps shrinking them by half until they behave. 🫶

Then you control the display interactively with mouse and keyboard commands:

• Left mouse button — expands the image by a factor of two.
• Right mouse button — reduces it by that same factor.
• Middle mouse button — if the image is bigger than the available window size, this repositions it within the window. Hold the middle button down while dragging the image to its new position. 🖱️

If your mouse has a scroll-wheel, it can move an oversized image vertically. Hold shift while wheeling and it scrolls through the pages instead. And the shift sense gets inverted if viewfax is started with -W on the command-line. Sneaky. 😭

---

🧚 Further interaction = single-key commands 🧚

• h or Help — displays a page of help information. Type 'q' to return to the original document.
• p or Prior or PgUP or - or BackSpace — displays the previous page from the command-line list.
• n or Next or PgDn or + or space — displays the next page from the command-line list.
• Shift HOME — displays the first page from the command-line list.
• Shift END — displays the last page from the command-line list.
• z — zoom in (same as right mouse button).
• Shift Z — zoom out (same as left mouse button).
• u — turns the image upside down, which is useful if the fax was originally fed the wrong way into the machine. 🙈 (we've all been there)
• Shift U — turns this and all following pages upside down.
• l — turns the image through 90 degrees, to view landscape text.
• Shift L — turns this and all following pages sideways.
• m — produce a left/right mirror image of the page.
• Shift M — mirror this and all following pages.
• cursor arrows — reposition the displayed image if it exceeds the window size.
• HOME — repositions so that the top left corner is visible.
• END — makes the bottom right corner visible.
• Print — if the environment variable VIEWFAX_PRINT is defined, the current page is printed. All pages are printed with Shift Print.
• e — if the environment variable VIEWFAX_EDIT is defined, the current page is passed to the editor. All input files can be edited with Shift e.
• q — terminates the program. bye bestie 👋
• Shift Q — terminates the program with non-zero exit status. Can be used to abort a shell script, e.g. when the user is previewing an outbound fax and decides not to send it. Main character decision-making energy. 💅

---

💜 OPTIONS 💜

viewfax is designed to "do the right thing" when given just a filename. But for the special cases, we have the following options. 🎀

Heads up bestie: tiff-files contain a header which overrides the -f, -n, -h, -w, -l, -m, and -u flags. The file said what it said, periodt.

• -f — indicates that raw input files are fine resolution (7.7 lines/mm) faxes. This is the default unless the filename begins with "fn". Tiff and "PC-Research" (DigiFAX) files are self-specifying.
• -n — indicates that raw input files are normal resolution (3.85 lines/mm) faxes. Each fax line is duplicated in the displayed image to give approximately equal vertical and horizontal scales.
• -hheight — specifies the number of fax lines. If this option is missing, viewfax counts the number of lines in the input file. It'll do the math for you 🧮
• -wwidth — specifies the number of pixels in each scan-line. The default value is 1728.
• -l — display in landscape mode. 🌄
• -u — turn the image upside down.
• -i — invert pixels (black/white).
• -b — preferred warning style: 'a' for audible bell (console beep), 'v' for visible bell (flash the window), 'n' for neither. 'v' is the default.
• -d or -display — use specified X server.
• -g or -geometry — the preferred size and position of the window, specified as widthxheight+x+y. If a position is given (x and y values), viewfax asks the window manager to place the window there. The initial size of the window is constrained to be at most widthxheight.

If the window is subsequently resized due to the user zooming in or out, the geometry is taken as a constraint on the screen area which may be used by viewfax.

If you do not supply a geometry value, everything works fine with ICCCM-compliant window managers like olwm, mwm, twm, and tvtwm. When fully zoomed out the viewfax window will occupy the entire screen.

fvwm users 📢: you will notice that the title bar and left border are moved off screen when viewfax repositions the window to (0,0). A workaround is to use -geometry +5+23 when using fvwm. The proper fix would be for someone to update the routine HandleConfigureRequest() in fvwm/events.c to correspond to the code in twm/events.c. (not me volunteering tho 😭)

• -mmemory limit — each page is kept in memory after being fetched and expanded, which saves time if the user returns to it in the same session. To prevent viewfax from using all the available swap space, a limit is placed on the total size of cached images. This defaults to 4 MBytes, enough for about 6 typical pages. If the memory limit is exceeded, old images are discarded and must be reloaded from disk if the user returns to them. The operation of this mechanism is transparent apart from the occasional delays due to reloading. The value specified on the command line can be suffixed k or m for kilo- or megabytes. ✨
• -r — the bit order of the bytes in the input file is reversed. The 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 -r flag is available to deal with the opposite order. little endian/big endian drama but for bits 💀
• -v — produce some informative messages (verbose mode). she's talking 🗣️
• -zzoom — specifies an initial zoom factor. A full-scale fax will usually not fit on the screen. If the -z option is not specified, viewfax scales the image by a power of 2 such that it is fully visible at a reduced size. The user can then use the mouse buttons (see above) to view expanded portions of the image.
• -2 — Assume that raw input files use group 3 two dimensional coding.
• -4 — Assume that raw input files use group 4 coding. The number of fax lines (-h option) is required in this case. no -h, no party 🚫

---

🌈 ENVIRONMENT 🌈

• VIEWFAX_PRINT — Defines a command that will print one or more fax pages.
• VIEWFAX_EDIT — Defines a command that will calls an editor on one or more fax pages.

These two variables are optional. If a variable is undefined, the corresponding keyboard command is ignored. If the variable is defined, it should contain the name of a command or executable script that performs the desired function. The command should process a single page if called with a -p page-number argument. Alternatively, if can be called with just a list of filenames, meaning that all pages should be processed.

Here is an oversimplified example of a print command. Note that it assumes that the format is tiff and will fail when handed a raw fax file. ⚠️

VIEWFAX_PRINT=printfax

/usr/local/bin/printfax:
#!/bin/sh
case "$1" in
-p) shift
    dopt=`expr $1 - 1`
    shift
    tiff2ps -d ${dopt} -2 -h 11.69 -w 8.27 "$1" | lp
    ;;
*)  tiff2ps -2 -h 11.69 -w 8.27 "$*" | lp
    ;;
esac

---

🦋 SEE ALSO 🦋

• mgetty (http://alpha.greenie.net/mgetty/) controls data/fax/voice modems.
• hylafax (http://www.hylafax.org/) is a full-function fax client/server system.
• g3topbm(1) and xv(1) can be used in a pipeline to view faxes. This will usually be slower than using viewfax, but xv has many capabilities for manipulating the image and saving it in other formats.
• faxview.tcl, (ftp://ftp.leo.org/pub/comp/os/unix/networking/mgetty/faxview.tcl.gz) a simple dialog for viewing FAX messages by Ralph Schleicher (rs@purple.in-ulm.de). This is a useful tool which provides a file menu from which incoming faxes can be selected for display with viewfax. 🎀
• CCITT (now ITU) Recommendation T.4, Standardization of Group 3 Facsimile Apparatus for Document Transmission.
• CCITT (now ITU) Recommendation T.6, Facsimile Coding Schemes and Coding Control Functions for Group 4 Facsimile Apparatus.

---

💀 BUGS 💀

• The user interface does not comply with any known style guide. (she's an icon, she's a legend, she is the moment)
• The help text looks moth-eaten because it is encoded as a fax. This avoids dealing with X11 fonts. ngl that's kind of genius
• The program does not refer to the X resources database.

---

👑 AUTHOR 👑

Frank D. Cringle (fdc@cliwe.ping.de).

---

and that's the whole page bestie!! this was Frank´s Hacks, dated 14 November 2004, viewfax(1) — literally a legend, we stan, bye 🫶✨