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