The following commands load a sample PRINTKIT-TEST-MARK Form definition for use with PrintKit, and define a PRINTKIT_TEST medium that can be used for printing the overlay.

1.Make sure the Form resource name matches the file name, and it doesn't contain any uppercase letters (use lowercase instead). PrintKit uses the file name (in lowercase) as the resource name. If the two do not match, the PostScript interpreter on your printer will report an undefinedresource error when you try to use the overlay.

In a typical Form definition, the form name appears near the end of the file preceding a defineresource command. For example:

Look for the name you have chosen for your Form resource instead of the /printkit-test-mark shown in the example. If there is a discrepancy, make corrections to the name.

Briefly, the defineresource command operates on three parameters that are defined in the code that precedes it – the name of the resource, the resource itself, and resource type. If you know a bit about PostScript, you'll notice the example code doesn't show the resource (it presumably was defined by the preceding portion of the file), and the exch command rearranges the parameter order to place the resource name first.

If your file doesn't look like this, the defineresource parameters may be defined in their natural order, in which case the resource name appears much earlier in the file, before the (typically long) definition of the resource itself. Unfortunately, there are almost limitless variations on how the resource definition can be coded in PostScript, some of which require considerable expertise to decipher. (If you're having trouble deciphering the PostScript, try testing the definition assuming the name matches correctly.)

2.Load the Form definition in PrintKit's PostScript Device Control Library.

PrintKit searches for Form resource definitions in its PostScript Device Control Libraries. Device control libraries are specified by the queue /LIBRARY qualifier; those containing PostScript modules have /DATA_TYPE=POSTSCRIPT set. The standard PrintKit PostScript Device Control Library is SYS$LIBRARY:PRINTKIT_PS.TLB.

Use the name you have chosen for your Form resource instead of the PRINTKIT-TEST-MARK shown in the example. If your PrintKit queue uses a site-specific configuration of Device Control Libraries, you may also need to choose a different name for the PostScript library.

3.Define a medium that displays the overlay.

Use the name you have chosen for your Form resource instead of the PRINTKIT-TEST-MARK shown in the example, and use an appropriate medium name.

4.Print a sample file to test the medium definition.

If you create a form overlay using software that can produce a Portable Document Format (PDF) file as output, you can use the XPDF pdftops utility to convert the PDF file to a Form resource. See PrintKit and Forms Overlays for more information on the XPDF software suite.

Once you have the XPDF installed on your OpenVMS system, the procedure for converting a PDF file to a Form resource is straightforward:

1.Invoke pdftops to convert the overlay file:

(Use the name of your overlay file in place of overlay-file.)

2.Edit the PostScript output file produced by pdftops so that it has the correct resource name. The output file produced by pdftops always specifies Foo as the name of the Form resource:

Find this line in the overlay-file.PS file produced by pdftops and change Foo to overlay-file.

One way to create a Form resource is to start with an Encapsulated PostScript (EPS) file and adjust it to be a Form resource. There are many applications that can produce PostScript output files in EPS format, and the adjustments to the EPS file require only a little care and the ability to use a text editor.

An EPS file is a PostScript file containing an illustration or other graphic arranged so that it can be encapsulated in another PostScript document. The EPS format ensures that the PostScript code in the file is self-contained and will be “well behaved” in its surrounding context. In addition, the format requires the file to contain Document Structuring Comments (DSCs) to assist in the use of the file.

For the most part, the restrictions imposed on EPS code also ensure the code will work correctly when used to define a Form resource. (There are a few details to watch out for, discussed in the instructions that follow.) And the required Document Structuring Comments provide all the additional information required to create a complete Form resource definition.

In brief, you convert an EPS file into a Form resource definition by adding a few lines of PostScript code to the file at the beginning of the code that draws the illustration and at the end of the file. You also change the heading line at the beginning of the modified file to indicate that it contains a Form resource definition, and is no longer an EPS file.

The following instructions show, step by step, the procedure for converting an EPS file to a Form definition. They use a very simple EPS file that displays the words “PRINTKIT OVERLAY” in the upper left corner of the page.

The contents of the file, before and after the conversion, are shown in the figure below. Numbered marks show the locations in the file that are changed at each step of the conversion.

Sample Form resource conversion. Left column is original EPS file, right is resulting Form resource.

	before	after
2.	%!PS-Adobe-3.0 EPSF-3.0 %%Title: printkit-test-mark form	%!PS-Adobe-3.0 Resource-Form %%Title: printkit-test-mark form
3.	%%BoundingBox: 0 0 612 792	%%BoundingBox: 0 0 612 792
	/ctrstr { gsave dup stringwidth 2 div neg exch 2 div neg exch rmoveto false charpath stroke grestore } def %%EndProlog	/ctrstr { gsave dup stringwidth 2 div neg exch 2 div neg exch rmoveto false charpath stroke grestore } def %%EndProlog
4.		<< /FormType 1 /BBox { 0 0 612 792 } /Matrix matrix /PaintProc { begin userdict begin
	%%BeginSetup save %%EndSetup 0 11 72 mul translate 45 rotate /Helvetica-Bold findfont 24 scalefont setfont 0 -180 moveto 0.1 setlinewidth (PRINTKIT) ctrstr 0 -24 rmoveto (OVERLAY) ctrstr	%%BeginSetup save %%EndSetup 0 11 72 mul translate 45 rotate /Helvetica-Bold findfont 24 scalefont setfont 0 -180 moveto 0.1 setlinewidth (PRINTKIT) ctrstr 0 -24 rmoveto (OVERLAY) ctrstr
5.	showpage
	%%Trailer restore	%%Trailer restore
6.		end end } >> /printkit-test-mark exch /Form defineresource pop
8.		/printkit-test-mark /Form findresource execform showpage

1.Use your chosen graphics application to produce the forms overlay, and output it as an EPS file.

The EPS format allows a bitmap screen preview to be included at the end of the EPS file. Tell your application not to generate this optional part of the EPS file.

The file should begin with the line:

The dsc-version and eps-version are decimal version numbers, such as 3.0). If the file does not begin with this comment, it is not an EPS file, and it may not produce a workable Form resource.

There is one PostScript construction to watch out for in your EPS file – scanned images, such as logos. Typically, applications encode the data from a scanned image in a format that cannot be incorporated into a Form resource. (Technically speaking, they represent it as in-line data that is read by PostScript operators, rather than as tokens to be scanned by the PostScript interpreter.) If your forms overlay uses scanned images, you'll probably need to convert them to line art. Many graphics applications have an autotrace function that will do this for you automatically.

2.Change the heading line to indicate a Form resource. Replace the first line of the EPS file with:

This indicates the modified file contains a Form resource definition, and is no longer an EPS file. Use the dsc-version from the original heading line.

3.The heading section should contain a %%BoundingBox comment that specifies the limits of the illustration displayed on the page. Note the four dimensions (the left, bottom, right, and top limits, in printer's points).

4.An EPS file consists of a header section (a block of comment lines at the beginning of the file), a prolog section (which may contain standard definitions), a setup section (PostScript setup for the illustration), a body section (the PostScript code that draws the illustration), and a trailer section (PostScript housekeeping). The prolog, setup, and trailer sections may be empty or missing.

You need to add lines to the EPS file between the prolog and setup sections. If one or the other of these sections is missing, place the added lines where the missing section would appear.

The end of the prolog section should be marked with an %%EndProlog comment. If the setup section is present, it is marked by a %%BeginSetup comment immediately following the end of the prolog. If there is no prolog or setup section, add the new lines before the first line in the file that is not a Document Structuring comment – that is, before the first line that does not begin with two percent signs (%%).

Use the name you have chosen for your Form resource instead of the printkit-test-mark shown in the example. The resource name appears twice in the added lines – here and at the very end.

Use the numbers you recorded from the %%BoundingBox comment as the numbers following the /BBox command.

As noted in the installation instructions above, the Form resource name must be the same as the VMS name of the file containing the definition, and it should not contain any uppercase letters (use lowercase instead).

5.

An EPS file may contain a showpage operator. Look for it at the end of the file and remove it if it is present.

The showpage may be performed indirectly by a PostScript procedure. In this case, what appears at the end of the file is only the name of the procedure; its definition will appear earlier in the file, probably in the prolog section. To get rid of the showpage operator in these cases, you can either remove it from the definition, or remove the entire reference to the defined procedure. If you choose to remove the procedure, be sure it doesn't have other effects that should be left unchanged.

For example, suppose you find a reference to a EJ procedure at the end of the file. Looking through the prolog, you find its definition:

You can either eliminate the EJ reference, or remove the showpage operator from its definition. In this case, it is safe to remove the entire reference because the gsave/grestore operators in the definition, in combination have no side-effects. If the definition contained an unmatched gsave or grestore, it would not have been safe to remove the reference.

In general, unless you are familiar with PostScript, the fewer changes you make to the EPS file, the safer you are.

6.

Add the lines indicated in the example at the end of the file. The last two lines you enter here aren't actually part of the definition. They are for testing, and you will remove them once you have determined that the definition works correctly.

7.

Test the Form resource definition file by printing it using PrintKit. It should display the illustration you plan to use as a forms overlay.

8.

Edit the file to remove the last two lines of code you added at the end of the file (the ones containing the findresource and showpage commands).

Two sample forms overlay definitions are included with PrintKit:

PRINTKIT_GRAYBAR.PS	graybar form
PRINTKIT_RULE.PS	ruled form

The definitions are stored as modules in the SYS$LIBRARY:PRINTKIT_PS.TLB Device Control Library. Also, reference copies are in the PrintKit examples directory, SYS$SYSROOT:[SYSHLP.EXAMPLES.PRINTKIT].

Both forms are hand-coded PostScript. They are set up to match the default ANSI-PPL3 portrait page layout and line spacing for letter size paper. You can use them unchanged, or as the starting point for forms of your own design. The form dimensions – number of lines and columns, line and column spacing, and so forth – are all parameterized.

If you have a basic understanding of PostScript syntax, it is straightforward to modify the forms for different page layouts. If you are not familiar with PostScript, either locate someone who can help, or create the forms you need using a graphics application, as discussed above.

PrintKit and Forms Overlays provides an overview of forms overlay handling in PrintKit. It also discusses the various ways of creating Form resources and provides links to software tools that can help automate the process.

The PrintKit User Guide describes medium specifications and forms overlay requirements. It also includes concise descriptions of the KITCP commands used to manage queue, document and medium specifications.

The PostScript Language Reference Manual, Second Edition, Adobe Systems Incorporated, provides a complete description of the Encapsulated PostScript File Format. This information is also available in the Encapsulated PostScript File Format Specification, available from the Adobe web site.