]> git.ipfire.org Git - thirdparty/cups.git/blame - doc/help/spec-ppd.html
projects / thirdparty / cups.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge changes from CUPS 1.5svn-r9407.
[thirdparty/cups.git] / doc / help / spec-ppd.html
CommitLineData
745129be 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
ef416fc2 2<html>
4744bd90 3<!-- SECTION: Specifications -->
ef416fc2 4<head>
10d09e33
MS		 5<title>CUPS PPD Extensions</title>
6<meta name="keywords" content="Specifications">
c779abb0 7<meta name="creator" content="Mini-XML v2.7">
10d09e33
MS		 8<style type="text/css"><!--
9BODY {
10 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
11}
12
13H1, H2, H3, H4, H5, H6, P, TD, TH {
14 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
15}
16
17KBD {
18 font-family: monaco, courier, monospace;
19 font-weight: bold;
20}
21
22PRE {
23 font-family: monaco, courier, monospace;
24}
25
26PRE.command {
27 border: dotted thin #7f7f7f;
28 margin-left: 36pt;
29 padding: 10px;
30}
31
32P.compact {
33 margin: 0;
34}
35
36P.example {
37 font-style: italic;
38 margin-left: 36pt;
39}
40
41PRE.example {
42 background: #eeeeee;
43 border: dotted thin #999999;
44 margin-left: 36pt;
45 padding: 10pt;
46}
47
48PRE.command EM, PRE.example EM {
49 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
50}
51
52P.command {
53 font-family: monaco, courier, monospace;
54 margin-left: 36pt;
55}
56
57P.formula {
58 font-style: italic;
59 margin-left: 36pt;
60}
61
62BLOCKQUOTE {
63 background: #eeeeee;
64 border: solid thin #999999;
65 padding: 10pt;
66}
67
68A IMG {
69 border: none;
70}
71
72A:link:hover IMG {
73 background: #f0f0f0;
74 border-radius: 10px;
75 -moz-border-radius: 10px;
76}
77
78A:link, A:visited {
79 font-weight: normal;
80 text-decoration: none;
81}
82
83A:link:hover, A:visited:hover, A:active {
84 text-decoration: underline;
85}
86
87SUB, SUP {
88 font-size: 50%;
89}
90
91TR.data, TD.data, TR.data TD {
92 margin-top: 10pt;
93 padding: 5pt;
94 border-bottom: solid 1pt #999999;
95}
96
97TR.data TH {
98 border-bottom: solid 1pt #999999;
99 padding-top: 10pt;
100 padding-left: 5pt;
101 text-align: left;
102}
103
104DIV.table TABLE {
105 border: solid thin #999999;
106 border-collapse: collapse;
107 border-spacing: 0;
108 margin-left: auto;
109 margin-right: auto;
110}
111
112DIV.table CAPTION {
113 caption-side: top;
114 font-size: 120%;
115 font-style: italic;
116 font-weight: bold;
117 margin-left: auto;
118 margin-right: auto;
119}
120
121DIV.table TABLE TD {
122 border: solid thin #cccccc;
123 padding-top: 5pt;
124}
125
126DIV.table TABLE TH {
127 background: #cccccc;
128 border: none;
129 border-bottom: solid thin #999999;
130}
131
132DIV.figure TABLE {
133 margin-left: auto;
134 margin-right: auto;
135}
136
137DIV.figure CAPTION {
138 caption-side: bottom;
139 font-size: 120%;
140 font-style: italic;
141 font-weight: bold;
142 margin-left: auto;
143 margin-right: auto;
144}
145
146TH.label {
147 text-align: right;
148 vertical-align: top;
149}
150
151TH.sublabel {
152 text-align: right;
153 font-weight: normal;
154}
155
156HR {
157 border: solid thin;
158}
159
160SPAN.info {
161 background: black;
162 border: thin solid black;
163 color: white;
164 font-size: 80%;
165 font-style: italic;
166 font-weight: bold;
167 white-space: nowrap;
168}
169
170H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
171 float: right;
172 font-size: 100%;
173}
174
175H1.title {
176}
177
178H2.title, H3.title {
179 border-bottom: solid 2pt #000000;
180}
181
182DIV.indent, TABLE.indent {
183 margin-top: 2em;
184 margin-left: auto;
185 margin-right: auto;
186 width: 90%;
187}
188
189TABLE.indent {
190 border-collapse: collapse;
191}
192
193TABLE.indent TD, TABLE.indent TH {
194 padding: 0;
195}
196
197TABLE.list {
198 border-collapse: collapse;
199 margin-left: auto;
200 margin-right: auto;
201 width: 90%;
202}
203
204TABLE.list TH {
205 background: white;
206 border-bottom: solid thin #cccccc;
207 color: #444444;
208 padding-top: 10pt;
209 padding-left: 5pt;
210 text-align: left;
211 vertical-align: bottom;
212 white-space: nowrap;
213}
214
215TABLE.list TH A {
216 color: #4444cc;
217}
218
219TABLE.list TD {
220 border-bottom: solid thin #eeeeee;
221 padding-top: 5pt;
222 padding-left: 5pt;
223}
224
225TABLE.list TR:nth-child(even) {
226 background: #f8f8f8;
227}
228
229TABLE.list TR:nth-child(odd) {
230 background: #f4f4f4;
231}
232
233DT {
234 margin-left: 36pt;
235 margin-top: 12pt;
236}
237
238DD {
239 margin-left: 54pt;
240}
241
242DL.category DT {
243 font-weight: bold;
244}
245
246P.summary {
247 margin-left: 36pt;
248 font-family: monaco, courier, monospace;
249}
250
251DIV.summary TABLE {
252 border: solid thin #999999;
253 border-collapse: collapse;
254 border-spacing: 0;
255 margin: 10px;
256}
257
258DIV.summary TABLE TD, DIV.summary TABLE TH {
259 border: solid thin #999999;
260 padding: 5px;
261 text-align: left;
262 vertical-align: top;
263}
264
265DIV.summary TABLE THEAD TH {
266 background: #eeeeee;
267}
268
269/* API documentation styles... */
270div.body h1 {
271 margin: 0;
272}
273div.body h2 {
274 margin-top: 1.5em;
275}
276div.body h3, div.body h4, div.body h5 {
277 margin-bottom: 0.5em;
278 margin-top: 1.5em;
279}
280.class, .enumeration, .function, .struct, .typedef, .union {
281 border-bottom: solid thin #999999;
282 margin-bottom: 0;
283 margin-top: 2em;
284}
285.description {
286 margin-top: 0.5em;
287}
288code, p.code, pre, ul.code li {
289 font-family: monaco, courier, monospace;
290 font-size: 90%;
291}
292ul.code, ul.contents, ul.subcontents {
293 list-style-type: none;
294 margin: 0;
295 padding-left: 0;
296}
297ul.code li {
298 margin: 0;
299}
300ul.contents > li {
301 margin-top: 1em;
302}
303ul.contents li ul.code, ul.contents li ul.subcontents {
304 padding-left: 2em;
305}
306div.body dl {
307 margin-left: 0;
308 margin-top: 0;
309}
310div.body dt {
311 font-style: italic;
312 margin-left: 0;
313 margin-top: 0;
314}
315div.body dd {
316 margin-bottom: 0.5em;
317}
318
319/* This is just for the HTML files generated with the framedhelp target */
320div.contents {
321 background: #e8e8e8;
322 border: solid thin black;
323 padding: 10px;
324}
325div.contents h1 {
326 font-size: 110%;
327}
328div.contents h2 {
329 font-size: 100%;
330}
331div.contents ul.contents {
332 font-size: 80%;
333}
334div.contents ul.subcontents li {
335 margin-left: 1em;
336 text-indent: -1em;
337}
338--></style>
ef416fc2 339</head>
340<body>
10d09e33 341<div class='body'>
ef416fc2 342<!--
10d09e33 343 "$Id: spec-ppd.html 9345 2010-10-26 23:46:51Z mike $"
ef416fc2 344
10d09e33 345 PPD extension documentation for CUPS.
ef416fc2 346
c7017ecc 347 Copyright 2007-2010 by Apple Inc.
f7deaa1a 348 Copyright 1997-2007 by Easy Software Products.
ef416fc2 349
350 These coded instructions, statements, and computer programs are the
db1f069b
MS		 351 property of Apple Inc. and are protected by Federal copyright
352 law. Distribution and use rights are outlined in the file "LICENSE.txt"
353 which should have been included with this file. If this file is
354 file is missing or damaged, see the license at "http://www.cups.org/".
ef416fc2 355-->
356
178cb736
MS		 357<H1 CLASS="title">CUPS PPD Extensions</H1>
358
10d09e33 359<p>This specification describes the attributes and extensions that CUPS adds to <a href="http://partners.adobe.com/public/developer/en/ps/5003.PPD_Spec_v4.3.pdf" target="_blank">Adobe TechNote #5003: PostScript Printer Description File Format Specification Version 4.3</a>. PostScript Printer Description ("PPD") files describe the capabilities of each printer and are used by CUPS to support printer-specific features and intelligent filtering.</p>
ef416fc2 360
10d09e33
MS		 361<div class='summary'><table summary='General Information'>
362<tbody>
363<tr>
364 <th>See Also</th>
365 <td>Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br>
366 Programming: <a href='raster-driver.html'>Developing Raster Printer Drivers</a><br>
367 Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
368 Programming: <a href='ppd-compiler.html'>Introduction to the PPD Compiler</a><br>
369 Programming: <a href='api-raster.html'>Raster API</a><br>
370 References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a></td>
371</tr>
372</tbody>
373</table></div>
374<h2 class="title">Contents</h2>
375<ul class="contents">
376<ul class="subcontents">
377<li><a href="#SYNTAX">PPD File Syntax</a></li>
378<li><a href="#AUTOCONFIG">Auto-Configuration</a><ul class="subcontents">
379<li><a href="#APAutoSetupTool">APAutoSetupTool</a></li>
380<li><a href="#QUERYKEYWORD">?MainKeyword</a></li>
381<li><a href="#OID">OIDMainKeyword</a></li>
382</ul></li>
383<li><a href="#PROFILES">Color Profiles</a><ul class="subcontents">
384<li><a href="#cupsColorProfile">cupsColorProfile</a></li>
385<li><a href="#cupsICCProfile">cupsICCProfile</a></li>
386<li><a href="#APCustom">Custom Color Matching Support</a></li>
387</ul></li>
388<li><a href="#CONSTRAINTS">Constraints</a><ul class="subcontents">
389<li><a href="#cupsUIConstraints">cupsUIConstraints</a></li>
390<li><a href="#cupsUIResolver">cupsUIResolver</a></li>
391</ul></li>
392<li><a href="#I18N">Globalized PPD Support</a></li>
393<li><a href="#OPTIONS">CUPS 1.3/Mac OS X 10.6Custom Options</a></li>
394<li><a href="#RASTERPS">Writing PostScript Option Commands for Raster Drivers</a></li>
395<li><a href="#MEDIA">Media Keywords</a><ul class="subcontents">
396<li><a href="#cupsMediaQualifier2">cupsMediaQualifier2</a></li>
397<li><a href="#cupsMediaQualifier3">cupsMediaQualifier3</a></li>
398<li><a href="#cupsMinSize">cupsMinSize</a></li>
399<li><a href="#cupsMaxSize">cupsMaxSize</a></li>
400</ul></li>
401<li><a href="#ATTRIBUTES">General Attributes</a><ul class="subcontents">
402<li><a href="#cupsBackSide">cupsBackSide</a></li>
403<li><a href="#cupsCommands">cupsCommands</a></li>
404<li><a href="#cupsEvenDuplex">cupsEvenDuplex</a></li>
405<li><a href="#cupsFax">cupsFax</a></li>
406<li><a href="#cupsFilter">cupsFilter</a></li>
407<li><a href="#cupsFlipDuplex">cupsFlipDuplex</a></li>
408<li><a href="#cupsIPPFinishings">cupsIPPFinishings</a></li>
409<li><a href="#cupsIPPReason">cupsIPPReason</a></li>
410<li><a href="#cupsLanguages">cupsLanguages</a></li>
411<li><a href="#cupsManualCopies">cupsManualCopies</a></li>
412<li><a href="#cupsMarkerName">cupsMarkerName</a></li>
413<li><a href="#cupsMarkerNotice">cupsMarkerNotice</a></li>
414<li><a href="#cupsModelNumber">cupsModelNumber</a></li>
415<li><a href="#cupsPJLCharset">cupsPJLCharset</a></li>
416<li><a href="#cupsPJLDisplay">cupsPJLDisplay</a></li>
417<li><a href="#cupsPortMonitor">cupsPortMonitor</a></li>
418<li><a href="#cupsPreFilter">cupsPreFilter</a></li>
419<li><a href="#cupsPrintQuality">cupsPrintQuality</a></li>
420<li><a href="#cupsSNMPSupplies">cupsSNMPSupplies</a></li>
421<li><a href="#cupsVersion">cupsVersion</a></li>
422</ul></li>
423<li><a href="#MACOSX">Mac OS X Attributes</a><ul class="subcontents">
424<li><a href="#APDialogExtension">APDialogExtension</a></li>
425<li><a href="#APDuplexRequiresFlippedMargin">APDuplexRequiresFlippedMargin</a></li>
426<li><a href="#APHelpBook">APHelpBook</a></li>
427<li><a href="#APICADriver">APICADriver</a></li>
428<li><a href="#APPrinterIconPath">APPrinterIconPath</a></li>
429<li><a href="#APPrinterLowInkTool">APPrinterLowInkTool</a></li>
430<li><a href="#APPrinterPreset">APPrinterPreset</a></li>
431<li><a href="#APPrinterUtilityPath">APPrinterUtilityPath</a></li>
432<li><a href="#APScannerOnly">APScannerOnly</a></li>
433<li><a href="#APScanAppBundleID">APScanAppBundleID</a></li>
434</ul></li>
435<li><a href="#HISTORY">Change History</a></li>
ef416fc2 436<h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2>
437
10d09e33 438<p>The PPD format is text-based and uses lines of up to 255 characters terminated by a carriage return, linefeed, or combination of carriage return and line feed. The following ABNF definition [<a href="http://tools.ietf.org/html/rfc5234" target="_blank">RFC5234</a>] defines the general format of lines in a PPD file:</p>
ef416fc2 439
440<pre class='command'>
441PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
442
dd1abb6b
MS		 443HEADER = "*PPD-Adobe:" *WSP DQUOTE VERSION DQUOTE LINE-END
444
445VERSION = "4.0" / "4.1" / "4.2" / "4.3"
ef416fc2 446
447COMMENT = "*%" *TCHAR LINE-END
448
449DATA = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
450 1*(*WSP VALUE) LINE-END
451
452VALUE = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE
453
454KCHAR = ALPHA / DIGIT / "_" / "." / "-"
455
b19ccc9e 456SCHAR = LINE-END / WSP / %x21.23-7E.A0-FF
ef416fc2 457
b19ccc9e 458TCHAR = %x20-7E.A0-FF
ef416fc2 459
460LINE-END = CR / LF / CR LF
461</pre>
462
463
db1f069b 464<h2 class='title'><a name='AUTOCONFIG'>Auto-Configuration</a></h2>
ef416fc2 465
10d09e33 466<p>CUPS supports several methods of auto-configuration via PPD keywords.</p>
4744bd90 467
10d09e33 468<h3><span class='info'>Deprecated</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3>
4744bd90 469
db1f069b 470<p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</p>
4744bd90 471
10d09e33 472<p>This deprecated keyword defines a program that sets the default option choices. It is run when a printer is added from the <var>Add Printer</var> window or the <var>Nearby Printers</var> list in the <var>Print</var> dialog.</p>
db1f069b 473
10d09e33
MS		 474<p>The program is provided with two arguments: the printer's device URI and the PPD file to be used for the printer. The program must write an updated PPD file to stdout.</p>
475
476<blockquote><b>Note:</b>
db1f069b 477
10d09e33
MS		 478<p>This keyword is deprecated. New printer drivers SHOULD provide a CUPS command filter and support the "AutoConfigure" command. Alternately, drivers MAY use the <a href="#OID">SNMP OID</a> keywords to configure network printers or <a href="#QUERYKEYWORD">PostScript query keywords</a> to configure PostScript printers.</p>
479
480</blockquote>
db1f069b 481<p>Examples:</p>
4744bd90 482
483<pre class='command'>
db1f069b
MS		 484*% Use our setup tool when adding a printer
485*APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool"
4744bd90 486</pre>
487
10d09e33 488<h3><span class='info'>Mac OS X 10.2/CUPS 1.4</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3>
a4d04587 489
db1f069b
MS		 490<p class='summary'>*?<i>MainKeyword</i>: "<br>
491 PostScript query code that writes a message using the = operator...<br>
492"<br>
493*End</p>
a4d04587 494
10d09e33 495<p>The <tt>?<i>MainKeyword</i></tt> keyword defines PostScript code that determines the currently selected/enabled option keyword (choice) for the main keyword (option). It is typically used when communicating with USB, serial, Appletalk, and AppSocket (port 9100) printers.</p>
db1f069b 496
10d09e33 497<p>The PostScript code typically sends its response back using the <tt>=</tt> operator.</p>
ef416fc2 498
a4d04587 499<p>Example:</p>
ef416fc2 500
501<pre class='command'>
db1f069b
MS		 502*OpenUI OptionDuplex/Duplexer Installed: Boolean
503*DuplexOptionDuplex: False
504*OptionDuplex False/Not Installed: ""
505*OptionDuplex True/Installed: ""
506
507<em>*% Query the printer for the presence of the duplexer option...</em>
508*?OptionDuplex: "
509 currentpagedevice /Duplex known
510 {(True)} {(False)} ifelse
511 = flush
512"
513*End
514*CloseUI: OptionDuplex
ef416fc2 515</pre>
516
10d09e33 517<h3><span class='info'>Mac OS X 10.4/CUPS 1.5</span><a name='OID'>OIDMainKeyword</a></h3>
a4d04587 518
db1f069b
MS		 519<p class='summary'>*?OID<i>MainKeyword</i>: ".n.n.n..."<br>
520*OID<i>MainKeyword</i> <i>OptionKeyword1</i>: "value"<br>
521...<br>
522*OID<i>MainKeyword</i> <i>OptionKeywordN</i>: "value"</p>
09a101d6 523
10d09e33 524<p>The <tt>OID<i>MainKeyword</i></tt> keyword is used to define SNMP OIDs that map to installable options. The first (query) line defines the OID to lookup on the network device. The second and subsequent keywords define a mapping from OID value to option keyword. Since SNMP is an IP-based network protocol, this method is typically only used to configure AppSocket, IPP, and LPD network printers.</p>
09a101d6 525
526<p>Examples:</p>
527
528<pre class='command'>
db1f069b
MS		 529*% Get the installed memory on the printer...
530*?OIDInstalledMemory: ".1.3.6.1.2.1.25.2.2.0"
531*OIDInstalledMemory 16MB: "16384 KBytes"
532*OIDInstalledMemory 32MB: "32768 KBytes"
533*OIDInstalledMemory 48MB: "49152 KBytes"
534*OIDInstalledMemory 72MB: "73728 KBytes"
09a101d6 535</pre>
536
3d8365b8 537
db1f069b 538<h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
3d8365b8 539
10d09e33 540<p>CUPS supports three types of color profiles. The first type is based on sRGB and is used by the standard CUPS raster filters and GPL Ghostscript. The second type is based on ICC profiles and is used by the Quartz-based filters on MacOS X. The final type is based on well-known colorspaces such as sRGB and Adobe RGB.</p>
3d8365b8 541
db1f069b 542<blockquote><b>Note:</b>
3d8365b8 543
10d09e33 544<p>At this time, none of the CUPS raster filters support ICC profiles. This will be addressed as time and resources permit.</p>
bc44d920 545
db1f069b 546</blockquote>
bc44d920 547
01ce6322 548<h3><span class='info'>Deprecated</span><a name='cupsColorProfile'>cupsColorProfile</a></h3>
bc44d920 549
10d09e33 550<p class='summary'>*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
bc44d920 551
10d09e33 552<p>This string keyword specifies an sRGB-based color profile consisting of gamma and density controls and a 3x3 CMY color transform matrix. <em>This keyword is not supported on Mac OS X.</em></p>
bc44d920 553
10d09e33 554<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-" to act as a wildcard. Otherwise they must match one of the <tt>Resolution</tt> or <tt>MediaType</tt> option keywords defined in the PPD file.</p>
bc44d920 555
db1f069b
MS		 556<p>The <i>density</i> and <i>gamma</i> values define gamma and
557density adjustment function such that:</p>
bc44d920 558
559<pre class='command'>
db1f069b 560f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
bc44d920 561</pre>
562
10d09e33 563<p>The <i>m00</i> through <i>m22</i> values define a 3x3 transformation matrix for the CMY color values. The density function is applied <i>after</i> the CMY transformation:</p>
bc44d920 564
db1f069b
MS		 565<pre class='command'>
566| m00 m01 m02 |
567| m10 m11 m12 |
568| m20 m21 m22 |
569</pre>
2abf387c 570
db1f069b 571<p>Examples:</p>
2abf387c 572
db1f069b
MS		 573<pre class='command'>
574<em>*% Specify a profile for printing at 360dpi on all media types</em>
575*cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
2abf387c 576
db1f069b
MS		 577<em>*% Specify a profile for printing at 720dpi on Glossy media</em>
578*cupsColorProfile 720dpi/Glossy: "1.0 2.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
2abf387c 579
db1f069b
MS		 580<em>*% Specify a default profile for printing at all other resolutions and media types</em>
581*cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
2abf387c 582</pre>
583
01ce6322 584
10d09e33 585<h3><span class='info'>Mac OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3>
3d8365b8 586
10d09e33 587<p class='summary'>*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"</p>
3d8365b8 588
10d09e33 589<p>This keyword specifies an ICC color profile that is used to convert the document colors to the device colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and <tt>Resolution</tt> option keywords specify a selector for color profiles. If omitted, the color profile will match any option keyword for the corresponding main keyword.</p>
db1f069b 590
10d09e33 591<p>The <tt>Description</tt> specifies human-readable text that is associated with the color profile. The <tt>filename</tt> portion specifies the ICC color profile to use; if the filename is not absolute, it is loaded relative to the <var>/usr/share/cups/profiles</var> directory.</p>
3d8365b8 592
593<p>Examples:</p>
594
595<pre class='command'>
db1f069b
MS		 596<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
597*cupsICCProfile CMYK..360dpi/360dpi CMYK: "/Library/Printers/vendor/Profiles/foo-360-cmyk.icc"
3d8365b8 598
db1f069b
MS		 599<em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
600*cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "/Library/Printers/vendor/Profiles/foo-720-glossy-rgb.icc"
a4d04587 601
db1f069b
MS		 602<em>*% Specify a default profile for printing at all other resolutions and media types</em>
603*cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc"
604</pre>
a4d04587 605
db1f069b 606<h4>Customizing the Profile Selection Keywords</h4>
ef416fc2 607
10d09e33 608<p>The <tt>MediaType</tt> and <tt>Resolution</tt> main keywords can be reassigned to different main keywords, allowing drivers to do color profile selection based on different parameters. The <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> keywords define the mapping from selector to main keyword:</p>
ef416fc2 609
610<pre class='command'>
db1f069b
MS		 611*cupsICCQualifier2: MainKeyword2
612*cupsICCQualifier3: MainKeyword3
613</pre>
ef416fc2 614
db1f069b 615<p>The default mapping is as follows:</p>
ef416fc2 616
db1f069b
MS		 617<pre class='command'>
618*cupsICCQualifier2: MediaType
619*cupsICCQualifier3: Resolution
ef416fc2 620</pre>
621
db1f069b 622<h3><span class='info'>Mac OS X 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3>
ef416fc2 623
db1f069b
MS		 624<p class='summary'>*<a href='#APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a>: true<br>
625*<a href='#APCustomColorMatchingName'>APCustomColorMatchingName</a> name/text: ""<br>
626*<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br>
627*<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</p>
a4d04587 628
10d09e33 629<p>These keywords tell the Mac OS X raster filters that the printer driver provides its own custom color matching and that generic color profiles should be used when generating 1-, 3-, and 4-component raster data as requested by the driver. The <tt>APCustomColorMatchingProfile</tt> and <tt>APDefaultColorMatchingProfile</tt> keywords specify alternate color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p>
09a101d6 630
5a662dc0
MS		 631<blockquote><b>Note:</b>
632
10d09e33 633<p>Prior to Mac OS X 10.6, the default RGB color space was Apple's "GenericRGB". The new default in Mac OS X 10.6 and later is "sRGB". For more information, see <a href="http://support.apple.com/kb/HT3712">"Mac OS X v10.6: About gamma 2.2"</a> on Apple's support site.</p>
5a662dc0
MS		 634
635</blockquote>
636
db1f069b 637<h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4>
09a101d6 638
db1f069b 639<p class='summary'>*APCustomColorMatchingName name/text: ""</p>
ef416fc2 640
10d09e33 641<p>This keyword defines an alternate name for the color matching provided by a driver in the <var>Color Matching</var> print panel. The default is to use the name "Vendor Matching" or its localized equivalent.</p>
db1f069b
MS		 642
643<p>Examples:</p>
ef416fc2 644
645<pre class='command'>
db1f069b
MS		 646*% Define the names for our color matching...
647*APCustomColorMatchingName name/AcmeColor(tm): ""
648*fr.APCustomColorMatchingName name/La AcmeColor(tm): ""
ef416fc2 649</pre>
650
db1f069b 651<h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4>
bc44d920 652
db1f069b 653<p class='summary'>*APCustomColorMatchingProfile: name</p>
a4d04587 654
10d09e33 655<p>This keyword defines a supported RGB color profile that can be used when doing custom color matching. Currently only <tt>sRGB</tt>, <tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported. If not specified, RGB data will use the GenericRGB colorspace.</p>
09a101d6 656
db1f069b 657<blockquote><b>Note:</b>
09a101d6 658
10d09e33 659<p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> keywords, you are responsible for providing the necessary user interface controls to select the profile in a <a href='#APDialogExtension'>print dialog pane</a>. Add the named profile to the print settings using the key <tt>kPMCustomColorMatchingProfileKey</tt>.</p>
db1f069b
MS		 660
661</blockquote>
09a101d6 662
663<p>Examples:</p>
664
665<pre class='command'>
db1f069b
MS		 666*% Use sRGB for RGB color by default, but support both sRGB and AdobeRGB
667*APSupportsCustomColorMatching: true
668*APDefaultCustomColorMatchingProfile: sRGB
669*APCustomColorMatchingProfile: sRGB
670*APCustomColorMatchingProfile: AdobeRGB
09a101d6 671</pre>
672
db1f069b 673<h4><span class='info'>Mac OS X 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4>
4744bd90 674
db1f069b 675<p class='summary'>*APDefaultCustomColorMatchingProfile: name</p>
4744bd90 676
10d09e33 677<p>This keyword defines the default RGB color profile that will be used when doing custom color matching. Currently only <tt>sRGB</tt>, <tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported.</p>
bc44d920 678
4744bd90 679<p>Examples:</p>
680
681<pre class='command'>
db1f069b
MS		 682*% Use sRGB for RGB color by default
683*APSupportsCustomColorMatching: true
684*APDefaultCustomColorMatchingProfile: sRGB
4744bd90 685</pre>
686
db1f069b 687<h4><span class='info'>Mac OS X 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4>
a4d04587 688
db1f069b 689<p class='summary'>*APSupportsCustomColorMatching: boolean</p>
a4d04587 690
10d09e33 691<p>This keyword specifies that the driver provides its own custom color matching. When <tt>true</tt>, the default hand-off colorspace will be GenericGray, GenericRGB, or GenericCMYK depending on the number of components the driver requests. The <a href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a> keyword can be used to override the default 3-component (RGB) colorspace.</p>
a4d04587 692
db1f069b
MS		 693<p>The default for <tt>APSupportsCustomColorMatching</tt> is <tt>false</tt>.</p>
694
695<p>Examples:</p>
a4d04587 696
697<pre class='command'>
db1f069b
MS		 698*APSupportsCustomColorMatching: true
699*APDefaultCustomColorMatchingProfile: sRGB
a4d04587 700</pre>
701
ef416fc2 702
66ab9486
MS		 703<h2 class='title'><a name='CONSTRAINTS'>Constraints</a></h2>
704
10d09e33 705<p>Constraints are option choices that are not allowed by the driver or device, for example printing 2-sided transparencies. All versions of CUPS support constraints defined by the legacy Adobe <tt>UIConstraints</tt> and <tt>NonUIConstraints</tt> keywords which support conflicts between any two option choices, for example:</p>
66ab9486
MS		 706
707<pre class='command'>
708*% Do not allow 2-sided printing on transparency media
709*UIConstraints: "*Duplex *MediaType Transparency"
710*UIConstraints: "*MediaType Transparency *Duplex"
711</pre>
712
10d09e33 713<p>While nearly all constraints can be expressed using these keywords, there are valid scenarios requiring constraints between more than two option choices. In addition, resolution of constraints is problematic since users and software have to guess how a particular constraint is best resolved.</p>
66ab9486 714
10d09e33 715<p>CUPS 1.4 and higher define two new keywords for constraints, <tt>cupsUIConstraints</tt> and <tt>cupsUIResolver</tt>. Each <tt>cupsUIConstraints</tt> keyword points to a <tt>cupsUIResolver</tt> keyword which specifies alternate options that resolve the conflict condition. The same <tt>cupsUIResolver</tt> can be used by multiple <tt>cupsUIConstraints</tt>.</p>
1340db2d
MS		 716
717<blockquote><b>Note:</b>
718
10d09e33 719<p>When developing PPD files that contain constraints, it is very important to use the <a href="man-cupstestppd.html">cupstestppd(1)</a> program to verify that your constraints are accurate and cannot result in unresolvable option selections.</p>
1340db2d
MS		 720
721</blockquote>
66ab9486 722
b0f6947b 723<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsUIConstraints'>cupsUIConstraints</a></h3>
66ab9486
MS		 724
725<p class='summary'>*cupsUIConstraints resolver: "*Keyword1 *Keyword2 ..."<br>
726*cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 ..."<br>
727*cupsUIConstraints resolver: "*Keyword1 *Keyword2 OptionKeyword2 ..."<br>
728*cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."<br>
729*cupsUIConstraints: "*InstallableKeyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p>
730
10d09e33 731<p>Lists two or more options which conflict. The "resolver" string is a (possibly unique) keyword which specifies which options to change when the constraint exists. When no resolver is provided, CUPS first tries the default choice followed by testing each option choice to resolve the conflict.</p>
66ab9486
MS		 732
733<p>Examples:</p>
734
735<pre class='command'>
736<em>*% Specify that 2-sided printing cannot happen on transparencies</em>
737*cupsUIConstraints transparency: "*Duplex *MediaType Transparency"
738
1340db2d
MS		 739<em>*% Specify that envelope printing cannot happen from the paper trays</em>
740*cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1"
741*cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1"
742*cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2"
743*cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2"
744
745<em>*% Specify an installable option constraint for the envelope feeder</em>
746*cupsUIConstraints: "*InputSlot EnvFeeder *InstalledEnvFeeder"
747
66ab9486
MS		 748<em>*% Specify that photo printing cannot happen on plain paper or transparencies at 1200dpi</em>
749*cupsUIConstraints photo: "*OutputMode Photo *MediaType Plain *Resolution 1200dpi"
750*cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi"
751</pre>
752
b0f6947b 753<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsUIResolver'>cupsUIResolver</a></h3>
66ab9486 754
c779abb0 755<p class='summary'>*cupsUIResolver resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p>
66ab9486 756
10d09e33 757<p>Specifies two or more options to mark/select to resolve a constraint. The "resolver" string identifies a particular action to take for one or more <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>. The same action can be used for multiple constraints. The option keyword pairs are treated as an ordered list of option selections to try - only the first N selections will be used, where N is the minimum number of selections required. Because <a href="api-ppd.html#cupsResolveConflicts"><code>cupsResolveConflicts()</code></a> will not change the most recent option selection passed to it, at least two options from the constraints must be listed to avoid situations where conflicts cannot be resolved.</p>
66ab9486
MS		 758
759<p>Examples:</p>
760
761<pre class='command'>
1340db2d
MS		 762<em>*% Specify the options to change for the 2-sided transparency constraint</em>
763*cupsUIResolver transparency: "*Duplex None *MediaType Plain"
764
765<em>*% Specify the options to change for the envelope printing constraints. Notice
766*% that we try to change the InputSlot to either the envelope feeder or the
767*% manual feed first, then we change the page size...</em>
768*cupsUIResolver envelope: "*InputSlot EnvFeeder *InputSlot ManualFeed *PageSize Letter"
66ab9486
MS		 769
770<em>*% Specify the options to change for the photo printing constraints</em>
771*cupsUIResolver photo: "*OutputMode Best *Resolution 600dpi"
772</pre>
773
774
db1f069b 775<h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
a4d04587 776
10d09e33 777<p>CUPS 1.2 and higher adds support for PPD files containing multiple languages by following the following additional rules:</p>
ef416fc2 778
db1f069b 779<ol>
ef416fc2 780
db1f069b 781 <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
a4d04587 782
db1f069b 783 <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
ef416fc2 784
10d09e33 785 <li>The <tt>cupsLanguages</tt> keyword MUST be provided and list each of the supported locales in the PPD file</li>
ef416fc2 786
10d09e33 787 <li>Main and option keywords MUST NOT exceed 34 (instead of 40) characters to allow room for the locale prefixes in translation keywords</li>
ef416fc2 788
db1f069b 789 <li>The main keyword "Translation" MUST NOT be used</li>
f7deaa1a 790
10d09e33 791 <li>Translation strings included with the main and option keywords MUST NOT contain characters outside the ASCII subset of ISOLatin1 and UTF-8; developers wishing to use characters outside ASCII MUST provide a separate set of English localization keywords for the affected keywords.</li>
f7deaa1a 792
10d09e33 793 <li>Localizations are specified using a locale prefix of the form "ll" or "ll_CC." where "ll" is the 2-letter ISO language code and "CC" is the 2-letter ISO country code<ul>
db1f069b
MS		 794 <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li>
795 <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li>
796 </ul></li>
f7deaa1a 797
10d09e33 798 <li>Locale-specific translation strings MUST be encoded using UTF-8.</li>
f7deaa1a 799
10d09e33
MS		 800 <li>Main keywords MUST be localized using one of the following forms:
801 <p><tt>*ll.Translation MainKeyword/translation text: ""</tt><br />
802 <tt>*ll_CC.Translation MainKeyword/translation text: ""</tt></p></li>
f7deaa1a 803
10d09e33
MS		 804 <li>Option keywords MUST be localized using one of the following forms:
805 <p><tt>*ll.MainKeyword OptionKeyword/translation text: ""</tt><br>
806 <tt>*ll_CC.MainKeyword OptionKeyword/translation text: ""</tt></p></li>
f7deaa1a 807
10d09e33 808 <li>Localization keywords MAY appear anywhere after the first line of the PPD file</li>
f7deaa1a 809
db1f069b 810</ol>
ef416fc2 811
db1f069b 812<blockquote><b>Note:</b>
a4d04587 813
10d09e33 814<p>We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt> and limit the allowed base translation strings to ASCII to avoid character coding issues that would otherwise occur. In addition, requiring the base translation strings to be in English allows for easier fallback translation when no localization is provided in the PPD file for a given locale.</p>
ef416fc2 815
db1f069b 816</blockquote>
a4d04587 817
ef416fc2 818<p>Examples:</p>
819
820<pre class='command'>
db1f069b
MS		 821*LanguageVersion: English
822*LanguageEncoding: ISOLatin1
823*cupsLanguages: "de fr_CA"
824*ModelName: "Foobar Laser 9999"
f7deaa1a 825
db1f069b
MS		 826<em>*% Localize ModelName for French and German</em>
827*fr_CA.Translation ModelName/La Foobar Laser 9999: ""
828*de.Translation ModelName/Foobar LaserDrucken 9999: ""
f7deaa1a 829
db1f069b
MS		 830*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
831<em>*% Localize printer-state-reason for French and German</em>
832*fr_CA.cupsIPPReason com.vendor-error/Une erreur s&egrave;rieuse s'est produite: "/help/com.vendor/error.html"
833*de.cupsIPPReason com.vendor-error/Eine ernste St&ouml;rung trat: "/help/com.vendor/error.html"
f7deaa1a 834
db1f069b 835...
f7deaa1a 836
db1f069b
MS		 837*OpenUI *InputSlot/Paper Source: PickOne
838*OrderDependency: 10 AnySetup *InputSlot
839*DefaultInputSlot: Auto
840<em>*% Localize InputSlot for French and German</em>
841*fr_CA.Translation InputSlot/Papier source: ""
842*de.Translation InputSlot/Papiereinzug: ""
843*InputSlot Auto/Default: "&lt;&lt;/ManualFeed false&gt;&gt;setpagedevice"
844<em>*% Localize InputSlot=Auto for French and German</em>
845*fr_CA.InputSlot Auto/Par Defaut: ""
846*de.InputSlot Auto/Standard: ""
847*InputSlot Manual/Manual Feed: "&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice"
848<em>*% Localize InputSlot=Manual for French and German</em>
849*fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: ""
850*de.InputSlot Manual/Manueller Einzug: ""
851*CloseUI: *InputSlot
f7deaa1a 852</pre>
853
ef416fc2 854
10d09e33 855<h2 class='title'><a name='OPTIONS'><span class="info">CUPS 1.3/Mac OS X 10.6</span>Custom Options</a></h2>
ef416fc2 856
10d09e33 857<p>CUPS supports custom options using an extension of the <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt> syntax:</p>
ef416fc2 858
859<pre class='command'>
860*CustomFoo True: "command"
861*ParamCustomFoo Name1/Text 1: order type minimum maximum
862*ParamCustomFoo Name2/Text 2: order type minimum maximum
863...
864*ParamCustomFoo NameN/Text N: order type minimum maximum
865</pre>
866
10d09e33
MS		 867<p>When the base option is part of the <tt>JCLSetup</tt> section, the "command" string contains JCL commands with "\order" placeholders for each numbered parameter. The CUPS API handles any necessary value quoting for HP-PJL commands. For example, if the JCL command string is "@PJL SET PASSCODE=\1" and the first
868option value is "1234" then CUPS will output the string "@PJL SET PASSCODE=1234".</p>
869
870<p>For non-<tt>JCLSetup</tt> options, the "order" value is a number from 1 to N and specifies the order of values as they are placed on the stack before the command. For example, if the PostScript command string is "&lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice" and the option value is "2.0" then CUPS will output the string "2.0 &lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice".</p>
ef416fc2 871
872<p>The "type" is one of the following keywords:</p>
873
874<ul>
875
10d09e33 876 <li><tt>curve</tt> - a real value from "minimum" to "maximum" representing a gamma correction curve using the function: f(x) = x <sup>value</sup></li>
ef416fc2 877
10d09e33 878 <li><tt>int</tt> - an integer value from "minimum" to "maximum"</li>
ef416fc2 879
10d09e33 880 <li><tt>invcurve</tt> - a real value from "minimum" to "maximum" representing a gamma correction curve using the function: f(x) = x <sup>1 / value</sup></li>
ef416fc2 881
10d09e33 882 <li><tt>passcode</tt> - a string of numbers value with a minimum of "minimum" numbers and a maximum of "maximum" numbers ("minimum" and "maximum" are numbers and passcode strings are not displayed in the user interface)</li>
ef416fc2 883
10d09e33 884 <li><tt>password</tt> - a string value with a minimum of "minimum" characters and a maximum of "maximum" characters ("minimum" and "maximum" are numbers and password strings are not displayed in the user interface)</li>
ef416fc2 885
10d09e33 886 <li><tt>points</tt> - a measurement value in points from "minimum" to "maximum"</li>
ef416fc2 887
10d09e33 888 <li><tt>real</tt> - a real value from "minimum" to "maximum"</li>
ef416fc2 889
10d09e33 890 <li><tt>string</tt> - a string value with a minimum of "minimum" characters and a maximum of "maximum" characters ("minimum" and "maximum" are numbers)</li>
ef416fc2 891
892</ul>
893
894<p>Examples:</p>
895
896<pre class='command'>
897<em>*% Base JCL key code option</em>
a41f09e2 898*JCLOpenUI JCLPasscode/Key Code: PickOne
ef416fc2 899*OrderDependency: 10 JCLSetup *JCLPasscode
900*DefaultJCLPasscode: None
901*JCLPasscode None/No Code: ""
902*JCLPasscode 1111: "@PJL SET PASSCODE = 1111&lt;0A&gt;"
903*JCLPasscode 2222: "@PJL SET PASSCODE = 2222&lt;0A&gt;"
904*JCLPasscode 3333: "@PJL SET PASSCODE = 3333&lt;0A&gt;"
905*JCLCloseUI: *JCLPasscode
906
907<em>*% Custom JCL key code option</em>
908*CustomJCLPasscode True: "@PJL SET PASSCODE = \1&lt;0A&gt;"
909*ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
910
911
a4d04587 912<em>*% Base PostScript watermark option</em>
913*OpenUI WatermarkText/Watermark Text: PickOne
914*OrderDependency: 10 AnySetup *WatermarkText
915*DefaultWatermarkText: None
916*WatermarkText None: ""
917*WatermarkText Draft: "&lt;&lt;/cupsString1(Draft)&gt;&gt;setpagedevice"
918*CloseUI: *WatermarkText
919
920<em>*% Custom PostScript watermark option</em>
b86bc4cf 921*CustomWatermarkText True: "&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice"
a4d04587 922*ParamCustomWatermarkText Text: 1 string 0 32
923
924
ef416fc2 925<em>*% Base PostScript gamma/density option</em>
926*OpenUI GammaDensity/Gamma and Density: PickOne
927*OrderDependency: 10 AnySetup *GammaDensity
928*DefaultGammaDensity: Normal
929*GammaDensity Normal/Normal: "&lt;&lt;/cupsReal1 1.0/cupsReal2 1.0&gt;&gt;setpagedevice"
930*GammaDensity Light/Lighter: "&lt;&lt;/cupsReal1 0.9/cupsReal2 0.67&gt;&gt;setpagedevice"
931*GammaDensity Dark/Darker: "&lt;&lt;/cupsReal1 1.1/cupsReal2 1.5&gt;&gt;setpagedevice"
a4d04587 932*CloseUI: *GammaDensity
ef416fc2 933
934<em>*% Custom PostScript gamma/density option</em>
b86bc4cf 935*CustomGammaDensity True: "&lt;&lt;/cupsReal1 3 -1 roll/cupsReal2 5 -1&gt;&gt;setpagedevice"
ef416fc2 936*ParamCustomGammaDensity Gamma: 1 curve 0.1 10
937*ParamCustomGammaDensity Density: 2 real 0 2
938</pre>
939
940
db1f069b 941<h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2>
a4d04587 942
10d09e33 943<p>PPD files are used for both PostScript and non-PostScript printers. For CUPS raster drivers, you use a subset of the PostScript language to set page device keywords such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p>
ef416fc2 944
db1f069b
MS		 945<pre class='command'>
946*PageSize A4: "&lt;&lt;/PageSize[595 842]&gt;&gt;setpagedevice"
947</pre>
ef416fc2 948
db1f069b 949<p>Custom options typically use other operators to organize the values into a key/value dictionary for <tt>setpagedevice</tt>. For example, our previous <tt>CustomWatermarkText</tt> option code uses the <tt>roll</tt> operator to move the custom string value into the dictionary for <tt>setpagedevice</tt>:</p>
ef416fc2 950
db1f069b
MS		 951<pre class='command'>
952*CustomWatermarkText True: "&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice"
953</pre>
ef416fc2 954
db1f069b 955<p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p>
ef416fc2 956
957<pre class='command'>
db1f069b
MS		 958(My Watermark)
959&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice
ef416fc2 960</pre>
961
db1f069b 962<p>The code moves the string value ("My Watermark") from the bottom of the stack to the top, creating a dictionary that looks like:</p>
ef416fc2 963
964<pre class='command'>
db1f069b 965&lt;&lt;/cupsString1(My Watermark)&gt;&gt;setpagedevice
ef416fc2 966</pre>
967
db1f069b 968<p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p>
ef416fc2 969
db1f069b 970<h3>Custom Page Size Code</a></h3>
ef416fc2 971
db1f069b 972<p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p>
ef416fc2 973
db1f069b
MS		 974<pre class='command'>
975*ParamCustomPageSize Width: 1 points <i>min-width max-width</i>
976*ParamCustomPageSize Height: 2 points <i>min-height max-height</i>
977*ParamCustomPageSize WidthOffset: 3 points 0 0
978*ParamCustomPageSize HeightOffset: 4 points 0 0
979*ParamCustomPageSize Orientation: 5 int 0 0
980*CustomPageSize True: "pop pop pop &lt;&lt;/PageSize[5 -2 roll]/ImagingBBox null&gt;&gt;setpagedevice"
ef416fc2 981</pre>
982
db1f069b 983<h3>Supported PostScript Operators</a></h3>
ef416fc2 984
db1f069b 985<p>CUPS supports the following PostScript operators in addition to the usual PostScript number, string (literal and hex-encoded), boolean, null, and name values:</p>
ef416fc2 986
db1f069b 987<ul>
ef416fc2 988
db1f069b 989 <li><tt>&lt;&lt;</tt> - Start a dictionary.</li>
ef416fc2 990
db1f069b 991 <li><tt>&gt;&gt;</tt> - End a dictionary.</li>
ef416fc2 992
db1f069b 993 <li><tt>[</tt> - Start an array.</li>
ef416fc2 994
db1f069b 995 <li><tt>]</tt> - End an array.</li>
ef416fc2 996
db1f069b 997 <li><tt>copy</tt> - Copy the top N objects on the stack.</li>
ef416fc2 998
db1f069b 999 <li><tt>dup</tt> - Copy the top object on the stack.</li>
ef416fc2 1000
db1f069b 1001 <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li>
ef416fc2 1002
db1f069b 1003 <li><tt>pop</tt> - Pop the top object on the stack.</li>
ef416fc2 1004
db1f069b 1005 <li><tt>roll</tt> - Shift the top N objects on the stack.</li>
ef416fc2 1006
db1f069b 1007 <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li>
ef416fc2 1008
db1f069b 1009</ul>
ef416fc2 1010
db1f069b 1011<blockquote><b>Note:</b>
ef416fc2 1012
db1f069b
MS		 1013<p><em>Never</em> use the unsupported <tt>dict</tt> or <tt>put</tt>
1014operators in your option code. These operators are typically used in
1015option code dating back to Level 1 PostScript printers, which did not
1016support the simpler <tt>&lt;&lt;</tt> or <tt>&gt;&gt;</tt> operators.
1017If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can
1018rewrite it very easily to use the newer <tt>&lt;&lt;</tt> and
1019<tt>&gt;&gt;</tt> operators instead. For example, the following code
1020to set the page size:</p>
09a101d6 1021
1022<style type='text/css'><!--
1023PRE B {
1024 background: #000000;
1025 color: #ffffff;
1026 padding: 2px 5px;
1027}
1028--></style>
1029
1030<pre class='command'>
1031<b>1 dict dup</b> /PageSize [612 792] <b>put</b> setpagedevice
1032</pre>
1033
1034<p>can be rewritten as:</p>
1035
1036<pre class='command'>
1037<b>&lt;&lt;</b> /PageSize [612 792] <b>&gt;&gt;</b> setpagedevice
1038</pre>
1039
1040</blockquote>
1041
db1f069b 1042<h3>Supported Page Device Attributes</a></h3>
b86bc4cf 1043
09a101d6 1044<p>Table 2 shows the supported page device attributes along with PostScript code examples.</p>
b86bc4cf 1045
1046<div class='table'>
1047<table summary='Supported Page Device Attributes'>
09a101d6 1048<caption>Table 2: <a name='TABLE_2'>Supported Page Device Attributes</a></caption>
b86bc4cf 1049<thead>
1050<tr>
1051 <th>Name(s)</th>
1052 <th>Type</th>
1053 <th>Description</th>
1054 <th>Example(s)</th>
1055</tr>
1056</thead>
1057<tbody>
1058<tr valign='top'>
1059 <td><tt>AdvanceDistance</tt></td>
1060 <td>Integer</td>
1061 <td>Specifies the number of points to advance roll media after printing.</td>
1062 <td><tt>&lt;&lt;/AdvanceDistance 18&gt;&gt;setpagedevice</tt></td>
1063</tr>
1064<tr valign='top'>
1065 <td><tt>AdvanceMedia</tt></td>
1066 <td>Integer</td>
1067 <td>Specifies when to advance the media: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td>
1068 <td><tt>&lt;&lt;/AdvanceMedia 4&gt;&gt;setpagedevice</tt></td>
1069</tr>
1070<tr valign='top'>
1071 <td><tt>Collate</tt></td>
1072 <td>Boolean</td>
1073 <td>Specifies whether collated copies are required.</td>
1074 <td><tt>&lt;&lt;/Collate true&gt;&gt;setpagedevice</tt></td>
1075</tr>
1076<tr valign='top'>
1077 <td><tt>CutMedia</tt></td>
1078 <td>Integer</td>
1079 <td>Specifies when to cut the media: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td>
1080 <td><tt>&lt;&lt;/CutMedia 1&gt;&gt;setpagedevice</tt></td>
1081</tr>
1082<tr valign='top'>
1083 <td><tt>Duplex</tt></td>
1084 <td>Boolean</td>
1085 <td>Specifies whether 2-sided printing is required.</td>
1086 <td><tt>&lt;&lt;/Duplex true&gt;&gt;setpagedevice</tt></td>
1087</tr>
1088<tr valign='top'>
1089 <td><tt>HWResolution</tt></td>
1090 <td>Integer Array</td>
1091 <td>Specifies the resolution of the page image in pixels per inch.</td>
1092 <td><tt>&lt;&lt;/HWResolution[1200 1200]&gt;&gt;setpagedevice</tt></td>
1093</tr>
1094<tr valign='top'>
1095 <td><tt>InsertSheet</tt></td>
1096 <td>Boolean</td>
1097 <td>Specifies whether to insert a blank sheet before the job.</td>
1098 <td><tt>&lt;&lt;/InsertSheet true&gt;&gt;setpagedevice</tt></td>
1099</tr>
1100<tr valign='top'>
1101 <td><tt>Jog</tt></td>
1102 <td>Integer</td>
1103 <td>Specifies when to shift the media in the output bin: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td>
1104 <td><tt>&lt;&lt;/Jog 2&gt;&gt;setpagedevice</tt></td>
1105</tr>
1106<tr valign='top'>
1107 <td><tt>LeadingEdge</tt></td>
1108 <td>Integer</td>
1109 <td>Specifies the leading edge of the media: 0 = top, 1 = right, 2 = bottom, 3 = left.</td>
1110 <td><tt>&lt;&lt;/LeadingEdge 0&gt;&gt;setpagedevice</tt></td>
1111</tr>
1112<tr valign='top'>
1113 <td><tt>ManualFeed</tt></td>
1114 <td>Boolean</td>
1115 <td>Specifies whether media should be drawn from the manual feed tray. Note: The <tt>MediaPosition</tt> attribute is preferred over the <tt>ManualFeed</tt> attribute.</td>
1116 <td><tt>&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice</tt></td>
1117</tr>
1118<tr valign='top'>
1119 <td><tt>MediaClass</tt></td>
1120 <td>String</td>
1121 <td>Specifies a named media.</td>
1122 <td><tt>&lt;&lt;/MediaClass (Invoices)&gt;&gt;setpagedevice</tt></td>
1123</tr>
1124<tr valign='top'>
1125 <td><tt>MediaColor</tt></td>
1126 <td>String</td>
1127 <td>Specifies the color of the media.</td>
1128 <td><tt>&lt;&lt;/MediaColor &gt;&gt;setpagedevice</tt></td>
1129</tr>
1130<tr valign='top'>
1131 <td><tt>MediaPosition</tt></td>
1132 <td>Integer</td>
1133 <td>Specifies the tray or source of the media.</td>
1134 <td><tt>&lt;&lt;/MediaPosition 12&gt;&gt;setpagedevice</tt></td>
1135</tr>
1136<tr valign='top'>
1137 <td><tt>MediaType</tt></td>
1138 <td>String</td>
1139 <td>Specifies the general media type.</td>
1140 <td><tt>&lt;&lt;/MediaType (Glossy)&gt;&gt;setpagedevice</tt></td>
1141</tr>
1142<tr valign='top'>
1143 <td><tt>MediaWeight</tt></td>
1144 <td>Integer</td>
1145 <td>Specifies the media weight in grams per meter<sup>2</sup>.</td>
1146 <td><tt>&lt;&lt;/MediaWeight 100&gt;&gt;setpagedevice</tt></td>
1147</tr>
1148<tr valign='top'>
1149 <td><tt>MirrorPrint</tt></td>
1150 <td>Boolean</td>
1151 <td>Specifies whether to flip the output image horizontally.</td>
1152 <td><tt>&lt;&lt;/MirrorPrint true&gt;&gt;setpagedevice</tt></td>
1153</tr>
1154<tr valign='top'>
1155 <td><tt>NegativePrint</tt></td>
1156 <td>Boolean</td>
1157 <td>Specifies whether to invert the output image.</td>
1158 <td><tt>&lt;&lt;/NegativePrint true&gt;&gt;setpagedevice</tt></td>
1159</tr>
1160<tr valign='top'>
1161 <td><tt>NumCopies</tt></td>
1162 <td>Integer</td>
1163 <td>Specifies the number of copies to produce of each page.</td>
1164 <td><tt>&lt;&lt;/NumCopies 100&gt;&gt;setpagedevice</tt></td>
1165</tr>
1166<tr valign='top'>
1167 <td><tt>Orientation</tt></td>
1168 <td>Integer</td>
1169 <td>Specifies the orientation of the output: 0 = portrait, 1 = landscape rotated counter-clockwise, 2 = upside-down, 3 = landscape rotated clockwise.</td>
1170 <td><tt>&lt;&lt;/Orientation 3&gt;&gt;setpagedevice</tt></td>
1171</tr>
1172<tr valign='top'>
1173 <td><tt>OutputFaceUp</tt></td>
1174 <td>Boolean</td>
1175 <td>Specifies whether to place the media face-up in the output bin/tray.</td>
1176 <td><tt>&lt;&lt;/OutputFaceUp true&gt;&gt;setpagedevice</tt></td>
1177</tr>
1178<tr valign='top'>
1179 <td><tt>OutputType</tt></td>
1180 <td>String</td>
1181 <td>Specifies the output type name.</td>
1182 <td><tt>&lt;&lt;/OutputType (Photo)&gt;&gt;setpagedevice</tt></td>
1183</tr>
1184<tr valign='top'>
1185 <td><tt>PageSize</tt></td>
1186 <td>Integer/Real Array</td>
1187 <td>Specifies the width and length/height of the page in points.</td>
1188 <td><tt>&lt;&lt;/PageSize[595 842]&gt;&gt;setpagedevice</tt></td>
1189</tr>
1190<tr valign='top'>
1191 <td><tt>Separations</tt></td>
1192 <td>Boolean</td>
1193 <td>Specifies whether to produce color separations.</td>
1194 <td><tt>&lt;&lt;/Separations true&gt;&gt;setpagedevice</tt></td>
1195</tr>
1196<tr valign='top'>
1197 <td><tt>TraySwitch</tt></td>
1198 <td>Boolean</td>
1199 <td>Specifies whether to switch trays automatically.</td>
1200 <td><tt>&lt;&lt;/TraySwitch true&gt;&gt;setpagedevice</tt></td>
1201</tr>
1202<tr valign='top'>
1203 <td><tt>Tumble</tt></td>
1204 <td>Boolean</td>
1205 <td>Specifies whether the back sides of pages are rotated 180 degrees.</td>
1206 <td><tt>&lt;&lt;/Tumble true&gt;&gt;setpagedevice</tt></td>
1207</tr>
1208<tr valign='top'>
1209 <td><tt>cupsBorderlessScalingFactor</tt></td>
1210 <td>Real</td>
1211 <td>Specifies the amount to scale the page image dimensions.</td>
1212 <td><tt>&lt;&lt;/cupsBorderlessScalingFactor 1.01&gt;&gt;setpagedevice</tt></td>
1213</tr>
1214<tr valign='top'>
1215 <td><tt>cupsColorOrder</tt></td>
1216 <td>Integer</td>
1217 <td>Specifies the order of colors: 0 = chunked, 1 = banded, 2 = planar.</td>
1218 <td><tt>&lt;&lt;/cupsColorOrder 0&gt;&gt;setpagedevice</tt></td>
1219</tr>
1220<tr valign='top'>
1221 <td><tt>cupsColorSpace</tt></td>
1222 <td>Integer</td>
1223 <td>Specifies the page image colorspace: 0 = W, 1 = RGB, 2 = RGBA, 3 = K, 4 = CMY, 5 = YMC, 6 = CMYK, 7 = YMCK, 8 = KCMY, 9 = KCMYcm, 10 = GMCK, 11 = GMCS, 12 = White, 13 = Gold, 14 = Silver, 15 = CIE XYZ, 16 = CIE Lab, 17 = RGBW, 32 to 46 = CIE Lab (1 to 15 inks)</td>
7dfedb92 1224 <td><tt>&lt;&lt;/cupsColorSpace 1 &gt;&gt;setpagedevice</tt></td>
b86bc4cf 1225</tr>
1226<tr valign='top'>
1227 <td><tt>cupsCompression</tt></td>
1228 <td>Integer</td>
1229 <td>Specifies a driver compression type/mode.</td>
1230 <td><tt>&lt;&lt;/cupsCompression 2&gt;&gt;setpagedevice</tt></td>
1231</tr>
1232<tr valign='top'>
1233 <td><tt>cupsInteger0<br>
1234 ...<br>
1235 cupsInteger15</tt></td>
1236 <td>Integer</td>
1237 <td>Specifies driver integer values.</td>
1238 <td><tt>&lt;&lt;/cupsInteger11 1234&gt;&gt;setpagedevice</tt></td>
1239</tr>
1240<tr valign='top'>
1241 <td><tt>cupsMarkerType</tt></td>
1242 <td>String</td>
1243 <td>Specifies the type of ink/toner to use.</td>
1244 <td><tt>&lt;&lt;/cupsMarkerType (Black+Color)&gt;&gt;setpagedevice</tt></td>
1245</tr>
1246<tr valign='top'>
1247 <td><tt>cupsMediaType</tt></td>
1248 <td>Integer</td>
1249 <td>Specifies a numeric media type.</td>
1250 <td><tt>&lt;&lt;/cupsMediaType 999&gt;&gt;setpagedevice</tt></td>
1251</tr>
1252<tr valign='top'>
1253 <td><tt>cupsPageSizeName</tt></td>
1254 <td>String</td>
1255 <td>Specifies the name of the page size.</td>
1256 <td><tt>&lt;&lt;/cupsPageSizeName (A4.Full)&gt;&gt;setpagedevice</tt></td>
1257</tr>
1258<tr valign='top'>
1259 <td><tt>cupsPreferredBitsPerColor</tt></td>
1260 <td>Integer</td>
1261 <td>Specifies the preferred number of bits per color, typically 8 or 16.</td>
1262 <td><tt>&lt;&lt;/cupsPreferredBitsPerColor 16&gt;&gt;setpagedevice</tt></td>
1263</tr>
1264<tr valign='top'>
1265 <td><tt>cupsReal0<br>
1266 ...<br>
1267 cupsReal15</tt></td>
1268 <td>Real</td>
1269 <td>Specifies driver real number values.</td>
1270 <td><tt>&lt;&lt;/cupsReal15 1.234&gt;&gt;setpagedevice</tt></td>
1271</tr>
1272<tr valign='top'>
1273 <td><tt>cupsRenderingIntent</tt></td>
1274 <td>String</td>
1275 <td>Specifies the color rendering intent.</td>
1276 <td><tt>&lt;&lt;/cupsRenderingIntent (AbsoluteColorimetric)&gt;&gt;setpagedevice</tt></td>
1277</tr>
1278<tr valign='top'>
1279 <td><tt>cupsRowCount</tt></td>
1280 <td>Integer</td>
1281 <td>Specifies the number of rows of raster data to print on each line for some drivers.</td>
1282 <td><tt>&lt;&lt;/cupsRowCount 24&gt;&gt;setpagedevice</tt></td>
1283</tr>
1284<tr valign='top'>
1285 <td><tt>cupsRowFeed</tt></td>
1286 <td>Integer</td>
1287 <td>Specifies the number of rows to feed between passes for some drivers.</td>
1288 <td><tt>&lt;&lt;/cupsRowFeed 17&gt;&gt;setpagedevice</tt></td>
1289</tr>
1290<tr valign='top'>
1291 <td><tt>cupsRowStep</tt></td>
1292 <td>Integer</td>
1293 <td>Specifies the number of lines between columns/rows on the print head for some drivers.</td>
1294 <td><tt>&lt;&lt;/cupsRowStep 2&gt;&gt;setpagedevice</tt></td>
1295</tr>
1296<tr valign='top'>
1297 <td><tt>cupsString0<br>
1298 ...<br>
1299 cupsString15</tt></td>
1300 <td>String</td>
1301 <td>Specifies driver string values.</td>
1302 <td><tt>&lt;&lt;/cupsString0(String Value)&gt;&gt;setpagedevice</tt></td>
1303</tr>
1304</tbody>
1305</table></div>
1306
1307
10d09e33 1308<h2 class='title'><a name='MEDIA'>Media Keywords</a></h2>
749b1e90 1309
10d09e33 1310<p>The CUPS media keywords allow drivers to specify alternate custom page
749b1e90
MS		 1311size limits based on up to two options.</p>
1312
b0f6947b 1313<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMediaQualifier2'>cupsMediaQualifier2</a></h3>
749b1e90
MS		 1314
1315<p class='summary'>*cupsMediaQualifier2: MainKeyword</p>
1316
10d09e33 1317<p>This keyword specifies the second option to use for overriding the
749b1e90
MS		 1318custom page size limits.</p>
1319
1320<p>Example:</p>
1321
1322<pre class='command'>
1323<em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1324*cupsMediaQualifier2: InputSlot
1325*cupsMediaQualifier3: Quality
1326*cupsMaxSize .Manual.: "1000 1000"
1327*cupsMinSize .Manual.: "100 100"
1328*cupsMinSize .Manual.Photo: "200 200"
1329*cupsMinSize ..Photo: "300 300"
1330</pre>
1331
b0f6947b 1332<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMediaQualifier3'>cupsMediaQualifier3</a></h3>
749b1e90
MS		 1333
1334<p class='summary'>*cupsMediaQualifier3: MainKeyword</p>
1335
10d09e33 1336<p>This keyword specifies the third option to use for overriding the
749b1e90
MS		 1337custom page size limits.</p>
1338
1339<p>Example:</p>
1340
1341<pre class='command'>
1342<em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1343*cupsMediaQualifier2: InputSlot
1344*cupsMediaQualifier3: Quality
1345*cupsMaxSize .Manual.: "1000 1000"
1346*cupsMinSize .Manual.: "100 100"
1347*cupsMinSize .Manual.Photo: "200 200"
1348*cupsMinSize ..Photo: "300 300"
1349</pre>
1350
b0f6947b 1351<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMinSize'>cupsMinSize</a></h3>
749b1e90
MS		 1352
1353<p class='summary'>*cupsMinSize .Qualifier2.Qualifier3: "width length"<br>
1354*cupsMinSize .Qualifier2.: "width length"<br>
1355*cupsMinSize ..Qualifier3: "width length"</p>
1356
10d09e33 1357<p>This keyword specifies alternate minimum custom page sizes in points.
749b1e90 1358The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and
10d09e33 1359<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords
749b1e90
MS		 1360are used to identify options to use for matching.</p>
1361
1362<p>Example:</p>
1363
1364<pre class='command'>
1365<em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1366*cupsMediaQualifier2: InputSlot
1367*cupsMediaQualifier3: Quality
1368*cupsMaxSize .Manual.: "1000 1000"
1369*cupsMinSize .Manual.: "100 100"
1370*cupsMinSize .Manual.Photo: "200 200"
1371*cupsMinSize ..Photo: "300 300"
1372</pre>
1373
b0f6947b 1374<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMaxSize'>cupsMaxSize</a></h3>
749b1e90
MS		 1375
1376<p class='summary'>*cupsMaxSize .Qualifier2.Qualifier3: "width length"<br>
1377*cupsMaxSize .Qualifier2.: "width length"<br>
1378*cupsMaxSize ..Qualifier3: "width length"</p>
1379
10d09e33 1380<p>This keyword specifies alternate maximum custom page sizes in points.
749b1e90 1381The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and
10d09e33 1382<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords
749b1e90
MS		 1383are used to identify options to use for matching.</p>
1384
1385<p>Example:</p>
1386
1387<pre class='command'>
1388<em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1389*cupsMediaQualifier2: InputSlot
1390*cupsMediaQualifier3: Quality
1391*cupsMaxSize .Manual.: "1000 1000"
1392*cupsMinSize .Manual.: "100 100"
1393*cupsMinSize .Manual.Photo: "200 200"
1394*cupsMinSize ..Photo: "300 300"
1395</pre>
1396
1397
db1f069b
MS		 1398<h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
1399
b0f6947b 1400<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsBackSide'>cupsBackSide</a></h3>
db1f069b
MS		 1401
1402<p class='summary'>*cupsBackSide: keyword</p>
1403
10d09e33 1404<p>This keyword requests special handling of the back side of pages
db1f069b 1405when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a>
10d09e33 1406shows the supported keyword values for this keyword and their effect
db1f069b
MS		 1407on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt>
1408is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver
1409will receive print data starting at the bottom right corner of the page, with
1410each line going right-to-left instead of left-to-right. The default value is
1411<code>Normal</code>.</p>
1412
1413<blockquote><b>Note:</b>
1414
1415<p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt>
10d09e33 1416keyword - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt>
db1f069b
MS		 1417will be ignored.</p>
1418
1419</blockquote>
1420
1421<div class='table'>
1422<table width='80%' summary='Back Side Raster Coordinate System'>
1423<caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption>
1424<thead>
1425<tr>
1426 <th>cupsBackSide</th>
1427 <th>Tumble Value</th>
1428 <th>Image Presentation</th>
1429</tr>
1430</thead>
1431<tbody>
1432<tr>
1433 <td><code>Normal</code></td>
1434 <td><code>false</code></td>
1435 <td>Left-to-right, top-to-bottom</td>
1436</tr>
1437<tr>
1438 <td><code>Normal</code></td>
1439 <td><code>true</code></td>
1440 <td>Left-to-right, top-to-bottom</td>
1441</tr>
1442<tr>
1443 <td><code>ManualTumble</code></td>
1444 <td><code>false</code></td>
1445 <td>Left-to-right, top-to-bottom</td>
1446</tr>
1447<tr>
1448 <td><code>ManualTumble</code></td>
1449 <td><code>true</code></td>
1450 <td>Right-to-left, bottom-to-top</td>
1451</tr>
1452<tr>
1453 <td><code>Rotated</code></td>
1454 <td><code>false</code></td>
1455 <td>Right-to-left, bottom-to-top</td>
1456</tr>
1457<tr>
1458 <td><code>Rotated</code></td>
1459 <td><code>true</code></td>
1460 <td>Right-to-left, top-to-bottom</td>
1461</tr>
1462<tr>
1463 <td><code>Flipped</code> *</td>
1464 <td><code>false</code></td>
1465 <td>Left-to-right, bottom-to-top</td>
1466</tr>
1467<tr>
1468 <td><code>Flipped</code> *</td>
1469 <td><code>true</code></td>
1470 <td>Right-to-left, top-to-bottom</td>
1471</tr>
1472</tbody>
1473</table>
1474</div>
1475
1476<p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p>
1477
1478<div class='figure'><table summary='Back side images'>
1479<caption>Figure 1: Back side images</caption>
1480<tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr>
1481</table></div>
1482
1483<p>Examples:</p>
1484
1485<pre class='command'>
1486<em>*% Flip the page image for the back side of duplexed output</em>
1487*cupsBackSide: Flipped
1488
1489<em>*% Rotate the page image for the back side of duplexed output</em>
1490*cupsBackSide: Rotated
1491</pre>
1492
1493<p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
10d09e33 1494keyword.</p>
db1f069b 1495
b0f6947b 1496<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsCommands'>cupsCommands</a></h3>
01ce6322
MS		 1497
1498<p class='summary'>*cupsCommands: "name name2 ... nameN"</p>
1499
10d09e33 1500<p>This string keyword specifies the commands that are supported by the
01ce6322
MS		 1501CUPS command file filter for this device. The command names are separated
1502by whitespace.</p>
1503
1504<p>Example:</p>
1505
1506<pre class='command'>
1507<em>*% Specify the list of commands we support</em>
1508*cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels com.vendor.foo"
1509</pre>
1510
1511
b0f6947b 1512<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3>
db1f069b
MS		 1513
1514<p class='summary'>*cupsEvenDuplex: boolean</p>
1515
10d09e33 1516<p>This boolean keyword notifies the RIP filters that the
db1f069b
MS		 1517destination printer requires an even number of pages when 2-sided
1518printing is selected. The default value is <code>false</code>.</p>
1519
1520<p>Example:</p>
1521
1522<pre class='command'>
1523<em>*% Always send an even number of pages when duplexing</em>
1524*cupsEvenDuplex: true
1525</pre>
1526
1527<h3><a name='cupsFax'>cupsFax</a></h3>
1528
1529<p class='summary'>*cupsFax: boolean</p>
1530
10d09e33 1531<p>This boolean keyword specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p>
db1f069b
MS		 1532
1533<p>Examples:</p>
1534
1535<pre class='command'>
1536*cupsFax: true
1537</pre>
1538
1539<h3><a name='cupsFilter'>cupsFilter</a></h3>
1540
1541<p class='summary'>*cupsFilter: "source/type cost program"</p>
1542
10d09e33 1543<p>This string keyword provides a conversion rule from the
db1f069b
MS		 1544given source type to the printer's native format using the
1545filter "program". If a printer supports the source type directly,
1546the special filter program "-" may be specified.</p>
1547
1548<p>Examples:</p>
1549
1550<pre class='command'>
1551<em>*% Standard raster printer driver filter</em>
1552*cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
1553
1554<em>*% Plain text filter</em>
1555*cupsFilter: "text/plain 10 texttofoo"
1556
1557<em>*% Pass-through filter for PostScript printers</em>
1558*cupsFilter: "application/vnd.cups-postscript 0 -"
1559</pre>
1560
1561<h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3>
1562
1563<p class='summary'>*cupsFlipDuplex: boolean</p>
1564
1565<p>Due to implementation differences between Mac OS X and Ghostscript,
10d09e33
MS		 1566the <tt>cupsFlipDuplex</tt> keyword is deprecated. Instead, use
1567the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> keyword to specify
db1f069b
MS		 1568the coordinate system (pixel layout) of the page data on the back side of
1569duplex pages.</p>
1570
1571<p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value
1572of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with
1573Ghostscript.</p>
1574
1575<p>The default value is <code>false</code>.</p>
1576
1577<blockquote><b>Note:</b>
1578
1579<p>Mac OS X drivers that previously used
1580<tt>cupsFlipDuplex</tt> may wish to provide both the old and
10d09e33 1581new keywords for maximum compatibility, for example:</p>
db1f069b
MS		 1582
1583<pre class='command'>
1584*cupsBackSide: Rotated
1585*cupsFlipDuplex: true
1586</pre>
1587
1588<p>Similarly, drivers written for other operating systems using
1589Ghostscript can use:</p>
1590
1591<pre class='command'>
1592*cupsBackSide: Flipped
1593*cupsFlipDuplex: true
1594</pre></blockquote>
1595
b0f6947b 1596<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3>
db1f069b
MS		 1597
1598<p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p>
1599
10d09e33 1600<p>This keyword defines a mapping from IPP <code>finishings</code>
db1f069b
MS		 1601values to PPD options and choices.</p>
1602
1603<p>Examples:</p>
1604
1605<pre class='command'>
1606*cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait"
1607*cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide"
1608*cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait"
1609*cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
1610</pre>
1611
b0f6947b 1612<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsIPPReason'>cupsIPPReason</a></h3>
db1f069b
MS		 1613
1614<p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
1615
10d09e33 1616<p>This optional keyword maps custom
db1f069b
MS		 1617<code>printer-state-reasons</code> keywords that are generated by
1618the driver to human readable text. The optional URIs string
1619contains zero or more URIs separated by a newline. Each URI can
1620be a CUPS server absolute path to a help file under the
1621scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
1622("http://www.domain.com/path/to/help/page.html"), or any other
1623valid URI which directs the user at additional information
1624concerning the condition that is being reported.</p>
1625
1626<p>Since the reason text is limited to 80 characters by the PPD specification,
1627longer text strings can be included by URI-encoding the text with the "text"
1628scheme, for example "text:some%20text". Multiple <code>text</code> URIs are
1629combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt>
1630into a single string that can be displayed to the user.</p>
1631
1632<p>Examples:</p>
1633
1634<pre class='command'>
1635<em>*% Map com.vendor-error to text but no page</em>
1636*cupsIPPReason com.vendor-error/A serious error occurred: ""
1637
1638<em>*% Map com.vendor-error to more than 80 characters of text but no page</em>
1639*cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time
1640text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country."
1641
1642<em>*% Map com.vendor-error to text and a local page</em>
1643*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
1644
1645<em>*% Map com.vendor-error to text and a remote page</em>
1646*cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
1647
1648<em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
839a51c8 1649*APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
db1f069b
MS		 1650*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
1651help:anchor='com.vendor-error'%20bookID=Vendor%20Help
1652http://www.vendor.com/help"
1653*End
1654</pre>
1655
b0f6947b 1656<h3><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a name='cupsLanguages'>cupsLanguages</a></h3>
db1f069b
MS		 1657
1658<p class='summary'>*cupsLanguages: "locale list"</p>
1659
10d09e33 1660<p>This keyword describes which language localizations are
db1f069b
MS		 1661included in the PPD. The "locale list" string is a space-delimited
1662list of locale names ("en", "en_US", "fr_CA", etc.)</p>
1663
1664<p>Example:</p>
1665
1666<pre class='command'>
1667<em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
5a738aea 1668*cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
db1f069b
MS		 1669</pre>
1670
1671<h3><a name='cupsManualCopies'>cupsManualCopies</a></h3>
1672
1673<p class='summary'>*cupsManualCopies: boolean</p>
1674
10d09e33 1675<p>This boolean keyword notifies the RIP filters that the
db1f069b
MS		 1676destination printer does not support copy generation in
1677hardware. The default value is <code>false</code>.</p>
1678
1679<p>Example:</p>
1680
1681<pre class='command'>
1682<em>*% Tell the RIP filters to generate the copies for us</em>
1683*cupsManualCopies: true
1684</pre>
1685
b0f6947b 1686<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMarkerName'>cupsMarkerName</a></h3>
634763e8
MS		 1687
1688<p class='summary'>*cupsMarkerName/Name Text: ""</p>
1689
10d09e33 1690<p>This optional keyword maps <code>marker-names</code> strings that are
634763e8
MS		 1691generated by the driver to human readable text.</p>
1692
1693<p>Examples:</p>
1694
1695<pre class='command'>
1696<em>*% Map cyanToner to "Cyan Toner"</em>
1697*cupsMarkerName cyanToner/Cyan Toner: ""
1698</pre>
1699
b0f6947b 1700<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3>
75bd9771
MS		 1701
1702<p class='summary'>*cupsMarkerNotice: "disclaimer text"</p>
1703
10d09e33 1704<p>This optional keyword provides disclaimer text for the supply level
75bd9771
MS		 1705information provided by the driver, typically something like "supply levels
1706are approximate".</p>
1707
1708<p>Examples:</p>
1709
1710<pre class='command'>
1711*cupsMarkerNotice: "Supply levels are approximate."
1712</pre>
1713
db1f069b
MS		 1714<h3><a name='cupsModelNumber'>cupsModelNumber</a></h3>
1715
1716<p class='summary'>*cupsModelNumber: number</p>
1717
10d09e33 1718<p>This integer keyword specifies a printer-specific model
db1f069b
MS		 1719number. This number can be used by a filter program to adjust
1720the output for a specific model of printer.</p>
1721
1722<p>Example:</p>
1723
1724<pre class='command'>
1725<em>*% Specify an integer for a driver-specific model number</em>
1726*cupsModelNumber: 1234
1727</pre>
1728
b0f6947b 1729<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3>
db1f069b
MS		 1730
1731<p class='summary'>*cupsPJLCharset: "ISO character set name"</p>
1732
10d09e33 1733<p>This string keyword specifies the character set that is used
db1f069b
MS		 1734for strings in PJL commands. If not specified, US-ASCII is
1735assumed.</p>
1736
1737<p>Example:</p>
1738
1739<pre class='command'>
1740<em>*% Specify UTF-8 is used in PJL strings</em>
1741*cupsPJLCharset: "UTF-8"
1742</pre>
1743
b0f6947b 1744<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3>
634763e8
MS		 1745
1746<p class='summary'>*cupsPJLDisplay: "what"</p>
1747
10d09e33 1748<p>This optional keyword specifies which command is used to display the
634763e8
MS		 1749job ID, name, and user on the printer's control panel. "What" is either "none"
1750to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg"
1751to use "@PJL RDYMSG DISPLAY". The default is "job".</p>
1752
1753<p>Examples:</p>
1754
1755<pre class='command'>
1756<em>*% Display job information using @PJL SET RDYMSG DISPLAY="foo"</em>
1757*cupsPJLDisplay: "rdymsg"
1758
1759<em>*% Display job information display</em>
1760*cupsPJLDisplay: "none"
1761</pre>
db1f069b 1762
b0f6947b 1763<h3><span class='info'>CUPS 1.2/Mac OS X 10.5</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3>
db1f069b
MS		 1764
1765<p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
1766
10d09e33 1767<p>This string keyword specifies printer-specific "port
db1f069b 1768monitor" filters that may be used with the printer. The CUPS
10d09e33 1769scheduler also looks for the <tt>Protocols</tt> keyword to see
db1f069b
MS		 1770if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
1771so, the corresponding port monitor ("bcp" and "tbcp",
1772respectively) is listed in the printer's
10d09e33 1773<tt>port-monitor-supported</tt> keyword.</p>
db1f069b 1774
10d09e33 1775<p>The "urischeme" portion of the keyword specifies the URI scheme
db1f069b
MS		 1776that this port monitor should be used for. Typically this is used to
1777pre-select a particular port monitor for each type of connection that
1778is supported by the printer. The "port monitor" string can be "none"
1779to disable the port monitor for the given URI scheme.</p>
1780
1781<p>Examples:</p>
1782
1783<pre class='command'>
1784<em>*% Specify a PostScript printer that supports the TBCP protocol</em>
1785*Protocols: TBCP PJL
1786
1787<em>*% Specify that TBCP should be used for socket connections but not USB</em>
1788*cupsPortMonitor socket/AppSocket Printing: "tbcp"
1789*cupsPortMonitor usb/USB Printing: "none"
1790
1791<em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
1792*cupsPortMonitor usb/USB Status Monitor: "epson-usb"
1793</pre>
1794
b0f6947b 1795<h3><span class='info'>CUPS 1.3/Mac OS X 10.5</span><a name='cupsPreFilter'>cupsPreFilter</a></h3>
db1f069b
MS		 1796
1797<p class='summary'>*cupsPreFilter: "source/type cost program"</p>
1798
10d09e33 1799<p>This string keyword provides a pre-filter rule. The pre-filter
db1f069b
MS		 1800program will be inserted in the conversion chain immediately
1801before the filter that accepts the given MIME type.</p>
1802
1803<p>Examples:</p>
1804
1805<pre class='command'>
1806<em>*% PDF pre-filter</em>
1807*cupsPreFilter: "application/pdf 100 mypdfprefilter"
1808
1809<em>*% PNG pre-filter</em>
1810*cupsPreFilter: "image/png 0 mypngprefilter"
1811</pre>
1812
c7017ecc
MS		 1813
1814<h3><span class='info'>CUPS 1.5</span><a name='cupsPrintQuality'>cupsPrintQuality</a></h3>
1815
1816<p class='summary'>*cupsPrintQuality keyword/text: "code"</p>
1817
10d09e33 1818<p>This UI keyword defines standard print qualities that directly map from the IPP "print-quality" job template keyword. Standard keyword values are "Draft", "Normal", and "High" which are mapped from the IPP "print-quality" values 3, 4, and 5 respectively. Each <code>cupsPrintQuality</code> option typically sets output mode and resolution parameters in the page device dictionary, eliminating the need for separate (and sometimes confusing) output mode and resolution options.</p>
c7017ecc
MS		 1819
1820<blockquote><b>Note:</b>
1821
1822<p>Unlike all of the other keywords defined in this document, <code>cupsPrintQuality</code> is a UI keyword that MUST be enclosed inside the PPD <code>OpenUI</code> and <code>CloseUI</code> keywords.</p>
1823
1824</blockquote>
1825
1826<p>Examples:</p>
1827
1828<pre class='command'>
1829*OpenUI *cupsPrintQuality/Print Quality: PickOne
1830*OrderDependency: 10 AnySetup *cupsPrintQuality
1831*DefaultcupsPrintQuality: Normal
1832*cupsPrintQuality Draft/Draft: "code"
1833*cupsPrintQuality Normal/Normal: "code"
1834*cupsPrintQuality High/Photo: "code"
1835*CloseUI: *cupsPrintQuality
1836</pre>
1837
b0f6947b 1838<h3><span class='info'>CUPS 1.4/Mac OS X 10.6</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3>
58dc1933
MS		 1839
1840<p class='summary'>*cupsSNMPSupplies: boolean</p>
1841
10d09e33 1842<p>This keyword tells the standard network backends whether they should query
58dc1933
MS		 1843the standard SNMP Printer MIB OIDs for supply levels. The default value is
1844<code>True</code>.
1845
1846<p>Example:</p>
1847
1848<pre class='command'>
1849<em>*% Do not use SNMP queries to report supply levels</em>
1850*cupsSNMPSupplies: False
1851</pre>
1852
db1f069b
MS		 1853<h3><a name='cupsVersion'>cupsVersion</a></h3>
1854
1855<p class='summary'>*cupsVersion: major.minor</p>
1856
10d09e33 1857<p>This required keyword describes which version of the CUPS
db1f069b
MS		 1858PPD file extensions was used. Currently it must be the string
1859"1.0", "1.1", "1.2", or "1.3".</p>
1860
1861<p>Example:</p>
1862
1863<pre class='command'>
1864<em>*% Specify a CUPS 1.2 driver</em>
1865*cupsVersion: "1.2"
1866</pre>
1867
1868
1869<h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2>
1870
db1f069b
MS		 1871<h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3>
1872
1873<p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p>
1874
10d09e33
MS		 1875<p>This keyword defines additional option panes that are displayed in the
1876print dialog. Each keyword adds one or more option panes. See the "OutputBinsPDE"
db1f069b
MS		 1877example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple
1878Technical Q&amp;A QA1352</a> for information on writing your own print dialog
1879plug-ins.</p>
1880
1881<blockquote><b>Note:</b>
1882
1883<p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat"
1884(32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled
1885in order to be usable with all applications.</p>
1886
1887</blockquote>
1888
1889<p>Examples:</p>
1890
1891<pre class='command'>
1892*% Add two panes for finishing and driver options
1893*APDialogExtension: "/Library/Printers/vendor/finishing.plugin"
1894*APDialogExtension: "/Library/Printers/vendor/options.plugin"
1895</pre>
1896
1897<h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3>
1898
1899<p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
1900
10d09e33 1901<p>This boolean keyword notifies the RIP filters that the
db1f069b
MS		 1902destination printer requires the top and bottom margins of the
1903<tt>ImageableArea</tt> to be swapped for the back page. The
1904default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt>
1905and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how
1906<tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt>
1907and the <tt>Tumble</tt> page attribute.</p>
1908
1909<div class='table'>
1910<table width='80%' summary='Margin Flipping Modes'>
1911<caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption>
1912<thead>
1913<tr>
1914 <th>APDuplexRequiresFlippedMargin</th>
1915 <th>cupsBackSide</th>
1916 <th>Tumble Value</th>
1917 <th>Margins</th>
1918</tr>
1919</thead>
1920<tbody>
1921<tr>
1922 <td>false</td>
1923 <td>any</td>
1924 <td>any</td>
1925 <td>Normal</td>
1926</tr>
1927<tr>
1928 <td>any</td>
1929 <td>Normal</td>
1930 <td>any</td>
1931 <td>Normal</td>
1932</tr>
1933<tr>
1934 <td>true</td>
1935 <td>ManualDuplex</td>
1936 <td>false</td>
1937 <td>Normal</td>
1938</tr>
1939<tr>
1940 <td>true</td>
1941 <td>ManualDuplex</td>
1942 <td>true</td>
1943 <td>Flipped</td>
1944</tr>
1945<tr>
1946 <td>true</td>
1947 <td>Rotated</td>
1948 <td>false</td>
1949 <td>Flipped</td>
1950</tr>
1951<tr>
1952 <td>true</td>
1953 <td>Rotated</td>
1954 <td>true</td>
1955 <td>Normal</td>
1956</tr>
1957<tr>
1958 <td>true or unspecified</td>
1959 <td>Flipped</td>
1960 <td>any</td>
1961 <td>Flipped</td>
1962</tr>
1963</tbody>
1964</table></div>
1965
1966<p>Example:</p>
1967
1968<pre class='command'>
1969<em>*% Rotate the back side images</em>
1970*cupsBackSide: Rotated
1971
1972<em>*% Don't swap the top and bottom margins for the back side</em>
1973*APDuplexRequiresFlippedMargin: false
1974</pre>
1975
1976<p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a>
10d09e33 1977keyword.</p>
db1f069b 1978
64a69576
MS		 1979<h3><a name='APHelpBook'>APHelpBook</a></h3>
1980
839a51c8 1981<p class='summary'>*APHelpBook: "bundle URL"</p>
64a69576 1982
10d09e33 1983<p>This string keyword specifies the Apple help book bundle to use when
64a69576 1984looking up IPP reason codes for this printer driver. The
10d09e33 1985<a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword maps
64a69576
MS		 1986"help" URIs to this file.</p>
1987
1988<p>Example:</p>
1989
1990<pre class='command'>
839a51c8 1991*APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
64a69576
MS		 1992</pre>
1993
c5571a1d
MS		 1994<h3><span class='info'>Mac OS X 10.6</span><a name='APICADriver'>APICADriver</a></h3>
1995
1996<p class='summary'>*APICADriver: boolean</p>
1997
10d09e33 1998<p>This keyword specifies whether the device has a matching Image Capture
c5571a1d
MS		 1999Architecture (ICA) driver for scanning. The default is <tt>False</tt>.</p>
2000
2001<p>Examples:</p>
2002
2003<pre class='command'>
2004*APICADriver: True
2005*APScanAppBundleID: "com.apple.ImageCaptureApp"
2006</pre>
2007
db1f069b
MS		 2008<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3>
2009
e4572d57 2010<p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"</p>
db1f069b 2011
10d09e33 2012<p>This keyword defines the location of a printer icon file to use when
e4572d57 2013displaying the printer. The file must be in the Apple icon format.</p>
db1f069b
MS		 2014
2015<p>Examples:</p>
2016
2017<pre class='command'>
2018*% Apple icon file
2019*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
db1f069b
MS		 2020</pre>
2021
2022<h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3>
2023
2024<p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p>
2025
10d09e33 2026<p>This keyword defines an program that checks the ink/toner/marker levels
db1f069b
MS		 2027on a printer, returning an XML document with those levels. See the "InkTool"
2028example and
2029<a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple
2030Technical Note TN2144</a> for more information.</p>
2031
2032<p>Examples:</p>
2033
2034<pre class='command'>
2035*% Use a vendor monitoring program
2036*APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool"
2037</pre>
2038
2039<h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3>
2040
2041<p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p>
2042
10d09e33 2043<p>This keyword defines presets for multiple options that show up
db1f069b
MS		 2044in the print dialog of applications (such as iPhoto) that set the job
2045style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or
2046more pairs of PPD options and choices as well as providing key/value data for
c7017ecc 2047the application. The following standard preset names are currently defined:</p>
db1f069b
MS		 2048
2049<ul>
2050
c7017ecc
MS		 2051 <li><code>General_with_Paper_Auto-Detect</code>; Normal quality general printing with auto-detected media.</li>
2052
2053 <li><code>General_with_Paper_Auto-Detect_-_Draft</code>; Draft quality general printing with auto-detected media.</li>
2054
2055 <li><code>General_on_Plain_Paper</code>; Normal quality general printing on plain paper.</li>
2056
2057 <li><code>General_on_Plain_Paper_-_Draft</code>; Draft quality general printing on plain paper.</li>
db1f069b 2058
c7017ecc 2059 <li><code>Photo_with_Paper_Auto-Detect</code>; Normal quality photo printing with auto-detected media.</li>
db1f069b 2060
c7017ecc 2061 <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; High quality photo printing with auto-detected media.</li>
db1f069b 2062
c7017ecc 2063 <li><code>Photo_on_Plain_Paper</code>; Normal quality photo printing on plain paper.</li>
db1f069b 2064
c7017ecc 2065 <li><code>Photo_on_Plain_Paper_-_Fine</code>; High quality photo printing on plain paper.</li>
db1f069b 2066
c7017ecc 2067 <li><code>Photo_on_Photo_Paper</code>; Normal quality photo printing on glossy photo paper.</li>
db1f069b 2068
c7017ecc 2069 <li><code>Photo_on_Photo_Paper_-_Fine</code>; High quality photo printing on glossy photo paper.</li>
db1f069b 2070
c7017ecc
MS		 2071 <li><code>Photo_on_Matte_Paper</code>; Normal quality photo printing on matte paper.</li>
2072
2073 <li><code>Photo_on_Matte_Paper_-_Fine</code>; High quality photo printing on matte paper.</li>
db1f069b
MS		 2074
2075</ul>
2076
2077<p>The value string consists of pairs of keywords, either an option name and
2078choice (*MainKeyword OptionKeyword) or a preset identifier and value
c7017ecc
MS		 2079(com.apple.print.preset.foo value). The following preset identifiers are currently used:</p>
2080
2081<ul>
2082
2083 <li><code>com.apple.print.preset.graphicsType</code>; specifies the type of printing used for this printing - "General" for general purpose printing and "Photo" for photo printing.</li>
2084
2085 <li><code>com.apple.print.preset.media-front-coating</code>; specifies the media type selected by this preset - "none" (plain paper), "glossy", "high-gloss", "semi-gloss", "satin", "matte", and "autodetect".</li>
2086
2087 <li><code>com.apple.print.preset.output-mode</code>; specifies the output mode for this preset - "color" (default for color printers) or "monochrome" (grayscale, default for B&amp;W printers).</li>
2088
2089 <li><code>com.apple.print.preset.quality</code>; specifies the overall print quality selected by this preset - "low" (draft), "mid" (normal), or "high".</li>
2090
2091</ul>
db1f069b
MS		 2092
2093<p>Presets, like options, can also be localized in multiple languages.</p>
2094
2095<p>Examples:</p>
2096
2097<pre class='command'>
2098*APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: "
2099 *MediaType Glossy
2100 *ColorModel RGB
2101 *Resolution 300dpi
2102 com.apple.print.preset.graphicsType Photo
2103 com.apple.print.preset.quality mid
2104 com.apple.print.preset.media-front-coating glossy"
2105*End
2106*fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: ""
2107</pre>
2108
2109<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3>
2110
2111<p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p>
2112
10d09e33 2113<p>This keyword defines a GUI application that can be used to do printer
db1f069b
MS		 2114maintenance functions such as cleaning the print head(s). See ... for more
2115information.</p>
2116
2117<p>Examples:</p>
2118
2119<pre class='command'>
2120*% Define the printer utility application
2121*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
2122</pre>
2123
b9faaae1
MS		 2124<h3><span class='info'>Mac OS X 10.6</span><a name='APScannerOnly'>APScannerOnly</a></h3>
2125
2126<p class='summary'>*APScannerOnly: boolean</p>
2127
10d09e33 2128<p>This keyword specifies whether the device has scanning but no printing
b9faaae1
MS		 2129capabilities. The default is <tt>False</tt>.</p>
2130
2131<p>Examples:</p>
2132
2133<pre class='command'>
2134*APICADriver: True
2135*APScannerOnly: True
2136</pre>
2137
db1f069b
MS		 2138<h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3>
2139
2140<p class='summary'>*APScanAppBundleID: "bundle ID"</p>
2141
10d09e33 2142<p>This keyword defines the application to use when scanning pages from
db1f069b
MS		 2143the device.</p>
2144
2145<p>Examples:</p>
2146
2147<pre class='command'>
c5571a1d 2148*APICADriver: True
db1f069b
MS		 2149*APScanAppBundleID: "com.apple.ImageCaptureApp"
2150</pre>
2151
2152
2153<h2 class='title'><a name='HISTORY'>Change History</a></h2>
2154
10d09e33
MS		 2155<h3>Changes in CUPS 1.5</h3>
2156
2157<ul>
2158
2159 <li>Changes all instances of PPD attributes to PPD keywords, to be consistent with the parent specification from Adobe.</li>
2160
2161</ul>
2162
2163
c7017ecc
MS		 2164<h3>Changes in CUPS 1.4.5</h3>
2165
2166<ul>
2167
2168 <li>Added <a href='#cupsPrintQuality'><tt>cupsPrintQuality</tt></a> UI keyword.</li>
2169
2170 <li>Added new properties and values for the <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a> keyword.</li>
2171
2172</ul>
2173
2174
b0f6947b 2175<h3>Changes in CUPS 1.4</h3>
634763e8
MS		 2176
2177<ul>
2178
c5571a1d 2179 <li>Added <a href='#APICADriver'><tt>APICADriver</tt></a>
10d09e33 2180 keyword.</li>
c5571a1d 2181
749b1e90 2182 <li>Added <a href='#cupsCommands'><tt>cupsCommands</tt></a>
10d09e33 2183 keyword.</li>
634763e8 2184
749b1e90 2185 <li>Added <a href='#cupsMarkerName'><tt>cupsMarkerName</tt></a>
10d09e33 2186 keyword.</li>
634763e8 2187
749b1e90 2188 <li>Added <a href='#cupsMarkerNotice'><tt>cupsMarkerNotice</tt></a>
10d09e33 2189 keyword.</li>
75bd9771 2190
749b1e90 2191 <li>Added <a href='#cupsPJLDisplay'><tt>cupsPJLDisplay</tt></a>
10d09e33 2192 keyword.</li>
01ce6322 2193
58dc1933 2194 <li>Added <a href='#cupsSNMPSupplies'><tt>cupsSNMPSupplies</tt></a>
10d09e33 2195 keyword.</li>
58dc1933 2196
749b1e90
MS		 2197 <li>Added <a href='#cupsUIResolver'><tt>cupsUIResolver</tt></a> and
2198 <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>
10d09e33 2199 keywords.</li>
66ab9486 2200
749b1e90
MS		 2201 <li>Added
2202 <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a>,
2203 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a>,
2204 <a href='#cupsMinSize'><tt>cupsMinSize</tt></a>, and
10d09e33 2205 <a href='#cupsMaxSize'><tt>cupsMaxSize</tt></a> keywords.</li>
749b1e90 2206
634763e8
MS		 2207</ul>
2208
2209
b0f6947b 2210<h3>Changes in CUPS 1.3.1</h3>
db1f069b
MS		 2211
2212<ul>
2213
10d09e33 2214 <li>Added missing Mac OS X <tt>AP</tt> keywords.</li>
db1f069b
MS		 2215
2216 <li>Added section on auto-configuration including the
2217 <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt>
10d09e33 2218 keywords.</li>
db1f069b
MS		 2219
2220 <li>Minor reorganization.</li>
2221
2222</ul>
2223
ef416fc2 2224
b0f6947b 2225<h3>Changes in CUPS 1.3</h3>
f7deaa1a 2226
2227<ul>
2228
749b1e90
MS		 2229 <li>Added <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> and
2230 deprecated <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a>.</li>
bc44d920 2231
749b1e90
MS		 2232 <li>Added text URI information to
2233 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> documentation.</li>
bc44d920 2234
749b1e90
MS		 2235 <li>Added <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a>,
2236 <a href='#cupsIPPFinishings'><tt>cupsIPPFinishings</tt></a>, and
10d09e33 2237 <a href='#cupsPreFilter'><tt>cupsPreFilter</tt></a> keywords.</li>
09a101d6 2238
749b1e90
MS		 2239 <li>Added discussion of custom option code, sample
2240 <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li>
f7deaa1a 2241
2242</ul>
2243
b0f6947b 2244<h3>Changes in CUPS 1.2.8</h3>
b86bc4cf 2245
2246<ul>
2247
2248 <li>Added section on supported PostScript commands for raster
2249 drivers</li>
2250
2251</ul>
2252
b0f6947b 2253<h3>Changes in CUPS 1.2</h3>
ef416fc2 2254
2255<ul>
2256
10d09e33 2257 <li>Added globalization support keywords</li>
ef416fc2 2258
2259 <li>Added custom option values support</li>
2260
10d09e33 2261 <li>Added <a href='#APHelpBook'><tt>APHelpBook</tt></a> keyword</li>
4744bd90 2262
749b1e90 2263 <li>Added <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
10d09e33 2264 keyword</li>
a4d04587 2265
10d09e33 2266 <li>Added <a href='#cupsICCProfile'><tt>cupsICCProfile</tt></a> keyword</li>
ef416fc2 2267
10d09e33 2268 <li>Added <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword</li>
4744bd90 2269
10d09e33 2270 <li>Added <a href='#cupsLanguages'><tt>cupsLanguages</tt></a> keyword</li>
a4d04587 2271
10d09e33 2272 <li>Added <a href='#cupsPortMonitor'><tt>cupsPortMonitor</tt></a> keyword</li>
ef416fc2 2273
10d09e33 2274 <li>Removed <tt>cupsProtocol</tt> keyword</li>
ef416fc2 2275
2276</ul>
2277
b0f6947b 2278<h3>Changes in CUPS 1.1</h3>
ef416fc2 2279
2280<ul>
2281
10d09e33 2282 <li>Added <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a> keyword</li>
ef416fc2 2283
10d09e33 2284 <li>Added <tt>cupsProtocol</tt> keyword</li>
ef416fc2 2285
2286</ul>
10d09e33 2287</div>
ef416fc2 2288</body>
2289</html>
Unnamed repository; edit this file 'description' to name the repository.