Configuring Xi-Text Form Types, Paper Types and Suffixes

What a form type is, the exact rule matching a job to a printer, and how a suffix changes without stopping the printer

Xi-TextXi-Textconfigurationform-typesprinterssetup-filesspchangesplistspstartspuchangespulistsqlist

A form type names the medium loaded in a printer and how output is formatted for it, and it is what decides which printer takes a job. This article covers the two parts of a form type, the rule that matches a job to a printer, and how to configure both.

What a form type is

Every job carries one form type and every printer carries one form type, each held as a single text field of at most 34 characters. A longer value is truncated to 34 characters. Xi-Text accepts any character, and the part before the first . or - becomes a file name, so it has to be usable as one.

The two parts of a form type

Every form type consists of two parts, divided at the first . or - in the name. Those two characters are the separators; they are built into the product and cannot be configured.

Paper Type
Everything up to the first . or - character

Represents the physical medium loaded in the printer

Changing it means halting the printer and starting it again - one command does both

Suffix (optional)
Everything after the first . or - character

Represents formatting variations or output processing

Can change automatically between jobs without printer intervention

The test that separates the two: if someone must physically touch the printer to change it, it is a paper type; if software can handle it, it is a suffix.

Three form types split at the separator

a4.ps
├── Paper type: a4
└── Suffix: ps

letterhead.p12
├── Paper type: letterhead
└── Suffix: p12

labels
└── Paper type: labels (no suffix)

The paper type decides which printer takes a job

The paper type determines which physical medium is loaded:

Standard sizes: a4, letter, legal, a3
Special media: labels, envelopes, letterhead
Custom forms: invoices, cheques, payslips

Changing a printer's paper type takes four steps:

Halt the printer
Physically change the paper
Update the form type in Xi-Text
Restart the printer

Steps 1, 3 and 4 are a single command. spstart ptr1 letterhead halts a running printer, changes its form type and starts it again by itself; the form type is the second positional argument, after the printer name. On a printer that is already halted, spchange ptr1 letterhead changes the form type without starting it, but spchange needs the add/delete printers permission, which spstart does not.

The spooler applies this rule each time it looks for work for an idle printer:

Take the printer's form type and cut it at the first . or - - that is the printer's paper type.
The job's form type must begin with those characters, compared ignoring case.
The next character of the job's form type must be the end of the name, or a . or -.

Three printers and four jobs show the rule working:

# Printers configured:
ptr1: a4
ptr2: letter
ptr3: a4

# Jobs submitted:
Job 1: a4.ps     ← Can print on ptr1 or ptr3
Job 2: a4.land   ← Can print on ptr1 or ptr3
Job 3: letter.ps ← Can print on ptr2 only
Job 4: a4        ← Can print on ptr1 or ptr3

The printer's own suffix takes no part in the comparison. A printer showing a4.ps accepts a4, a4.pcl and a4-p12 as readily as a4.ps, and so does a printer showing plain a4. What neither accepts is a4wide, because the character after a4 is neither the end of the name nor a separator.

A job whose paper type matches no printer waits. There is no error, no message and no timeout: it keeps its place in the queue until a printer is loaded with a matching paper type, or the job is changed or deleted. This is the commonest reason for a job that never prints while printers sit idle.

The printer's form type is also overwritten by every job it takes. When a printer starts a job whose form type differs from its own, it adopts the job's form type in full, so the form type shown by splist is the one from the last job printed - which may carry a suffix, or lack one, that nobody configured. The paper type part cannot change this way, because the matching rule has already made it equal.

What a suffix does

A suffix specifies a formatting variation that leaves the paper alone. No suffix has a built-in meaning: a suffix does whatever the printer's setup file says it does, and a suffix that no setup file mentions is accepted and does nothing. The names below are conventions in common use:

.ps - PostScript output
.pcl - PCL (HP Printer Command Language)
.p10 - 10 characters per inch
.p12 - 12 characters per inch
.landscape - Landscape orientation
.duplex - Double-sided printing

Suffixes enable:

Automatic format conversion (PostScript to PCL)
Font selection
Pitch/orientation changes
Input and output tray (bin) selection
Filter selection
Special processing

Switching between suffixes

When the printer picks up a job whose form type differs from the one it is currently set to:

Current job completes
The printer goes into the startup state
The sufend string for the outgoing suffix is sent
The setup files are read again for the new form type - the .device file, then the file named after the paper type, or default
The sufstart string for the new suffix is sent
The printer returns to printing and the job begins

This happens without a printer restart. Two consequences follow. Because the setup files are read again at this point, an edit made since the printer started takes effect at the next suffix change, and a setup file that has since become unparseable puts the printer into the error state in the middle of a run. And if the setup file selected for the new form type asks for an alignment page, the printer prints one and waits in a/w oper for an operator to approve it, so a suffix change is not always unattended.

Which naming rules the product enforces

Two of the rules below are enforced by the product: the 34-character limit, and the exclusion of . and - from a paper type - a . or - is the separator, so a paper type cannot contain one. Everything else here is convention, and Xi-Text accepts a name that ignores it.

Naming a paper type

Use descriptive names: a4, letter, not type1, type2 - convention
Lower case is conventional: letterhead not LetterHead - convention, but see the note below
No spaces: use underscores if needed - convention; a space is accepted and makes the setup file awkward to handle. Do not use a hyphen as a word separator, because it starts the suffix
. and - cannot appear in a paper type - enforced
34 characters is the limit for the whole form type, paper type and suffix together, and a longer value is truncated - enforced

Case needs care. Matching a job to a printer ignores case, so a job submitted as A4.ps is accepted by a printer loaded with a4. The setup file is then opened by name, and that lookup is case sensitive, so the printer looks for a file called A4, does not find one, and falls back to default. Keeping to one case throughout avoids this.

Naming a suffix

Short and meaningful: .ps not .postscript - convention
Consistent across printers: .ps should mean PostScript everywhere - convention, and the reference manual recommends it
Lower case conventional; suffix patterns in setup files are matched case sensitively, so the case used in the form type has to match the case in the setup file
The suffix is everything after the first separator, so a4.ps.duplex has paper type a4 and one suffix, ps.duplex

Setting up form types

Creating a setup file for a paper type

For each printer, create a setup file in that printer's own directory whose name is the paper type. The default location is /var/spool/xi/printers; if your installation differs, read the SPOOLPT setting from /etc/xi/textconfig.

cd /var/spool/xi/printers/ptr1

# Create setup file for a4 paper.
# A name that is not a keyword defines a symbolic string, and the
# value runs to the end of the line. \e is escape.

cat > a4 << 'EOF'
A4SIZE=\e&l26A
setup=A4SIZE
EOF

# Create setup file for letter paper
cat > letter << 'EOF'
LETTERSIZE=\e&l2A
setup=LETTERSIZE
EOF

The files must be owned by the system user: only files it owns are offered in the form type lists spq displays. There is no keyword that names the printer's make or emulation, and the full keyword set and string syntax belong to Xi-Text Printer Setup Files: What They Contain and When They Are Read. What matters here is the file's name, which is the paper type.

Handling suffixes in a setup file

Suffix-specific handling is written as a conditional block. The block opens with { and closes with }, and holds one or more patterns in round brackets, each followed by the settings to apply. The first pattern that matches the suffix wins and the rest are skipped; * matches anything, ? matches one character, [...] matches a set, and @ matches the empty suffix.

PORTRAIT=\e&l0O
LANDSCAPE=\e&l1O

{
    (ps)
        # PostScript jobs - no conversion needed
        nohdr
    (l*)
        # Any suffix beginning with l - rotate output
        sufstart LANDSCAPE
    (*)
        # Anything else
        sufstart PORTRAIT
}

There is no keyword that names a suffix and no end marker other than the closing brace. The equals sign makes a difference: sufstart LANDSCAPE appends to whatever the file has already put in that string, while sufstart=LANDSCAPE discards what was there and starts again. A file may contain several such blocks, and each is evaluated independently against the same suffix.

The default setup file

Xi-Text reads the .device file first if there is one, then looks for a file whose name is the paper type; if it cannot find that, it uses the file named default:

/var/spool/xi/printers/ptr1/default

One default file therefore covers every paper type a printer is given. Most installations need only that file: the printer installation script (Ptrinstall) creates two files and looks at no others - .device for the hardware interface, and default for the paper handling.

If neither a file named after the paper type nor a default file can be found, the printer does not start. It goes to the error state, and the reason - naming the directory and the file it wanted - is appended to /var/spool/xi/spd/spshed_reps.

Changing the name of the fallback file

The reference manual describes a master configuration setting, DEFAULT_FORM, which changes the name of the file Xi-Text falls back on when nothing matches the paper type, and states that an empty value disables the fallback so that an exact paper type match is required:

# In /etc/xi/textconfig
DEFAULT_FORM=fallback

On the current release this setting cannot be used. The master configuration parser accepts only letters and digits in a setting name, so it stops at the underscore in DEFAULT_FORM and treats the line as malformed. Every Xi-Text program reads that file as it starts, so adding the line above stops the entire installation - each command exits at once with

Config file (/etc/xi/textconfig) error at line NN - Expecting = after name

If the line has been added, delete it and the commands work again. If you need the fallback file named something other than default, contact Xi Software rather than editing the configuration.

Each user has a default form type

Each user has a default form type, used when a job is submitted without -f, and an allowed form type pattern. A user who does not hold the "use other forms" privilege may submit only form types matching that pattern, and is refused with "Invalid form type" followed by the pattern. Both are held in the user permissions file rather than in a configuration file, and both are set with spuchange or through the spuser screen.

Reading the current defaults

# Default form type and allowed pattern, per user
spulist -F '%u %f %a'

The first line of spulist's output is the system default that new users inherit; -s suppresses that line and -S suppresses the per-user lines.

Changing the system-wide default

The system default is chosen when Xi-Text is installed. To change it:

# Set the system default form type and allowed pattern
spuchange -D -f a4 -F a4

# ...and copy the new defaults over every existing user as well
spuchange -A -D -f a4 -F a4

Changing one user's default

# Change one user's default form type
spuchange -u -f letter fred

A user may also freeze a form type into their own spr options. That applies to spr alone and leaves the default recorded for them unchanged:

spr -f letter --freeze-home

One form type across several printers

Make the same form type work on every printer. If a user submits a4.ps:

On PostScript printer: send directly
On PCL printer: convert PostScript to PCL
On text-only printer: error or convert to text

The same form type on three printers

Printer 1 (PostScript):
    a4.ps → passed straight through

Printer 2 (PCL):
    a4.ps → filter converts PostScript to PCL

Printer 3 (Text):
    a4.ps → filter converts PostScript to text

The conversion is named by the filter keyword inside the block for that suffix, and Xi-Text ships no converter of its own: Ptrinstall writes a filter line invoking Ghostscript when it sets up a PCL printer that must accept PostScript.

The standard form type

The default installation uses standard as the initial default form type. The name is a placeholder.

Change it to the name of the site's own standard paper, such as a4 or letter.

The printer installation script prompts to update this if it sees standard as the default, and applies the change to every existing user as well as to the system default.

A printer's own help file

Create a help file in a printer's directory to summarise its paper types and suffixes:

# Create help file for printer ptr1
cat > /var/spool/xi/printers/ptr1/-Help << 'EOF'
Available paper types:
  a4         - A4 paper (210x297mm)
  letter     - US Letter (8.5x11")
  letterhead - Company letterhead

Available suffixes:
  .ps        - PostScript output
  .pcl       - PCL output
  .p10       - 10 characters per inch
  .landscape - Landscape orientation
EOF

This is shown when someone presses ? while changing that printer's form type in spq. Without it, the same key lists the setup files found in the printer's own directory - which is why setup files are named after paper types, and why anything else kept in the directory should be given a name beginning with . or - so that it stays out of the list. Only files owned by the system user are listed. The name -Help can be changed with the HELPNAME setting in /etc/xi/textconfig.

Checking which form types are in use

Jobs and their form types

# List jobs with their form types
sqlist -F '%N %u %f %h'

Neither spq nor sqlist has an option to select jobs by form type; filter the sqlist output instead.

sqlist -F '%N %f' | grep 'a4\.ps$'

Printer form types

# splist's default output already includes each printer's form type
splist

The paper types a printer has setup files for

# List setup files (available paper types) for printer
ls -a /var/spool/xi/printers/ptr1/

# Exclude the names Xi-Text treats as invisible (those starting with . or -)
ls -a /var/spool/xi/printers/ptr1/ | grep -v '^[.-]'

Three configuration patterns

One file for everything

Single default file handles everything:
/var/spool/xi/printers/ptr1/default

One file per paper type

Separate setup file per paper type:
/var/spool/xi/printers/ptr1/a4
/var/spool/xi/printers/ptr1/letter
/var/spool/xi/printers/ptr1/legal

Hardware settings kept apart from paper handling

Common hardware settings, paper-specific setup:
/var/spool/xi/printers/ptr1/.device       (hardware)
/var/spool/xi/printers/ptr1/default       (paper handling)

Checking that it worked

After configuring form types:

Submit test job:

   echo "Test" | spr -f a4.ps -P ptr1

Check printer accepts form type:

   splist
   # Verify printer shows correct form type

Test suffix switching:

   echo "Test 1" | spr -f a4.ps -P ptr1
   echo "Test 2" | spr -f a4.pcl -P ptr1
   # Should switch automatically

Verify setup file selection: Nothing is written to the system log when a setup file is read successfully - only failures are recorded, and each entry names the printer directory and the file that was being read. Silence here means the files parsed:

   tail -20 /var/spool/xi/spd/spshed_reps

When the form type is the cause

The job stays in the queue and the printer shows idle

Check:

Do the two paper types match? Compare only the part before the first . or - ; the suffixes are irrelevant to selection.

   sqlist -F '%N %u %f'   # Check job form types
   splist                 # Check printer form types

If they match and the job still waits, the form type is not the cause. A job is also passed over when it is outside the printer's size limits, when its class code does not intersect the printer's, when it names a different printer, or when its hold time has not arrived - see Managing Xi-Text Printer States and Operations. A missing setup file does not leave a job waiting; it puts the printer into the error state instead.

The printer enters the error state after a form type change