doc/help/spec-ppd.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
   2 <html>
   3 <!-- SECTION: Specifications -->
   4 <head>
   5         <title>CUPS PPD Extensions</title>
   6         <meta name='keywords' content='Programming, PostScript Printer Description'>
   7         <link rel='stylesheet' type='text/css' href='../cups-printable.css'>
   8 </head>
   9 <body>
  10 <!--
  11   "$Id: spec-ppd.html 7677 2008-06-19 23:22:19Z mike $"
  12
  13   CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
  14
  15   Copyright 2007-2008 by Apple Inc.
  16   Copyright 1997-2007 by Easy Software Products.
  17
  18   These coded instructions, statements, and computer programs are the
  19   property of Apple Inc. and are protected by Federal copyright
  20   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
  21   which should have been included with this file.  If this file is
  22   file is missing or damaged, see the license at "http://www.cups.org/".
  23 -->
  24
  25 <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
  26
  27 <p>This specification describes the attributes and extensions
  28 that CUPS adds to <a
  29 href="http://partners.adobe.com/public/developer/en/ps/5003.PPD_Spec_v4.3.pdf">
  30 Adobe TechNote #5003: PostScript Printer Description File Format
  31 Specification Version 4.3</a>. PostScript Printer Description
  32 ("PPD") files describe the capabilities of each printer and are
  33 used by CUPS to support printer-specific features and intelligent
  34 filtering.</p>
  35
  36 <h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2>
  37
  38 <p>The PPD format is text-based and uses lines of up to 255
  39 characters terminated by a carriage return, linefeed, or
  40 combination of carriage return and line feed. The following ABNF
  41 definition [RFC2234] defines the general format of lines in a PPD
  42 file:</p>
  43
  44 <pre class='command'>
  45 PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
  46
  47 HEADER   = "*PPD-Adobe:" *WSP DQUOTE VERSION DQUOTE LINE-END
  48
  49 VERSION  = "4.0" / "4.1" / "4.2" / "4.3"
  50
  51 COMMENT  = "*%" *TCHAR LINE-END
  52
  53 DATA     = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
  54            1*(*WSP VALUE) LINE-END
  55
  56 VALUE    = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE
  57
  58 KCHAR    = ALPHA / DIGIT / "_" / "." / "-"
  59
  60 SCHAR    = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF
  61
  62 TCHAR    = %x20-7E / %xA0-FF
  63
  64 LINE-END = CR / LF / CR LF
  65 </pre>
  66
  67
  68 <h2 class='title'><a name='AUTOCONFIG'>Auto-Configuration</a></h2>
  69
  70 <p>CUPS supports several methods of auto-configuration via PPD attributes.
  71 <em>Currently these methods are only implemented on Mac OS X.</em></p>
  72
  73 <h3><span class='info'>Mac OS X 10.5</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3>
  74
  75 <p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</p>
  76
  77 <p>This attribute defines a program that sets the default option choices. It
  78 is run when a printer is added from the printer browser instead of the
  79 normal PostScript query and SNMP OID attribute lookups.</p>
  80
  81 <p>The program is provided with two arguments: the printer's device URI and
  82 the PPD file to be used for the printer. The program must write an updated
  83 PPD file to stdout.</p>
  84
  85 <p>Examples:</p>
  86
  87 <pre class='command'>
  88 *% Use our setup tool when adding a printer
  89 *APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool"
  90 </pre>
  91
  92 <h3><span class='info'>Mac OS X 10.2</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3>
  93
  94 <p class='summary'>*?<i>MainKeyword</i>: "<br>
  95   PostScript query code that writes a message using the = operator...<br>
  96 "<br>
  97 *End</p>
  98
  99 <p>The <tt>?<i>MainKeyword</i></tt> attribute defines PostScript code that
 100 determines the currently selected/enabled option keyword (choice) for the
 101 main keyword (option). It is typically used when communicating with USB,
 102 serial, Appletalk, and AppSocket (port 9100) printers.</p>
 103
 104 <p>The PostScript code typically sends its response back using the <tt>=</tt>
 105 operator.</p>
 106
 107 <p>Example:</p>
 108
 109 <pre class='command'>
 110 *OpenUI OptionDuplex/Duplexer Installed: Boolean
 111 *DuplexOptionDuplex: False
 112 *OptionDuplex False/Not Installed: ""
 113 *OptionDuplex True/Installed: ""
 114
 115 <em>*% Query the printer for the presence of the duplexer option...</em>
 116 *?OptionDuplex: "
 117   currentpagedevice /Duplex known
 118   {(True)} {(False)} ifelse
 119   = flush
 120 "
 121 *End
 122 *CloseUI: OptionDuplex
 123 </pre>
 124
 125 <h3><span class='info'>Mac OS X 10.4</span><a name='OID'>OIDMainKeyword</a></h3>
 126
 127 <p class='summary'>*?OID<i>MainKeyword</i>: ".n.n.n..."<br>
 128 *OID<i>MainKeyword</i> <i>OptionKeyword1</i>: "value"<br>
 129 ...<br>
 130 *OID<i>MainKeyword</i> <i>OptionKeywordN</i>: "value"</p>
 131
 132 <p>The <tt>OID<i>MainKeyword</i></tt> attribute is used to define
 133 SNMP OIDs that map to installable options. The first (query) line
 134 defines the OID to lookup on the network device. The second and
 135 subsequent attributes define a mapping from OID value to option
 136 keyword. Since SNMP is an IP-based network protocol, this method
 137 is typically only used to configure AppSocket, IPP, and LPD network
 138 printers.</p>
 139
 140 <p>Examples:</p>
 141
 142 <pre class='command'>
 143 *% Get the installed memory on the printer...
 144 *?OIDInstalledMemory: ".1.3.6.1.2.1.25.2.2.0"
 145 *OIDInstalledMemory 16MB: "16384 KBytes"
 146 *OIDInstalledMemory 32MB: "32768 KBytes"
 147 *OIDInstalledMemory 48MB: "49152 KBytes"
 148 *OIDInstalledMemory 72MB: "73728 KBytes"
 149 </pre>
 150
 151
 152 <h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
 153
 154 <p>CUPS supports three types of color profiles. The first type is
 155 based on sRGB and is used by the standard CUPS raster filters and
 156 GPL Ghostscript. The second type is based on ICC profiles and is
 157 used by the Quartz-based filters on MacOS X. The final type is
 158 based on well-known colorspaces such as sRGB and Adobe RGB.</p>
 159
 160 <blockquote><b>Note:</b>
 161
 162 <p>At this time, none of the CUPS raster
 163 filters support ICC profiles. This will be addressed as time
 164 and resources permit.</p>
 165
 166 </blockquote>
 167
 168 <h3><span class='info'>Deprecated</span><a name='cupsColorProfile'>cupsColorProfile</a></h3>
 169
 170 <p class='summary'>*cupsColorProfile Resolution/MediaType: "density
 171 gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
 172
 173 <p>This string attribute specifies an sRGB-based color profile
 174 consisting of gamma and density controls and a 3x3 CMY color
 175 transform matrix.</p>
 176
 177 <p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
 178 to act as a wildcard. Otherwise they must match one of the
 179 <tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
 180 the PPD file.</p>
 181
 182 <p>The <i>density</i> and <i>gamma</i> values define gamma and
 183 density adjustment function such that:</p>
 184
 185 <pre class='command'>
 186 f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
 187 </pre>
 188
 189 <p>The <i>m00</i> through <i>m22</i> values define a 3x3
 190 transformation matrix for the CMY color values. The density
 191 function is applied <i>after</i> the CMY transformation:</p>
 192
 193 <pre class='command'>
 194 | m00 m01 m02 |
 195 | m10 m11 m12 |
 196 | m20 m21 m22 |
 197 </pre>
 198
 199 <p>Examples:</p>
 200
 201 <pre class='command'>
 202 <em>*% Specify a profile for printing at 360dpi on all media types</em>
 203 *cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
 204
 205 <em>*% Specify a profile for printing at 720dpi on Glossy media</em>
 206 *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"
 207
 208 <em>*% Specify a default profile for printing at all other resolutions and media types</em>
 209 *cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
 210 </pre>
 211
 212
 213 <h3><span class='info'>Mac OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3>
 214
 215 <p class='summary'>*cupsICCProfile
 216 ColorModel.MediaType.Resolution/Description: "filename"</p>
 217
 218 <p>This attribute specifies an ICC color profile that is
 219 used to convert the document colors to the device
 220 colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
 221 <tt>Resolution</tt> keywords specify a selector for color
 222 profiles. If omitted, the color profile will match any option
 223 keyword for the corresponding main keyword.</p>
 224
 225 <p>The <tt>Description</tt> specifies human-readable text that
 226 is associated with the color profile. The <tt>filename</tt>
 227 portion specifies the ICC color profile to use; if the filename
 228 is not absolute, it is loaded relative to the
 229 <var>/usr/share/cups/profiles</var> directory.</p>
 230
 231 <p>Examples:</p>
 232
 233 <pre class='command'>
 234 <em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
 235 *cupsICCProfile CMYK..360dpi/360dpi CMYK: "/Library/Printers/vendor/Profiles/foo-360-cmyk.icc"
 236
 237 <em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
 238 *cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "/Library/Printers/vendor/Profiles/foo-720-glossy-rgb.icc"
 239
 240 <em>*% Specify a default profile for printing at all other resolutions and media types</em>
 241 *cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc"
 242 </pre>
 243
 244 <h4>Customizing the Profile Selection Keywords</h4>
 245
 246 <p>The <tt>MediaType</tt> and <tt>Resolution</tt> keywords can be
 247 reassigned to different main keywords, allowing drivers to do
 248 color profile selection based on different parameters. The
 249 <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt>
 250 attributes define the mapping from selector to main keyword:</p>
 251
 252 <pre class='command'>
 253 *cupsICCQualifier2: MainKeyword2
 254 *cupsICCQualifier3: MainKeyword3
 255 </pre>
 256
 257 <p>The default mapping is as follows:</p>
 258
 259 <pre class='command'>
 260 *cupsICCQualifier2: MediaType
 261 *cupsICCQualifier3: Resolution
 262 </pre>
 263
 264 <h3><span class='info'>Mac OS X 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3>
 265
 266 <p class='summary'>*<a href='#APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a>: true<br>
 267 *<a href='#APCustomColorMatchingName'>APCustomColorMatchingName</a> name/text: ""<br>
 268 *<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br>
 269 *<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</p>
 270
 271 <p>These attributes tell the Mac OS X raster filters that the printer
 272 driver provides its own custom color matching and that generic color
 273 profiles should be used when generating 1-, 3-, and 4-component raster
 274 data as requested by the driver. The <tt>APCustomColorMatchingProfile</tt>
 275 and <tt>APDefaultColorMatchingProfile</tt> attributes specify alternate
 276 color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p>
 277
 278 <h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4>
 279
 280 <p class='summary'>*APCustomColorMatchingName name/text: ""</p>
 281
 282 <p>This attribute defines an alternate name for the color matching
 283 provided by a driver in the <var>Color Matching</var> print panel.
 284 The default is to use the name "Vendor Matching" or its localized
 285 equivalent.</p>
 286
 287 <p>Examples:</p>
 288
 289 <pre class='command'>
 290 *% Define the names for our color matching...
 291 *APCustomColorMatchingName name/AcmeColor(tm): ""
 292 *fr.APCustomColorMatchingName name/La AcmeColor(tm): ""
 293 </pre>
 294
 295 <h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4>
 296
 297 <p class='summary'>*APCustomColorMatchingProfile: name</p>
 298
 299 <p>This attribute defines a supported RGB color profile that can be used
 300 when doing custom color matching. Currently only <tt>sRGB</tt> and
 301 <tt>AdobeRGB</tt> are supported. If not specified, RGB data will use the
 302 Generic RGB colorspace.</p>
 303
 304 <blockquote><b>Note:</b>
 305
 306 <p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> attributes,
 307 you are responsible for providing the necessary user interface controls to
 308 select the profile in a <a href='#APDialogExtension'>print dialog pane</a>.
 309 Add the named profile to the print settings using the key
 310 <tt>kPMCustomColorMatchingProfileKey</tt>.</p>
 311
 312 </blockquote>
 313
 314 <p>Examples:</p>
 315
 316 <pre class='command'>
 317 *% Use sRGB for RGB color by default, but support both sRGB and AdobeRGB
 318 *APSupportsCustomColorMatching: true
 319 *APDefaultCustomColorMatchingProfile: sRGB
 320 *APCustomColorMatchingProfile: sRGB
 321 *APCustomColorMatchingProfile: AdobeRGB
 322 </pre>
 323
 324 <h4><span class='info'>Mac OS X 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4>
 325
 326 <p class='summary'>*APDefaultCustomColorMatchingProfile: name</p>
 327
 328 <p>This attribute defines the default RGB color profile that will be used
 329 when doing custom color matching. Currently only <tt>sRGB</tt> and
 330 <tt>AdobeRGB</tt> are supported.</p>
 331
 332 <p>Examples:</p>
 333
 334 <pre class='command'>
 335 *% Use sRGB for RGB color by default
 336 *APSupportsCustomColorMatching: true
 337 *APDefaultCustomColorMatchingProfile: sRGB
 338 </pre>
 339
 340 <h4><span class='info'>Mac OS X 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4>
 341
 342 <p class='summary'>*APSupportsCustomColorMatching: boolean</p>
 343
 344 <p>This attribute specifies that the driver provides its own custom color
 345 matching. When <tt>true</tt>, the default hand-off colorspace will be
 346 Generic Gray, Generic RGB, or Generic CMYK depending on the number of
 347 components the driver requests. The <a
 348 href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a>
 349 attribute can be used to override the default 3-component (RGB) colorspace.</p>
 350
 351 <p>The default for <tt>APSupportsCustomColorMatching</tt> is <tt>false</tt>.</p>
 352
 353 <p>Examples:</p>
 354
 355 <pre class='command'>
 356 *APSupportsCustomColorMatching: true
 357 *APDefaultCustomColorMatchingProfile: sRGB
 358 </pre>
 359
 360
 361 <h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
 362
 363 <p>CUPS 1.2 and higher adds support for PPD files containing multiple
 364 languages by following the following additional rules:</p>
 365
 366 <ol>
 367
 368         <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
 369
 370         <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
 371
 372         <li>The <tt>cupsLanguages</tt> attribute MUST be provided and
 373         list each of the supported locales in the PPD file</li>
 374
 375         <li>Main and option keywords MUST NOT exceed 34 (instead of 40)
 376         characters to allow room for the locale prefixes in translation
 377         attributes</li>
 378
 379         <li>The main keyword "Translation" MUST NOT be used</li>
 380
 381         <li>Translation strings included with the main and option
 382         keywords MUST NOT contain characters outside the ASCII
 383         subset of ISOLatin1 and UTF-8; developers wishing to use
 384         characters outside ASCII MUST provide a separate set of
 385         English localization attributes for the affected keywords.</li>
 386
 387         <li>Localizations are specified using a locale prefix of
 388         the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
 389         language code and "CC" is the 2-letter ISO country
 390         code<ul>
 391                 <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li>
 392                 <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li>
 393         </ul></li>
 394
 395         <li>Locale-specific translation strings MUST be encoded
 396         using UTF-8.</li>
 397
 398         <li>Main keywords MUST be localized using one of the
 399         following forms:
 400         <p><tt>*ll.Translation MainKeyword/translation
 401         text: ""</tt><br />
 402         <tt>*ll_CC.Translation MainKeyword/translation
 403         text: ""</tt></p></li>
 404
 405         <li>Option keywords MUST be localized using one of the
 406         following forms:
 407         <p><tt>*ll.MainKeyword OptionKeyword/translation
 408         text: ""</tt><br />
 409         <tt>*ll_CC.MainKeyword OptionKeyword/translation
 410         text: ""</tt></p></li>
 411
 412         <li>Localization attributes MAY appear anywhere after the
 413         first line of the PPD file</li>
 414
 415 </ol>
 416
 417 <blockquote><b>Note:</b>
 418
 419 <p>We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt>
 420 and limit the allowed base translation strings to ASCII to avoid
 421 character coding issues that would otherwise occur. In addition,
 422 requiring the base translation strings to be in English allows
 423 for easier fallback translation when no localization is provided
 424 in the PPD file for a given locale.</p>
 425
 426 </blockquote>
 427
 428 <p>Examples:</p>
 429
 430 <pre class='command'>
 431 *LanguageVersion: English
 432 *LanguageEncoding: ISOLatin1
 433 *cupsLanguages: "de fr_CA"
 434 *ModelName: "Foobar Laser 9999"
 435
 436 <em>*% Localize ModelName for French and German</em>
 437 *fr_CA.Translation ModelName/La Foobar Laser 9999: ""
 438 *de.Translation ModelName/Foobar LaserDrucken 9999: ""
 439
 440 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
 441 <em>*% Localize printer-state-reason for French and German</em>
 442 *fr_CA.cupsIPPReason com.vendor-error/Une erreur s&egrave;rieuse s'est produite: "/help/com.vendor/error.html"
 443 *de.cupsIPPReason com.vendor-error/Eine ernste St&ouml;rung trat: "/help/com.vendor/error.html"
 444
 445 ...
 446
 447 *OpenUI *InputSlot/Paper Source: PickOne
 448 *OrderDependency: 10 AnySetup *InputSlot
 449 *DefaultInputSlot: Auto
 450 <em>*% Localize InputSlot for French and German</em>
 451 *fr_CA.Translation InputSlot/Papier source: ""
 452 *de.Translation InputSlot/Papiereinzug: ""
 453 *InputSlot Auto/Default: "&lt;&lt;/ManualFeed false&gt;&gt;setpagedevice"
 454 <em>*% Localize InputSlot=Auto for French and German</em>
 455 *fr_CA.InputSlot Auto/Par Defaut: ""
 456 *de.InputSlot Auto/Standard: ""
 457 *InputSlot Manual/Manual Feed: "&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice"
 458 <em>*% Localize InputSlot=Manual for French and German</em>
 459 *fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: ""
 460 *de.InputSlot Manual/Manueller Einzug: ""
 461 *CloseUI: *InputSlot
 462 </pre>
 463
 464
 465 <h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
 466
 467 <p>CUPS supports custom options using an extension of the
 468 <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt>
 469 syntax:</p>
 470
 471 <pre class='command'>
 472 *CustomFoo True: "command"
 473 *ParamCustomFoo Name1/Text 1: order type minimum maximum
 474 *ParamCustomFoo Name2/Text 2: order type minimum maximum
 475 ...
 476 *ParamCustomFoo NameN/Text N: order type minimum maximum
 477 </pre>
 478
 479 <p>When the base option is part of the <tt>JCLSetup</tt> section,
 480 the "command" string contains JCL commands with "\order"
 481 placeholders for each numbered parameter. The CUPS API handles
 482 any necessary value quoting for HP-PJL commands. For example, if
 483 the JCL command string is "@PJL SET PASSCODE=\1" and the first
 484 option value is "1234" then CUPS will output the string
 485 "@PJL SET PASSCODE=1234".</p>
 486
 487 <p>For non-<tt>JCLSetup</tt> options, the "order" value is a
 488 number from 1 to N and specifies the order of values as they are
 489 placed on the stack before the command. For example, if the
 490 PostScript command string is
 491 "&lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice" and the
 492 option value is "2.0" then CUPS will output the string
 493 "2.0 &lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice".</p>
 494
 495 <p>The "type" is one of the following keywords:</p>
 496
 497 <ul>
 498
 499         <li><tt>curve</tt> - a real value from "minimum" to
 500         "maximum" representing a gamma correction curve using the
 501         function: f(x) = x <sup>value</sup></li>
 502
 503         <li><tt>int</tt> - an integer value from "minimum" to
 504         "maximum"</li>
 505
 506         <li><tt>invcurve</tt> - a real value from "minimum" to
 507         "maximum" representing a gamma correction curve using the
 508         function: f(x) = x <sup>1 / value</sup></li>
 509
 510         <li><tt>passcode</tt> - a string of numbers value with a
 511         minimum of "minimum" numbers and a maximum of "maximum"
 512         numbers ("minimum" and "maximum" are numbers and passcode
 513         strings are not displayed in the user interface)</li>
 514
 515         <li><tt>password</tt> - a string value with a minimum of
 516         "minimum" characters and a maximum of "maximum"
 517         characters ("minimum" and "maximum" are numbers and password
 518         strings are not displayed in the user interface)</li>
 519
 520         <li><tt>points</tt> - a measurement value in points from
 521         "minimum" to "maximum"</li>
 522
 523         <li><tt>real</tt> - a real value from "minimum" to
 524         "maximum"</li>
 525
 526         <li><tt>string</tt> - a string value with a minimum of
 527         "minimum" characters and a maximum of "maximum"
 528         characters ("minimum" and "maximum" are numbers)</li>
 529
 530 </ul>
 531
 532 <blockquote><b>Note:</b>
 533
 534 <p>Custom options are not directly supported by the Mac OS X Print Dialog
 535 nor by the CUPS web interface at this time. Vendors that use custom
 536 options on Mac OS X must provide their own user interface via the
 537 <a href='#APDialogExtension'><tt>APDialogExtension</tt></a> attribute.</p>
 538
 539 </blockquote>
 540
 541 <p>Examples:</p>
 542
 543 <pre class='command'>
 544 <em>*% Base JCL key code option</em>
 545 *JCLOpenUI JCLPasscode/Key Code: PickOne
 546 *OrderDependency: 10 JCLSetup *JCLPasscode
 547 *DefaultJCLPasscode: None
 548 *JCLPasscode None/No Code: ""
 549 *JCLPasscode 1111: "@PJL SET PASSCODE = 1111&lt;0A&gt;"
 550 *JCLPasscode 2222: "@PJL SET PASSCODE = 2222&lt;0A&gt;"
 551 *JCLPasscode 3333: "@PJL SET PASSCODE = 3333&lt;0A&gt;"
 552 *JCLCloseUI: *JCLPasscode
 553
 554 <em>*% Custom JCL key code option</em>
 555 *CustomJCLPasscode True: "@PJL SET PASSCODE = \1&lt;0A&gt;"
 556 *ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
 557
 558
 559 <em>*% Base PostScript watermark option</em>
 560 *OpenUI WatermarkText/Watermark Text: PickOne
 561 *OrderDependency: 10 AnySetup *WatermarkText
 562 *DefaultWatermarkText: None
 563 *WatermarkText None: ""
 564 *WatermarkText Draft: "&lt;&lt;/cupsString1(Draft)&gt;&gt;setpagedevice"
 565 *CloseUI: *WatermarkText
 566
 567 <em>*% Custom PostScript watermark option</em>
 568 *CustomWatermarkText True: "&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice"
 569 *ParamCustomWatermarkText Text: 1 string 0 32
 570
 571
 572 <em>*% Base PostScript gamma/density option</em>
 573 *OpenUI GammaDensity/Gamma and Density: PickOne
 574 *OrderDependency: 10 AnySetup *GammaDensity
 575 *DefaultGammaDensity: Normal
 576 *GammaDensity Normal/Normal: "&lt;&lt;/cupsReal1 1.0/cupsReal2 1.0&gt;&gt;setpagedevice"
 577 *GammaDensity Light/Lighter: "&lt;&lt;/cupsReal1 0.9/cupsReal2 0.67&gt;&gt;setpagedevice"
 578 *GammaDensity Dark/Darker: "&lt;&lt;/cupsReal1 1.1/cupsReal2 1.5&gt;&gt;setpagedevice"
 579 *CloseUI: *GammaDensity
 580
 581 <em>*% Custom PostScript gamma/density option</em>
 582 *CustomGammaDensity True: "&lt;&lt;/cupsReal1 3 -1 roll/cupsReal2 5 -1&gt;&gt;setpagedevice"
 583 *ParamCustomGammaDensity Gamma: 1 curve 0.1 10
 584 *ParamCustomGammaDensity Density: 2 real 0 2
 585 </pre>
 586
 587
 588 <h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2>
 589
 590 <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 attributes such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p>
 591
 592 <pre class='command'>
 593 *PageSize A4: "&lt;&lt;/PageSize[595 842]&gt;&gt;setpagedevice"
 594 </pre>
 595
 596 <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>
 597
 598 <pre class='command'>
 599 *CustomWatermarkText True: "&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice"
 600 </pre>
 601
 602 <p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p>
 603
 604 <pre class='command'>
 605 (My Watermark)
 606 &lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice
 607 </pre>
 608
 609 <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>
 610
 611 <pre class='command'>
 612 &lt;&lt;/cupsString1(My Watermark)&gt;&gt;setpagedevice
 613 </pre>
 614
 615 <p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p>
 616
 617 <h3>Custom Page Size Code</a></h3>
 618
 619 <p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p>
 620
 621 <pre class='command'>
 622 *ParamCustomPageSize Width:        1 points <i>min-width max-width</i>
 623 *ParamCustomPageSize Height:       2 points <i>min-height max-height</i>
 624 *ParamCustomPageSize WidthOffset:  3 points 0 0
 625 *ParamCustomPageSize HeightOffset: 4 points 0 0
 626 *ParamCustomPageSize Orientation:  5 int 0 0
 627 *CustomPageSize True: "pop pop pop &lt;&lt;/PageSize[5 -2 roll]/ImagingBBox null&gt;&gt;setpagedevice"
 628 </pre>
 629
 630 <h3>Supported PostScript Operators</a></h3>
 631
 632 <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>
 633
 634 <ul>
 635
 636         <li><tt>&lt;&lt;</tt> - Start a dictionary.</li>
 637
 638         <li><tt>&gt;&gt;</tt> - End a dictionary.</li>
 639
 640         <li><tt>[</tt> - Start an array.</li>
 641
 642         <li><tt>]</tt> - End an array.</li>
 643
 644         <li><tt>copy</tt> - Copy the top N objects on the stack.</li>
 645
 646         <li><tt>dup</tt> - Copy the top object on the stack.</li>
 647
 648         <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li>
 649
 650         <li><tt>pop</tt> - Pop the top object on the stack.</li>
 651
 652         <li><tt>roll</tt> - Shift the top N objects on the stack.</li>
 653
 654         <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li>
 655
 656 </ul>
 657
 658 <blockquote><b>Note:</b>
 659
 660 <p><em>Never</em> use the unsupported <tt>dict</tt> or <tt>put</tt>
 661 operators in your option code. These operators are typically used in
 662 option code dating back to Level 1 PostScript printers, which did not
 663 support the simpler <tt>&lt;&lt;</tt> or <tt>&gt;&gt;</tt> operators.
 664 If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can
 665 rewrite it very easily to use the newer <tt>&lt;&lt;</tt> and
 666 <tt>&gt;&gt;</tt> operators instead. For example, the following code
 667 to set the page size:</p>
 668
 669 <style type='text/css'><!--
 670 PRE B {
 671   background: #000000;
 672   color: #ffffff;
 673   padding: 2px 5px;
 674 }
 675 --></style>
 676
 677 <pre class='command'>
 678 <b>1 dict dup</b> /PageSize [612 792] <b>put</b> setpagedevice
 679 </pre>
 680
 681 <p>can be rewritten as:</p>
 682
 683 <pre class='command'>
 684 <b>&lt;&lt;</b> /PageSize [612 792] <b>&gt;&gt;</b> setpagedevice
 685 </pre>
 686
 687 </blockquote>
 688
 689 <h3>Supported Page Device Attributes</a></h3>
 690
 691 <p>Table 2 shows the supported page device attributes along with PostScript code examples.</p>
 692
 693 <div class='table'>
 694 <table summary='Supported Page Device Attributes'>
 695 <caption>Table 2: <a name='TABLE_2'>Supported Page Device Attributes</a></caption>
 696 <thead>
 697 <tr>
 698         <th>Name(s)</th>
 699         <th>Type</th>
 700         <th>Description</th>
 701         <th>Example(s)</th>
 702 </tr>
 703 </thead>
 704 <tbody>
 705 <tr valign='top'>
 706         <td><tt>AdvanceDistance</tt></td>
 707         <td>Integer</td>
 708         <td>Specifies the number of points to advance roll media after printing.</td>
 709         <td><tt>&lt;&lt;/AdvanceDistance 18&gt;&gt;setpagedevice</tt></td>
 710 </tr>
 711 <tr valign='top'>
 712         <td><tt>AdvanceMedia</tt></td>
 713         <td>Integer</td>
 714         <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>
 715         <td><tt>&lt;&lt;/AdvanceMedia 4&gt;&gt;setpagedevice</tt></td>
 716 </tr>
 717 <tr valign='top'>
 718         <td><tt>Collate</tt></td>
 719         <td>Boolean</td>
 720         <td>Specifies whether collated copies are required.</td>
 721         <td><tt>&lt;&lt;/Collate true&gt;&gt;setpagedevice</tt></td>
 722 </tr>
 723 <tr valign='top'>
 724         <td><tt>CutMedia</tt></td>
 725         <td>Integer</td>
 726         <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>
 727         <td><tt>&lt;&lt;/CutMedia 1&gt;&gt;setpagedevice</tt></td>
 728 </tr>
 729 <tr valign='top'>
 730         <td><tt>Duplex</tt></td>
 731         <td>Boolean</td>
 732         <td>Specifies whether 2-sided printing is required.</td>
 733         <td><tt>&lt;&lt;/Duplex true&gt;&gt;setpagedevice</tt></td>
 734 </tr>
 735 <tr valign='top'>
 736         <td><tt>HWResolution</tt></td>
 737         <td>Integer Array</td>
 738         <td>Specifies the resolution of the page image in pixels per inch.</td>
 739         <td><tt>&lt;&lt;/HWResolution[1200 1200]&gt;&gt;setpagedevice</tt></td>
 740 </tr>
 741 <tr valign='top'>
 742         <td><tt>InsertSheet</tt></td>
 743         <td>Boolean</td>
 744         <td>Specifies whether to insert a blank sheet before the job.</td>
 745         <td><tt>&lt;&lt;/InsertSheet true&gt;&gt;setpagedevice</tt></td>
 746 </tr>
 747 <tr valign='top'>
 748         <td><tt>Jog</tt></td>
 749         <td>Integer</td>
 750         <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>
 751         <td><tt>&lt;&lt;/Jog 2&gt;&gt;setpagedevice</tt></td>
 752 </tr>
 753 <tr valign='top'>
 754         <td><tt>LeadingEdge</tt></td>
 755         <td>Integer</td>
 756         <td>Specifies the leading edge of the media: 0 = top, 1 = right, 2 = bottom, 3 = left.</td>
 757         <td><tt>&lt;&lt;/LeadingEdge 0&gt;&gt;setpagedevice</tt></td>
 758 </tr>
 759 <tr valign='top'>
 760         <td><tt>ManualFeed</tt></td>
 761         <td>Boolean</td>
 762         <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>
 763         <td><tt>&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice</tt></td>
 764 </tr>
 765 <tr valign='top'>
 766         <td><tt>MediaClass</tt></td>
 767         <td>String</td>
 768         <td>Specifies a named media.</td>
 769         <td><tt>&lt;&lt;/MediaClass (Invoices)&gt;&gt;setpagedevice</tt></td>
 770 </tr>
 771 <tr valign='top'>
 772         <td><tt>MediaColor</tt></td>
 773         <td>String</td>
 774         <td>Specifies the color of the media.</td>
 775         <td><tt>&lt;&lt;/MediaColor &gt;&gt;setpagedevice</tt></td>
 776 </tr>
 777 <tr valign='top'>
 778         <td><tt>MediaPosition</tt></td>
 779         <td>Integer</td>
 780         <td>Specifies the tray or source of the media.</td>
 781         <td><tt>&lt;&lt;/MediaPosition 12&gt;&gt;setpagedevice</tt></td>
 782 </tr>
 783 <tr valign='top'>
 784         <td><tt>MediaType</tt></td>
 785         <td>String</td>
 786         <td>Specifies the general media type.</td>
 787         <td><tt>&lt;&lt;/MediaType (Glossy)&gt;&gt;setpagedevice</tt></td>
 788 </tr>
 789 <tr valign='top'>
 790         <td><tt>MediaWeight</tt></td>
 791         <td>Integer</td>
 792         <td>Specifies the media weight in grams per meter<sup>2</sup>.</td>
 793         <td><tt>&lt;&lt;/MediaWeight 100&gt;&gt;setpagedevice</tt></td>
 794 </tr>
 795 <tr valign='top'>
 796         <td><tt>MirrorPrint</tt></td>
 797         <td>Boolean</td>
 798         <td>Specifies whether to flip the output image horizontally.</td>
 799         <td><tt>&lt;&lt;/MirrorPrint true&gt;&gt;setpagedevice</tt></td>
 800 </tr>
 801 <tr valign='top'>
 802         <td><tt>NegativePrint</tt></td>
 803         <td>Boolean</td>
 804         <td>Specifies whether to invert the output image.</td>
 805         <td><tt>&lt;&lt;/NegativePrint true&gt;&gt;setpagedevice</tt></td>
 806 </tr>
 807 <tr valign='top'>
 808         <td><tt>NumCopies</tt></td>
 809         <td>Integer</td>
 810         <td>Specifies the number of copies to produce of each page.</td>
 811         <td><tt>&lt;&lt;/NumCopies 100&gt;&gt;setpagedevice</tt></td>
 812 </tr>
 813 <tr valign='top'>
 814         <td><tt>Orientation</tt></td>
 815         <td>Integer</td>
 816         <td>Specifies the orientation of the output: 0 = portrait, 1 = landscape rotated counter-clockwise, 2 = upside-down, 3 = landscape rotated clockwise.</td>
 817         <td><tt>&lt;&lt;/Orientation 3&gt;&gt;setpagedevice</tt></td>
 818 </tr>
 819 <tr valign='top'>
 820         <td><tt>OutputFaceUp</tt></td>
 821         <td>Boolean</td>
 822         <td>Specifies whether to place the media face-up in the output bin/tray.</td>
 823         <td><tt>&lt;&lt;/OutputFaceUp true&gt;&gt;setpagedevice</tt></td>
 824 </tr>
 825 <tr valign='top'>
 826         <td><tt>OutputType</tt></td>
 827         <td>String</td>
 828         <td>Specifies the output type name.</td>
 829         <td><tt>&lt;&lt;/OutputType (Photo)&gt;&gt;setpagedevice</tt></td>
 830 </tr>
 831 <tr valign='top'>
 832         <td><tt>PageSize</tt></td>
 833         <td>Integer/Real Array</td>
 834         <td>Specifies the width and length/height of the page in points.</td>
 835         <td><tt>&lt;&lt;/PageSize[595 842]&gt;&gt;setpagedevice</tt></td>
 836 </tr>
 837 <tr valign='top'>
 838         <td><tt>Separations</tt></td>
 839         <td>Boolean</td>
 840         <td>Specifies whether to produce color separations.</td>
 841         <td><tt>&lt;&lt;/Separations true&gt;&gt;setpagedevice</tt></td>
 842 </tr>
 843 <tr valign='top'>
 844         <td><tt>TraySwitch</tt></td>
 845         <td>Boolean</td>
 846         <td>Specifies whether to switch trays automatically.</td>
 847         <td><tt>&lt;&lt;/TraySwitch true&gt;&gt;setpagedevice</tt></td>
 848 </tr>
 849 <tr valign='top'>
 850         <td><tt>Tumble</tt></td>
 851         <td>Boolean</td>
 852         <td>Specifies whether the back sides of pages are rotated 180 degrees.</td>
 853         <td><tt>&lt;&lt;/Tumble true&gt;&gt;setpagedevice</tt></td>
 854 </tr>
 855 <tr valign='top'>
 856         <td><tt>cupsBorderlessScalingFactor</tt></td>
 857         <td>Real</td>
 858         <td>Specifies the amount to scale the page image dimensions.</td>
 859         <td><tt>&lt;&lt;/cupsBorderlessScalingFactor 1.01&gt;&gt;setpagedevice</tt></td>
 860 </tr>
 861 <tr valign='top'>
 862         <td><tt>cupsColorOrder</tt></td>
 863         <td>Integer</td>
 864         <td>Specifies the order of colors: 0 = chunked, 1 = banded, 2 = planar.</td>
 865         <td><tt>&lt;&lt;/cupsColorOrder 0&gt;&gt;setpagedevice</tt></td>
 866 </tr>
 867 <tr valign='top'>
 868         <td><tt>cupsColorSpace</tt></td>
 869         <td>Integer</td>
 870         <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>
 871         <td><tt>&lt;&lt;/cupsColorSpace 1 &gt;&gt;setpagedevice</tt></td>
 872 </tr>
 873 <tr valign='top'>
 874         <td><tt>cupsCompression</tt></td>
 875         <td>Integer</td>
 876         <td>Specifies a driver compression type/mode.</td>
 877         <td><tt>&lt;&lt;/cupsCompression 2&gt;&gt;setpagedevice</tt></td>
 878 </tr>
 879 <tr valign='top'>
 880         <td><tt>cupsInteger0<br>
 881         ...<br>
 882         cupsInteger15</tt></td>
 883         <td>Integer</td>
 884         <td>Specifies driver integer values.</td>
 885         <td><tt>&lt;&lt;/cupsInteger11 1234&gt;&gt;setpagedevice</tt></td>
 886 </tr>
 887 <tr valign='top'>
 888         <td><tt>cupsMarkerType</tt></td>
 889         <td>String</td>
 890         <td>Specifies the type of ink/toner to use.</td>
 891         <td><tt>&lt;&lt;/cupsMarkerType (Black+Color)&gt;&gt;setpagedevice</tt></td>
 892 </tr>
 893 <tr valign='top'>
 894         <td><tt>cupsMediaType</tt></td>
 895         <td>Integer</td>
 896         <td>Specifies a numeric media type.</td>
 897         <td><tt>&lt;&lt;/cupsMediaType 999&gt;&gt;setpagedevice</tt></td>
 898 </tr>
 899 <tr valign='top'>
 900         <td><tt>cupsPageSizeName</tt></td>
 901         <td>String</td>
 902         <td>Specifies the name of the page size.</td>
 903         <td><tt>&lt;&lt;/cupsPageSizeName (A4.Full)&gt;&gt;setpagedevice</tt></td>
 904 </tr>
 905 <tr valign='top'>
 906         <td><tt>cupsPreferredBitsPerColor</tt></td>
 907         <td>Integer</td>
 908         <td>Specifies the preferred number of bits per color, typically 8 or 16.</td>
 909         <td><tt>&lt;&lt;/cupsPreferredBitsPerColor 16&gt;&gt;setpagedevice</tt></td>
 910 </tr>
 911 <tr valign='top'>
 912         <td><tt>cupsReal0<br>
 913         ...<br>
 914         cupsReal15</tt></td>
 915         <td>Real</td>
 916         <td>Specifies driver real number values.</td>
 917         <td><tt>&lt;&lt;/cupsReal15 1.234&gt;&gt;setpagedevice</tt></td>
 918 </tr>
 919 <tr valign='top'>
 920         <td><tt>cupsRenderingIntent</tt></td>
 921         <td>String</td>
 922         <td>Specifies the color rendering intent.</td>
 923         <td><tt>&lt;&lt;/cupsRenderingIntent (AbsoluteColorimetric)&gt;&gt;setpagedevice</tt></td>
 924 </tr>
 925 <tr valign='top'>
 926         <td><tt>cupsRowCount</tt></td>
 927         <td>Integer</td>
 928         <td>Specifies the number of rows of raster data to print on each line for some drivers.</td>
 929         <td><tt>&lt;&lt;/cupsRowCount 24&gt;&gt;setpagedevice</tt></td>
 930 </tr>
 931 <tr valign='top'>
 932         <td><tt>cupsRowFeed</tt></td>
 933         <td>Integer</td>
 934         <td>Specifies the number of rows to feed between passes for some drivers.</td>
 935         <td><tt>&lt;&lt;/cupsRowFeed 17&gt;&gt;setpagedevice</tt></td>
 936 </tr>
 937 <tr valign='top'>
 938         <td><tt>cupsRowStep</tt></td>
 939         <td>Integer</td>
 940         <td>Specifies the number of lines between columns/rows on the print head for some drivers.</td>
 941         <td><tt>&lt;&lt;/cupsRowStep 2&gt;&gt;setpagedevice</tt></td>
 942 </tr>
 943 <tr valign='top'>
 944         <td><tt>cupsString0<br>
 945         ...<br>
 946         cupsString15</tt></td>
 947         <td>String</td>
 948         <td>Specifies driver string values.</td>
 949         <td><tt>&lt;&lt;/cupsString0(String Value)&gt;&gt;setpagedevice</tt></td>
 950 </tr>
 951 </tbody>
 952 </table></div>
 953
 954
 955 <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
 956
 957 <h3><span class='info'>CUPS 1.3</span><a name='cupsBackSide'>cupsBackSide</a></h3>
 958
 959 <p class='summary'>*cupsBackSide: keyword</p>
 960
 961 <p>This attribute requests special handling of the back side of pages
 962 when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a>
 963 shows the supported keyword values for this attribute and their effect
 964 on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt>
 965 is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver
 966 will receive print data starting at the bottom right corner of the page, with
 967 each line going right-to-left instead of left-to-right. The default value is
 968 <code>Normal</code>.</p>
 969
 970 <blockquote><b>Note:</b>
 971
 972 <p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt>
 973 attribute - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt>
 974 will be ignored.</p>
 975
 976 </blockquote>
 977
 978 <div class='table'>
 979 <table width='80%' summary='Back Side Raster Coordinate System'>
 980 <caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption>
 981 <thead>
 982 <tr>
 983         <th>cupsBackSide</th>
 984         <th>Tumble Value</th>
 985         <th>Image Presentation</th>
 986 </tr>
 987 </thead>
 988 <tbody>
 989 <tr>
 990         <td><code>Normal</code></td>
 991         <td><code>false</code></td>
 992         <td>Left-to-right, top-to-bottom</td>
 993 </tr>
 994 <tr>
 995         <td><code>Normal</code></td>
 996         <td><code>true</code></td>
 997         <td>Left-to-right, top-to-bottom</td>
 998 </tr>
 999 <tr>
1000         <td><code>ManualTumble</code></td>
1001         <td><code>false</code></td>
1002         <td>Left-to-right, top-to-bottom</td>
1003 </tr>
1004 <tr>
1005         <td><code>ManualTumble</code></td>
1006         <td><code>true</code></td>
1007         <td>Right-to-left, bottom-to-top</td>
1008 </tr>
1009 <tr>
1010         <td><code>Rotated</code></td>
1011         <td><code>false</code></td>
1012         <td>Right-to-left, bottom-to-top</td>
1013 </tr>
1014 <tr>
1015         <td><code>Rotated</code></td>
1016         <td><code>true</code></td>
1017         <td>Right-to-left, top-to-bottom</td>
1018 </tr>
1019 <tr>
1020         <td><code>Flipped</code> *</td>
1021         <td><code>false</code></td>
1022         <td>Left-to-right, bottom-to-top</td>
1023 </tr>
1024 <tr>
1025         <td><code>Flipped</code> *</td>
1026         <td><code>true</code></td>
1027         <td>Right-to-left, top-to-bottom</td>
1028 </tr>
1029 </tbody>
1030 </table>
1031 </div>
1032
1033 <p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p>
1034
1035 <div class='figure'><table summary='Back side images'>
1036 <caption>Figure 1: Back side images</caption>
1037 <tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr>
1038 </table></div>
1039
1040 <p>Examples:</p>
1041
1042 <pre class='command'>
1043 <em>*% Flip the page image for the back side of duplexed output</em>
1044 *cupsBackSide: Flipped
1045
1046 <em>*% Rotate the page image for the back side of duplexed output</em>
1047 *cupsBackSide: Rotated
1048 </pre>
1049
1050 <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
1051 attribute.</p>
1052
1053 <h3><span class='info'>CUPS 1.4</span><a name='cupsCommands'>cupsCommands</a></h3>
1054
1055 <p class='summary'>*cupsCommands: "name name2 ... nameN"</p>
1056
1057 <p>This string attribute specifies the commands that are supported by the
1058 CUPS command file filter for this device. The command names are separated
1059 by whitespace.</p>
1060
1061 <p>Example:</p>
1062
1063 <pre class='command'>
1064 <em>*% Specify the list of commands we support</em>
1065 *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels com.vendor.foo"
1066 </pre>
1067
1068
1069 <h3><span class='info'>CUPS 1.3</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3>
1070
1071 <p class='summary'>*cupsEvenDuplex: boolean</p>
1072
1073 <p>This boolean attribute notifies the RIP filters that the
1074 destination printer requires an even number of pages when 2-sided
1075 printing is selected. The default value is <code>false</code>.</p>
1076
1077 <p>Example:</p>
1078
1079 <pre class='command'>
1080 <em>*% Always send an even number of pages when duplexing</em>
1081 *cupsEvenDuplex: true
1082 </pre>
1083
1084 <h3><a name='cupsFax'>cupsFax</a></h3>
1085
1086 <p class='summary'>*cupsFax: boolean</p>
1087
1088 <p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p>
1089
1090 <p>Examples:</p>
1091
1092 <pre class='command'>
1093 *cupsFax: true
1094 </pre>
1095
1096 <h3><a name='cupsFilter'>cupsFilter</a></h3>
1097
1098 <p class='summary'>*cupsFilter: "source/type cost program"</p>
1099
1100 <p>This string attribute provides a conversion rule from the
1101 given source type to the printer's native format using the
1102 filter "program". If a printer supports the source type directly,
1103 the special filter program "-" may be specified.</p>
1104
1105 <p>Examples:</p>
1106
1107 <pre class='command'>
1108 <em>*% Standard raster printer driver filter</em>
1109 *cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
1110
1111 <em>*% Plain text filter</em>
1112 *cupsFilter: "text/plain 10 texttofoo"
1113
1114 <em>*% Pass-through filter for PostScript printers</em>
1115 *cupsFilter: "application/vnd.cups-postscript 0 -"
1116 </pre>
1117
1118 <h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3>
1119
1120 <p class='summary'>*cupsFlipDuplex: boolean</p>
1121
1122 <p>Due to implementation differences between Mac OS X and Ghostscript,
1123 the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use
1124 the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> attribute to specify
1125 the coordinate system (pixel layout) of the page data on the back side of
1126 duplex pages.</p>
1127
1128 <p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value
1129 of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with
1130 Ghostscript.</p>
1131
1132 <p>The default value is <code>false</code>.</p>
1133
1134 <blockquote><b>Note:</b>
1135
1136 <p>Mac OS X drivers that previously used
1137 <tt>cupsFlipDuplex</tt> may wish to provide both the old and
1138 new attributes for maximum compatibility, for example:</p>
1139
1140 <pre class='command'>
1141 *cupsBackSide: Rotated
1142 *cupsFlipDuplex: true
1143 </pre>
1144
1145 <p>Similarly, drivers written for other operating systems using
1146 Ghostscript can use:</p>
1147
1148 <pre class='command'>
1149 *cupsBackSide: Flipped
1150 *cupsFlipDuplex: true
1151 </pre></blockquote>
1152
1153 <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3>
1154
1155 <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p>
1156
1157 <p>This attribute defines a mapping from IPP <code>finishings</code>
1158 values to PPD options and choices.</p>
1159
1160 <p>Examples:</p>
1161
1162 <pre class='command'>
1163 *cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait"
1164 *cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide"
1165 *cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait"
1166 *cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
1167 </pre>
1168
1169 <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPReason'>cupsIPPReason</a></h3>
1170
1171 <p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
1172
1173 <p>This optional attribute maps custom
1174 <code>printer-state-reasons</code> keywords that are generated by
1175 the driver to human readable text. The optional URIs string
1176 contains zero or more URIs separated by a newline. Each URI can
1177 be a CUPS server absolute path to a help file under the
1178 scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
1179 ("http://www.domain.com/path/to/help/page.html"), or any other
1180 valid URI which directs the user at additional information
1181 concerning the condition that is being reported.</p>
1182
1183 <p>Since the reason text is limited to 80 characters by the PPD specification,
1184 longer text strings can be included by URI-encoding the text with the "text"
1185 scheme, for example "text:some%20text". Multiple <code>text</code> URIs are
1186 combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt>
1187 into a single string that can be displayed to the user.</p>
1188
1189 <p>Examples:</p>
1190
1191 <pre class='command'>
1192 <em>*% Map com.vendor-error to text but no page</em>
1193 *cupsIPPReason com.vendor-error/A serious error occurred: ""
1194
1195 <em>*% Map com.vendor-error to more than 80 characters of text but no page</em>
1196 *cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time
1197 text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country."
1198
1199 <em>*% Map com.vendor-error to text and a local page</em>
1200 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
1201
1202 <em>*% Map com.vendor-error to text and a remote page</em>
1203 *cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
1204
1205 <em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
1206 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
1207 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
1208 help:anchor='com.vendor-error'%20bookID=Vendor%20Help
1209 http://www.vendor.com/help"
1210 *End
1211 </pre>
1212
1213 <h3><span class='info'>CUPS 1.2</span><a name='cupsLanguages'>cupsLanguages</a></h3>
1214
1215 <p class='summary'>*cupsLanguages: "locale list"</p>
1216
1217 <p>This attribute describes which language localizations are
1218 included in the PPD. The "locale list" string is a space-delimited
1219 list of locale names ("en", "en_US", "fr_CA", etc.)</p>
1220
1221 <p>Example:</p>
1222
1223 <pre class='command'>
1224 <em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
1225 *cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
1226 </pre>
1227
1228 <h3><a name='cupsManualCopies'>cupsManualCopies</a></h3>
1229
1230 <p class='summary'>*cupsManualCopies: boolean</p>
1231
1232 <p>This boolean attribute notifies the RIP filters that the
1233 destination printer does not support copy generation in
1234 hardware. The default value is <code>false</code>.</p>
1235
1236 <p>Example:</p>
1237
1238 <pre class='command'>
1239 <em>*% Tell the RIP filters to generate the copies for us</em>
1240 *cupsManualCopies: true
1241 </pre>
1242
1243 <h3><span class='info'>CUPS 1.4</span><a name='cupsMarkerName'>cupsMarkerName</a></h3>
1244
1245 <p class='summary'>*cupsMarkerName/Name Text: ""</p>
1246
1247 <p>This optional attribute maps <code>marker-names</code> strings that are
1248 generated by the driver to human readable text.</p>
1249
1250 <p>Examples:</p>
1251
1252 <pre class='command'>
1253 <em>*% Map cyanToner to "Cyan Toner"</em>
1254 *cupsMarkerName cyanToner/Cyan Toner: ""
1255 </pre>
1256
1257 <h3><span class='info'>CUPS 1.4</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3>
1258
1259 <p class='summary'>*cupsMarkerNotice: "disclaimer text"</p>
1260
1261 <p>This optional attribute provides disclaimer text for the supply level
1262 information provided by the driver, typically something like "supply levels
1263 are approximate".</p>
1264
1265 <p>Examples:</p>
1266
1267 <pre class='command'>
1268 *cupsMarkerNotice: "Supply levels are approximate."
1269 </pre>
1270
1271 <h3><a name='cupsModelNumber'>cupsModelNumber</a></h3>
1272
1273 <p class='summary'>*cupsModelNumber: number</p>
1274
1275 <p>This integer attribute specifies a printer-specific model
1276 number. This number can be used by a filter program to adjust
1277 the output for a specific model of printer.</p>
1278
1279 <p>Example:</p>
1280
1281 <pre class='command'>
1282 <em>*% Specify an integer for a driver-specific model number</em>
1283 *cupsModelNumber: 1234
1284 </pre>
1285
1286 <h3><span class='info'>CUPS 1.3</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3>
1287
1288 <p class='summary'>*cupsPJLCharset: "ISO character set name"</p>
1289
1290 <p>This string attribute specifies the character set that is used
1291 for strings in PJL commands. If not specified, US-ASCII is
1292 assumed.</p>
1293
1294 <p>Example:</p>
1295
1296 <pre class='command'>
1297 <em>*% Specify UTF-8 is used in PJL strings</em>
1298 *cupsPJLCharset: "UTF-8"
1299 </pre>
1300
1301 <h3><span class='info'>CUPS 1.4</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3>
1302
1303 <p class='summary'>*cupsPJLDisplay: "what"</p>
1304
1305 <p>This optional attribute specifies which command is used to display the
1306 job ID, name, and user on the printer's control panel. "What" is either "none"
1307 to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg"
1308 to use "@PJL RDYMSG DISPLAY". The default is "job".</p>
1309
1310 <p>Examples:</p>
1311
1312 <pre class='command'>
1313 <em>*% Display job information using @PJL SET RDYMSG DISPLAY="foo"</em>
1314 *cupsPJLDisplay: "rdymsg"
1315
1316 <em>*% Display job information display</em>
1317 *cupsPJLDisplay: "none"
1318 </pre>
1319
1320 <h3><span class='info'>CUPS 1.2</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3>
1321
1322 <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
1323
1324 <p>This string attribute specifies printer-specific "port
1325 monitor" filters that may be used with the printer. The CUPS
1326 scheduler also looks for the <tt>Protocols</tt> attribute to see
1327 if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
1328 so, the corresponding port monitor ("bcp" and "tbcp",
1329 respectively) is listed in the printer's
1330 <tt>port-monitor-supported</tt> attribute.</p>
1331
1332 <p>The "urischeme" portion of the attribute specifies the URI scheme
1333 that this port monitor should be used for. Typically this is used to
1334 pre-select a particular port monitor for each type of connection that
1335 is supported by the printer. The "port monitor" string can be "none"
1336 to disable the port monitor for the given URI scheme.</p>
1337
1338 <p>Examples:</p>
1339
1340 <pre class='command'>
1341 <em>*% Specify a PostScript printer that supports the TBCP protocol</em>
1342 *Protocols: TBCP PJL
1343
1344 <em>*% Specify that TBCP should be used for socket connections but not USB</em>
1345 *cupsPortMonitor socket/AppSocket Printing: "tbcp"
1346 *cupsPortMonitor usb/USB Printing: "none"
1347
1348 <em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
1349 *cupsPortMonitor usb/USB Status Monitor: "epson-usb"
1350 </pre>
1351
1352 <h3><span class='info'>CUPS 1.3</span><a name='cupsPreFilter'>cupsPreFilter</a></h3>
1353
1354 <p class='summary'>*cupsPreFilter: "source/type cost program"</p>
1355
1356 <p>This string attribute provides a pre-filter rule. The pre-filter
1357 program will be inserted in the conversion chain immediately
1358 before the filter that accepts the given MIME type.</p>
1359
1360 <p>Examples:</p>
1361
1362 <pre class='command'>
1363 <em>*% PDF pre-filter</em>
1364 *cupsPreFilter: "application/pdf 100 mypdfprefilter"
1365
1366 <em>*% PNG pre-filter</em>
1367 *cupsPreFilter: "image/png 0 mypngprefilter"
1368 </pre>
1369
1370 <h3><a name='cupsVersion'>cupsVersion</a></h3>
1371
1372 <p class='summary'>*cupsVersion: major.minor</p>
1373
1374 <p>This required attribute describes which version of the CUPS
1375 PPD file extensions was used. Currently it must be the string
1376 "1.0", "1.1", "1.2", or "1.3".</p>
1377
1378 <p>Example:</p>
1379
1380 <pre class='command'>
1381 <em>*% Specify a CUPS 1.2 driver</em>
1382 *cupsVersion: "1.2"
1383 </pre>
1384
1385
1386 <h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2>
1387
1388 <h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3>
1389
1390 <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p>
1391
1392 <p>This attribute defines additional option panes that are displayed in the
1393 print dialog. Each attribute adds one or more option panes. See the "OutputBinsPDE"
1394 example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple
1395 Technical Q&amp;A QA1352</a> for information on writing your own print dialog
1396 plug-ins.</p>
1397
1398 <blockquote><b>Note:</b>
1399
1400 <p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat"
1401 (32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled
1402 in order to be usable with all applications.</p>
1403
1404 </blockquote>
1405
1406 <p>Examples:</p>
1407
1408 <pre class='command'>
1409 *% Add two panes for finishing and driver options
1410 *APDialogExtension: "/Library/Printers/vendor/finishing.plugin"
1411 *APDialogExtension: "/Library/Printers/vendor/options.plugin"
1412 </pre>
1413
1414 <h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3>
1415
1416 <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
1417
1418 <p>This boolean attribute notifies the RIP filters that the
1419 destination printer requires the top and bottom margins of the
1420 <tt>ImageableArea</tt> to be swapped for the back page. The
1421 default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt>
1422 and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how
1423 <tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt>
1424 and the <tt>Tumble</tt> page attribute.</p>
1425
1426 <div class='table'>
1427 <table width='80%' summary='Margin Flipping Modes'>
1428 <caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption>
1429 <thead>
1430 <tr>
1431         <th>APDuplexRequiresFlippedMargin</th>
1432         <th>cupsBackSide</th>
1433         <th>Tumble Value</th>
1434         <th>Margins</th>
1435 </tr>
1436 </thead>
1437 <tbody>
1438 <tr>
1439         <td>false</td>
1440         <td>any</td>
1441         <td>any</td>
1442         <td>Normal</td>
1443 </tr>
1444 <tr>
1445         <td>any</td>
1446         <td>Normal</td>
1447         <td>any</td>
1448         <td>Normal</td>
1449 </tr>
1450 <tr>
1451         <td>true</td>
1452         <td>ManualDuplex</td>
1453         <td>false</td>
1454         <td>Normal</td>
1455 </tr>
1456 <tr>
1457         <td>true</td>
1458         <td>ManualDuplex</td>
1459         <td>true</td>
1460         <td>Flipped</td>
1461 </tr>
1462 <tr>
1463         <td>true</td>
1464         <td>Rotated</td>
1465         <td>false</td>
1466         <td>Flipped</td>
1467 </tr>
1468 <tr>
1469         <td>true</td>
1470         <td>Rotated</td>
1471         <td>true</td>
1472         <td>Normal</td>
1473 </tr>
1474 <tr>
1475         <td>true or unspecified</td>
1476         <td>Flipped</td>
1477         <td>any</td>
1478         <td>Flipped</td>
1479 </tr>
1480 </tbody>
1481 </table></div>
1482
1483 <p>Example:</p>
1484
1485 <pre class='command'>
1486 <em>*% Rotate the back side images</em>
1487 *cupsBackSide: Rotated
1488
1489 <em>*% Don't swap the top and bottom margins for the back side</em>
1490 *APDuplexRequiresFlippedMargin: false
1491 </pre>
1492
1493 <p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a>
1494 attribute.</p>
1495
1496 <h3><a name='APHelpBook'>APHelpBook</a></h3>
1497
1498 <p class='summary'>*APHelpBook: "bundle URL"</p>
1499
1500 <p>This string attribute specifies the Apple help book bundle to use when
1501 looking up IPP reason codes for this printer driver. The
1502 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute maps
1503 "help" URIs to this file.</p>
1504
1505 <p>Example:</p>
1506
1507 <pre class='command'>
1508 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
1509 </pre>
1510
1511 <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3>
1512
1513 <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename"</p>
1514
1515 <p>This attribute defines the location of a printer icon file to use when
1516 displaying the printer.</p>
1517
1518 <p>Examples:</p>
1519
1520 <pre class='command'>
1521 *% Apple icon file
1522 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
1523
1524 *% TIFF icon file
1525 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.tiff"
1526
1527 *% PNG icon file
1528 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.png"
1529
1530 *% JPEG icon file
1531 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.jpg"
1532 </pre>
1533
1534 <h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3>
1535
1536 <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p>
1537
1538 <p>This attribute defines an program that checks the ink/toner/marker levels
1539 on a printer, returning an XML document with those levels. See the "InkTool"
1540 example and
1541 <a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple
1542 Technical Note TN2144</a> for more information.</p>
1543
1544 <p>Examples:</p>
1545
1546 <pre class='command'>
1547 *% Use a vendor monitoring program
1548 *APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool"
1549 </pre>
1550
1551 <h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3>
1552
1553 <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p>
1554
1555 <p>This attribute defines presets for multiple options that show up
1556 in the print dialog of applications (such as iPhoto) that set the job
1557 style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or
1558 more pairs of PPD options and choices as well as providing key/value data for
1559 the application. The following preset names are currently defined:</p>
1560
1561 <ul>
1562
1563         <li><code>Photo_with_Paper_Auto-Detect</code>; Photo printing
1564         with paper auto-detect</li>
1565
1566         <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; Photo printing
1567         with paper auto-detect - fine</li>
1568
1569         <li><code>Photo_on_Plain_Paper</code>; Photo printing on plain paper</li>
1570
1571         <li><code>Photo_on_Plain_Paper_-_Fine</code>; Photo printing on plain
1572         paper - fine</li>
1573
1574         <li><code>Photo_on_Photo_Paper</code>; Photo printing on photo paper</li>
1575
1576         <li><code>Photo_on_Photo_Paper_-_Fine</code>; Photo printing on photo
1577         paper - fine</li>
1578
1579         <li><code>Photo_on_Matte_Paper</code>; Photo printing on matte paper</li>
1580
1581         <li><code>Photo_on_Matte_Paper_-_Fine</code>; Photo printing on matte
1582         paper - fine</li>
1583
1584 </ul>
1585
1586 <p>The value string consists of pairs of keywords, either an option name and
1587 choice (*MainKeyword OptionKeyword) or a preset identifier and value
1588 (com.apple.print.preset.foo value). Preset identifiers and their supported
1589 values are documented in "<a
1590 href='http://developer.apple.com/documentation/Printing/Conceptual/PresetDraft/presets_intro/chapter_1_section_2.html'
1591 >Creating Printing Presets for iPhoto: Printing Presets File Format</a>".</p>
1592
1593 <p>Presets, like options, can also be localized in multiple languages.</p>
1594
1595 <p>Examples:</p>
1596
1597 <pre class='command'>
1598 *APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: "
1599   *MediaType Glossy
1600   *ColorModel RGB
1601   *Resolution 300dpi
1602   com.apple.print.preset.graphicsType Photo
1603   com.apple.print.preset.quality mid
1604   com.apple.print.preset.media-front-coating glossy"
1605 *End
1606 *fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: ""
1607 </pre>
1608
1609 <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3>
1610
1611 <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p>
1612
1613 <p>This attribute defines a GUI application that can be used to do printer
1614 maintenance functions such as cleaning the print head(s). See ... for more
1615 information.</p>
1616
1617 <p>Examples:</p>
1618
1619 <pre class='command'>
1620 *% Define the printer utility application
1621 *APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
1622 </pre>
1623
1624 <h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3>
1625
1626 <p class='summary'>*APScanAppBundleID: "bundle ID"</p>
1627
1628 <p>This attribute defines the application to use when scanning pages from
1629 the device.</p>
1630
1631 <p>Examples:</p>
1632
1633 <pre class='command'>
1634 *APScanAppBundleID: "com.apple.ImageCaptureApp"
1635 </pre>
1636
1637
1638 <h2 class='title'><a name='HISTORY'>Change History</a></h2>
1639
1640 <h3>Changes in CUPS 1.4</a></h3>
1641
1642 <ul>
1643
1644         <li>Added <tt>cupsCommands</tt> attribute.</li>
1645
1646         <li>Added <tt>cupsMarkerName</tt> attribute.</li>
1647
1648         <li>Added <tt>cupsMarkerNotice</tt> attribute.</li>
1649
1650         <li>Added <tt>cupsPJLDisplay</tt> attribute.</li>
1651
1652 </ul>
1653
1654
1655 <h3>Changes in CUPS 1.3.1</a></h3>
1656
1657 <ul>
1658
1659         <li>Added missing Mac OS X <tt>AP</tt> attributes.</li>
1660
1661         <li>Added section on auto-configuration including the
1662         <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt>
1663         attributes.</li>
1664
1665         <li>Minor reorganization.</li>
1666
1667 </ul>
1668
1669
1670 <h3>Changes in CUPS 1.3</a></h3>
1671
1672 <ul>
1673
1674         <li>Added <tt>cupsBackSide</tt> and deprecated <tt>cupsFlipDuplex</tt>.</li>
1675
1676         <li>Added text URI information to <tt>cupsIPPReason</tt> documentation.</li>
1677
1678         <li>Added <tt>APPrinterPreset</tt>, <tt>cupsIPPFinishings</tt>, and <tt>cupsPreFilter</tt> attributes.</li>
1679
1680         <li>Added discussion of custom option code, sample <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li>
1681
1682 </ul>
1683
1684 <h3>Changes in CUPS 1.2.8</a></h3>
1685
1686 <ul>
1687
1688         <li>Added section on supported PostScript commands for raster
1689         drivers</li>
1690
1691 </ul>
1692
1693 <h3>Changes in CUPS 1.2</a></h3>
1694
1695 <ul>
1696
1697         <li>Added globalization support attributes</li>
1698
1699         <li>Added custom option values support</li>
1700
1701         <li>Added <tt>APHelpBook</tt> attribute</li>
1702
1703         <li>Added <tt>APDuplexRequiresFlippedMargin</tt> attribute</li>
1704
1705         <li>Added <tt>cupsICCProfile</tt> attribute</li>
1706
1707         <li>Added <tt>cupsIPPReason</tt> attribute</li>
1708
1709         <li>Added <tt>cupsLanguages</tt> attribute</li>
1710
1711         <li>Added <tt>cupsPortMonitor</tt> attribute</li>
1712
1713         <li>Removed <tt>cupsProtocol</tt> attribute</li>
1714
1715 </ul>
1716
1717 <h3>Changes in CUPS 1.1</a></h3>
1718
1719 <ul>
1720
1721         <li>Added <tt>cupsFlipDuplex</tt> attribute</li>
1722
1723         <li>Added <tt>cupsProtocol</tt> attribute</li>
1724
1725 </ul>
1726
1727 </body>
1728 </html>