doc/help/spec-ppd.html

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