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

[Michael Sweet]

Carl Worth wrote:
> ...
> One suggestion Keith made to me this weekend is to change the above
> set_document_feature and set_page_feature to something like:
> 
> void
> cairo_ps_surface_emit_dsc_document_comment (cairo_surface_t *surface,
> 					    const char	    *comment);
> 
> void
> cairo_ps_surface_emit_dsc_page_comment (cairo_surface_t *surface,
> 					const char	*comment);
> 
> The suggestion seems appealing since it is no more complicated in
> terms of API, but it is definitely less restrictive.
 >
> But as I looked into actually doing this, the problem becomes that
> there are more than just two classes of DSC comments. Maybe replacing
> {document,page} with {header,body,page} would be sufficient? Or maybe
> there would be more classes needed. Would a user care about putting
> something into the defaults section for example? If so is that another
> class? Or would we allow the user to create a defaults section through
> dsc_body_comments.

For the purposes of the kind of comments you want to support, you'll
want to support the header, DocumentSetup, and PageSetup sections:

     %!PS-Adobe-3.0
     %%BoundingBox: (atend)
     %%Pages: (atend)
     ... other Cairo-generated DSC comments ...     % A - surface created
     ... header comments ...
     %%EndComments                                  % B - document start
     %%BeginProlog
     ... Cairo-defined procedures ...
     %%EndProlog
     %%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
     gsave
     ... Cairo drawing commands ...
     grestore showpage
     %%Page: (2) 2                                  % 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
     gsave
     ... Cairo drawing commands ...
     grestore showpage
     ...
     %%Page: (N) N                                 % C - page start
     %%BeginPageSetup
     ... PageSetup comments ...
     %%PageBoundingBox: 0 0 width height           % D - drawing start
     %%BeginFeature: *PageSize name
     <</PageSize[width height]>>setpagedevice      % per-page size
     %%EndFeature: *PageSize
     %%EndPageSetup
     gsave
     ... Cairo drawing commands ...
     grestore showpage
     %%Trailer                                     % Close surface
     %%BoundingBox: 0 0 max-width max-height
     %%Pages: N
     %%EOF

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);

then you can properly support them all.  Creating the PS surface
will emit everything up to line A.  emit_dsc_comment will add
to the header section until start_document or start_page is called.
Once start_document is called, emit_dsc_comment will add to the
DocumentSetup section until start_page is called. After start_page
is called, emit_dsc_comment will add to the PageSetup section
until something is drawn, at which point emit_dsc_comment is
ignored until the next start_page call.

If start_document is not called before start_page, then start_page
will call start_document.

 > ...
> [*] There are also other DSC comments such as %%Copyright, %%Title,
> and %%Version that will definitely be interesting to a user. But for
> the reasons explained in a recent mail, I'm explicitly not worrying
> about these for now. They're not as important for the task of getting
> the right ink on the page, (which is the priority for 1.2), and I'd
> really like to come up with a backend-independent means of setting
> this kind of metadata since it can be useful for PS, PDF, and PNG
> output.

The changes I mentioned will allow applications to support these
comments immediately, at least for PS output...

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