doc/help/spec-ppd.html

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