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

[Michael Sweet]

Carl Worth wrote:
> ...
> Obviously, there _are_ a lot of printing-specific options, settings,
> and metadata that users will need to provide. And the point has been
> made above that these need to be available on a per-page basis.
> 
> I'm wondering if we can't just use cairo_t for these, and specify that
> the time to set them is before any drawing operation on any given
> page. That is, just after cairo_create or cairo_show_page, and before
> any of cairo_stroke, cairo_fill, cairo_paint, cairo_mask,
> cairo_show_text/glyphs on that page.

That would work.  IMHO, the only "required" per-page attributes are
the media attributes: media color (the color of the paper, not whether
the output is in color), page size, media source, media type, and
media weight.

Most other attributes are used at the document level (resolution, 
duplexing, stapling, folding), and things like "color model" can
be assigned automatically from the page contents, e.g. app/user sets
the color model to grayscale, color, photo, or auto.

> A few of us (and likely a group missing some printing experts) started
> talking about what this new options-setting API would look like at the
> GNOME summit. The strawman we came up with is here, and might make a
> good starting point for further discussion:
> 
> 	http://live.gnome.org/GtkTeamPrintingBreakout
> 	(See the "Cairo's printing API" section)
> 
> It's clearly not complete, but the question is whether this is a
> workable-basis for extending to something complete.

I would recommend using a keyword/enumeration-based API rather than
a different function for each property.  To support both numeric and
string properties, consider the OpenGL way:

     cairo_document_properties_set_integer(cdp_t *props, cdpk_t key, int 
val);
     cairo_document_properties_set_real(cdp_t *props, cdpk_t key, double 
val);
     cairo_document_properties_set_string(cdp_t *props, cdpk_t key, 
const char *val);

     (cdp_t == cairo_document_properties_t)
     (cdpk_t == cairo_document_properties_keyword_t)

Do *not* use an enumeration for paper sizes (!) - you will be
repeating the mistakes of WIN32/GDI and MacOS/QuickDraw.  Instead,
use strings based on the Printer Working Group's work (which is also
used for CUPS and PAPI, BTW) - there are standard names, and all
custom size names are self-describing, i.e. you get the width and
length of the page from the name.

Also, most PDF properties are applicable to PS output as well...

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