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