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