PDF2FAX(8)

💌 PDF2FAX(8) — the manual, but make it cute

System Manager's Manual energy, bestie. Let's get into it. 🎀

---

✨ NAME ✨

pdf2fax — takes an image-y Portable Document Format file and turns it into something you can fax, courtesy of HylaFAX. 💖

---

🦋 SYNOPSIS 🦋

/var/spool/hylafax/bin/pdf2fax [ options ] [ files...  ]

---

🌸 DESCRIPTION 🌸

Okay so. pdf2fax eats Portable Document Format (PDF) input and spits out a TIFF Class F image file that's ready for facsimile transmission. Slay. It's usually the HylaFAX scheduler process, faxq(8), that calls it — so it's not really out here living its own life, it's a team player. The actual PDF imaging is typically done with the freely available Ghostscript software.

Here's the little plot twist: pdf2fax isn't a whole standalone thing — it's actually a link (symbolic or otherwise, we don't gatekeep) to the script that's appropriate for whatever PDF imaging tool you've got. That link gets set up when the faxsetup(8) script runs to configure a HylaFAX server machine for use. So the link is basically the glow-up, and the script is the real one. iykyk. 💅

Input files containing PDF? Just drop them on the command line. If you give it none — literally none — then pdf2fax will read from standard input. No input, no problem, it's flexible like that. 🫶

By default, pdf2fax generates a 98 line/inch output document whose page width is 1728 pixels and page length is 297 mm (that's a standard A4 page, but at low resolution, so she's giving compact-but-clear). Horizontal resolution is always 204 dpi — that part is not negotiable, bestie, it's just the rule. But the command line options let you pick a different vertical resolution and different page dimensions if you want to customise the vibe. ✨

If no filename is given, pdf2fax writes its output to a file named pdf.fax. Want a different name? The -o option has you covered, iconic behaviour.

By default, output is compressed using the standard Group 3 1D-encoding scheme, with EOL codes padded to byte boundaries. And if you pass the -2 option, the output gets encoded with the optional Group 3 2D-encoding scheme instead (EOL codes are still padded to byte boundaries, that part doesn't change). Not me being picky about byte boundaries — the bytes are picky, I'm just reporting. 😭

This script can modify outgoing facsimile, such as watermarking. To do this, create a shell script etc/FaxModify in the spooling area that alters the document. Custom watermark era. 🎀

Heads up though: bin/pdf2fax is usually just a link to a shell script that invokes the appropriate PDF RIP to do the work. So don't be shocked when it's a link. It's a link. That's the whole bit.

---

💅 OPTIONS 💅

The following operations are recognized:

• -1 — Write Group 3 1D-encoded data to the output file.
• -2 — Write Group 3 2D-encoded data to the output file.
• -3 — Write Group 4 MMR-encoded data to the output file.
• -m pages — Set the maximum number of pages that are permitted in the output file. If more pages are present in the input document, then abort processing. (Yes, abort. She means it. 💀)
• -o file — Write output to the specified file instead of the default pdf.fax filename.
• -w width — Set the output page width, in pixels. By default, pages are 1728 pixels wide.
• -l length — Set the output page length in millimeters. By default, pages are 297 millimeters long.
• -r vres — Set the vertical resolution, in lines/inch, at which to image the PDF.

---

🌈 RUNTIME ENVIRONMENT 🌈

Before user-supplied PDF gets passed to the PDF interpreter, a limited number of operators are defined. These operators are operators commonly found in a LaserWriter printer and (sometimes) generated by Macintosh-based applications. Vintage-coded but we respect it. ⭐

The default Display PDF-based execution environment includes support for the following fonts:

• AvantGarde-Book
• AvantGarde-BookOblique
• AvantGarde-Demi
• AvantGarde-DemiOblique
• Bookman-Demi
• Bookman-DemiItalic
• Bookman-Light
• Bookman-LightItalic
• Courier
• Courier-Bold
• Courier-BoldOblique
• Courier-Oblique
• Helvetica
• Helvetica-Bold
• Helvetica-BoldOblique
• Helvetica-Narrow
• Helvetica-Narrow-Bold
• Helvetica-Narrow-BoldOblique
• Helvetica-Narrow-Oblique
• Helvetica-Oblique
• Lithos-Bold
• NewCenturySchlbk-Bold
• NewCenturySchlbk-BoldItalic
• NewCenturySchlbk-Italic
• NewCenturySchlbk-Roman
• Palatino-Bold
• Palatino-BoldItalic
• Palatino-Italic
• Palatino-Roman
• StoneSerif
• Symbol
• Tekton
• Times-Bold
• Times-BoldItalic
• Times-Italic
• Times-Roman
• ZapfChancery-MediumItalic
• ZapfDingbats

Note that this is the same set of fonts supported by the DPS extension to the X server. Matching set, no notes. 👑

The default Ghostscript-based environment is more uncertain; consult the Ghostscript documentation for information on what fonts are available. Lowkey mysterious. Go read the docs, bestie. 🙈

---

💀 BUGS 💀

• Output from the Display PDF version of this command is encoded according to the Display PDF binary encoding protocol.
• Ghostscript-based versions of this program fail to exit with non-zero status when an invalid PDF document is processed. This makes it problematic for the HylaFAX queue manager to determine when a problem arises when preparing a job for transmission. So like... it's broken and it won't tell you it's broken. The queue manager is out here guessing. Not the communication style we deserve. 😭

---

🎀 SEE ALSO 🎀

sendfax(1), faxq(8), hylafax-server(5)

---

And that's the whole page, bestie — written March 08, 2001, from the System Manager's Manual. Genuinely iconic for a fax script from 2001 to be this well documented. Periodt. 🦋✨💖