Configuring Xi-Text Form Types, Paper Types and Suffixes

Understanding Form Types

A form type in Xi-Text represents the complete specification of what medium is loaded in a printer and how to format output for it. Form types enable users to submit jobs without knowing which physical printer will be used.

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 silently truncated to 34 characters rather than refused. Xi-Text places no restriction on which characters you use, but the part before the first . or - becomes a file name, so it has to be usable as one.

Form Type Structure

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.

Examples

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

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

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

How Paper Types Work

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

Important: When a printer's paper type changes, the operator must:

1. Halt the printer
2. Physically change the paper
3. Update the form type in Xi-Text
4. 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.

Xi-Text will only send a job to a printer when the job's paper type matches the printer's loaded paper type. The rule the spooler applies each time it looks for work for an idle printer is exactly this:

• 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 simply 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.

How Suffixes Work

Suffixes specify formatting variations that don't require paper changes. 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, not product features:

Common suffix conventions:

• .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

Suffix Switching

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

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

No printer restart required - this happens automatically. Two consequences are worth knowing. 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.

Form Type Naming Conventions

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.

Paper Type Naming

• 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 without warning - 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 silently falls back to default. Keeping to one case throughout avoids this.

Suffix Naming

• 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 Paper Type Support

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 - the setup file describes behaviour, not hardware identity - 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 and nothing else.

Handling Suffixes in Setup Files

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. Note also the difference the equals sign makes: 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

This enables:

• Catch-all for uncommon paper types
• Simplified configuration (single setup file handles all paper types)
• Graceful degradation

Note: Most installations only need a default 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 Default File Name

⚠️ Advanced - do not use on this release

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

Warning: 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.

User Default Form Types

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.

View Current Default

# 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.

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

Per-User 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

Form Type Compatibility Across Printers

Best practice: Make the same form type work consistently across all printers.

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

This consistency lets users worry about output format, not which printer receives the job.

Example: Multi-Printer Consistency

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

Same form type, different handling, consistent user experience. 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.

Special Form Type: "standard"

The default installation uses standard as the initial default form type. This is just a placeholder name with no special meaning.

Recommendation: During installation or after, change standard to a meaningful name like a4 or letter for your site's actual standard paper.

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.

Form Type Online Help

You can summarise a printer's paper types and suffixes by creating a help file in its directory:

# 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 Form Type Usage

View Jobs by Form Type

# 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$'

View Printer Form Types

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

Available Form Types

# 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 '^[.-]'

Common Configuration Patterns

Minimal Configuration

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

Paper-Specific Configuration

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 + Paper Configuration

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

Testing Form Type Configuration

After configuring form types:

1. Submit test job:

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

1. Check printer accepts form type:

   splist
   # Verify printer shows correct form type

1. Test suffix switching:

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

1. 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

Troubleshooting Form Type Issues

Job Not Selected by Printer

Symptom: Job stays in queue, printer shows idle

Check:

1. 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

1. 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.

Printer Shows Error on Startup

Symptom: Printer enters Error state after changing form type

Check:

1. A setup file exists for the new paper type, or a default file does
2. Setup file has correct syntax
3. System log shows specific error:

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

Suffix Has No Effect

Symptom: Jobs print, but every suffix produces the same output

Check the conditional block in the setup file. Read the .device file as well, since it is read first and forms part of the same parse:

   cat /var/spool/xi/printers/ptr1/.device
   cat /var/spool/xi/printers/ptr1/a4

1. The patterns carry no leading dot
2. They match the case of the suffix actually submitted
3. The first pattern that matches is the one you meant - a leading (*) arm swallows everything after it
4. No line earlier in the file begins with a backslash outside a NAME= definition, which would have ended the parse in silence before the block was reached

A pattern of its own is the quickest test: add the block below, submit a job with the .test suffix, and see whether TEST appears on a page of its own - inside a quoted string ^L is a form feed.

   {
       (test)
           sufstart "TEST^L"
   }

Related Articles

• Xi-Text Printer Setup Files: What They Contain and When They Are Read - Detailed setup file syntax
• Managing Xi-Text Printer States and Operations - Changing printer form types
• Diagnosing Why an Xi-Text Job Will Not Print - Troubleshooting form type mismatches

Documentation Reference

For complete form type handling and setup file syntax, see:

• Xi-Text System Reference Manual, Chapter: Printer definitions
• Xi-Text Administration Guide, Chapter: Print jobs and form types
• Xi-Text User Guide, Chapter: Form Types