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

[Carl Worth]

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?

   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?

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?

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?

   The syntax of the %% options appears to necessitate a space after
   the + to separate the DSC option name from its value. And the
   examples I can see of %%+ appear to also be expecting a space
   between the two lines, so I'm guessing that this line-breaking must
   happen at a space.

   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?

   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.

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

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.

Thanks,

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060502/9976f908/attachment-0001.pgp