Setting Up and Working With Xi-Text Alignment Pages

Understanding Alignment Pages

An alignment page is a test pattern Xi-Text sends to a printer so that an operator can check the stationery is positioned correctly before any real work is printed on it. While the operator judges the page, the printer waits in the a/w oper state and the job that triggered the check waits with it. The operator approves the page and printing continues, or rejects it, in which case the page is printed again.

It is worth using for:

• Pre-printed invoice and statement forms
• Address labels, especially continuous feed
• Letterhead with specific print zones
• Multi-part forms
• Any stationery where a misfeed wastes the media

It adds nothing on plain paper, on ordinary text, or on PostScript and PDF work that positions itself.

When the Alignment Page Actually Prints

This is the part most often misunderstood, and getting it wrong makes every other step look broken.

The alignment page is not printed when the printer starts. Starting a printer with alignment configured does three things: it reads the setup files, it records that alignment is required, and it puts the printer into idle. The (N/A) marker appears at that moment. Nothing has been printed and nothing is waiting for the operator.

The page prints when the printer is given its first job. At that point, and before anything belonging to the job reaches the paper:

1. Xi-Text sends the docstart string, if one is configured
2. Xi-Text sends the alignment file, or runs the alignment command
3. Xi-Text sends the docend string, if one is configured
4. The printer enters a/w oper and waits

The banner page and the job itself are printed only after the operator approves. A printer that is idle with no work queued therefore shows (N/A) indefinitely and prints no alignment page - which is correct behaviour, and is what the reference manual describes.

Approval lasts until the printer is restarted or changes form type. Once the operator approves, the requirement is cleared and every subsequent job prints straight through. It is not repeated per job and not repeated per copy. It is re-imposed in exactly two situations: the printer is halted and started again, or the printer takes a job whose form type differs from the one it currently holds, in which case the setup files for the new form type are read and, if that form type also configures alignment, the cycle happens again.

Configuring Alignment

Alignment is a property of a printer's setup files, not of the printer record, so it is configured per form type. There are two keywords, and a printer may use one or the other:

• align - the value names a file whose contents are sent to the printer
• execalign - the value is a command that is run, and whatever it writes goes to the printer

# In /var/spool/xi/printers/ptr1/invoice
align=.invoice-align

Both keywords write to the same setting, so the last one in the file wins. Writing both is a way to be surprised.

Where the file is looked for. A value that does not begin with / is taken relative to the printer's own directory, so the line above names /var/spool/xi/printers/ptr1/.invoice-align. An absolute path is used as given:

align=/usr/local/lib/xi-alignments/invoice.align

A leading dot is a convention, so that the alignment file does not appear in the list of paper types offered to users. It has no other meaning.

How the value is read, and two ways to get it wrong

The value after the = runs to the end of the line. Two consequences bite people:

• A comment on the same line becomes part of the file name. Comments are recognised between keywords, not inside a value, so align=.invoice-align # for invoices looks for a file whose name is the whole of .invoice-align # for invoices. Put comments on their own line.
• A tab ends the value silently. Anything after a tab character is discarded without a message.

Escape sequences are never interpreted in an alignment value, so a backslash in a path is taken literally. Write the keyword and its value as one word each side of the =, with no space before it - the form the reference manual uses in its own examples.

Alignment takes effect the next time the setup files are read, which means after the printer is restarted, or when it next changes form type.

Creating the Alignment File

The file is copied to the printer byte for byte. It is not parsed, and there is no comment syntax: every character in it, including anything that looks like a comment, is printed. Keep the file to exactly what should appear on the page.

A page throw is appended after the file only when no docend string is configured - the assumption being that docend ejects the page itself. Without a delimiter keyword the throw is a single form feed; with one, the delimiter string is sent instead, and where that delimiter is a newline the file is padded out to the configured page length.

If the printer has a filter command, the alignment file is passed through it exactly as job data is. That is usually what you want on a printer whose filter converts text to the printer's language, and is the wrong thing on a filter that expects PostScript. Where the filter is unsuitable, use execalign instead - a command's output bypasses the filter.

Box pattern for a pre-printed form

+--------+--------+--------+--------+
|        |        |        |        |
|   1    |   2    |   3    |   4    |
|        |        |        |        |
+--------+--------+--------+--------+
|        |        |        |        |
|   5    |   6    |   7    |   8    |
|        |        |        |        |
+--------+--------+--------+--------+

Invoice Number: _______________
Date: _______________
Amount: _______________

Label sheet pattern

[1 ]  [2 ]  [3 ]
[4 ]  [5 ]  [6 ]
[7 ]  [8 ]  [9 ]
[10]  [11]  [12]
[13]  [14]  [15]
[16]  [17]  [18]
[19]  [20]  [21]
[22]  [23]  [24]

Letterhead pattern

                    Company Name Here
                    123 Main Street
                    Town and Postcode


Dear Customer,

This is a test alignment page.

X marks the position:  X


Signature line: ________________________

Ownership and permissions

The file must be readable by the spooler account:

chown spooler: /var/spool/xi/printers/ptr1/.invoice-align
chmod 644 /var/spool/xi/printers/ptr1/.invoice-align

Generating the Page With a Command

execalign runs a command and sends its output to the printer:

# In /var/spool/xi/printers/ptr1/invoice
execalign=/usr/local/bin/generate-invoice-align

Five things about how it runs decide whether it works:

• It is run through a shell, so a full command line with arguments and redirection is legal. Give an absolute path - the printer's own directory is not searched.
• Both standard output and standard error go to the printer. Anything the command complains about is printed on the stationery, so a script that writes progress messages to standard error will spoil the page it is producing. Send diagnostics to a file instead.
• The current directory is the spool directory, not the printer's directory.
• The output does not go through the printer's filter, and no page throw is appended. The command must emit its own form feed, or the setup file must supply a docend.
• If the command cannot be run, or exits non-zero, the alignment is silently skipped. The printer prints the job without ever entering a/w oper, and the only visible trace is that the (N/A) marker stays on until the job finishes. Nothing is written to the system log. Unlike the file form, an execalign value is never checked when the setup file is read, so a typo in the path is invisible until the first job.

The command runs with the job's details in its environment. The ones an alignment script is likely to want are:

SPOOLPTR    Printer name
SPOOLDEV    Device or network address
SPOOLFORM   Form type in force
SPOOLJOB    Job number of the job that is waiting
SPOOLHOST   Originating host if the job came in over the network, otherwise empty
SPOOLUSER   Numeric user id of the job's owner
SPOOLJUNAME Name of the job's owner
SPOOLHDR    Job title

An example script:

#!/bin/sh
# /usr/local/bin/generate-invoice-align

echo "Alignment test for $SPOOLPTR"
echo "Next job: $SPOOLJOB"
echo ""
echo "+--------+--------+"
echo "|        |        |"
echo "|   A    |   B    |"
echo "|        |        |"
echo "+--------+--------+"
printf '\f'

chmod 755 /usr/local/bin/generate-invoice-align
chown spooler: /usr/local/bin/generate-invoice-align

Approving and Rejecting

While the printer waits, splist shows it as a/w oper and the (N/A) marker is set. The marker is not in the default listing format, so ask for it explicitly:

splist -F "%p %s %n" ptr1

ptr1 a/w oper (N/A)

In spq's printer screen the marker appears on the right of the printer's line.

To approve - the alignment is correct, printing continues with the banner and the job:

spok ptr1

or press y on the printer's line in spq. While the printer is in a/w oper there is no confirmation prompt; the reply is sent at once.

To reject - the alignment page is printed again from the beginning, including the docstart and docend strings, and the printer returns to a/w oper:

spnok ptr1

or press n. There is no limit on how many times this may be repeated. Adjust the paper between attempts: reseat the stationery, check the tractor feed or the guides, and reject again until the pattern lands where it should.

Both commands and both keys need the select printer list privilege, which ordinary users hold by default. It is a different privilege from the one that starts and stops printers.

Two other things end the wait. Halting the printer takes it out of a/w oper and leaves the alignment still required. Aborting the waiting job abandons the alignment and returns the printer to idle.

Bypassing and Reinstating Alignment

The same two commands and keys have a second meaning on an idle printer, and this is how alignment is turned off and on without editing a setup file.

To skip the next alignment - the operator is satisfied the stationery is already correct:

spok ptr1

The (N/A) marker is cleared and the next job prints straight through. In spq, pressing y on an idle printer asks "Bypass alignment for printer ptr1?" and waits for y or n.

To require alignment again:

spnok ptr1

The (N/A) marker reappears and the next job - not the next start - triggers the alignment cycle. In spq, pressing n on an idle printer asks "Rerun alignment for printer ptr1?".

On a printer in any other state both commands do nothing and report nothing; spq says the printer is not waiting for alignment pages to be approved.

Alignment, Form Types and Copies

Form types. The alignment file in force is the one named by the setup files for the printer's current form type, so different stationery can have different test patterns in the same printer directory. When a printer running one form type takes a job needing another, it re-reads the setup files and re-imposes alignment if the new form type configures it - so a printer that alternates between two stationery types asks for an alignment page each time it switches. This is the case the manual omits, and it surprises operators who have been told alignment happens only at start-up.

Copies. The alignment page happens once, before the first copy, and has no effect on the copies count. It does add its characters to the job's accounting total when it is sent as a file without a filter, so a site charging by character sees the alignment page charged to whichever job triggered it.

Single-sheet mode. A printer configured with the single keyword waits in a/w oper before every job as well. On the first job after a start, an operator therefore confirms twice - once for the alignment page, then again for the sheet. In single-sheet mode y and n mean the same thing, so use spok rather than spnok on a printer that has both.

Troubleshooting

The printer goes into error as soon as it is started

If align names a file the spooler account cannot read - because it does not exist, is in the wrong directory, or has the wrong owner - the setup-file reader fails and the printer goes straight to error. The system log carries a message about the initialisation process rather than about the alignment file, so the file name is not in the message. Check the file first:

ls -l /var/spool/xi/printers/ptr1/.invoice-align
su spooler -c "cat /var/spool/xi/printers/ptr1/.invoice-align > /dev/null"

The commonest causes are a comment left on the align= line, a leading space after the =, and a file owned by root rather than by spooler.

The printer starts, shows (N/A), and nothing prints

This is normal when the queue holds no work for that printer. The alignment page is printed when the first job is selected. Check with sqlist that a job exists which this printer can take - the form type, class code and size limits all have to match, as article 26 describes.

The job printed without an alignment page

Three possibilities, in order of likelihood. The requirement had already been cleared, by an earlier approval or by spok on the idle printer; check with splist -F "%p %s %n". The setup file in force for that form type has no align line - remember the alignment file is chosen by form type. Or the printer uses execalign and the command failed, which is silent; run the command by hand as the spooler account and check its exit status.

The alignment page prints garbled

The file is passed through the printer's filter, so a filter that expects a particular input language will mangle a plain-text pattern. Either write the alignment file in whatever the filter expects, or switch to execalign, whose output bypasses the filter entirely.

The other cause is escape sequences in the setup file's setup or docstart strings that do not suit the printer. Article 16 covers how those strings are written and the traps in them.

The page prints but the printer never asks for approval

With execalign, a command that exits non-zero after producing some output leaves the printer printing the job rather than waiting. Check the command's exit status. With align, a page that appears but no a/w oper means the file was read after all and something else cleared the requirement.

y or spok appears to do nothing

Confirm the printer really is in a/w oper with splist ptr1. Both the key and the command are silent no-ops on a halted, offline or errored printer. Check also that the right printer is selected in spq, and that the account holds the select printer list privilege.

A Complete Example

Device settings, shared by every form type on this printer:

# /var/spool/xi/printers/ptr1/.device
baud 9600
open 30
offline 30

The invoice form type:

# /var/spool/xi/printers/ptr1/invoice

# Escape sequences are given names first
RESET=\eE
A4SIZE=\e&l26A
EJECT=\f

setup RESET A4SIZE

# Alignment pattern for invoice stationery
align=.invoice-align

# Eject at the end of each document
docend=EJECT

# No banner page on pre-printed stationery
nohdr

The alignment pattern itself, in /var/spool/xi/printers/ptr1/.invoice-align. It carries no comment line naming the file, because every character in it prints:

+------------------+
| INVOICE          |
| Number: ______   |
|                  |
| Date: ______     |
|                  |
| Amount: ______   |
+------------------+

The operating procedure:

1. Load the invoice stationery
2. Start the printer: spstart ptr1 invoice
3. The printer goes idle showing (N/A); nothing prints yet
4. When the first invoice job is queued, the alignment pattern prints and the printer shows a/w oper
5. Compare the pattern against the pre-printed boxes
6. If it is right: spok ptr1 - the banner and the job follow
7. If it is wrong: spnok ptr1, adjust the stationery, and repeat

Best Practices

Make the pattern obviously right or obviously wrong:

Corners, rules and field markers that line up with the pre-printed boxes are judged in a second. A page of prose is not.

Test on the real stationery:

Plain paper of the same size proves nothing about a form whose boxes are in fixed places.

Write the procedure down for the operators:

One card per form type, saying what the pattern should look like, which keys approve and reject, and how the paper is adjusted, removes most of the calls this feature generates.

Remember it is per form type:

A printer that switches stationery asks again. Give each form type its own alignment file rather than sharing one.

Prefer a file to a command unless you need one:

A file is checked when the setup file is read, so a mistake shows up at once. A command is checked nowhere, and a mistake in it silently disables alignment on the printer it was meant to protect.