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='MEDIA'>Media Attributes</a></h2>
1026
1027 <p>The CUPS media attributes allow drivers to specify alternate custom page
1028 size limits based on up to two options.</p>
1029
1030 <h3><span class='info'>CUPS 1.4</span><a name='cupsMediaQualifier2'>cupsMediaQualifier2</a></h3>
1031
1032 <p class='summary'>*cupsMediaQualifier2: MainKeyword</p>
1033
1034 <p>This attribute specifies the second option to use for overriding the
1035 custom page size limits.</p>
1036
1037 <p>Example:</p>
1038
1039 <pre class='command'>
1040 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1041 *cupsMediaQualifier2: InputSlot
1042 *cupsMediaQualifier3: Quality
1043 *cupsMaxSize .Manual.: "1000 1000"
1044 *cupsMinSize .Manual.: "100 100"
1045 *cupsMinSize .Manual.Photo: "200 200"
1046 *cupsMinSize ..Photo: "300 300"
1047 </pre>
1048
1049 <h3><span class='info'>CUPS 1.4</span><a name='cupsMediaQualifier3'>cupsMediaQualifier3</a></h3>
1050
1051 <p class='summary'>*cupsMediaQualifier3: MainKeyword</p>
1052
1053 <p>This attribute specifies the third option to use for overriding the
1054 custom page size limits.</p>
1055
1056 <p>Example:</p>
1057
1058 <pre class='command'>
1059 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1060 *cupsMediaQualifier2: InputSlot
1061 *cupsMediaQualifier3: Quality
1062 *cupsMaxSize .Manual.: "1000 1000"
1063 *cupsMinSize .Manual.: "100 100"
1064 *cupsMinSize .Manual.Photo: "200 200"
1065 *cupsMinSize ..Photo: "300 300"
1066 </pre>
1067
1068 <h3><span class='info'>CUPS 1.4</span><a name='cupsMinSize'>cupsMinSize</a></h3>
1069
1070 <p class='summary'>*cupsMinSize .Qualifier2.Qualifier3: "width length"<br>
1071 *cupsMinSize .Qualifier2.: "width length"<br>
1072 *cupsMinSize ..Qualifier3: "width length"</p>
1073
1074 <p>This attribute specifies alternate minimum custom page sizes in points.
1075 The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and
1076 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> attributes
1077 are used to identify options to use for matching.</p>
1078
1079 <p>Example:</p>
1080
1081 <pre class='command'>
1082 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1083 *cupsMediaQualifier2: InputSlot
1084 *cupsMediaQualifier3: Quality
1085 *cupsMaxSize .Manual.: "1000 1000"
1086 *cupsMinSize .Manual.: "100 100"
1087 *cupsMinSize .Manual.Photo: "200 200"
1088 *cupsMinSize ..Photo: "300 300"
1089 </pre>
1090
1091 <h3><span class='info'>CUPS 1.4</span><a name='cupsMaxSize'>cupsMaxSize</a></h3>
1092
1093 <p class='summary'>*cupsMaxSize .Qualifier2.Qualifier3: "width length"<br>
1094 *cupsMaxSize .Qualifier2.: "width length"<br>
1095 *cupsMaxSize ..Qualifier3: "width length"</p>
1096
1097 <p>This attribute specifies alternate maximum custom page sizes in points.
1098 The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and
1099 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> attributes
1100 are used to identify options to use for matching.</p>
1101
1102 <p>Example:</p>
1103
1104 <pre class='command'>
1105 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em>
1106 *cupsMediaQualifier2: InputSlot
1107 *cupsMediaQualifier3: Quality
1108 *cupsMaxSize .Manual.: "1000 1000"
1109 *cupsMinSize .Manual.: "100 100"
1110 *cupsMinSize .Manual.Photo: "200 200"
1111 *cupsMinSize ..Photo: "300 300"
1112 </pre>
1113
1114
1115 <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
1116
1117 <h3><span class='info'>CUPS 1.3</span><a name='cupsBackSide'>cupsBackSide</a></h3>
1118
1119 <p class='summary'>*cupsBackSide: keyword</p>
1120
1121 <p>This attribute requests special handling of the back side of pages
1122 when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a>
1123 shows the supported keyword values for this attribute and their effect
1124 on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt>
1125 is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver
1126 will receive print data starting at the bottom right corner of the page, with
1127 each line going right-to-left instead of left-to-right. The default value is
1128 <code>Normal</code>.</p>
1129
1130 <blockquote><b>Note:</b>
1131
1132 <p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt>
1133 attribute - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt>
1134 will be ignored.</p>
1135
1136 </blockquote>
1137
1138 <div class='table'>
1139 <table width='80%' summary='Back Side Raster Coordinate System'>
1140 <caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption>
1141 <thead>
1142 <tr>
1143         <th>cupsBackSide</th>
1144         <th>Tumble Value</th>
1145         <th>Image Presentation</th>
1146 </tr>
1147 </thead>
1148 <tbody>
1149 <tr>
1150         <td><code>Normal</code></td>
1151         <td><code>false</code></td>
1152         <td>Left-to-right, top-to-bottom</td>
1153 </tr>
1154 <tr>
1155         <td><code>Normal</code></td>
1156         <td><code>true</code></td>
1157         <td>Left-to-right, top-to-bottom</td>
1158 </tr>
1159 <tr>
1160         <td><code>ManualTumble</code></td>
1161         <td><code>false</code></td>
1162         <td>Left-to-right, top-to-bottom</td>
1163 </tr>
1164 <tr>
1165         <td><code>ManualTumble</code></td>
1166         <td><code>true</code></td>
1167         <td>Right-to-left, bottom-to-top</td>
1168 </tr>
1169 <tr>
1170         <td><code>Rotated</code></td>
1171         <td><code>false</code></td>
1172         <td>Right-to-left, bottom-to-top</td>
1173 </tr>
1174 <tr>
1175         <td><code>Rotated</code></td>
1176         <td><code>true</code></td>
1177         <td>Right-to-left, top-to-bottom</td>
1178 </tr>
1179 <tr>
1180         <td><code>Flipped</code> *</td>
1181         <td><code>false</code></td>
1182         <td>Left-to-right, bottom-to-top</td>
1183 </tr>
1184 <tr>
1185         <td><code>Flipped</code> *</td>
1186         <td><code>true</code></td>
1187         <td>Right-to-left, top-to-bottom</td>
1188 </tr>
1189 </tbody>
1190 </table>
1191 </div>
1192
1193 <p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p>
1194
1195 <div class='figure'><table summary='Back side images'>
1196 <caption>Figure 1: Back side images</caption>
1197 <tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr>
1198 </table></div>
1199
1200 <p>Examples:</p>
1201
1202 <pre class='command'>
1203 <em>*% Flip the page image for the back side of duplexed output</em>
1204 *cupsBackSide: Flipped
1205
1206 <em>*% Rotate the page image for the back side of duplexed output</em>
1207 *cupsBackSide: Rotated
1208 </pre>
1209
1210 <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
1211 attribute.</p>
1212
1213 <h3><span class='info'>CUPS 1.4</span><a name='cupsCommands'>cupsCommands</a></h3>
1214
1215 <p class='summary'>*cupsCommands: "name name2 ... nameN"</p>
1216
1217 <p>This string attribute specifies the commands that are supported by the
1218 CUPS command file filter for this device. The command names are separated
1219 by whitespace.</p>
1220
1221 <p>Example:</p>
1222
1223 <pre class='command'>
1224 <em>*% Specify the list of commands we support</em>
1225 *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels com.vendor.foo"
1226 </pre>
1227
1228
1229 <h3><span class='info'>CUPS 1.3</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3>
1230
1231 <p class='summary'>*cupsEvenDuplex: boolean</p>
1232
1233 <p>This boolean attribute notifies the RIP filters that the
1234 destination printer requires an even number of pages when 2-sided
1235 printing is selected. The default value is <code>false</code>.</p>
1236
1237 <p>Example:</p>
1238
1239 <pre class='command'>
1240 <em>*% Always send an even number of pages when duplexing</em>
1241 *cupsEvenDuplex: true
1242 </pre>
1243
1244 <h3><a name='cupsFax'>cupsFax</a></h3>
1245
1246 <p class='summary'>*cupsFax: boolean</p>
1247
1248 <p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p>
1249
1250 <p>Examples:</p>
1251
1252 <pre class='command'>
1253 *cupsFax: true
1254 </pre>
1255
1256 <h3><a name='cupsFilter'>cupsFilter</a></h3>
1257
1258 <p class='summary'>*cupsFilter: "source/type cost program"</p>
1259
1260 <p>This string attribute provides a conversion rule from the
1261 given source type to the printer's native format using the
1262 filter "program". If a printer supports the source type directly,
1263 the special filter program "-" may be specified.</p>
1264
1265 <p>Examples:</p>
1266
1267 <pre class='command'>
1268 <em>*% Standard raster printer driver filter</em>
1269 *cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
1270
1271 <em>*% Plain text filter</em>
1272 *cupsFilter: "text/plain 10 texttofoo"
1273
1274 <em>*% Pass-through filter for PostScript printers</em>
1275 *cupsFilter: "application/vnd.cups-postscript 0 -"
1276 </pre>
1277
1278 <h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3>
1279
1280 <p class='summary'>*cupsFlipDuplex: boolean</p>
1281
1282 <p>Due to implementation differences between Mac OS X and Ghostscript,
1283 the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use
1284 the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> attribute to specify
1285 the coordinate system (pixel layout) of the page data on the back side of
1286 duplex pages.</p>
1287
1288 <p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value
1289 of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with
1290 Ghostscript.</p>
1291
1292 <p>The default value is <code>false</code>.</p>
1293
1294 <blockquote><b>Note:</b>
1295
1296 <p>Mac OS X drivers that previously used
1297 <tt>cupsFlipDuplex</tt> may wish to provide both the old and
1298 new attributes for maximum compatibility, for example:</p>
1299
1300 <pre class='command'>
1301 *cupsBackSide: Rotated
1302 *cupsFlipDuplex: true
1303 </pre>
1304
1305 <p>Similarly, drivers written for other operating systems using
1306 Ghostscript can use:</p>
1307
1308 <pre class='command'>
1309 *cupsBackSide: Flipped
1310 *cupsFlipDuplex: true
1311 </pre></blockquote>
1312
1313 <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3>
1314
1315 <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p>
1316
1317 <p>This attribute defines a mapping from IPP <code>finishings</code>
1318 values to PPD options and choices.</p>
1319
1320 <p>Examples:</p>
1321
1322 <pre class='command'>
1323 *cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait"
1324 *cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide"
1325 *cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait"
1326 *cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
1327 </pre>
1328
1329 <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPReason'>cupsIPPReason</a></h3>
1330
1331 <p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
1332
1333 <p>This optional attribute maps custom
1334 <code>printer-state-reasons</code> keywords that are generated by
1335 the driver to human readable text. The optional URIs string
1336 contains zero or more URIs separated by a newline. Each URI can
1337 be a CUPS server absolute path to a help file under the
1338 scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
1339 ("http://www.domain.com/path/to/help/page.html"), or any other
1340 valid URI which directs the user at additional information
1341 concerning the condition that is being reported.</p>
1342
1343 <p>Since the reason text is limited to 80 characters by the PPD specification,
1344 longer text strings can be included by URI-encoding the text with the "text"
1345 scheme, for example "text:some%20text". Multiple <code>text</code> URIs are
1346 combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt>
1347 into a single string that can be displayed to the user.</p>
1348
1349 <p>Examples:</p>
1350
1351 <pre class='command'>
1352 <em>*% Map com.vendor-error to text but no page</em>
1353 *cupsIPPReason com.vendor-error/A serious error occurred: ""
1354
1355 <em>*% Map com.vendor-error to more than 80 characters of text but no page</em>
1356 *cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time
1357 text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country."
1358
1359 <em>*% Map com.vendor-error to text and a local page</em>
1360 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
1361
1362 <em>*% Map com.vendor-error to text and a remote page</em>
1363 *cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
1364
1365 <em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
1366 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
1367 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
1368 help:anchor='com.vendor-error'%20bookID=Vendor%20Help
1369 http://www.vendor.com/help"
1370 *End
1371 </pre>
1372
1373 <h3><span class='info'>CUPS 1.2</span><a name='cupsLanguages'>cupsLanguages</a></h3>
1374
1375 <p class='summary'>*cupsLanguages: "locale list"</p>
1376
1377 <p>This attribute describes which language localizations are
1378 included in the PPD. The "locale list" string is a space-delimited
1379 list of locale names ("en", "en_US", "fr_CA", etc.)</p>
1380
1381 <p>Example:</p>
1382
1383 <pre class='command'>
1384 <em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
1385 *cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
1386 </pre>
1387
1388 <h3><a name='cupsManualCopies'>cupsManualCopies</a></h3>
1389
1390 <p class='summary'>*cupsManualCopies: boolean</p>
1391
1392 <p>This boolean attribute notifies the RIP filters that the
1393 destination printer does not support copy generation in
1394 hardware. The default value is <code>false</code>.</p>
1395
1396 <p>Example:</p>
1397
1398 <pre class='command'>
1399 <em>*% Tell the RIP filters to generate the copies for us</em>
1400 *cupsManualCopies: true
1401 </pre>
1402
1403 <h3><span class='info'>CUPS 1.4</span><a name='cupsMarkerName'>cupsMarkerName</a></h3>
1404
1405 <p class='summary'>*cupsMarkerName/Name Text: ""</p>
1406
1407 <p>This optional attribute maps <code>marker-names</code> strings that are
1408 generated by the driver to human readable text.</p>
1409
1410 <p>Examples:</p>
1411
1412 <pre class='command'>
1413 <em>*% Map cyanToner to "Cyan Toner"</em>
1414 *cupsMarkerName cyanToner/Cyan Toner: ""
1415 </pre>
1416
1417 <h3><span class='info'>CUPS 1.4</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3>
1418
1419 <p class='summary'>*cupsMarkerNotice: "disclaimer text"</p>
1420
1421 <p>This optional attribute provides disclaimer text for the supply level
1422 information provided by the driver, typically something like "supply levels
1423 are approximate".</p>
1424
1425 <p>Examples:</p>
1426
1427 <pre class='command'>
1428 *cupsMarkerNotice: "Supply levels are approximate."
1429 </pre>
1430
1431 <h3><a name='cupsModelNumber'>cupsModelNumber</a></h3>
1432
1433 <p class='summary'>*cupsModelNumber: number</p>
1434
1435 <p>This integer attribute specifies a printer-specific model
1436 number. This number can be used by a filter program to adjust
1437 the output for a specific model of printer.</p>
1438
1439 <p>Example:</p>
1440
1441 <pre class='command'>
1442 <em>*% Specify an integer for a driver-specific model number</em>
1443 *cupsModelNumber: 1234
1444 </pre>
1445
1446 <h3><span class='info'>CUPS 1.3</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3>
1447
1448 <p class='summary'>*cupsPJLCharset: "ISO character set name"</p>
1449
1450 <p>This string attribute specifies the character set that is used
1451 for strings in PJL commands. If not specified, US-ASCII is
1452 assumed.</p>
1453
1454 <p>Example:</p>
1455
1456 <pre class='command'>
1457 <em>*% Specify UTF-8 is used in PJL strings</em>
1458 *cupsPJLCharset: "UTF-8"
1459 </pre>
1460
1461 <h3><span class='info'>CUPS 1.4</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3>
1462
1463 <p class='summary'>*cupsPJLDisplay: "what"</p>
1464
1465 <p>This optional attribute specifies which command is used to display the
1466 job ID, name, and user on the printer's control panel. "What" is either "none"
1467 to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg"
1468 to use "@PJL RDYMSG DISPLAY". The default is "job".</p>
1469
1470 <p>Examples:</p>
1471
1472 <pre class='command'>
1473 <em>*% Display job information using @PJL SET RDYMSG DISPLAY="foo"</em>
1474 *cupsPJLDisplay: "rdymsg"
1475
1476 <em>*% Display job information display</em>
1477 *cupsPJLDisplay: "none"
1478 </pre>
1479
1480 <h3><span class='info'>CUPS 1.2</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3>
1481
1482 <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
1483
1484 <p>This string attribute specifies printer-specific "port
1485 monitor" filters that may be used with the printer. The CUPS
1486 scheduler also looks for the <tt>Protocols</tt> attribute to see
1487 if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
1488 so, the corresponding port monitor ("bcp" and "tbcp",
1489 respectively) is listed in the printer's
1490 <tt>port-monitor-supported</tt> attribute.</p>
1491
1492 <p>The "urischeme" portion of the attribute specifies the URI scheme
1493 that this port monitor should be used for. Typically this is used to
1494 pre-select a particular port monitor for each type of connection that
1495 is supported by the printer. The "port monitor" string can be "none"
1496 to disable the port monitor for the given URI scheme.</p>
1497
1498 <p>Examples:</p>
1499
1500 <pre class='command'>
1501 <em>*% Specify a PostScript printer that supports the TBCP protocol</em>
1502 *Protocols: TBCP PJL
1503
1504 <em>*% Specify that TBCP should be used for socket connections but not USB</em>
1505 *cupsPortMonitor socket/AppSocket Printing: "tbcp"
1506 *cupsPortMonitor usb/USB Printing: "none"
1507
1508 <em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
1509 *cupsPortMonitor usb/USB Status Monitor: "epson-usb"
1510 </pre>
1511
1512 <h3><span class='info'>CUPS 1.3</span><a name='cupsPreFilter'>cupsPreFilter</a></h3>
1513
1514 <p class='summary'>*cupsPreFilter: "source/type cost program"</p>
1515
1516 <p>This string attribute provides a pre-filter rule. The pre-filter
1517 program will be inserted in the conversion chain immediately
1518 before the filter that accepts the given MIME type.</p>
1519
1520 <p>Examples:</p>
1521
1522 <pre class='command'>
1523 <em>*% PDF pre-filter</em>
1524 *cupsPreFilter: "application/pdf 100 mypdfprefilter"
1525
1526 <em>*% PNG pre-filter</em>
1527 *cupsPreFilter: "image/png 0 mypngprefilter"
1528 </pre>
1529
1530 <h3><a name='cupsVersion'>cupsVersion</a></h3>
1531
1532 <p class='summary'>*cupsVersion: major.minor</p>
1533
1534 <p>This required attribute describes which version of the CUPS
1535 PPD file extensions was used. Currently it must be the string
1536 "1.0", "1.1", "1.2", or "1.3".</p>
1537
1538 <p>Example:</p>
1539
1540 <pre class='command'>
1541 <em>*% Specify a CUPS 1.2 driver</em>
1542 *cupsVersion: "1.2"
1543 </pre>
1544
1545
1546 <h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2>
1547
1548 <h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3>
1549
1550 <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p>
1551
1552 <p>This attribute defines additional option panes that are displayed in the
1553 print dialog. Each attribute adds one or more option panes. See the "OutputBinsPDE"
1554 example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple
1555 Technical Q&amp;A QA1352</a> for information on writing your own print dialog
1556 plug-ins.</p>
1557
1558 <blockquote><b>Note:</b>
1559
1560 <p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat"
1561 (32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled
1562 in order to be usable with all applications.</p>
1563
1564 </blockquote>
1565
1566 <p>Examples:</p>
1567
1568 <pre class='command'>
1569 *% Add two panes for finishing and driver options
1570 *APDialogExtension: "/Library/Printers/vendor/finishing.plugin"
1571 *APDialogExtension: "/Library/Printers/vendor/options.plugin"
1572 </pre>
1573
1574 <h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3>
1575
1576 <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
1577
1578 <p>This boolean attribute notifies the RIP filters that the
1579 destination printer requires the top and bottom margins of the
1580 <tt>ImageableArea</tt> to be swapped for the back page. The
1581 default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt>
1582 and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how
1583 <tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt>
1584 and the <tt>Tumble</tt> page attribute.</p>
1585
1586 <div class='table'>
1587 <table width='80%' summary='Margin Flipping Modes'>
1588 <caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption>
1589 <thead>
1590 <tr>
1591         <th>APDuplexRequiresFlippedMargin</th>
1592         <th>cupsBackSide</th>
1593         <th>Tumble Value</th>
1594         <th>Margins</th>
1595 </tr>
1596 </thead>
1597 <tbody>
1598 <tr>
1599         <td>false</td>
1600         <td>any</td>
1601         <td>any</td>
1602         <td>Normal</td>
1603 </tr>
1604 <tr>
1605         <td>any</td>
1606         <td>Normal</td>
1607         <td>any</td>
1608         <td>Normal</td>
1609 </tr>
1610 <tr>
1611         <td>true</td>
1612         <td>ManualDuplex</td>
1613         <td>false</td>
1614         <td>Normal</td>
1615 </tr>
1616 <tr>
1617         <td>true</td>
1618         <td>ManualDuplex</td>
1619         <td>true</td>
1620         <td>Flipped</td>
1621 </tr>
1622 <tr>
1623         <td>true</td>
1624         <td>Rotated</td>
1625         <td>false</td>
1626         <td>Flipped</td>
1627 </tr>
1628 <tr>
1629         <td>true</td>
1630         <td>Rotated</td>
1631         <td>true</td>
1632         <td>Normal</td>
1633 </tr>
1634 <tr>
1635         <td>true or unspecified</td>
1636         <td>Flipped</td>
1637         <td>any</td>
1638         <td>Flipped</td>
1639 </tr>
1640 </tbody>
1641 </table></div>
1642
1643 <p>Example:</p>
1644
1645 <pre class='command'>
1646 <em>*% Rotate the back side images</em>
1647 *cupsBackSide: Rotated
1648
1649 <em>*% Don't swap the top and bottom margins for the back side</em>
1650 *APDuplexRequiresFlippedMargin: false
1651 </pre>
1652
1653 <p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a>
1654 attribute.</p>
1655
1656 <h3><a name='APHelpBook'>APHelpBook</a></h3>
1657
1658 <p class='summary'>*APHelpBook: "bundle URL"</p>
1659
1660 <p>This string attribute specifies the Apple help book bundle to use when
1661 looking up IPP reason codes for this printer driver. The
1662 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute maps
1663 "help" URIs to this file.</p>
1664
1665 <p>Example:</p>
1666
1667 <pre class='command'>
1668 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
1669 </pre>
1670
1671 <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3>
1672
1673 <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename"</p>
1674
1675 <p>This attribute defines the location of a printer icon file to use when
1676 displaying the printer.</p>
1677
1678 <p>Examples:</p>
1679
1680 <pre class='command'>
1681 *% Apple icon file
1682 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
1683
1684 *% TIFF icon file
1685 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.tiff"
1686
1687 *% PNG icon file
1688 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.png"
1689
1690 *% JPEG icon file
1691 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.jpg"
1692 </pre>
1693
1694 <h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3>
1695
1696 <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p>
1697
1698 <p>This attribute defines an program that checks the ink/toner/marker levels
1699 on a printer, returning an XML document with those levels. See the "InkTool"
1700 example and
1701 <a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple
1702 Technical Note TN2144</a> for more information.</p>
1703
1704 <p>Examples:</p>
1705
1706 <pre class='command'>
1707 *% Use a vendor monitoring program
1708 *APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool"
1709 </pre>
1710
1711 <h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3>
1712
1713 <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p>
1714
1715 <p>This attribute defines presets for multiple options that show up
1716 in the print dialog of applications (such as iPhoto) that set the job
1717 style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or
1718 more pairs of PPD options and choices as well as providing key/value data for
1719 the application. The following preset names are currently defined:</p>
1720
1721 <ul>
1722
1723         <li><code>Photo_with_Paper_Auto-Detect</code>; Photo printing
1724         with paper auto-detect</li>
1725
1726         <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; Photo printing
1727         with paper auto-detect - fine</li>
1728
1729         <li><code>Photo_on_Plain_Paper</code>; Photo printing on plain paper</li>
1730
1731         <li><code>Photo_on_Plain_Paper_-_Fine</code>; Photo printing on plain
1732         paper - fine</li>
1733
1734         <li><code>Photo_on_Photo_Paper</code>; Photo printing on photo paper</li>
1735
1736         <li><code>Photo_on_Photo_Paper_-_Fine</code>; Photo printing on photo
1737         paper - fine</li>
1738
1739         <li><code>Photo_on_Matte_Paper</code>; Photo printing on matte paper</li>
1740
1741         <li><code>Photo_on_Matte_Paper_-_Fine</code>; Photo printing on matte
1742         paper - fine</li>
1743
1744 </ul>
1745
1746 <p>The value string consists of pairs of keywords, either an option name and
1747 choice (*MainKeyword OptionKeyword) or a preset identifier and value
1748 (com.apple.print.preset.foo value). Preset identifiers and their supported
1749 values are documented in "<a
1750 href='http://developer.apple.com/documentation/Printing/Conceptual/PresetDraft/presets_intro/chapter_1_section_2.html'
1751 >Creating Printing Presets for iPhoto: Printing Presets File Format</a>".</p>
1752
1753 <p>Presets, like options, can also be localized in multiple languages.</p>
1754
1755 <p>Examples:</p>
1756
1757 <pre class='command'>
1758 *APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: "
1759   *MediaType Glossy
1760   *ColorModel RGB
1761   *Resolution 300dpi
1762   com.apple.print.preset.graphicsType Photo
1763   com.apple.print.preset.quality mid
1764   com.apple.print.preset.media-front-coating glossy"
1765 *End
1766 *fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: ""
1767 </pre>
1768
1769 <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3>
1770
1771 <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p>
1772
1773 <p>This attribute defines a GUI application that can be used to do printer
1774 maintenance functions such as cleaning the print head(s). See ... for more
1775 information.</p>
1776
1777 <p>Examples:</p>
1778
1779 <pre class='command'>
1780 *% Define the printer utility application
1781 *APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
1782 </pre>
1783
1784 <h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3>
1785
1786 <p class='summary'>*APScanAppBundleID: "bundle ID"</p>
1787
1788 <p>This attribute defines the application to use when scanning pages from
1789 the device.</p>
1790
1791 <p>Examples:</p>
1792
1793 <pre class='command'>
1794 *APScanAppBundleID: "com.apple.ImageCaptureApp"
1795 </pre>
1796
1797
1798 <h2 class='title'><a name='HISTORY'>Change History</a></h2>
1799
1800 <h3>Changes in CUPS 1.4</a></h3>
1801
1802 <ul>
1803
1804         <li>Added <a href='#cupsCommands'><tt>cupsCommands</tt></a>
1805         attribute.</li>
1806
1807         <li>Added <a href='#cupsMarkerName'><tt>cupsMarkerName</tt></a>
1808         attribute.</li>
1809
1810         <li>Added <a href='#cupsMarkerNotice'><tt>cupsMarkerNotice</tt></a>
1811         attribute.</li>
1812
1813         <li>Added <a href='#cupsPJLDisplay'><tt>cupsPJLDisplay</tt></a>
1814         attribute.</li>
1815
1816         <li>Added <a href='#cupsUIResolver'><tt>cupsUIResolver</tt></a> and
1817         <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>
1818         attributes.</li>
1819
1820         <li>Added
1821         <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a>,
1822         <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a>,
1823         <a href='#cupsMinSize'><tt>cupsMinSize</tt></a>, and
1824         <a href='#cupsMaxSize'><tt>cupsMaxSize</tt></a> attributes.</li>
1825
1826 </ul>
1827
1828
1829 <h3>Changes in CUPS 1.3.1</a></h3>
1830
1831 <ul>
1832
1833         <li>Added missing Mac OS X <tt>AP</tt> attributes.</li>
1834
1835         <li>Added section on auto-configuration including the
1836         <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt>
1837         attributes.</li>
1838
1839         <li>Minor reorganization.</li>
1840
1841 </ul>
1842
1843
1844 <h3>Changes in CUPS 1.3</a></h3>
1845
1846 <ul>
1847
1848         <li>Added <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> and
1849         deprecated <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a>.</li>
1850
1851         <li>Added text URI information to
1852         <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> documentation.</li>
1853
1854         <li>Added <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a>,
1855         <a href='#cupsIPPFinishings'><tt>cupsIPPFinishings</tt></a>, and
1856         <a href='#cupsPreFilter'><tt>cupsPreFilter</tt></a> attributes.</li>
1857
1858         <li>Added discussion of custom option code, sample
1859         <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li>
1860
1861 </ul>
1862
1863 <h3>Changes in CUPS 1.2.8</a></h3>
1864
1865 <ul>
1866
1867         <li>Added section on supported PostScript commands for raster
1868         drivers</li>
1869
1870 </ul>
1871
1872 <h3>Changes in CUPS 1.2</a></h3>
1873
1874 <ul>
1875
1876         <li>Added globalization support attributes</li>
1877
1878         <li>Added custom option values support</li>
1879
1880         <li>Added <a href='#APHelpBook'><tt>APHelpBook</tt></a> attribute</li>
1881
1882         <li>Added <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
1883         attribute</li>
1884
1885         <li>Added <a href='#cupsICCProfile'><tt>cupsICCProfile</tt></a> attribute</li>
1886
1887         <li>Added <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute</li>
1888
1889         <li>Added <a href='#cupsLanguages'><tt>cupsLanguages</tt></a> attribute</li>
1890
1891         <li>Added <a href='#cupsPortMonitor'><tt>cupsPortMonitor</tt></a> attribute</li>
1892
1893         <li>Removed <tt>cupsProtocol</tt> attribute</li>
1894
1895 </ul>
1896
1897 <h3>Changes in CUPS 1.1</a></h3>
1898
1899 <ul>
1900
1901         <li>Added <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a> attribute</li>
1902
1903         <li>Added <tt>cupsProtocol</tt> attribute</li>
1904
1905 </ul>
1906
1907 </body>
1908 </html>