PS/PDF API Change Proposal: (Re: [cairo] Semantics of transparent objects)

[Michael Sweet]

Carl Worth wrote:
> On Mon, 01 May 2006 20:31:32 -0400, Michael Sweet wrote:
>> For the purposes of the kind of comments you want to support, you'll
>> want to support the header, DocumentSetup, and PageSetup sections:
> 
> Thanks again! As always, your insight into PostScript is invaluable.
> 
> Just a couple of quick questions on your example output:
> 
>>      %%BeginSetup                                   % B (end)
>>      ... DocumentSetup comments ...
>>      %%BeginFeature: *PageSize name
>>      <</PageSize[width height]>>setpagedevice       % initial size
>>      %%EndFeature: *PageSize
>>      %%EndSetup
>>      %%Page: (1) 1                                  % C - page start
>>      %%BeginPageSetup                               % C (end)
>>      ... PageSetup comments ...
>>      %%PageBoundingBox: 0 0 width height            % D - drawing start
>>      %%BeginFeature: *PageSize name
>>      <</PageSize[width height]>>setpagedevice       % per-page size
>>      %%EndFeature: *PageSize
>>      %%EndPageSetup
> 
> 1. Is the BeginFeature stuff a comment that the user of the cairo API
>    will need to provide support for? Or are you just showing what the
>    eventual output will look like after processing of an
>    IncludeFeature comment?

That's just an example of the stuff that Cairo would add around the
document-level comments, along with the initial size of the surface.

>    More specifically, I was not planning on cairo ever having enough
>    information. And I was planning on having the API for emitting a
>    DSC comment accept only the portion after the "%%" so that cairo
>    would generate the "%%" symbols.
> 
>    If I do that, then the DSC comment API would not be able to
>    generate PostScript code as is needed between BeginFeature and
>    EndFeature above. Does that seem like a problem?

IMHO, you don't need to support insertion of feature code; there
may be applications that want to do that, but *most* applications
don't need it and the high-end apps needing to do custom PS stuff
probably won't use Cairo to do it...

That said, I would not add the %% to the comment automatically for
the user - some common comments are not defined by the DSC but are
well-recognized (like Adobe's %ADO comments).  Technically this
could also mean that applications could insert actual code - I'd
warn developers not to do this (things can break in unexpected ways,
etc...)

> 2. Is the ordering of something like PageBoundingBox in the example
>    above significant? For example, could it come first, before any of
>    the user's DSC comments? Also, cairo is setting up a per-page
>    transformation within the PageSetup section, (which seems to be the
>    recommended place for that according to the DSC stuff). Would the
>    order of that transformation code relative to PageBoundingBox and
>    other DSC comments be significant? If so, where should it go?
>    Or should I move that transformation out of page setup and into the
>    page drawing commands?

The order of the comments themselves is not important, however you
*do* need to put all of the comments before your page transform
code because the feature stuff will often reset the graphics
state and CUPS stops processing IncludeFeature and PageBoundingBox
once it finds unbounded PostScript code (i.e. code that isn't inside
a Begin/EndFeature block).  The main reason for this is we need to
insert our imposition/rotation/scaling code before any page-level
transforms for things to work...

> 3. Your example doesn't show it, but I've got a question about the %%+
>    line continuation syntax. I was planning on making cairo provide
>    the necessary line-wrapping, and automatically generate %%+ as
>    needed. Does it provide for breaking a line at any position or must
>    it be at a whitespace location?

It must be a whitespace location, but continuation lines are only
generally used for listing resources (fonts, etc.)  I don't believe
they are allowed for Begin/EndFeaturem, IncludeFeature, or
PageBoundingBox.

The only examples of the continuation comment are for DocumentMedia,
DocumentNeededResources, DocumentSuppliedResources, and PageResources.
Each of them is basically line-oriented, and the resource comments
use a keyword for the resource type.

>    Are there any practical cases where a useful value might have no
>    space for 255 character (seems quite likely). Or is there any
>    possible structure of a DSC value that could be broken by doing the
>    line breaking at the "wrong" spot?

CUPS will only read lines up to 255 characters; the next N characters
for the line are basically read as a separate line, but we don't add
newlines.

Right now, CUPS does nothing with resources or media definitions.
In the future we will and will support the continuation comment...

For listing of resources and media declarations, it would be highly
unlikely to have line longer than 255 characters.  If you do, just
truncate (or omit) the comment.  I recommend listing each resource
or media definition on its own line for simplicity.

>    If so, it'd be easy enough for me to just not do any wrapping in
>    cairo and make the user worry about it. But if I can do it reliably
>    it seems I might as well provide that convenience.

Given the uses of the continuation comment, I'd only support it for
the stuff you write.

>> So, if you provide 1 function for comments:
>>
>>      cairo_ps_surface_emit_dsc_comment(cairo_surface_t *surface, const 
>> char *comment);
>>
>> and two "start" functions:
>>
>>      cairo_ps_surface_start_document(cairo_surface_t *surface);
>>      cairo_ps_surface_start_page(cairo_surface_t *surface);
> 
> That looks pretty good. I think I'll tweak the names slightly to
> provide better association between them (and to the DSC structure
> itself). I'm thinking:
> 
> 	cairo_public void
> 	cairo_ps_surface_dsc_comment (cairo_surface_t   *surface,
> 	                              const char        *comment);
> 
> 	cairo_public_void
> 	cairo_ps_surface_dsc_begin_setup (cairo_surface_t *surface);
> 
> 	cairo_public_void
> 	cairo_ps_surface_dsc_begin_page_setup (cairo_surface_t *surface);
> 
> I'll also explicitly document that the begin_page_setup call is only
> necessary on the first page. After that, we already have a
> cairo_show_page function to mark each page boundary, and by then there
> is no ambiguity about what dsc_comment should do, (as there's no
> useful place for a comment other than within the PageSetup section).

Sounds good!

> Do let me know if it looks like I'm still missing anything. And I'll
> be providing a patch with an implementation of all this quite shortly.

No, I think you have it all covered!

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