Load cups into easysw/current.
[thirdparty/cups.git] / 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>