doc/help/spec-ppd.html

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