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