(v13) Tips for using the page device

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.

• Inheriting values in the page device: grestore, restore, and the like restores the properties of the page device to what they were at the corresponding gsave, save, and so on. However, remember that when simply changing from one page device to another explicitly, all the properties except the ones you are setting are carried over to the new page device.

This is obvious in an example such as:

            currentpagedevice /MediaColor get == % gives null
            << /MediaColor (Blue) >> setpagedevice currentpagedevice /MediaColor get == % gives (Blue)
            << /MediaWeight 80 >> setpagedevice
            currentpagedevice /MediaColor get == % still gives(Blue) gsave
            << /MediaColor (Green) >> setpagedevice currentpagedevice /MediaColor get == % gives (Green) grestore
            currentpagedevice /MediaColor get == % gives (Blue)

but it might be forgotten when executing outside the server loop context. This can occur in jobs which use exitserver or startjob operators or, for core-RIP developers, when setting up for a job from the %config% device (which can be avoided by using setrealdevice see (v13) The setrealdevice operator). Outside the server loop’s save/restore context, one job inherits the previous job’s properties unless a specific alternative is given. Setting a key to null, in nearly all cases, restores the default.

• Efficiency: because setpagedevice is a complex operator, its use is fairly expensive. It executes all three stages every time even for the simplest operands. Therefore it is wise to collect together as many of the properties as you can at one time and make one call to setpagedevice rather than many consecutive ones. For example, where possible, use:

<< /PageSize [1200 1200] /Margins [10 10] >> setpagedevice

rather than:

            << /PageSize [1200 1200] >> setpagedevice
            << /Margins [10 10] >> setpagedevice

• Initialization effects: As mentioned above, setpagedevice completely initializes a new page device. Therefore there is no point in doing graphics between calls to setpagedevice unless there is also a showpage. For example, the following is not useful (only “play on!” would appear on the page):

            << ... >> setpagedevice
            100 100 moveto (If music be) show gsave
            ...
            << ... >> setpagedevice
            100 200 moveto (the food of love,) show grestore
            100 300 moveto (play on!) show showpage

It is both activation by an explicit call of setpagedevice, and implicit reactivation by restore and grestore that erases the raster.

• Policies for unknown keys: The philosophy of setpagedevice is to ignore keys that it does not understand, so that a job can do the best it can on a range of systems. This does mean that you have to be careful with spelling, especially regarding case sensitivity. You can make the page device produce an error when an unrecognized key is encountered, by setting a default entry in the Policies dictionary; while this may be useful for debugging, we do not recommend it in a released product.
• Level 1 compatibility: Level 1 PostScript-language jobs makes use of the page device and the setpagedevice operator implicitly. The mixture of operators and procedures in statusdict and userdict such as setpageparams, letter, a4tray, setexposure, and so on, are all now special cases of the setpagedevice operator and are coded as such see (v13) Level 1 compatibility operators.
• Powerful techniques: The page device offers some powerful techniques to modify and control incoming jobs, especially through the BeginPage, EndPage, and Install procedures. More detail is available elsewhere in this content.