Understanding Xi-Text Printer Setup Files

How Printer Setup Files Work

Xi-Text uses text-based setup files to define how each printer operates. These files control everything from hardware communication parameters to page formatting and post-processing filters.

Each printer has its own directory containing one or more setup files. The setup file system enables the same form type (like "a4.ps") to work correctly on different printer models without users needing to know which physical printer they're using.

Directory Structure

Setup files are located in printer-specific subdirectories under the printers directory (default: /usr/spool/progs/printers).

For a printer named ptr1, setup files are in:

/usr/spool/progs/printers/ptr1/

File Types in Printer Directories

Setup Files (Paper Types)

Files without leading . or - characters are setup files representing paper types:

/usr/spool/progs/printers/ptr1/a4
/usr/spool/progs/printers/ptr1/letter
/usr/spool/progs/printers/ptr1/default

The .device File

The .device file contains hardware-specific settings shared across all paper types:

/usr/spool/progs/printers/ptr1/.device

This file should contain:

• Baud rate and serial parameters
• Network/terminal server settings
• Hardware interface protocol
• Device communication timeouts

The .device file is read before the paper-type setup file for every job.

Helper Files

Files beginning with . or - are ignored by form type selection:

/usr/spool/progs/printers/ptr1/.setpage    # Alignment page
/usr/spool/progs/printers/ptr1/-Help       # Online help text
/usr/spool/progs/printers/ptr1/.record     # Accounting data

How Xi-Text Selects Setup Files

When a job prints, Xi-Text:

1. Extracts the paper type (everything before first . or -)
2. Looks for a setup file matching the paper type name
3. Falls back to default if no match is found
4. Reads .device file first (if present)
5. Reads the selected setup file
6. Processes suffix-specific commands within the setup file

Example Selection

For printer ptr1 with these files:

.device
a4
letter
default

Form type selections:

• a4.ps → reads .device, then a4 (suffix: ps)
• letter.p10 → reads .device, then letter (suffix: p10)
• legal → reads .device, then default (no suffix)

When Setup Files Are Read

Setup files are processed:

1. At printer startup - Complete .device + setup file read
2. When suffix changes - Setup file re-read for new suffix handling
3. Not automatically on file changes - Printer must be restarted

Best practice: Always stop and restart a printer after modifying its setup files, even though Xi-Text might detect some changes automatically.

What Setup Files Control

Setup files can specify:

Hardware Parameters (typically in .device)

• Serial port settings (baud rate, parity, stop bits)
• Network parameters for terminal servers
• Timeout values
• Flow control settings

Print Job Handling

• Banner page control (on/off, customization)
• Single-job mode (manual feed)
• Page delimiter characters
• Page range interpretation

Strings Sent to Printer

• setup - Initialization string
• docstart - Before each document
• docend - After each document
• pagestart - Before each page
• pageend - After each page
• sufstart - When suffix changes
• shutdown - When printer stops
• abort - On job cancellation

Processing Options

• filter - Post-processing command for all output
• ptr_type - Printer model identifier
• align - Alignment page file
• execalign - Command to generate alignment page

Conditional Handling

• Suffix-specific settings using conditional constructs
• Form-type-dependent string selection

Common Setup File Patterns

Simple PostScript Printer

# .device file
port=/dev/ttyS0
baud=9600

# default setup file
ptr_type=ps

PCL Printer with Multiple Paper Types

# .device file
port=/dev/lp0

# a4 setup file
ptr_type=pcl
setup=\033&l26A         # A4 paper size

# letter setup file
ptr_type=pcl
setup=\033&l2A          # Letter paper size

Network Terminal Server

# .device file
port=<printer01>        # Note: angle brackets for network
connect_cmd=/usr/spool/progs/tsconnect %P %N
timeout=30

# default setup file
ptr_type=ps

Syntax Errors and Diagnostics

Setup file syntax errors prevent printer startup. When a printer enters Error state:

1. Check system log file:

bash

   tail -20 /usr/spool/spd/spshed_reps

1. Look for messages like:
   • "Syntax error in setup file"
   • "Unknown keyword"
   • "Missing required parameter"
2. View from spq using the X command

Common syntax issues:

• Unmatched quotes in strings
• Invalid keyword names
• Malformed conditional statements
• Missing required assignments

File Permissions

Setup files should be:

• Owner: spooler (or appropriate service user)
• Permissions: 644 (read for all, write for owner)
• Directory: 755 (readable and executable for all)

Check permissions:

bash

ls -la /usr/spool/progs/printers/ptr1/

Fix if needed:

bash

chown -R spooler:spooler /usr/spool/progs/printers/ptr1/
chmod 755 /usr/spool/progs/printers/ptr1/
chmod 644 /usr/spool/progs/printers/ptr1/*

Template Directories with Symbolic Links

For identical printers, create a master template directory and link to it:

bash

# Master template
/usr/spool/progs/printers/hp-laserjet-template/

# Symbolic links
/usr/spool/progs/printers/office1 -> hp-laserjet-template
/usr/spool/progs/printers/office2 -> hp-laserjet-template

Individual files can also be linked:

bash

cd /usr/spool/progs/printers/office1
ln -s ../template-printer/a4 a4

Testing Setup Files

After creating or modifying setup files:

1. Check file syntax by starting the printer
2. Monitor the system log for errors
3. Test with a simple job
4. Verify strings are sent correctly (use printer self-test or network capture)

Related Articles

• Configuring Form Types and Paper Types - Understanding form type structure
• Managing Printer States and Operations - Starting and stopping printers
• Printer Enters Error State - Troubleshooting setup file problems

Documentation Reference

For complete setup file syntax and all available keywords, see the Xi-Text System Reference Manual, Chapter: Printer Definitions.