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: Programming -->
   4 <head>
   5         <title>CUPS PPD Extensions</title>
   6         <meta name='keywords' content='Programming, PostScript Printer Description'>
   7 </head>
   8 <body>
   9 <!--
  10   "$Id: spec-ppd.html 4918 2006-01-12 05:14:40Z mike $"
  11
  12   CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
  13
  14   Copyright 1997-2006 by Easy Software Products.
  15
  16   These coded instructions, statements, and computer programs are the
  17   property of Easy Software Products and are protected by Federal
  18   copyright law.  Distribution and use rights are outlined in the file
  19   "LICENSE.txt" which should have been included with this file.  If this
  20   file is missing or damaged please contact Easy Software Products
  21   at:
  22
  23       Attn: CUPS Licensing Information
  24       Easy Software Products
  25       44141 Airport View Drive, Suite 204
  26       Hollywood, Maryland 20636 USA
  27
  28       Voice: (301) 373-9600
  29       EMail: cups-info@cups.org
  30         WWW: http://www.cups.org
  31 -->
  32
  33 <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
  34
  35 <p>This specification describes the attributes and extensions
  36 that CUPS adds to <a
  37 href="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
  38 Adobe TechNote #5003: PostScript Printer Description File Format
  39 Specification Version 4.3</a>. PostScript Printer Description
  40 ("PPD") files describe the capabilities of each printer and are
  41 used by CUPS to support printer-specific features and intelligent
  42 filtering.</p>
  43
  44 <h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2>
  45
  46 <p>The PPD format is text-based and uses lines of up to 255
  47 characters terminated by a carriage return, linefeed, or
  48 combination of carriage return and line feed. The following ABNF
  49 definition [RFC2234] defines the general format of lines in a PPD
  50 file:</p>
  51
  52 <pre class='command'>
  53 PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
  54
  55 HEADER   = "*" 0x50.50.44.2D.41.64.6F.62.65 ":"   ; *PPD-Adobe:
  56            *WSP DQUOTE "4.3" DQUOTE LINE-END
  57
  58 COMMENT  = "*%" *TCHAR LINE-END
  59
  60 DATA     = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
  61            1*(*WSP VALUE) LINE-END
  62
  63 VALUE    = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE
  64
  65 KCHAR    = ALPHA / DIGIT / "_" / "." / "-"
  66
  67 SCHAR    = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF
  68
  69 TCHAR    = %x20-7E / %xA0-FF
  70
  71 LINE-END = CR / LF / CR LF
  72 </pre>
  73
  74
  75 <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
  76
  77 <h3>cupsFilter</h3>
  78
  79 <p>This string attribute provides a conversion rule of the
  80 form:</p>
  81
  82 <pre class='command'>
  83 source/type cost program
  84 </pre>
  85
  86 <p>The destination type is assumed to the printer's type. If a
  87 printer supports the source type directly, the special filter
  88 program "-" may be specified.</p>
  89
  90 <p>Examples:</p>
  91
  92 <pre class='command'>
  93 <em>*% Standard raster printer driver filter</em>
  94 *cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
  95
  96 <em>*% Plain text filter</em>
  97 *cupsFilter: "text/plain 10 texttofoo"
  98
  99 <em>*% Pass-through filter for PostScript printers</em>
 100 *cupsFilter: "application/vnd.cups-postscript 0 -"
 101 </pre>
 102
 103 <h3>cupsFlipDuplex</h3>
 104
 105 <p>This boolean attribute notifies the RIP filters that the
 106 destination printer requires an upside-down image for the back
 107 page. The default value is false.</p>
 108
 109 <p>Example:</p>
 110
 111 <pre class='command'>
 112 <em>*% Flip the page image for the back side of duplexed output</em>
 113 *cupsFlipDuplex: true
 114 </pre>
 115
 116 <h3>cupsManualCopies</h3>
 117
 118 <p>This boolean attribute notifies the RIP filters that the
 119 destination printer does not support copy generation in
 120 hardware. The default value is false.</p>
 121
 122 <p>Example:</p>
 123
 124 <pre class='command'>
 125 <em>*% Tell the RIP filters to generate the copies for us</em>
 126 *cupsManualCopies: true
 127 </pre>
 128
 129 <h3>cupsModelNumber</h3>
 130
 131 <p>This integer attribute specifies a printer-specific model
 132 number. This number can be used by a filter program to adjust
 133 the output for a specific model of printer.</p>
 134
 135 <p>Example:</p>
 136
 137 <pre class='command'>
 138 <em>*% Specify an integer for a driver-specific model number</em>
 139 *cupsModelNumber: 1234
 140 </pre>
 141
 142 <h3>cupsPortMonitor</h3>
 143
 144 <p>This string attribute specifies printer-specific "port
 145 monitor" filters that may be used with the printer. The CUPS
 146 scheduler also looks for the <tt>Protocols</tt> attribute to see
 147 if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
 148 so, the corresponding port monitor ("bcp" and "tbcp",
 149 respectively) is listed in the printer's
 150 <tt>port-monitor-supported</tt> attribute.</p>
 151
 152 <p>Examples:</p>
 153
 154 <pre class='command'>
 155 <em>*% Specify a PostScript printer that supports the TBCP protocol</em>
 156 *Protocols: TBCP PJL
 157
 158 <em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
 159 *cupsPortMonitor epson-usb/USB Status Monitor: "epson-usb"
 160 </pre>
 161
 162 <h3>cupsVersion</h3>
 163
 164 <p>This required attribute describes which version of the CUPS
 165 PPD file extensions was used. Currently it must be the string
 166 "1.0", "1.1", or "1.2".</p>
 167
 168 <p>Example:</p>
 169
 170 <pre class='command'>
 171 <em>*% Specify a CUPS 1.2 driver</em>
 172 *cupsVersion: "1.2"
 173 </pre>
 174
 175
 176 <h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
 177
 178 <p>CUPS supports custom options using an extension of the
 179 <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt>
 180 syntax:</p>
 181
 182 <pre class='command'>
 183 *CustomFoo True: "command"
 184 *ParamCustomFoo Name1/Text 1: order type minimum maximum
 185 *ParamCustomFoo Name2/Text 2: order type minimum maximum
 186 ...
 187 *ParamCustomFoo NameN/Text N: order type minimum maximum
 188 </pre>
 189
 190 <p>When the base option is part of the <tt>JCLSetup</tt> section,
 191 the "command" string contains JCL commands with "\order"
 192 placeholders for each numbered parameter. The CUPS API handles
 193 any necessary value quoting for HP-PJL commands.</p>
 194
 195 <p>For non-<tt>JCLSetup</tt> options, the "order" value is a
 196 number from 1 to N and specifies the order of values as they are
 197 placed on the stack before the command.</p>
 198
 199 <p>The "type" is one of the following keywords:</p>
 200
 201 <ul>
 202
 203         <li><tt>curve</tt> - a real value from "minimum" to
 204         "maximum" representing a gamma correction curve using the
 205         function: f(x) = x <sup>value</sup></li>
 206
 207         <li><tt>int</tt> - an integer value from "minimum" to
 208         "maximum"</li>
 209
 210         <li><tt>invcurve</tt> - a real value from "minimum" to
 211         "maximum" representing a gamma correction curve using the
 212         function: f(x) = x <sup>1 / value</sup></li>
 213
 214         <li><tt>passcode</tt> - a string of numbers value with a
 215         minimum of "minimum" numbers and a maximum of "maximum"
 216         numbers (passcode strings are not displayed in the user
 217         interface)</li>
 218
 219         <li><tt>password</tt> - a string value with a minimum of
 220         "minimum" characters and a maximum of "maximum"
 221         characters (password strings are not displayed in the
 222         user interface)</li>
 223
 224         <li><tt>points</tt> - a measurement value in points from
 225         "minimum" to "maximum"</li>
 226
 227         <li><tt>real</tt> - a real value from "minimum" to
 228         "maximum"</li>
 229
 230         <li><tt>string</tt> - a string value with a minimum of
 231         "minimum" characters and a maximum of "maximum"
 232         characters</li>
 233
 234 </ul>
 235
 236 <p>Examples:</p>
 237
 238 <pre class='command'>
 239 <em>*% Base JCL key code option</em>
 240 *OpenUI JCLPasscode/Key Code: PickOne
 241 *OrderDependency: 10 JCLSetup *JCLPasscode
 242 *DefaultJCLPasscode: None
 243 *JCLPasscode None/No Code: ""
 244 *JCLPasscode 1111: "@PJL SET PASSCODE = 1111&lt;0A&gt;"
 245 *JCLPasscode 2222: "@PJL SET PASSCODE = 2222&lt;0A&gt;"
 246 *JCLPasscode 3333: "@PJL SET PASSCODE = 3333&lt;0A&gt;"
 247 *JCLCloseUI: *JCLPasscode
 248
 249 <em>*% Custom JCL key code option</em>
 250 *CustomJCLPasscode True: "@PJL SET PASSCODE = \1&lt;0A&gt;"
 251 *ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
 252
 253
 254 <em>*% Base PostScript gamma/density option</em>
 255 *OpenUI GammaDensity/Gamma and Density: PickOne
 256 *OrderDependency: 10 AnySetup *GammaDensity
 257 *DefaultGammaDensity: Normal
 258 *GammaDensity Normal/Normal: "&lt;&lt;/cupsReal1 1.0/cupsReal2 1.0&gt;&gt;setpagedevice"
 259 *GammaDensity Light/Lighter: "&lt;&lt;/cupsReal1 0.9/cupsReal2 0.67&gt;&gt;setpagedevice"
 260 *GammaDensity Dark/Darker: "&lt;&lt;/cupsReal1 1.1/cupsReal2 1.5&gt;&gt;setpagedevice"
 261 *JCLCloseUI: *GammaDensity
 262
 263 <em>*% Custom PostScript gamma/density option</em>
 264 *CustomGammaDensity True: "&lt;&lt;/cupsReal1 3 1 roll/cupsReal2 3 1&gt;&gt;setpagedevice"
 265 *ParamCustomGammaDensity Gamma: 1 curve 0.1 10
 266 *ParamCustomGammaDensity Density: 2 real 0 2
 267 </pre>
 268
 269
 270 <h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
 271
 272 <h3>cupsColorProfile</h3>
 273
 274 <p>This string attribute specifies a color profile of the
 275 form:</p>
 276
 277 <pre class='command'>
 278 *cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
 279 </pre>
 280
 281 <p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
 282 to act as a wildcard. Otherwise they must match one of the
 283 <tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
 284 the PPD file.</p>
 285
 286 <p>The <i>density</i> and <i>gamma</i> values define gamma and
 287 density adjustment function such that:</p>
 288
 289 <pre class='command'>
 290 f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
 291 </pre>
 292
 293 <p>The <i>m00</i> through <i>m22</i> values define a 3x3
 294 transformation matrix for the CMY color values. The density
 295 function is applied <i>after</i> the CMY transformation:</p>
 296
 297 <pre class='command'>
 298 | m00 m01 m02 |
 299 | m10 m11 m12 |
 300 | m20 m21 m22 |
 301 </pre>
 302
 303 <p>Examples:</p>
 304
 305 <pre class='command'>
 306 <em>*% Specify a profile for printing at 360dpi on all media types</em>
 307 *cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
 308
 309 <em>*% Specify a profile for printing at 720dpi on Glossy media</em>
 310 *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"
 311
 312 <em>*% Specify a default profile for printing at all other resolutions and media types</em>
 313 *cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
 314 </pre>
 315
 316 <h3>cupsICCProfile</h3>
 317
 318 <p>This attribute specifies an ICC color profile of the
 319 form:</p>
 320
 321 <pre class='command'>
 322 *cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
 323 </pre>
 324
 325 <p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
 326 <tt>Resolution</tt> keywords specify a selector for color
 327 profiles. If omitted, the color profile will match any option
 328 keyword for the corresponding main keyword.</p>
 329
 330 <p>The <tt>Description</tt> specifies human-readable text that
 331 is associated with the color profile. The <tt>filename</tt>
 332 portion specifies the ICC color profile to use; if the filename
 333 is not absolute, it is loaded relative to the
 334 <var>/usr/share/cups/profiles</var> directory.</p>
 335
 336 <p>Examples:</p>
 337
 338 <pre class='command'>
 339 <em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
 340 *cupsICCProfile CMYK..360dpi/360dpi CMYK: "vendor/foo-360-cmyk.icc"
 341
 342 <em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
 343 *cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "vendor/foo-720-glossy-rgb.icc"
 344
 345 <em>*% Specify a default profile for printing at all other resolutions and media types</em>
 346 *cupsICCProfile .../Default: "vendor/foo-default.icc"
 347 </pre>
 348
 349 <h4>Customizing the Profile Selection Keywords</h4>
 350
 351 <p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
 352 <tt>Resolution</tt> keywords can be reassigned to different main
 353 keywords, allowing drivers to do color profile selection based
 354 on different parameters. The <tt>cupsICCQualifier1</tt>,
 355 <tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt>
 356 attributes define the mapping from selector to main keyword:</p>
 357
 358 <pre class='command'>
 359 *cupsICCQualifier1: MainKeyword
 360 *cupsICCQualifier2: MainKeyword
 361 *cupsICCQualifier3: MainKeyword
 362 </pre>
 363
 364 <p>The default mapping is as follows:</p>
 365
 366 <pre class='command'>
 367 *cupsICCQualifier1: ColorModel
 368 *cupsICCQualifier2: MediaType
 369 *cupsICCQualifier3: Resolution
 370 </pre>
 371
 372
 373 <h2 class='title'><a name='I18N'>I18N Support</a></h2>
 374
 375 <p>CUPS 1.2 and higher adds support for PPD files containing multiple
 376 languages by following the following rules:</p>
 377
 378 <ol>
 379
 380         <li>The <tt>LanguageVersion</tt> is <tt>English</tt></li>
 381
 382         <li>The <tt>LanguageEncoding</tt> is <tt>ISOLatin1</tt></li>
 383
 384         <li>Main and option keywords may not exceed 34
 385         characters, which is a subset of what the Adobe PPD spec
 386         allows.</li>
 387
 388         <li>Translations are specified using a locale prefix of
 389         the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
 390         language code and "CC" is the 2-letter ISO country
 391         code</li>
 392
 393         <li>Translation strings are encoded using UTF-8.</li>
 394
 395         <li>Main keywords are translated using any of the
 396         following forms:
 397         <p><tt>*ll.Translation MainKeyword/translation
 398         text: ""</tt><br />
 399         <tt>*ll_CC.Translation MainKeyword/translation
 400         text: ""</tt></p></li>
 401
 402         <li>Option keywords are translated using any of the
 403         following forms:
 404         <p><tt>*ll.MainKeyword OptionKeyword/translation
 405         text: ""</tt><br />
 406         <tt>*ll_CC.MainKeyword OptionKeyword/translation
 407         text: ""</tt></p></li>
 408
 409 </ol>
 410
 411 <p>Examples:</p>
 412
 413
 414 <pre class='command'>
 415 *LanguageVersion: English
 416 *LanguageEncoding: ISOLatin1
 417 *ModelName: "Foobar Laser 9999"
 418
 419 <em>*% Localize for French and German</em>
 420 *fr_FR.Translation ModelName/La Foobar Laser 9999: ""
 421 *de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""
 422
 423 ...
 424
 425 *OpenUI *InputSlot/Paper Source: PickOne
 426 *OrderDependency: 10 AnySetup *InputSlot
 427 *DefaultInputSlot: Auto
 428 <em>*% Localize for French and German</em>
 429 *fr_FR.Translation InputSlot/Papier source: ""
 430 *de_DE.Translation InputSlot/Papiereinzug: ""
 431 *InputSlot Auto/Default: "&lt;&lt;/ManualFeed false&gt;&gt;setpagedevice"
 432 <em>*% Localize for French and German</em>
 433 *fr_FR.InputSlot Auto/Par Defaut: ""
 434 *de_DE.InputSlot Auto/Standard: ""
 435 *InputSlot Manual/Manual Feed: "&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice"
 436 <em>*% Localize for French and German</em>
 437 *fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
 438 *de_DE.InputSlot Manual/Manueller Einzug: ""
 439 *CloseUI: *InputSlot
 440 </pre>
 441
 442
 443 <h2 class='title'><a name='HISTORY'>Change History</a></h2>
 444
 445 <h3>Changes in CUPS 1.2</h3>
 446
 447 <ul>
 448
 449         <li>Added I18N support attributes</li>
 450
 451         <li>Added custom option values support</li>
 452
 453         <li>Added <tt>cupsICCProfile</tt> attribute</li>
 454
 455         <li>Added <tt>cupsPortMonitor</tt> attribute</li>
 456
 457         <li>Removed <tt>cupsProtocol</tt> attribute</li>
 458
 459 </ul>
 460
 461 <h3>Changes in CUPS 1.1</h3>
 462
 463 <ul>
 464
 465         <li>Added <tt>cupsFlipDuplex</tt> attribute</li>
 466
 467         <li>Added <tt>cupsProtocol</tt> attribute</li>
 468
 469 </ul>
 470
 471 </body>
 472 </html>