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='CONSTRAINTS'>Constraints</a></h2>
 362
 363 <p>Constraints are option choices that are not allowed by the driver or
 364 device, for example printing 2-sided transparencies. All versions of CUPS
 365 support constraints defined by the legacy Adobe <tt>UIConstraints</tt> and
 366 <tt>NonUIConstraints</tt> attributes which support conflicts between any two
 367 option choices, for example:</p>
 368
 369 <pre class='command'>
 370 *% Do not allow 2-sided printing on transparency media
 371 *UIConstraints: "*Duplex *MediaType Transparency"
 372 *UIConstraints: "*MediaType Transparency *Duplex"
 373 </pre>
 374
 375 <p>While nearly all constraints can be expressed using these attributes, there
 376 are valid scenarios requiring constraints between more than two option choices.
 377 In addition, resolution of constraints is problematic since users and software
 378 have to guess how a particular constraint is best resolved.</p>
 379
 380 <p>CUPS 1.4 and higher define two new attributes for constraints,
 381 <tt>cupsUIConstraints</tt> and <tt>cupsUIResolver</tt>. Each
 382 <tt>cupsUIConstraints</tt> attribute points to a <tt>cupsUIResolver</tt>
 383 attribute which corrects the conflict condition. The same
 384 <tt>cupsUIResolver</tt> can be used by multiple <tt>cupsUIConstraints</tt>.</p>
 385
 386 <h3><span class='info'>CUPS 1.4</span><a name='cupsUIConstraints'>cupsUIConstraints</a></h3>
 387
 388 <p class='summary'>*cupsUIConstraints resolver: "*Keyword1 *Keyword2 ..."<br>
 389 *cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 ..."<br>
 390 *cupsUIConstraints resolver: "*Keyword1 *Keyword2 OptionKeyword2 ..."<br>
 391 *cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."<br>
 392 *cupsUIConstraints: "*InstallableKeyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p>
 393
 394 <p>Lists two or more options which conflict. The "resolver" string is a
 395 (possibly unique) keyword which specifies which options to change when the
 396 constraint exists. When no resolver is provided, a "revert to defaults"
 397 change is assumed - this type of constraint is typically only used for
 398 installable options.</p>
 399
 400 <p>Examples:</p>
 401
 402 <pre class='command'>
 403 <em>*% Specify that 2-sided printing cannot happen on transparencies</em>
 404 *cupsUIConstraints transparency: "*Duplex *MediaType Transparency"
 405
 406 <em>*% Specify that photo printing cannot happen on plain paper or transparencies at 1200dpi</em>
 407 *cupsUIConstraints photo: "*OutputMode Photo *MediaType Plain *Resolution 1200dpi"
 408 *cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi"
 409 </pre>
 410
 411 <h3><span class='info'>CUPS 1.4</span><a name='cupsUIResolver'>cupsUIResolver</a></h3>
 412
 413 <p class='summary'>*cupsUIResolution resolver: "*Keyword OptionKeyword ..."</p>
 414
 415 <p>Specifies one or more options to mark/select to resolve a constraint. The
 416 "resolver" string identifies a particular action to take for one or more
 417 <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>. The same action
 418 can be used for multiple constraints.</p>
 419
 420 <p>Examples:</p>
 421
 422 <pre class='command'>
 423 <em>*% Specify the option to change for the 2-sided transparency constraint</em>
 424 *cupsUIResolver transparency: "*Duplex None"
 425
 426 <em>*% Specify the options to change for the photo printing constraints</em>
 427 *cupsUIResolver photo: "*OutputMode Best *Resolution 600dpi"
 428 </pre>
 429
 430
 431 <h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
 432
 433 <p>CUPS 1.2 and higher adds support for PPD files containing multiple
 434 languages by following the following additional rules:</p>
 435
 436 <ol>
 437
 438         <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
 439
 440         <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
 441
 442         <li>The <tt>cupsLanguages</tt> attribute MUST be provided and
 443         list each of the supported locales in the PPD file</li>
 444
 445         <li>Main and option keywords MUST NOT exceed 34 (instead of 40)
 446         characters to allow room for the locale prefixes in translation
 447         attributes</li>
 448
 449         <li>The main keyword "Translation" MUST NOT be used</li>
 450
 451         <li>Translation strings included with the main and option
 452         keywords MUST NOT contain characters outside the ASCII
 453         subset of ISOLatin1 and UTF-8; developers wishing to use
 454         characters outside ASCII MUST provide a separate set of
 455         English localization attributes for the affected keywords.</li>
 456
 457         <li>Localizations are specified using a locale prefix of
 458         the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
 459         language code and "CC" is the 2-letter ISO country
 460         code<ul>
 461                 <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li>
 462                 <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li>
 463         </ul></li>
 464
 465         <li>Locale-specific translation strings MUST be encoded
 466         using UTF-8.</li>
 467
 468         <li>Main keywords MUST be localized using one of the
 469         following forms:
 470         <p><tt>*ll.Translation MainKeyword/translation
 471         text: ""</tt><br />
 472         <tt>*ll_CC.Translation MainKeyword/translation
 473         text: ""</tt></p></li>
 474
 475         <li>Option keywords MUST be localized using one of the
 476         following forms:
 477         <p><tt>*ll.MainKeyword OptionKeyword/translation
 478         text: ""</tt><br />
 479         <tt>*ll_CC.MainKeyword OptionKeyword/translation
 480         text: ""</tt></p></li>
 481
 482         <li>Localization attributes MAY appear anywhere after the
 483         first line of the PPD file</li>
 484
 485 </ol>
 486
 487 <blockquote><b>Note:</b>
 488
 489 <p>We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt>
 490 and limit the allowed base translation strings to ASCII to avoid
 491 character coding issues that would otherwise occur. In addition,
 492 requiring the base translation strings to be in English allows
 493 for easier fallback translation when no localization is provided
 494 in the PPD file for a given locale.</p>
 495
 496 </blockquote>
 497
 498 <p>Examples:</p>
 499
 500 <pre class='command'>
 501 *LanguageVersion: English
 502 *LanguageEncoding: ISOLatin1
 503 *cupsLanguages: "de fr_CA"
 504 *ModelName: "Foobar Laser 9999"
 505
 506 <em>*% Localize ModelName for French and German</em>
 507 *fr_CA.Translation ModelName/La Foobar Laser 9999: ""
 508 *de.Translation ModelName/Foobar LaserDrucken 9999: ""
 509
 510 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
 511 <em>*% Localize printer-state-reason for French and German</em>
 512 *fr_CA.cupsIPPReason com.vendor-error/Une erreur s&egrave;rieuse s'est produite: "/help/com.vendor/error.html"
 513 *de.cupsIPPReason com.vendor-error/Eine ernste St&ouml;rung trat: "/help/com.vendor/error.html"
 514
 515 ...
 516
 517 *OpenUI *InputSlot/Paper Source: PickOne
 518 *OrderDependency: 10 AnySetup *InputSlot
 519 *DefaultInputSlot: Auto
 520 <em>*% Localize InputSlot for French and German</em>
 521 *fr_CA.Translation InputSlot/Papier source: ""
 522 *de.Translation InputSlot/Papiereinzug: ""
 523 *InputSlot Auto/Default: "&lt;&lt;/ManualFeed false&gt;&gt;setpagedevice"
 524 <em>*% Localize InputSlot=Auto for French and German</em>
 525 *fr_CA.InputSlot Auto/Par Defaut: ""
 526 *de.InputSlot Auto/Standard: ""
 527 *InputSlot Manual/Manual Feed: "&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice"
 528 <em>*% Localize InputSlot=Manual for French and German</em>
 529 *fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: ""
 530 *de.InputSlot Manual/Manueller Einzug: ""
 531 *CloseUI: *InputSlot
 532 </pre>
 533
 534
 535 <h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
 536
 537 <p>CUPS supports custom options using an extension of the
 538 <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt>
 539 syntax:</p>
 540
 541 <pre class='command'>
 542 *CustomFoo True: "command"
 543 *ParamCustomFoo Name1/Text 1: order type minimum maximum
 544 *ParamCustomFoo Name2/Text 2: order type minimum maximum
 545 ...
 546 *ParamCustomFoo NameN/Text N: order type minimum maximum
 547 </pre>
 548
 549 <p>When the base option is part of the <tt>JCLSetup</tt> section,
 550 the "command" string contains JCL commands with "\order"
 551 placeholders for each numbered parameter. The CUPS API handles
 552 any necessary value quoting for HP-PJL commands. For example, if
 553 the JCL command string is "@PJL SET PASSCODE=\1" and the first
 554 option value is "1234" then CUPS will output the string
 555 "@PJL SET PASSCODE=1234".</p>
 556
 557 <p>For non-<tt>JCLSetup</tt> options, the "order" value is a
 558 number from 1 to N and specifies the order of values as they are
 559 placed on the stack before the command. For example, if the
 560 PostScript command string is
 561 "&lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice" and the
 562 option value is "2.0" then CUPS will output the string
 563 "2.0 &lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice".</p>
 564
 565 <p>The "type" is one of the following keywords:</p>
 566
 567 <ul>
 568
 569         <li><tt>curve</tt> - a real value from "minimum" to
 570         "maximum" representing a gamma correction curve using the
 571         function: f(x) = x <sup>value</sup></li>
 572
 573         <li><tt>int</tt> - an integer value from "minimum" to
 574         "maximum"</li>
 575
 576         <li><tt>invcurve</tt> - a real value from "minimum" to
 577         "maximum" representing a gamma correction curve using the
 578         function: f(x) = x <sup>1 / value</sup></li>
 579
 580         <li><tt>passcode</tt> - a string of numbers value with a
 581         minimum of "minimum" numbers and a maximum of "maximum"
 582         numbers ("minimum" and "maximum" are numbers and passcode
 583         strings are not displayed in the user interface)</li>
 584
 585         <li><tt>password</tt> - a string value with a minimum of
 586         "minimum" characters and a maximum of "maximum"
 587         characters ("minimum" and "maximum" are numbers and password
 588         strings are not displayed in the user interface)</li>
 589
 590         <li><tt>points</tt> - a measurement value in points from
 591         "minimum" to "maximum"</li>
 592
 593         <li><tt>real</tt> - a real value from "minimum" to
 594         "maximum"</li>
 595
 596         <li><tt>string</tt> - a string value with a minimum of
 597         "minimum" characters and a maximum of "maximum"
 598         characters ("minimum" and "maximum" are numbers)</li>
 599
 600 </ul>
 601
 602 <blockquote><b>Note:</b>
 603
 604 <p>Custom options are not directly supported by the Mac OS X Print Dialog
 605 nor by the CUPS web interface at this time. Vendors that use custom
 606 options on Mac OS X must provide their own user interface via the
 607 <a href='#APDialogExtension'><tt>APDialogExtension</tt></a> attribute.</p>
 608
 609 </blockquote>
 610
 611 <p>Examples:</p>
 612
 613 <pre class='command'>
 614 <em>*% Base JCL key code option</em>
 615 *JCLOpenUI JCLPasscode/Key Code: PickOne
 616 *OrderDependency: 10 JCLSetup *JCLPasscode
 617 *DefaultJCLPasscode: None
 618 *JCLPasscode None/No Code: ""
 619 *JCLPasscode 1111: "@PJL SET PASSCODE = 1111&lt;0A&gt;"
 620 *JCLPasscode 2222: "@PJL SET PASSCODE = 2222&lt;0A&gt;"
 621 *JCLPasscode 3333: "@PJL SET PASSCODE = 3333&lt;0A&gt;"
 622 *JCLCloseUI: *JCLPasscode
 623
 624 <em>*% Custom JCL key code option</em>
 625 *CustomJCLPasscode True: "@PJL SET PASSCODE = \1&lt;0A&gt;"
 626 *ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
 627
 628
 629 <em>*% Base PostScript watermark option</em>
 630 *OpenUI WatermarkText/Watermark Text: PickOne
 631 *OrderDependency: 10 AnySetup *WatermarkText
 632 *DefaultWatermarkText: None
 633 *WatermarkText None: ""
 634 *WatermarkText Draft: "&lt;&lt;/cupsString1(Draft)&gt;&gt;setpagedevice"
 635 *CloseUI: *WatermarkText
 636
 637 <em>*% Custom PostScript watermark option</em>
 638 *CustomWatermarkText True: "&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice"
 639 *ParamCustomWatermarkText Text: 1 string 0 32
 640
 641
 642 <em>*% Base PostScript gamma/density option</em>
 643 *OpenUI GammaDensity/Gamma and Density: PickOne
 644 *OrderDependency: 10 AnySetup *GammaDensity
 645 *DefaultGammaDensity: Normal
 646 *GammaDensity Normal/Normal: "&lt;&lt;/cupsReal1 1.0/cupsReal2 1.0&gt;&gt;setpagedevice"
 647 *GammaDensity Light/Lighter: "&lt;&lt;/cupsReal1 0.9/cupsReal2 0.67&gt;&gt;setpagedevice"
 648 *GammaDensity Dark/Darker: "&lt;&lt;/cupsReal1 1.1/cupsReal2 1.5&gt;&gt;setpagedevice"
 649 *CloseUI: *GammaDensity
 650
 651 <em>*% Custom PostScript gamma/density option</em>
 652 *CustomGammaDensity True: "&lt;&lt;/cupsReal1 3 -1 roll/cupsReal2 5 -1&gt;&gt;setpagedevice"
 653 *ParamCustomGammaDensity Gamma: 1 curve 0.1 10
 654 *ParamCustomGammaDensity Density: 2 real 0 2
 655 </pre>
 656
 657
 658 <h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2>
 659
 660 <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>
 661
 662 <pre class='command'>
 663 *PageSize A4: "&lt;&lt;/PageSize[595 842]&gt;&gt;setpagedevice"
 664 </pre>
 665
 666 <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>
 667
 668 <pre class='command'>
 669 *CustomWatermarkText True: "&lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice"
 670 </pre>
 671
 672 <p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p>
 673
 674 <pre class='command'>
 675 (My Watermark)
 676 &lt;&lt;/cupsString1 3 -1 roll&gt;&gt;setpagedevice
 677 </pre>
 678
 679 <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>
 680
 681 <pre class='command'>
 682 &lt;&lt;/cupsString1(My Watermark)&gt;&gt;setpagedevice
 683 </pre>
 684
 685 <p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p>
 686
 687 <h3>Custom Page Size Code</a></h3>
 688
 689 <p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p>
 690
 691 <pre class='command'>
 692 *ParamCustomPageSize Width:        1 points <i>min-width max-width</i>
 693 *ParamCustomPageSize Height:       2 points <i>min-height max-height</i>
 694 *ParamCustomPageSize WidthOffset:  3 points 0 0
 695 *ParamCustomPageSize HeightOffset: 4 points 0 0
 696 *ParamCustomPageSize Orientation:  5 int 0 0
 697 *CustomPageSize True: "pop pop pop &lt;&lt;/PageSize[5 -2 roll]/ImagingBBox null&gt;&gt;setpagedevice"
 698 </pre>
 699
 700 <h3>Supported PostScript Operators</a></h3>
 701
 702 <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>
 703
 704 <ul>
 705
 706         <li><tt>&lt;&lt;</tt> - Start a dictionary.</li>
 707
 708         <li><tt>&gt;&gt;</tt> - End a dictionary.</li>
 709
 710         <li><tt>[</tt> - Start an array.</li>
 711
 712         <li><tt>]</tt> - End an array.</li>
 713
 714         <li><tt>copy</tt> - Copy the top N objects on the stack.</li>
 715
 716         <li><tt>dup</tt> - Copy the top object on the stack.</li>
 717
 718         <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li>
 719
 720         <li><tt>pop</tt> - Pop the top object on the stack.</li>
 721
 722         <li><tt>roll</tt> - Shift the top N objects on the stack.</li>
 723
 724         <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li>
 725
 726 </ul>
 727
 728 <blockquote><b>Note:</b>
 729
 730 <p><em>Never</em> use the unsupported <tt>dict</tt> or <tt>put</tt>
 731 operators in your option code. These operators are typically used in
 732 option code dating back to Level 1 PostScript printers, which did not
 733 support the simpler <tt>&lt;&lt;</tt> or <tt>&gt;&gt;</tt> operators.
 734 If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can
 735 rewrite it very easily to use the newer <tt>&lt;&lt;</tt> and
 736 <tt>&gt;&gt;</tt> operators instead. For example, the following code
 737 to set the page size:</p>
 738
 739 <style type='text/css'><!--
 740 PRE B {
 741   background: #000000;
 742   color: #ffffff;
 743   padding: 2px 5px;
 744 }
 745 --></style>
 746
 747 <pre class='command'>
 748 <b>1 dict dup</b> /PageSize [612 792] <b>put</b> setpagedevice
 749 </pre>
 750
 751 <p>can be rewritten as:</p>
 752
 753 <pre class='command'>
 754 <b>&lt;&lt;</b> /PageSize [612 792] <b>&gt;&gt;</b> setpagedevice
 755 </pre>
 756
 757 </blockquote>
 758
 759 <h3>Supported Page Device Attributes</a></h3>
 760
 761 <p>Table 2 shows the supported page device attributes along with PostScript code examples.</p>
 762
 763 <div class='table'>
 764 <table summary='Supported Page Device Attributes'>
 765 <caption>Table 2: <a name='TABLE_2'>Supported Page Device Attributes</a></caption>
 766 <thead>
 767 <tr>
 768         <th>Name(s)</th>
 769         <th>Type</th>
 770         <th>Description</th>
 771         <th>Example(s)</th>
 772 </tr>
 773 </thead>
 774 <tbody>
 775 <tr valign='top'>
 776         <td><tt>AdvanceDistance</tt></td>
 777         <td>Integer</td>
 778         <td>Specifies the number of points to advance roll media after printing.</td>
 779         <td><tt>&lt;&lt;/AdvanceDistance 18&gt;&gt;setpagedevice</tt></td>
 780 </tr>
 781 <tr valign='top'>
 782         <td><tt>AdvanceMedia</tt></td>
 783         <td>Integer</td>
 784         <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>
 785         <td><tt>&lt;&lt;/AdvanceMedia 4&gt;&gt;setpagedevice</tt></td>
 786 </tr>
 787 <tr valign='top'>
 788         <td><tt>Collate</tt></td>
 789         <td>Boolean</td>
 790         <td>Specifies whether collated copies are required.</td>
 791         <td><tt>&lt;&lt;/Collate true&gt;&gt;setpagedevice</tt></td>
 792 </tr>
 793 <tr valign='top'>
 794         <td><tt>CutMedia</tt></td>
 795         <td>Integer</td>
 796         <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>
 797         <td><tt>&lt;&lt;/CutMedia 1&gt;&gt;setpagedevice</tt></td>
 798 </tr>
 799 <tr valign='top'>
 800         <td><tt>Duplex</tt></td>
 801         <td>Boolean</td>
 802         <td>Specifies whether 2-sided printing is required.</td>
 803         <td><tt>&lt;&lt;/Duplex true&gt;&gt;setpagedevice</tt></td>
 804 </tr>
 805 <tr valign='top'>
 806         <td><tt>HWResolution</tt></td>
 807         <td>Integer Array</td>
 808         <td>Specifies the resolution of the page image in pixels per inch.</td>
 809         <td><tt>&lt;&lt;/HWResolution[1200 1200]&gt;&gt;setpagedevice</tt></td>
 810 </tr>
 811 <tr valign='top'>
 812         <td><tt>InsertSheet</tt></td>
 813         <td>Boolean</td>
 814         <td>Specifies whether to insert a blank sheet before the job.</td>
 815         <td><tt>&lt;&lt;/InsertSheet true&gt;&gt;setpagedevice</tt></td>
 816 </tr>
 817 <tr valign='top'>
 818         <td><tt>Jog</tt></td>
 819         <td>Integer</td>
 820         <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>
 821         <td><tt>&lt;&lt;/Jog 2&gt;&gt;setpagedevice</tt></td>
 822 </tr>
 823 <tr valign='top'>
 824         <td><tt>LeadingEdge</tt></td>
 825         <td>Integer</td>
 826         <td>Specifies the leading edge of the media: 0 = top, 1 = right, 2 = bottom, 3 = left.</td>
 827         <td><tt>&lt;&lt;/LeadingEdge 0&gt;&gt;setpagedevice</tt></td>
 828 </tr>
 829 <tr valign='top'>
 830         <td><tt>ManualFeed</tt></td>
 831         <td>Boolean</td>
 832         <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>
 833         <td><tt>&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice</tt></td>
 834 </tr>
 835 <tr valign='top'>
 836         <td><tt>MediaClass</tt></td>
 837         <td>String</td>
 838         <td>Specifies a named media.</td>
 839         <td><tt>&lt;&lt;/MediaClass (Invoices)&gt;&gt;setpagedevice</tt></td>
 840 </tr>
 841 <tr valign='top'>
 842         <td><tt>MediaColor</tt></td>
 843         <td>String</td>
 844         <td>Specifies the color of the media.</td>
 845         <td><tt>&lt;&lt;/MediaColor &gt;&gt;setpagedevice</tt></td>
 846 </tr>
 847 <tr valign='top'>
 848         <td><tt>MediaPosition</tt></td>
 849         <td>Integer</td>
 850         <td>Specifies the tray or source of the media.</td>
 851         <td><tt>&lt;&lt;/MediaPosition 12&gt;&gt;setpagedevice</tt></td>
 852 </tr>
 853 <tr valign='top'>
 854         <td><tt>MediaType</tt></td>
 855         <td>String</td>
 856         <td>Specifies the general media type.</td>
 857         <td><tt>&lt;&lt;/MediaType (Glossy)&gt;&gt;setpagedevice</tt></td>
 858 </tr>
 859 <tr valign='top'>
 860         <td><tt>MediaWeight</tt></td>
 861         <td>Integer</td>
 862         <td>Specifies the media weight in grams per meter<sup>2</sup>.</td>
 863         <td><tt>&lt;&lt;/MediaWeight 100&gt;&gt;setpagedevice</tt></td>
 864 </tr>
 865 <tr valign='top'>
 866         <td><tt>MirrorPrint</tt></td>
 867         <td>Boolean</td>
 868         <td>Specifies whether to flip the output image horizontally.</td>
 869         <td><tt>&lt;&lt;/MirrorPrint true&gt;&gt;setpagedevice</tt></td>
 870 </tr>
 871 <tr valign='top'>
 872         <td><tt>NegativePrint</tt></td>
 873         <td>Boolean</td>
 874         <td>Specifies whether to invert the output image.</td>
 875         <td><tt>&lt;&lt;/NegativePrint true&gt;&gt;setpagedevice</tt></td>
 876 </tr>
 877 <tr valign='top'>
 878         <td><tt>NumCopies</tt></td>
 879         <td>Integer</td>
 880         <td>Specifies the number of copies to produce of each page.</td>
 881         <td><tt>&lt;&lt;/NumCopies 100&gt;&gt;setpagedevice</tt></td>
 882 </tr>
 883 <tr valign='top'>
 884         <td><tt>Orientation</tt></td>
 885         <td>Integer</td>
 886         <td>Specifies the orientation of the output: 0 = portrait, 1 = landscape rotated counter-clockwise, 2 = upside-down, 3 = landscape rotated clockwise.</td>
 887         <td><tt>&lt;&lt;/Orientation 3&gt;&gt;setpagedevice</tt></td>
 888 </tr>
 889 <tr valign='top'>
 890         <td><tt>OutputFaceUp</tt></td>
 891         <td>Boolean</td>
 892         <td>Specifies whether to place the media face-up in the output bin/tray.</td>
 893         <td><tt>&lt;&lt;/OutputFaceUp true&gt;&gt;setpagedevice</tt></td>
 894 </tr>
 895 <tr valign='top'>
 896         <td><tt>OutputType</tt></td>
 897         <td>String</td>
 898         <td>Specifies the output type name.</td>
 899         <td><tt>&lt;&lt;/OutputType (Photo)&gt;&gt;setpagedevice</tt></td>
 900 </tr>
 901 <tr valign='top'>
 902         <td><tt>PageSize</tt></td>
 903         <td>Integer/Real Array</td>
 904         <td>Specifies the width and length/height of the page in points.</td>
 905         <td><tt>&lt;&lt;/PageSize[595 842]&gt;&gt;setpagedevice</tt></td>
 906 </tr>
 907 <tr valign='top'>
 908         <td><tt>Separations</tt></td>
 909         <td>Boolean</td>
 910         <td>Specifies whether to produce color separations.</td>
 911         <td><tt>&lt;&lt;/Separations true&gt;&gt;setpagedevice</tt></td>
 912 </tr>
 913 <tr valign='top'>
 914         <td><tt>TraySwitch</tt></td>
 915         <td>Boolean</td>
 916         <td>Specifies whether to switch trays automatically.</td>
 917         <td><tt>&lt;&lt;/TraySwitch true&gt;&gt;setpagedevice</tt></td>
 918 </tr>
 919 <tr valign='top'>
 920         <td><tt>Tumble</tt></td>
 921         <td>Boolean</td>
 922         <td>Specifies whether the back sides of pages are rotated 180 degrees.</td>
 923         <td><tt>&lt;&lt;/Tumble true&gt;&gt;setpagedevice</tt></td>
 924 </tr>
 925 <tr valign='top'>
 926         <td><tt>cupsBorderlessScalingFactor</tt></td>
 927         <td>Real</td>
 928         <td>Specifies the amount to scale the page image dimensions.</td>
 929         <td><tt>&lt;&lt;/cupsBorderlessScalingFactor 1.01&gt;&gt;setpagedevice</tt></td>
 930 </tr>
 931 <tr valign='top'>
 932         <td><tt>cupsColorOrder</tt></td>
 933         <td>Integer</td>
 934         <td>Specifies the order of colors: 0 = chunked, 1 = banded, 2 = planar.</td>
 935         <td><tt>&lt;&lt;/cupsColorOrder 0&gt;&gt;setpagedevice</tt></td>
 936 </tr>
 937 <tr valign='top'>
 938         <td><tt>cupsColorSpace</tt></td>
 939         <td>Integer</td>
 940         <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>
 941         <td><tt>&lt;&lt;/cupsColorSpace 1 &gt;&gt;setpagedevice</tt></td>
 942 </tr>
 943 <tr valign='top'>
 944         <td><tt>cupsCompression</tt></td>
 945         <td>Integer</td>
 946         <td>Specifies a driver compression type/mode.</td>
 947         <td><tt>&lt;&lt;/cupsCompression 2&gt;&gt;setpagedevice</tt></td>
 948 </tr>
 949 <tr valign='top'>
 950         <td><tt>cupsInteger0<br>
 951         ...<br>
 952         cupsInteger15</tt></td>
 953         <td>Integer</td>
 954         <td>Specifies driver integer values.</td>
 955         <td><tt>&lt;&lt;/cupsInteger11 1234&gt;&gt;setpagedevice</tt></td>
 956 </tr>
 957 <tr valign='top'>
 958         <td><tt>cupsMarkerType</tt></td>
 959         <td>String</td>
 960         <td>Specifies the type of ink/toner to use.</td>
 961         <td><tt>&lt;&lt;/cupsMarkerType (Black+Color)&gt;&gt;setpagedevice</tt></td>
 962 </tr>
 963 <tr valign='top'>
 964         <td><tt>cupsMediaType</tt></td>
 965         <td>Integer</td>
 966         <td>Specifies a numeric media type.</td>
 967         <td><tt>&lt;&lt;/cupsMediaType 999&gt;&gt;setpagedevice</tt></td>
 968 </tr>
 969 <tr valign='top'>
 970         <td><tt>cupsPageSizeName</tt></td>
 971         <td>String</td>
 972         <td>Specifies the name of the page size.</td>
 973         <td><tt>&lt;&lt;/cupsPageSizeName (A4.Full)&gt;&gt;setpagedevice</tt></td>
 974 </tr>
 975 <tr valign='top'>
 976         <td><tt>cupsPreferredBitsPerColor</tt></td>
 977         <td>Integer</td>
 978         <td>Specifies the preferred number of bits per color, typically 8 or 16.</td>
 979         <td><tt>&lt;&lt;/cupsPreferredBitsPerColor 16&gt;&gt;setpagedevice</tt></td>
 980 </tr>
 981 <tr valign='top'>
 982         <td><tt>cupsReal0<br>
 983         ...<br>
 984         cupsReal15</tt></td>
 985         <td>Real</td>
 986         <td>Specifies driver real number values.</td>
 987         <td><tt>&lt;&lt;/cupsReal15 1.234&gt;&gt;setpagedevice</tt></td>
 988 </tr>
 989 <tr valign='top'>
 990         <td><tt>cupsRenderingIntent</tt></td>
 991         <td>String</td>
 992         <td>Specifies the color rendering intent.</td>
 993         <td><tt>&lt;&lt;/cupsRenderingIntent (AbsoluteColorimetric)&gt;&gt;setpagedevice</tt></td>
 994 </tr>
 995 <tr valign='top'>
 996         <td><tt>cupsRowCount</tt></td>
 997         <td>Integer</td>
 998         <td>Specifies the number of rows of raster data to print on each line for some drivers.</td>
 999         <td><tt>&lt;&lt;/cupsRowCount 24&gt;&gt;setpagedevice</tt></td>
1000 </tr>
1001 <tr valign='top'>
1002         <td><tt>cupsRowFeed</tt></td>
1003         <td>Integer</td>
1004         <td>Specifies the number of rows to feed between passes for some drivers.</td>
1005         <td><tt>&lt;&lt;/cupsRowFeed 17&gt;&gt;setpagedevice</tt></td>
1006 </tr>
1007 <tr valign='top'>
1008         <td><tt>cupsRowStep</tt></td>
1009         <td>Integer</td>
1010         <td>Specifies the number of lines between columns/rows on the print head for some drivers.</td>
1011         <td><tt>&lt;&lt;/cupsRowStep 2&gt;&gt;setpagedevice</tt></td>
1012 </tr>
1013 <tr valign='top'>
1014         <td><tt>cupsString0<br>
1015         ...<br>
1016         cupsString15</tt></td>
1017         <td>String</td>
1018         <td>Specifies driver string values.</td>
1019         <td><tt>&lt;&lt;/cupsString0(String Value)&gt;&gt;setpagedevice</tt></td>
1020 </tr>
1021 </tbody>
1022 </table></div>
1023
1024
1025 <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
1026
1027 <h3><span class='info'>CUPS 1.3</span><a name='cupsBackSide'>cupsBackSide</a></h3>
1028
1029 <p class='summary'>*cupsBackSide: keyword</p>
1030
1031 <p>This attribute requests special handling of the back side of pages
1032 when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a>
1033 shows the supported keyword values for this attribute and their effect
1034 on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt>
1035 is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver
1036 will receive print data starting at the bottom right corner of the page, with
1037 each line going right-to-left instead of left-to-right. The default value is
1038 <code>Normal</code>.</p>
1039
1040 <blockquote><b>Note:</b>
1041
1042 <p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt>
1043 attribute - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt>
1044 will be ignored.</p>
1045
1046 </blockquote>
1047
1048 <div class='table'>
1049 <table width='80%' summary='Back Side Raster Coordinate System'>
1050 <caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption>
1051 <thead>
1052 <tr>
1053         <th>cupsBackSide</th>
1054         <th>Tumble Value</th>
1055         <th>Image Presentation</th>
1056 </tr>
1057 </thead>
1058 <tbody>
1059 <tr>
1060         <td><code>Normal</code></td>
1061         <td><code>false</code></td>
1062         <td>Left-to-right, top-to-bottom</td>
1063 </tr>
1064 <tr>
1065         <td><code>Normal</code></td>
1066         <td><code>true</code></td>
1067         <td>Left-to-right, top-to-bottom</td>
1068 </tr>
1069 <tr>
1070         <td><code>ManualTumble</code></td>
1071         <td><code>false</code></td>
1072         <td>Left-to-right, top-to-bottom</td>
1073 </tr>
1074 <tr>
1075         <td><code>ManualTumble</code></td>
1076         <td><code>true</code></td>
1077         <td>Right-to-left, bottom-to-top</td>
1078 </tr>
1079 <tr>
1080         <td><code>Rotated</code></td>
1081         <td><code>false</code></td>
1082         <td>Right-to-left, bottom-to-top</td>
1083 </tr>
1084 <tr>
1085         <td><code>Rotated</code></td>
1086         <td><code>true</code></td>
1087         <td>Right-to-left, top-to-bottom</td>
1088 </tr>
1089 <tr>
1090         <td><code>Flipped</code> *</td>
1091         <td><code>false</code></td>
1092         <td>Left-to-right, bottom-to-top</td>
1093 </tr>
1094 <tr>
1095         <td><code>Flipped</code> *</td>
1096         <td><code>true</code></td>
1097         <td>Right-to-left, top-to-bottom</td>
1098 </tr>
1099 </tbody>
1100 </table>
1101 </div>
1102
1103 <p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p>
1104
1105 <div class='figure'><table summary='Back side images'>
1106 <caption>Figure 1: Back side images</caption>
1107 <tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr>
1108 </table></div>
1109
1110 <p>Examples:</p>
1111
1112 <pre class='command'>
1113 <em>*% Flip the page image for the back side of duplexed output</em>
1114 *cupsBackSide: Flipped
1115
1116 <em>*% Rotate the page image for the back side of duplexed output</em>
1117 *cupsBackSide: Rotated
1118 </pre>
1119
1120 <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
1121 attribute.</p>
1122
1123 <h3><span class='info'>CUPS 1.4</span><a name='cupsCommands'>cupsCommands</a></h3>
1124
1125 <p class='summary'>*cupsCommands: "name name2 ... nameN"</p>
1126
1127 <p>This string attribute specifies the commands that are supported by the
1128 CUPS command file filter for this device. The command names are separated
1129 by whitespace.</p>
1130
1131 <p>Example:</p>
1132
1133 <pre class='command'>
1134 <em>*% Specify the list of commands we support</em>
1135 *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels com.vendor.foo"
1136 </pre>
1137
1138
1139 <h3><span class='info'>CUPS 1.3</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3>
1140
1141 <p class='summary'>*cupsEvenDuplex: boolean</p>
1142
1143 <p>This boolean attribute notifies the RIP filters that the
1144 destination printer requires an even number of pages when 2-sided
1145 printing is selected. The default value is <code>false</code>.</p>
1146
1147 <p>Example:</p>
1148
1149 <pre class='command'>
1150 <em>*% Always send an even number of pages when duplexing</em>
1151 *cupsEvenDuplex: true
1152 </pre>
1153
1154 <h3><a name='cupsFax'>cupsFax</a></h3>
1155
1156 <p class='summary'>*cupsFax: boolean</p>
1157
1158 <p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p>
1159
1160 <p>Examples:</p>
1161
1162 <pre class='command'>
1163 *cupsFax: true
1164 </pre>
1165
1166 <h3><a name='cupsFilter'>cupsFilter</a></h3>
1167
1168 <p class='summary'>*cupsFilter: "source/type cost program"</p>
1169
1170 <p>This string attribute provides a conversion rule from the
1171 given source type to the printer's native format using the
1172 filter "program". If a printer supports the source type directly,
1173 the special filter program "-" may be specified.</p>
1174
1175 <p>Examples:</p>
1176
1177 <pre class='command'>
1178 <em>*% Standard raster printer driver filter</em>
1179 *cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
1180
1181 <em>*% Plain text filter</em>
1182 *cupsFilter: "text/plain 10 texttofoo"
1183
1184 <em>*% Pass-through filter for PostScript printers</em>
1185 *cupsFilter: "application/vnd.cups-postscript 0 -"
1186 </pre>
1187
1188 <h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3>
1189
1190 <p class='summary'>*cupsFlipDuplex: boolean</p>
1191
1192 <p>Due to implementation differences between Mac OS X and Ghostscript,
1193 the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use
1194 the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> attribute to specify
1195 the coordinate system (pixel layout) of the page data on the back side of
1196 duplex pages.</p>
1197
1198 <p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value
1199 of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with
1200 Ghostscript.</p>
1201
1202 <p>The default value is <code>false</code>.</p>
1203
1204 <blockquote><b>Note:</b>
1205
1206 <p>Mac OS X drivers that previously used
1207 <tt>cupsFlipDuplex</tt> may wish to provide both the old and
1208 new attributes for maximum compatibility, for example:</p>
1209
1210 <pre class='command'>
1211 *cupsBackSide: Rotated
1212 *cupsFlipDuplex: true
1213 </pre>
1214
1215 <p>Similarly, drivers written for other operating systems using
1216 Ghostscript can use:</p>
1217
1218 <pre class='command'>
1219 *cupsBackSide: Flipped
1220 *cupsFlipDuplex: true
1221 </pre></blockquote>
1222
1223 <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3>
1224
1225 <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p>
1226
1227 <p>This attribute defines a mapping from IPP <code>finishings</code>
1228 values to PPD options and choices.</p>
1229
1230 <p>Examples:</p>
1231
1232 <pre class='command'>
1233 *cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait"
1234 *cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide"
1235 *cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait"
1236 *cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
1237 </pre>
1238
1239 <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPReason'>cupsIPPReason</a></h3>
1240
1241 <p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
1242
1243 <p>This optional attribute maps custom
1244 <code>printer-state-reasons</code> keywords that are generated by
1245 the driver to human readable text. The optional URIs string
1246 contains zero or more URIs separated by a newline. Each URI can
1247 be a CUPS server absolute path to a help file under the
1248 scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
1249 ("http://www.domain.com/path/to/help/page.html"), or any other
1250 valid URI which directs the user at additional information
1251 concerning the condition that is being reported.</p>
1252
1253 <p>Since the reason text is limited to 80 characters by the PPD specification,
1254 longer text strings can be included by URI-encoding the text with the "text"
1255 scheme, for example "text:some%20text". Multiple <code>text</code> URIs are
1256 combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt>
1257 into a single string that can be displayed to the user.</p>
1258
1259 <p>Examples:</p>
1260
1261 <pre class='command'>
1262 <em>*% Map com.vendor-error to text but no page</em>
1263 *cupsIPPReason com.vendor-error/A serious error occurred: ""
1264
1265 <em>*% Map com.vendor-error to more than 80 characters of text but no page</em>
1266 *cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time
1267 text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country."
1268
1269 <em>*% Map com.vendor-error to text and a local page</em>
1270 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
1271
1272 <em>*% Map com.vendor-error to text and a remote page</em>
1273 *cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
1274
1275 <em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
1276 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
1277 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
1278 help:anchor='com.vendor-error'%20bookID=Vendor%20Help
1279 http://www.vendor.com/help"
1280 *End
1281 </pre>
1282
1283 <h3><span class='info'>CUPS 1.2</span><a name='cupsLanguages'>cupsLanguages</a></h3>
1284
1285 <p class='summary'>*cupsLanguages: "locale list"</p>
1286
1287 <p>This attribute describes which language localizations are
1288 included in the PPD. The "locale list" string is a space-delimited
1289 list of locale names ("en", "en_US", "fr_CA", etc.)</p>
1290
1291 <p>Example:</p>
1292
1293 <pre class='command'>
1294 <em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
1295 *cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
1296 </pre>
1297
1298 <h3><a name='cupsManualCopies'>cupsManualCopies</a></h3>
1299
1300 <p class='summary'>*cupsManualCopies: boolean</p>
1301
1302 <p>This boolean attribute notifies the RIP filters that the
1303 destination printer does not support copy generation in
1304 hardware. The default value is <code>false</code>.</p>
1305
1306 <p>Example:</p>
1307
1308 <pre class='command'>
1309 <em>*% Tell the RIP filters to generate the copies for us</em>
1310 *cupsManualCopies: true
1311 </pre>
1312
1313 <h3><span class='info'>CUPS 1.4</span><a name='cupsMarkerName'>cupsMarkerName</a></h3>
1314
1315 <p class='summary'>*cupsMarkerName/Name Text: ""</p>
1316
1317 <p>This optional attribute maps <code>marker-names</code> strings that are
1318 generated by the driver to human readable text.</p>
1319
1320 <p>Examples:</p>
1321
1322 <pre class='command'>
1323 <em>*% Map cyanToner to "Cyan Toner"</em>
1324 *cupsMarkerName cyanToner/Cyan Toner: ""
1325 </pre>
1326
1327 <h3><span class='info'>CUPS 1.4</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3>
1328
1329 <p class='summary'>*cupsMarkerNotice: "disclaimer text"</p>
1330
1331 <p>This optional attribute provides disclaimer text for the supply level
1332 information provided by the driver, typically something like "supply levels
1333 are approximate".</p>
1334
1335 <p>Examples:</p>
1336
1337 <pre class='command'>
1338 *cupsMarkerNotice: "Supply levels are approximate."
1339 </pre>
1340
1341 <h3><a name='cupsModelNumber'>cupsModelNumber</a></h3>
1342
1343 <p class='summary'>*cupsModelNumber: number</p>
1344
1345 <p>This integer attribute specifies a printer-specific model
1346 number. This number can be used by a filter program to adjust
1347 the output for a specific model of printer.</p>
1348
1349 <p>Example:</p>
1350
1351 <pre class='command'>
1352 <em>*% Specify an integer for a driver-specific model number</em>
1353 *cupsModelNumber: 1234
1354 </pre>
1355
1356 <h3><span class='info'>CUPS 1.3</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3>
1357
1358 <p class='summary'>*cupsPJLCharset: "ISO character set name"</p>
1359
1360 <p>This string attribute specifies the character set that is used
1361 for strings in PJL commands. If not specified, US-ASCII is
1362 assumed.</p>
1363
1364 <p>Example:</p>
1365
1366 <pre class='command'>
1367 <em>*% Specify UTF-8 is used in PJL strings</em>
1368 *cupsPJLCharset: "UTF-8"
1369 </pre>
1370
1371 <h3><span class='info'>CUPS 1.4</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3>
1372
1373 <p class='summary'>*cupsPJLDisplay: "what"</p>
1374
1375 <p>This optional attribute specifies which command is used to display the
1376 job ID, name, and user on the printer's control panel. "What" is either "none"
1377 to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg"
1378 to use "@PJL RDYMSG DISPLAY". The default is "job".</p>
1379
1380 <p>Examples:</p>
1381
1382 <pre class='command'>
1383 <em>*% Display job information using @PJL SET RDYMSG DISPLAY="foo"</em>
1384 *cupsPJLDisplay: "rdymsg"
1385
1386 <em>*% Display job information display</em>
1387 *cupsPJLDisplay: "none"
1388 </pre>
1389
1390 <h3><span class='info'>CUPS 1.2</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3>
1391
1392 <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
1393
1394 <p>This string attribute specifies printer-specific "port
1395 monitor" filters that may be used with the printer. The CUPS
1396 scheduler also looks for the <tt>Protocols</tt> attribute to see
1397 if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
1398 so, the corresponding port monitor ("bcp" and "tbcp",
1399 respectively) is listed in the printer's
1400 <tt>port-monitor-supported</tt> attribute.</p>
1401
1402 <p>The "urischeme" portion of the attribute specifies the URI scheme
1403 that this port monitor should be used for. Typically this is used to
1404 pre-select a particular port monitor for each type of connection that
1405 is supported by the printer. The "port monitor" string can be "none"
1406 to disable the port monitor for the given URI scheme.</p>
1407
1408 <p>Examples:</p>
1409
1410 <pre class='command'>
1411 <em>*% Specify a PostScript printer that supports the TBCP protocol</em>
1412 *Protocols: TBCP PJL
1413
1414 <em>*% Specify that TBCP should be used for socket connections but not USB</em>
1415 *cupsPortMonitor socket/AppSocket Printing: "tbcp"
1416 *cupsPortMonitor usb/USB Printing: "none"
1417
1418 <em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
1419 *cupsPortMonitor usb/USB Status Monitor: "epson-usb"
1420 </pre>
1421
1422 <h3><span class='info'>CUPS 1.3</span><a name='cupsPreFilter'>cupsPreFilter</a></h3>
1423
1424 <p class='summary'>*cupsPreFilter: "source/type cost program"</p>
1425
1426 <p>This string attribute provides a pre-filter rule. The pre-filter
1427 program will be inserted in the conversion chain immediately
1428 before the filter that accepts the given MIME type.</p>
1429
1430 <p>Examples:</p>
1431
1432 <pre class='command'>
1433 <em>*% PDF pre-filter</em>
1434 *cupsPreFilter: "application/pdf 100 mypdfprefilter"
1435
1436 <em>*% PNG pre-filter</em>
1437 *cupsPreFilter: "image/png 0 mypngprefilter"
1438 </pre>
1439
1440 <h3><a name='cupsVersion'>cupsVersion</a></h3>
1441
1442 <p class='summary'>*cupsVersion: major.minor</p>
1443
1444 <p>This required attribute describes which version of the CUPS
1445 PPD file extensions was used. Currently it must be the string
1446 "1.0", "1.1", "1.2", or "1.3".</p>
1447
1448 <p>Example:</p>
1449
1450 <pre class='command'>
1451 <em>*% Specify a CUPS 1.2 driver</em>
1452 *cupsVersion: "1.2"
1453 </pre>
1454
1455
1456 <h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2>
1457
1458 <h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3>
1459
1460 <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p>
1461
1462 <p>This attribute defines additional option panes that are displayed in the
1463 print dialog. Each attribute adds one or more option panes. See the "OutputBinsPDE"
1464 example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple
1465 Technical Q&amp;A QA1352</a> for information on writing your own print dialog
1466 plug-ins.</p>
1467
1468 <blockquote><b>Note:</b>
1469
1470 <p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat"
1471 (32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled
1472 in order to be usable with all applications.</p>
1473
1474 </blockquote>
1475
1476 <p>Examples:</p>
1477
1478 <pre class='command'>
1479 *% Add two panes for finishing and driver options
1480 *APDialogExtension: "/Library/Printers/vendor/finishing.plugin"
1481 *APDialogExtension: "/Library/Printers/vendor/options.plugin"
1482 </pre>
1483
1484 <h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3>
1485
1486 <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
1487
1488 <p>This boolean attribute notifies the RIP filters that the
1489 destination printer requires the top and bottom margins of the
1490 <tt>ImageableArea</tt> to be swapped for the back page. The
1491 default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt>
1492 and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how
1493 <tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt>
1494 and the <tt>Tumble</tt> page attribute.</p>
1495
1496 <div class='table'>
1497 <table width='80%' summary='Margin Flipping Modes'>
1498 <caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption>
1499 <thead>
1500 <tr>
1501         <th>APDuplexRequiresFlippedMargin</th>
1502         <th>cupsBackSide</th>
1503         <th>Tumble Value</th>
1504         <th>Margins</th>
1505 </tr>
1506 </thead>
1507 <tbody>
1508 <tr>
1509         <td>false</td>
1510         <td>any</td>
1511         <td>any</td>
1512         <td>Normal</td>
1513 </tr>
1514 <tr>
1515         <td>any</td>
1516         <td>Normal</td>
1517         <td>any</td>
1518         <td>Normal</td>
1519 </tr>
1520 <tr>
1521         <td>true</td>
1522         <td>ManualDuplex</td>
1523         <td>false</td>
1524         <td>Normal</td>
1525 </tr>
1526 <tr>
1527         <td>true</td>
1528         <td>ManualDuplex</td>
1529         <td>true</td>
1530         <td>Flipped</td>
1531 </tr>
1532 <tr>
1533         <td>true</td>
1534         <td>Rotated</td>
1535         <td>false</td>
1536         <td>Flipped</td>
1537 </tr>
1538 <tr>
1539         <td>true</td>
1540         <td>Rotated</td>
1541         <td>true</td>
1542         <td>Normal</td>
1543 </tr>
1544 <tr>
1545         <td>true or unspecified</td>
1546         <td>Flipped</td>
1547         <td>any</td>
1548         <td>Flipped</td>
1549 </tr>
1550 </tbody>
1551 </table></div>
1552
1553 <p>Example:</p>
1554
1555 <pre class='command'>
1556 <em>*% Rotate the back side images</em>
1557 *cupsBackSide: Rotated
1558
1559 <em>*% Don't swap the top and bottom margins for the back side</em>
1560 *APDuplexRequiresFlippedMargin: false
1561 </pre>
1562
1563 <p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a>
1564 attribute.</p>
1565
1566 <h3><a name='APHelpBook'>APHelpBook</a></h3>
1567
1568 <p class='summary'>*APHelpBook: "bundle URL"</p>
1569
1570 <p>This string attribute specifies the Apple help book bundle to use when
1571 looking up IPP reason codes for this printer driver. The
1572 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute maps
1573 "help" URIs to this file.</p>
1574
1575 <p>Example:</p>
1576
1577 <pre class='command'>
1578 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
1579 </pre>
1580
1581 <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3>
1582
1583 <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename"</p>
1584
1585 <p>This attribute defines the location of a printer icon file to use when
1586 displaying the printer.</p>
1587
1588 <p>Examples:</p>
1589
1590 <pre class='command'>
1591 *% Apple icon file
1592 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
1593
1594 *% TIFF icon file
1595 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.tiff"
1596
1597 *% PNG icon file
1598 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.png"
1599
1600 *% JPEG icon file
1601 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.jpg"
1602 </pre>
1603
1604 <h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3>
1605
1606 <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p>
1607
1608 <p>This attribute defines an program that checks the ink/toner/marker levels
1609 on a printer, returning an XML document with those levels. See the "InkTool"
1610 example and
1611 <a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple
1612 Technical Note TN2144</a> for more information.</p>
1613
1614 <p>Examples:</p>
1615
1616 <pre class='command'>
1617 *% Use a vendor monitoring program
1618 *APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool"
1619 </pre>
1620
1621 <h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3>
1622
1623 <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p>
1624
1625 <p>This attribute defines presets for multiple options that show up
1626 in the print dialog of applications (such as iPhoto) that set the job
1627 style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or
1628 more pairs of PPD options and choices as well as providing key/value data for
1629 the application. The following preset names are currently defined:</p>
1630
1631 <ul>
1632
1633         <li><code>Photo_with_Paper_Auto-Detect</code>; Photo printing
1634         with paper auto-detect</li>
1635
1636         <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; Photo printing
1637         with paper auto-detect - fine</li>
1638
1639         <li><code>Photo_on_Plain_Paper</code>; Photo printing on plain paper</li>
1640
1641         <li><code>Photo_on_Plain_Paper_-_Fine</code>; Photo printing on plain
1642         paper - fine</li>
1643
1644         <li><code>Photo_on_Photo_Paper</code>; Photo printing on photo paper</li>
1645
1646         <li><code>Photo_on_Photo_Paper_-_Fine</code>; Photo printing on photo
1647         paper - fine</li>
1648
1649         <li><code>Photo_on_Matte_Paper</code>; Photo printing on matte paper</li>
1650
1651         <li><code>Photo_on_Matte_Paper_-_Fine</code>; Photo printing on matte
1652         paper - fine</li>
1653
1654 </ul>
1655
1656 <p>The value string consists of pairs of keywords, either an option name and
1657 choice (*MainKeyword OptionKeyword) or a preset identifier and value
1658 (com.apple.print.preset.foo value). Preset identifiers and their supported
1659 values are documented in "<a
1660 href='http://developer.apple.com/documentation/Printing/Conceptual/PresetDraft/presets_intro/chapter_1_section_2.html'
1661 >Creating Printing Presets for iPhoto: Printing Presets File Format</a>".</p>
1662
1663 <p>Presets, like options, can also be localized in multiple languages.</p>
1664
1665 <p>Examples:</p>
1666
1667 <pre class='command'>
1668 *APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: "
1669   *MediaType Glossy
1670   *ColorModel RGB
1671   *Resolution 300dpi
1672   com.apple.print.preset.graphicsType Photo
1673   com.apple.print.preset.quality mid
1674   com.apple.print.preset.media-front-coating glossy"
1675 *End
1676 *fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: ""
1677 </pre>
1678
1679 <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3>
1680
1681 <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p>
1682
1683 <p>This attribute defines a GUI application that can be used to do printer
1684 maintenance functions such as cleaning the print head(s). See ... for more
1685 information.</p>
1686
1687 <p>Examples:</p>
1688
1689 <pre class='command'>
1690 *% Define the printer utility application
1691 *APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
1692 </pre>
1693
1694 <h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3>
1695
1696 <p class='summary'>*APScanAppBundleID: "bundle ID"</p>
1697
1698 <p>This attribute defines the application to use when scanning pages from
1699 the device.</p>
1700
1701 <p>Examples:</p>
1702
1703 <pre class='command'>
1704 *APScanAppBundleID: "com.apple.ImageCaptureApp"
1705 </pre>
1706
1707
1708 <h2 class='title'><a name='HISTORY'>Change History</a></h2>
1709
1710 <h3>Changes in CUPS 1.4</a></h3>
1711
1712 <ul>
1713
1714         <li>Added <tt>cupsCommands</tt> attribute.</li>
1715
1716         <li>Added <tt>cupsMarkerName</tt> attribute.</li>
1717
1718         <li>Added <tt>cupsMarkerNotice</tt> attribute.</li>
1719
1720         <li>Added <tt>cupsPJLDisplay</tt> attribute.</li>
1721
1722         <li>Added <tt>cupsUIResolver</tt> and <tt>cupsUIConstraints</tt>
1723         attributes.</li>
1724
1725 </ul>
1726
1727
1728 <h3>Changes in CUPS 1.3.1</a></h3>
1729
1730 <ul>
1731
1732         <li>Added missing Mac OS X <tt>AP</tt> attributes.</li>
1733
1734         <li>Added section on auto-configuration including the
1735         <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt>
1736         attributes.</li>
1737
1738         <li>Minor reorganization.</li>
1739
1740 </ul>
1741
1742
1743 <h3>Changes in CUPS 1.3</a></h3>
1744
1745 <ul>
1746
1747         <li>Added <tt>cupsBackSide</tt> and deprecated <tt>cupsFlipDuplex</tt>.</li>
1748
1749         <li>Added text URI information to <tt>cupsIPPReason</tt> documentation.</li>
1750
1751         <li>Added <tt>APPrinterPreset</tt>, <tt>cupsIPPFinishings</tt>, and <tt>cupsPreFilter</tt> attributes.</li>
1752
1753         <li>Added discussion of custom option code, sample <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li>
1754
1755 </ul>
1756
1757 <h3>Changes in CUPS 1.2.8</a></h3>
1758
1759 <ul>
1760
1761         <li>Added section on supported PostScript commands for raster
1762         drivers</li>
1763
1764 </ul>
1765
1766 <h3>Changes in CUPS 1.2</a></h3>
1767
1768 <ul>
1769
1770         <li>Added globalization support attributes</li>
1771
1772         <li>Added custom option values support</li>
1773
1774         <li>Added <tt>APHelpBook</tt> attribute</li>
1775
1776         <li>Added <tt>APDuplexRequiresFlippedMargin</tt> attribute</li>
1777
1778         <li>Added <tt>cupsICCProfile</tt> attribute</li>
1779
1780         <li>Added <tt>cupsIPPReason</tt> attribute</li>
1781
1782         <li>Added <tt>cupsLanguages</tt> attribute</li>
1783
1784         <li>Added <tt>cupsPortMonitor</tt> attribute</li>
1785
1786         <li>Removed <tt>cupsProtocol</tt> attribute</li>
1787
1788 </ul>
1789
1790 <h3>Changes in CUPS 1.1</a></h3>
1791
1792 <ul>
1793
1794         <li>Added <tt>cupsFlipDuplex</tt> attribute</li>
1795
1796         <li>Added <tt>cupsProtocol</tt> attribute</li>
1797
1798 </ul>
1799
1800 </body>
1801 </html>