[cups.general] How does "stopped cleartomark" work?

[Michael Sweet]

Johannes Meixner wrote:
> Hello,
> 
> CUPS' pstops filter (form CUPS version 1.1.23) adds printer
> specific features like
> --------------------------------------------------------------
> [{
> %%BeginFeature: *PageSize A4
> <</PageSize[595 842]/ImagingBBox null>>setpagedevice
> %%EndFeature
> } stopped cleartomark
> --------------------------------------------------------------
> 
> I do not understand how "[ {...} stopped cleartomark" works.
> 
> Acording to the Adobe PostScript Language Reference (3. edition)
> "stopped" leaves "false" on the stack if {...} returns noramlly
> and "true" otherwise but regardless of the outcome
> "cleartomark" is executed in any case.
> 
> I am missing the "if" as in Adobe's example for "stopped":
> "{...} stopped {handleerror} if"
> 
> Why is there no "if" or why is there "stopped" when nothing
> depends on its outcome?

It is mainly there to prevent the printer from aborting the job.
Basically, code run via the "stopped" operator can be undone, so
you can (for example) roll back any setpagedevice commands if they
did not work.

We *could* actually use the results to display an error page or
provide feedback to the error_log file (for non-PS printers,
anyways), but right now we just ignore the return value via the
cleartomark operator...

Similarly, we could use:

     {
     %%BeginFeature: *Foo bar
     ... some commands ...
     %%EndFeature
     } stopped pop

However, if the feature code put more values on the stack, then
we would leave things in an inconsistent state.  So, the "[" marks
the beginning the of stack for the feature command and the
"cleartomark" clears everything off the stack to that mark.
(code that adds a mark on the stack can still cause problems, but
there isn't any way to protect against that...)

-- 
______________________________________________________________________
Michael Sweet, Easy Software Products           mike at easysw dot com
Internet Printing and Document Software          http://www.easysw.com