The Postscript Page Description Language

showpage

The showpage command transmits the contents of the current page to the current output device, causing any marks painted on the page to be rendered on the output medium. showpage then erases the current page and reinitializes the graphics state in preparation for composing the next page.

The main actions of showpage are as follows:

1. Executes the EndPage procedure in the page device dictionary, passing an integer page count on the operand stack along with a reason code indicating that the procedure was called from showpage;

2. If the boolean result returned by the EndPage procedure is true, transmits the page’s contents to the current output device and performs the equivalent of an erasepage operation, clearing the contents of raster memory in preparation for the next page. If the EndPage procedure returns false, showpage skips this step.

3. Performs the equivalent of an initgraphics operation, reinitializing the graphics state for the next page.

4. Executes the BeginPage procedure in the page device dictionary, passing an integer page count on the operand stack.

If the BeginPage or EndPage procedure invokes showpage, an undefined error occurs.

BeginPage procedure

An optional, user defined procedure to be executed at the beginning of each page. Before calling the procedure, the interpreter initializes the graphics state, erases the current page if appropriate, and pushes an integer on the operand stack indicating how many times showpage has been invoked since the current device was activated.

EndPage procedure

An optional, user defined procedure to be executed at the end of each page. Before calling the procedure, the interpreter pushes two integers on the operand stack—a count of previous showpage executions for this device and a reason code indicating the circumstances under which this call is being made:

• 0=During showpage or (LanguageLevel 3) copypage
• 1=During copypage (LanguageLevel 2 only)
• 2=At device deactivation

The EndPage procedure is expected to consume these operands. The procedure is permitted to alter the graphics state and to paint marks on the current page; such marks are added to the page just completed.

The procedure must return a boolean value specifying whether to transmit the page image to the physical output device.

Note: The use of BeginPage and EndPage to achieve effects spanning multiple pages sacrifices any page independence the document may have. In general, a page description should not include definitions of BeginPage or EndPage in its invocations of setpagedevice. Instead, a software print manager should prepend such commands to the page description when printing is requested.

With suitable definitions, these procedures can:

• Cause multiple virtual pages within a document to be printed on a single physical page (“2-up” or “n-up” printing)
• Shift the positions of even- and odd-page images differently for binding
• Add marks to each page that either underlie or overprint the material provided by the page description

Redefining showpage

As shown by Don Lancaster^ at:
http://www.tinaja.com/psutils/divertsp.psl you can do things to existing PS documents or print jobs by injecting a bit of code that redefines the showpage command to include things you want done to each page. This simple example could probably be better accomplished by changing the EndPage procedure assuming PS2 is being used.

 true setglobal                                               % persist on save/restores
 globaldict begin
/sysshowpage {systemdict /showpage get exec} def

/showpage {						% redefine custom showpage  
% do whatever you want here, e.g. draw a form image (execform) over the printed data from the app.
	sysshowpage					% do the real showpage  
	} def 
 end							% cease persistent
 false setglobal

Comments: