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