(v13) Positioning and printing pages using BeginPage and EndPage

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

BeginPage is used to transform each page in the job into its correct position on the output page. These transformations are completely general—there is no need for the pages to be positioned on a grid— binding margins can be calculated and pages can even be rotated. BeginPage can also be used to put additional marks on the page—see (v13) Adding to the page.

At the time BeginPage is called, the graphics state has been re-initialized so that the coordinate system is that of the output page, and more significantly, the clipping is set up to enclose the whole of the output page. Therefore, the BeginPage procedure must also clip to the individual page of the job in its position on the page; otherwise, marks which were not intended to be visible in the original job may appear on the output.

EndPage is then used to determine when the output page is full of input pages. EndPage returns a Boolean to say whether the page should be printed or not; its main purpose here is to calculate that value. It must also decide what to do at the end of the job when there may or may not be some remaining pages left over. EndPage is called at device deactivation (that is, loosely speaking, when a second setpagedevice operator is called, or more likely when restore reinstates a previous page device as illustrated in the following sequence).

            save
            <<...>> setpagedevice % (1), deactivates previous page device
                        % calling EndPage and BeginPage
            ...
            <<...>> setpagedevice % (2), deactivates (1) (calling EndPage
                        % and BeginPage) but no pages yet
            ...
            <<...>> setpagedevice % (3), deactivates (2) (calling EndPage
                        % and BeginPage) but no pages yet
            ...
            showpage % calls EndPage and BeginPage
            ...
            restore % deactivates (3), calling EndPage which can emit the
                    % remaining pages

The restore may be implicit in the server loop or may be in the job itself. This mechanism is described in more detail in [RB2] (section 4.11).

EndPage could also add marks to the output, but would be limited to the clipping set up for the page in the previous BeginPage, which may have been restricted further by the job. This would require a call to the initclip operator to work round.

Nevertheless, EndPage is a better place—to avoid extra pages with just the additional marks if AutoShowpage is true.