doc/ppd.shtml

   1 <html>
   2 <head>
   3         <title>CUPS PostScript Printer Description (PPD) File Specification</title>
   4         <meta name='COPYRIGHT' content='Copyright 2004, All Rights Reserved'/>
   5         <meta name='DOCNUMBER' content='CUPS-PPD-1.2'/>
   6         <meta name='Auther' content='Easy Software Products'/>
   7 </head>
   8 <body>
   9
  10
  11 <h1>Scope</h1>
  12
  13 <h2>Identification</h2>
  14
  15 <p>This document describes the PostScript Printer Description
  16 (PPD) file format and the supported extensions for the Common
  17 UNIX Printing System ("CUPS") Version 1.2. It should be used in
  18 conjunction with the Adobe PostScript Printer Description File
  19 Format Specification, Version 4.3 when creating PPD files for
  20 CUPS.</p>
  21
  22 <embed src="system-overview.shtml"/>
  23
  24 <h2>Document Overview</h2>
  25
  26 <p>This CUPS PostScript Printer Description File Specification
  27 document is organized into the following sections:</p>
  28
  29 <ul>
  30
  31         <li>1 - Scope</li>
  32
  33         <li>2 - References</li>
  34
  35         <li>3 - PPD File Syntax</li>
  36
  37         <li>4 - General Attributes</li>
  38
  39         <li>5 - Custom Options</li>
  40
  41         <li>6 - Color Profiles</li>
  42
  43         <li>7 - I18N Support</li>
  44
  45         <li>A - Glossary</li>
  46
  47         <li>B - Change History</li>
  48
  49 </ul>
  50
  51 <embed src="references.shtml"/>
  52
  53 <h1>PPD File Syntax</h1>
  54
  55 <p>PostScript Printer Description ("PPD") files describe the
  56 capabilities of each printer and are used by CUPS to support
  57 printer-specific features and intelligent filtering.</p>
  58
  59 <p>The PPD file format is described in <a
  60 href="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
  61 Adobe TechNote #5003: PostScript Printer Description File Format
  62 Specification Version 4.3</a>.</p>
  63
  64 <p>The format is text-based and uses lines of up to 255
  65 characters terminated by a carriage return, linefeed, or
  66 combination of carriage return and line feed. The following ABNF
  67 definition [RFC2234] defines the general format of lines in a
  68 PPD file:</p>
  69
  70 <pre>
  71     PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
  72
  73     HEADER   = "*" 0x50.50.44.2D.41.64.6F.62.65 ":"   ; *PPD-Adobe:
  74                *WSP DQUOTE "4.3" DQUOTE LINE-END
  75
  76     COMMENT  = "*%" *TCHAR LINE-END
  77
  78     DATA     = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
  79                1*(*WSP VALUE) LINE-END
  80
  81     VALUE    = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE
  82
  83     KCHAR    = ALPHA / DIGIT / "_" / "." / "-"
  84
  85     SCHAR    = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF
  86
  87     TCHAR    = %x20-7E / %xA0-FF
  88
  89     LINE-END = CR / LF / CR LF
  90 </pre>
  91
  92
  93 <h1>General Attributes</h1>
  94
  95 <h2>cupsFilter</h2>
  96
  97 <p>This string attribute provides a conversion rule of the
  98 form:</p>
  99
 100 <pre>
 101     source/type cost program
 102 </pre>
 103
 104 <p>The destination type is assumed to the printer's type. If a
 105 printer supports the source type directly the special filter
 106 program "-" may be specified.</p>
 107
 108 <h2>cupsFlipDuplex</h2>
 109
 110 <p>This boolean attribute notifies the RIP filters that the
 111 destination printer requires an upside-down image for the back
 112 page. The default value is false.</p>
 113
 114 <h2>cupsManualCopies</h2>
 115
 116 <p>This boolean attribute notifies the RIP filters that the
 117 destination printer does not support copy generation in
 118 hardware. The default value is false.</p>
 119
 120 <h2>cupsModelNumber</h2>
 121
 122 <p>This integer attribute specifies a printer-specific model
 123 number. This number can be used by a filter program to adjust
 124 the output for a specific model of printer.</p>
 125
 126 <h2>cupsProtocol</h2>
 127
 128 <p>This optional attribute describes which binary communication
 129 protocol to use when printing binary PostScript data. The
 130 strings "None", "BCP", and "TBCP" are recognized, corresponding
 131 to no encoding, BCP, and TBCP respectively.</p>
 132
 133 <h2>cupsVersion</h2>
 134
 135 <p>This required attribute describes which version of the CUPS
 136 IDD was used for the PPD file extensions. Currently it must be
 137 the string "1.0", "1.1", or "1.2".</p>
 138
 139
 140 <h1>Custom Options</h1>
 141
 142
 143 <h1>Color Profiles</h1>
 144
 145 <h4>cupsColorProfile</h4>
 146
 147 <p>This string attribute specifies a color profile of the
 148 form:</p>
 149
 150 <pre>
 151     *cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
 152 </pre>
 153
 154 <p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
 155 to act as a wildcard. Otherwise they must match one of the
 156 <tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
 157 the PPD file.</p>
 158
 159 <p>The <i>density</i> and <i>gamma</i> values define gamma and
 160 density adjustment function such that:</p>
 161
 162 <pre>
 163     f(x) = density * x<SUp>gamma</SUp>
 164 </pre>
 165
 166 <p>The <i>m00</i> through <i>m22</i> values define a 3x3
 167 transformation matrix for the CMY color values. The density
 168 function is applied <i>after</i> the CMY transformation:</p>
 169
 170 <pre>
 171     | m00 m01 m02 |
 172     | m10 m11 m12 |
 173     | m20 m21 m22 |
 174 </pre>
 175
 176 <h2>cupsICCProfile</h2>
 177
 178 <p>This attribute specifies an ICC color profile of the
 179 form:</p>
 180
 181 <pre>
 182     *cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
 183 </pre>
 184
 185 <p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
 186 <tt>Resolution</tt> keywords specify a selector for color
 187 profiles. If omitted, the color profile will match any option
 188 keyword for the corresponding main keyword.</p>
 189
 190 <p>The <tt>Description</tt> specifies human-readable text that
 191 is associated with the color profile. The <tt>filename</tt>
 192 portion specifies the ICC color profile to use; if the filename
 193 is not absolute, it is loaded relative to the
 194 <var>/usr/share/cups/profiles</var> directory.</p>
 195
 196 <h3>Customizing the Profile Selection Keywords</h3>
 197
 198 <p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
 199 <tt>Resolution</tt> keywords can be reassigned to different main
 200 keywords, allowing drivers to do color profile selection based
 201 on different parameters. The <tt>cupsICCQualifier1</tt>,
 202 <tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt>
 203 attributes define the mapping from selector to main keyword:</p>
 204
 205 <pre>
 206     *cupsICCQualifier1: MainKeyword
 207     *cupsICCQualifier2: MainKeyword
 208     *cupsICCQualifier3: MainKeyword
 209 </pre>
 210
 211 <p>The default mapping is as follows:</p>
 212
 213 <pre>
 214     *cupsICCQualifier1: ColorModel
 215     *cupsICCQualifier2: MediaType
 216     *cupsICCQualifier3: Resolution
 217 </pre>
 218
 219 <h1><a name'I18N'>I18N Support</a></h1>
 220
 221 <p>CUPS 1.2 and higher adds support for PPD files containing multiple
 222 languages by following the following rules:</p>
 223
 224 <ol>
 225
 226         <li>The <tt>LanguageVersion</tt> is <tt>English</tt></li>
 227
 228         <li>The <tt>LanguageEncoding</tt> is <tt>ISOLatin1</tt></li>
 229
 230         <li>Main and option keywords may not exceed 34
 231         characters, which is a subset of what the Adobe PPD spec
 232         allows.</li>
 233
 234         <li>Translations are specified using a locale prefix of
 235         the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
 236         language code and "CC" is the 2-letter ISO country
 237         code</li>
 238
 239         <li>Translation strings are encoded using UTF-8.</li>
 240
 241         <li>Main keywords are translated using any of the
 242         following forms:
 243         <p><tt>*ll.Translation MainKeyword/translation
 244         text: ""</tt><br />
 245         <tt>*ll_CC.Translation MainKeyword/translation
 246         text: ""</tt></p></li>
 247
 248         <li>Option keywords are translated using any of the
 249         following forms:
 250         <p><tt>*ll.MainKeyword OptionKeyword/translation
 251         text: ""</tt><br />
 252         <tt>*ll_CC.MainKeyword OptionKeyword/translation
 253         text: ""</tt></p></li>
 254
 255 </ol>
 256
 257 <p>The following example shows how a fictional Foobar Laser 9999
 258 PPD file would be localized for English, French, and German:</p>
 259
 260 <pre>
 261     *LanguageVersion: English
 262     *LanguageEncoding: ISOLatin1
 263     *ModelName: "Foobar Laser 9999"
 264     *fr_FR.Translation ModelName/La Foobar Laser 9999: ""
 265     *de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""
 266     ...
 267     *OpenUI *InputSlot/Paper Source: PickOne
 268     *OrderDependency: 10 AnySetup *InputSlot
 269     *DefaultInputSlot: Auto
 270     *fr_FR.Translation InputSlot/Papier source: ""
 271     *de_DE.Translation InputSlot/Papiereinzug: ""
 272     *InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice"
 273     *fr_FR.InputSlot Auto/Par Defaut: ""
 274     *de_DE.InputSlot Auto/Standard: ""
 275     *InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice"
 276     *fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
 277     *de_DE.InputSlot Manual/Manueller Einzug: ""
 278     *CloseUI: *InputSlot
 279 </pre>
 280
 281 <embed src="glossary.shtml"/>
 282
 283 <h1>Change History</h1>
 284
 285 <h2>Changes in CUPS 1.2</h2>
 286
 287 <ul>
 288
 289         <li><tt>cupsICCProfile</tt></li>
 290
 291         <li>New I18N support</li>
 292
 293         <li></li>
 294
 295         <li></li>
 296
 297         <li></li>
 298
 299         <li></li>
 300
 301         <li></li>
 302
 303         <li></li>
 304
 305         <li></li>
 306
 307 </ul>
 308
 309 <h2>Changes in CUPS 1.1</h2>
 310
 311 <ul>
 312
 313         <li><tt>cupsProtocol</tt></li>
 314
 315         <li><tt>cupsFlipDuplex</tt></li>
 316
 317         <li></li>
 318
 319         <li></li>
 320
 321         <li></li>
 322
 323         <li></li>
 324
 325         <li></li>
 326
 327         <li></li>
 328
 329         <li></li>
 330
 331 </ul>
 332
 333 </body>
 334 </html>