]> git.ipfire.org Git - thirdparty/cups.git/blob - doc/help/spec-ppd.html
6dc27cb6b6513e1131f9f220e2f9e9d7770e58cb
[thirdparty/cups.git] / 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 <link rel='stylesheet' type='text/css' href='../cups.css'>
8 </head>
9 <body>
10 <!--
11 "$Id: spec-ppd.html 5138 2006-02-21 10:49:06Z mike $"
12
13 CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
14
15 Copyright 1997-2006 by Easy Software Products.
16
17 These coded instructions, statements, and computer programs are the
18 property of Easy Software Products and are protected by Federal
19 copyright law. Distribution and use rights are outlined in the file
20 "LICENSE.txt" which should have been included with this file. If this
21 file is missing or damaged please contact Easy Software Products
22 at:
23
24 Attn: CUPS Licensing Information
25 Easy Software Products
26 44141 Airport View Drive, Suite 204
27 Hollywood, Maryland 20636 USA
28
29 Voice: (301) 373-9600
30 EMail: cups-info@cups.org
31 WWW: http://www.cups.org
32 -->
33
34 <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
35
36 <p>This specification describes the attributes and extensions
37 that CUPS adds to <a
38 href="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
39 Adobe TechNote #5003: PostScript Printer Description File Format
40 Specification Version 4.3</a>. PostScript Printer Description
41 ("PPD") files describe the capabilities of each printer and are
42 used by CUPS to support printer-specific features and intelligent
43 filtering.</p>
44
45 <h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2>
46
47 <p>The PPD format is text-based and uses lines of up to 255
48 characters terminated by a carriage return, linefeed, or
49 combination of carriage return and line feed. The following ABNF
50 definition [RFC2234] defines the general format of lines in a PPD
51 file:</p>
52
53 <pre class='command'>
54 PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
55
56 HEADER = "*" 0x50.50.44.2D.41.64.6F.62.65 ":" ; *PPD-Adobe:
57 *WSP DQUOTE "4.3" DQUOTE LINE-END
58
59 COMMENT = "*%" *TCHAR LINE-END
60
61 DATA = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
62 1*(*WSP VALUE) LINE-END
63
64 VALUE = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE
65
66 KCHAR = ALPHA / DIGIT / "_" / "." / "-"
67
68 SCHAR = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF
69
70 TCHAR = %x20-7E / %xA0-FF
71
72 LINE-END = CR / LF / CR LF
73 </pre>
74
75
76 <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
77
78 <h3>APDuplexRequiresFlippedMargin</h3>
79
80 <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
81
82 <p>This boolean attribute notifies the RIP filters that the
83 destination printer does not require the top and bottom margins
84 of the <tt>ImageableArea</tt> swapped for the back page. The
85 default value is <code>true</code>.</p>
86
87 <p>Example:</p>
88
89 <pre class='command'>
90 <em>*% Don't swap the top and bottom margins for the back side</em>
91 *APDuplexRequiresFlippedMargin: false
92 </pre>
93
94 <p>Also see the related <tt>cupsFlipDuplex</tt> attribute.</p>
95
96 <h3>cupsFilter</h3>
97
98 <p class='summary'>*cupsFilter: "source/type cost program"</p>
99
100 <p>This string attribute provides a conversion rule from the
101 given source type to the printer's native format using the
102 filter "program". If a printer supports the source type directly,
103 the special filter program "-" may be specified.</p>
104
105 <p>Examples:</p>
106
107 <pre class='command'>
108 <em>*% Standard raster printer driver filter</em>
109 *cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
110
111 <em>*% Plain text filter</em>
112 *cupsFilter: "text/plain 10 texttofoo"
113
114 <em>*% Pass-through filter for PostScript printers</em>
115 *cupsFilter: "application/vnd.cups-postscript 0 -"
116 </pre>
117
118 <h3>cupsFlipDuplex</h3>
119
120 <p class='summary'>*cupsFlipDuplex: boolean</p>
121
122 <p>This boolean attribute notifies the RIP filters that the
123 destination printer requires an upside-down image for the back
124 page. The default value is <code>false</code>.</p>
125
126 <p>Example:</p>
127
128 <pre class='command'>
129 <em>*% Flip the page image for the back side of duplexed output</em>
130 *cupsFlipDuplex: true
131 </pre>
132
133 <p>Also see the related <tt>APDuplexRequiresFlippedMargins</tt> attribute.</p>
134
135 <h3>cupsLanguages</h3>
136
137 <p class='summary'>*cupsLanguages: "locale list"</p>
138
139 <p>This attribute describes which language localizations are
140 included in the PPD. The "locale list" string is a space-delimited
141 list of locale names ("en", "en_US", "fr_FR", etc.)</p>
142
143 <p>Example:</p>
144
145 <pre class='command'>
146 <em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
147 *cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
148 </pre>
149
150 <h3>cupsManualCopies</h3>
151
152 <p class='summary'>*cupsManualCopies: boolean</p>
153
154 <p>This boolean attribute notifies the RIP filters that the
155 destination printer does not support copy generation in
156 hardware. The default value is <code>false</code>.</p>
157
158 <p>Example:</p>
159
160 <pre class='command'>
161 <em>*% Tell the RIP filters to generate the copies for us</em>
162 *cupsManualCopies: true
163 </pre>
164
165 <h3>cupsModelNumber</h3>
166
167 <p class='summary'>*cupsModelNumber: number</p>
168
169 <p>This integer attribute specifies a printer-specific model
170 number. This number can be used by a filter program to adjust
171 the output for a specific model of printer.</p>
172
173 <p>Example:</p>
174
175 <pre class='command'>
176 <em>*% Specify an integer for a driver-specific model number</em>
177 *cupsModelNumber: 1234
178 </pre>
179
180 <h3>cupsPortMonitor</h3>
181
182 <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
183
184 <p>This string attribute specifies printer-specific "port
185 monitor" filters that may be used with the printer. The CUPS
186 scheduler also looks for the <tt>Protocols</tt> attribute to see
187 if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
188 so, the corresponding port monitor ("bcp" and "tbcp",
189 respectively) is listed in the printer's
190 <tt>port-monitor-supported</tt> attribute.</p>
191
192 <p>The "urischeme" portion of the attribute specifies the URI scheme
193 that this port monitor should be used for. Typically this is used to
194 pre-select a particular port monitor for each type of connection that
195 is supported by the printer. The "port monitor" string can be "none"
196 to disable the port monitor for the given URI scheme.</p>
197
198 <p>Examples:</p>
199
200 <pre class='command'>
201 <em>*% Specify a PostScript printer that supports the TBCP protocol</em>
202 *Protocols: TBCP PJL
203
204 <em>*% Specify that TBCP should be used for socket connections but not USB</em>
205 *cupsPortMonitor socket/AppSocket Printing: "tbcp"
206 *cupsPortMonitor usb/USB Printing: "none"
207
208 <em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
209 *cupsPortMonitor usb/USB Status Monitor: "epson-usb"
210 </pre>
211
212 <h3>cupsVersion</h3>
213
214 <p class='summary'>*cupsVersion: major.minor</p>
215
216 <p>This required attribute describes which version of the CUPS
217 PPD file extensions was used. Currently it must be the string
218 "1.0", "1.1", or "1.2".</p>
219
220 <p>Example:</p>
221
222 <pre class='command'>
223 <em>*% Specify a CUPS 1.2 driver</em>
224 *cupsVersion: "1.2"
225 </pre>
226
227
228 <h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
229
230 <p>CUPS supports custom options using an extension of the
231 <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt>
232 syntax:</p>
233
234 <pre class='command'>
235 *CustomFoo True: "command"
236 *ParamCustomFoo Name1/Text 1: order type minimum maximum
237 *ParamCustomFoo Name2/Text 2: order type minimum maximum
238 ...
239 *ParamCustomFoo NameN/Text N: order type minimum maximum
240 </pre>
241
242 <p>When the base option is part of the <tt>JCLSetup</tt> section,
243 the "command" string contains JCL commands with "\order"
244 placeholders for each numbered parameter. The CUPS API handles
245 any necessary value quoting for HP-PJL commands. For example, if
246 the JCL command string is "@PJL SET PASSCODE=\1" and the first
247 option value is "1234" then CUPS will output the string
248 "@PJL SET PASSCODE=1234".</p>
249
250 <p>For non-<tt>JCLSetup</tt> options, the "order" value is a
251 number from 1 to N and specifies the order of values as they are
252 placed on the stack before the command. For example, if the
253 PostScript command string is
254 "&lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice" and the
255 option value is "2.0" then CUPS will output the string
256 "2.0 &lt;&lt;/cupsReal1 2 1 roll&gt;&gt;setpagedevice".</p>
257
258 <blockquote><b>Note:</b> Currently only CustomPageSize supports
259 more than 1 parameter. This restriction is due to value encoding
260 issues, since the "Custom.value" format does not allow for
261 specification of named parameters. We anticipate supporting the
262 collection value format "{Name1=foo Name2=bar}" for the final
263 CUPS 1.2 release. In addition, the collection value format will
264 allow string values to contain spaces.</blockquote>
265
266 <p>The "type" is one of the following keywords:</p>
267
268 <ul>
269
270 <li><tt>curve</tt> - a real value from "minimum" to
271 "maximum" representing a gamma correction curve using the
272 function: f(x) = x <sup>value</sup></li>
273
274 <li><tt>int</tt> - an integer value from "minimum" to
275 "maximum"</li>
276
277 <li><tt>invcurve</tt> - a real value from "minimum" to
278 "maximum" representing a gamma correction curve using the
279 function: f(x) = x <sup>1 / value</sup></li>
280
281 <li><tt>passcode</tt> - a string of numbers value with a
282 minimum of "minimum" numbers and a maximum of "maximum"
283 numbers ("minimum" and "maximum" are numbers and passcode
284 strings are not displayed in the user interface)</li>
285
286 <li><tt>password</tt> - a string value with a minimum of
287 "minimum" characters and a maximum of "maximum"
288 characters ("minimum" and "maximum" are numbers and password
289 strings are not displayed in the user interface)</li>
290
291 <li><tt>points</tt> - a measurement value in points from
292 "minimum" to "maximum"</li>
293
294 <li><tt>real</tt> - a real value from "minimum" to
295 "maximum"</li>
296
297 <li><tt>string</tt> - a string value with a minimum of
298 "minimum" characters and a maximum of "maximum"
299 characters ("minimum" and "maximum" are numbers)</li>
300
301 </ul>
302
303 <p>Examples:</p>
304
305 <pre class='command'>
306 <em>*% Base JCL key code option</em>
307 *OpenUI JCLPasscode/Key Code: PickOne
308 *OrderDependency: 10 JCLSetup *JCLPasscode
309 *DefaultJCLPasscode: None
310 *JCLPasscode None/No Code: ""
311 *JCLPasscode 1111: "@PJL SET PASSCODE = 1111&lt;0A&gt;"
312 *JCLPasscode 2222: "@PJL SET PASSCODE = 2222&lt;0A&gt;"
313 *JCLPasscode 3333: "@PJL SET PASSCODE = 3333&lt;0A&gt;"
314 *JCLCloseUI: *JCLPasscode
315
316 <em>*% Custom JCL key code option</em>
317 *CustomJCLPasscode True: "@PJL SET PASSCODE = \1&lt;0A&gt;"
318 *ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
319
320
321 <em>*% Base PostScript watermark option</em>
322 *OpenUI WatermarkText/Watermark Text: PickOne
323 *OrderDependency: 10 AnySetup *WatermarkText
324 *DefaultWatermarkText: None
325 *WatermarkText None: ""
326 *WatermarkText Draft: "&lt;&lt;/cupsString1(Draft)&gt;&gt;setpagedevice"
327 *CloseUI: *WatermarkText
328
329 <em>*% Custom PostScript watermark option</em>
330 *CustomWatermarkText True: "&lt;&lt;/cupsString1 2 1 roll&gt;&gt;setpagedevice"
331 *ParamCustomWatermarkText Text: 1 string 0 32
332
333
334 <em>*% Base PostScript gamma/density option</em>
335 *OpenUI GammaDensity/Gamma and Density: PickOne
336 *OrderDependency: 10 AnySetup *GammaDensity
337 *DefaultGammaDensity: Normal
338 *GammaDensity Normal/Normal: "&lt;&lt;/cupsReal1 1.0/cupsReal2 1.0&gt;&gt;setpagedevice"
339 *GammaDensity Light/Lighter: "&lt;&lt;/cupsReal1 0.9/cupsReal2 0.67&gt;&gt;setpagedevice"
340 *GammaDensity Dark/Darker: "&lt;&lt;/cupsReal1 1.1/cupsReal2 1.5&gt;&gt;setpagedevice"
341 *CloseUI: *GammaDensity
342
343 <em>*% Custom PostScript gamma/density option</em>
344 *CustomGammaDensity True: "&lt;&lt;/cupsReal1 3 1 roll/cupsReal2 3 1&gt;&gt;setpagedevice"
345 *ParamCustomGammaDensity Gamma: 1 curve 0.1 10
346 *ParamCustomGammaDensity Density: 2 real 0 2
347 </pre>
348
349
350 <h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
351
352 <p>CUPS supports two types of color profiles. The first type is
353 based on sRGB and is used by the standard CUPS raster filters and
354 ESP Ghostscript. The second type is based on ICC profiles and is
355 used by the Core Graphics-based filters on MacOS X.</p>
356
357 <blockquote><b>Note:</b> At this time, none of the CUPS raster
358 filters support ICC profiles. This will be addressed as time
359 and resources permit.</blockquote>
360
361 <h3>cupsColorProfile</h3>
362
363 <p class='summary'>*cupsColorProfile Resolution/MediaType: "density
364 gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
365
366 <p>This string attribute specifies an sRGB-based color profile
367 consisting of gamma and density controls and a 3x3 CMY color
368 transform matrix.</p>
369
370 <p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
371 to act as a wildcard. Otherwise they must match one of the
372 <tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
373 the PPD file.</p>
374
375 <p>The <i>density</i> and <i>gamma</i> values define gamma and
376 density adjustment function such that:</p>
377
378 <pre class='command'>
379 f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
380 </pre>
381
382 <p>The <i>m00</i> through <i>m22</i> values define a 3x3
383 transformation matrix for the CMY color values. The density
384 function is applied <i>after</i> the CMY transformation:</p>
385
386 <pre class='command'>
387 | m00 m01 m02 |
388 | m10 m11 m12 |
389 | m20 m21 m22 |
390 </pre>
391
392 <p>Examples:</p>
393
394 <pre class='command'>
395 <em>*% Specify a profile for printing at 360dpi on all media types</em>
396 *cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
397
398 <em>*% Specify a profile for printing at 720dpi on Glossy media</em>
399 *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"
400
401 <em>*% Specify a default profile for printing at all other resolutions and media types</em>
402 *cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
403 </pre>
404
405 <h3>cupsICCProfile</h3>
406
407 <p class='summary'>*cupsICCProfile
408 ColorModel.MediaType.Resolution/Description: "filename"</p>
409
410 <p>This attribute specifies an ICC color profile that is
411 used to convert the document colors to the device
412 colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
413 <tt>Resolution</tt> keywords specify a selector for color
414 profiles. If omitted, the color profile will match any option
415 keyword for the corresponding main keyword.</p>
416
417 <p>The <tt>Description</tt> specifies human-readable text that
418 is associated with the color profile. The <tt>filename</tt>
419 portion specifies the ICC color profile to use; if the filename
420 is not absolute, it is loaded relative to the
421 <var>/usr/share/cups/profiles</var> directory.</p>
422
423 <p>Examples:</p>
424
425 <pre class='command'>
426 <em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
427 *cupsICCProfile CMYK..360dpi/360dpi CMYK: "vendor/foo-360-cmyk.icc"
428
429 <em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
430 *cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "vendor/foo-720-glossy-rgb.icc"
431
432 <em>*% Specify a default profile for printing at all other resolutions and media types</em>
433 *cupsICCProfile ../Default: "vendor/foo-default.icc"
434 </pre>
435
436 <h4>Customizing the Profile Selection Keywords</h4>
437
438 <p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
439 <tt>Resolution</tt> keywords can be reassigned to different main
440 keywords, allowing drivers to do color profile selection based
441 on different parameters. The <tt>cupsICCQualifier1</tt>,
442 <tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt>
443 attributes define the mapping from selector to main keyword:</p>
444
445 <pre class='command'>
446 *cupsICCQualifier1: MainKeyword
447 *cupsICCQualifier2: MainKeyword
448 *cupsICCQualifier3: MainKeyword
449 </pre>
450
451 <p>The default mapping is as follows:</p>
452
453 <pre class='command'>
454 *cupsICCQualifier1: ColorModel
455 *cupsICCQualifier2: MediaType
456 *cupsICCQualifier3: Resolution
457 </pre>
458
459
460 <h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
461
462 <p>CUPS 1.2 and higher adds support for PPD files containing multiple
463 languages by following the following additional rules:</p>
464
465 <ol>
466
467 <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
468
469 <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
470
471 <li>The <tt>cupsLanguages</tt> attribute MUST be provided and
472 list each of the supported locales in the PPD file</li>
473
474 <li>Main and option keywords MUST NOT exceed 34 (instead of 40)
475 characters to allow room for the locale prefixes in translation
476 attributes</li>
477
478 <li>The main keyword "Translation" MUST NOT be used</li>
479
480 <li>Translation strings included with the main and option
481 keywords MUST NOT contain characters outside the ASCII
482 subset of ISOLatin1 and UTF-8; developers wishing to use
483 characters outside ASCII MUST provide a separate set of
484 English localization attributes for the affected keywords.</li>
485
486 <li>Localizations are specified using a locale prefix of
487 the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
488 language code and "CC" is the 2-letter ISO country
489 code</li>
490
491 <li>Locale-specific translation strings MUST be encoded
492 using UTF-8.</li>
493
494 <li>Main keywords MUST be localized using one of the
495 following forms:
496 <p><tt>*ll.Translation MainKeyword/translation
497 text: ""</tt><br />
498 <tt>*ll_CC.Translation MainKeyword/translation
499 text: ""</tt></p></li>
500
501 <li>Option keywords MUST be localized using one of the
502 following forms:
503 <p><tt>*ll.MainKeyword OptionKeyword/translation
504 text: ""</tt><br />
505 <tt>*ll_CC.MainKeyword OptionKeyword/translation
506 text: ""</tt></p></li>
507
508 <li>Localization attributes MAY appear anywhere after the
509 first line of the PPD file</li>
510
511 </ol>
512
513 <blockquote><b>Note:</b>
514 We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt>
515 and limit the allowed base translation strings to ASCII to avoid
516 character coding issues that would otherwise occur. In addition,
517 requiring the base translation strings to be in English allows
518 for easier fallback translation when no localization is provided
519 in the PPD file for a given locale.</blockquote>
520
521 <p>Examples:</p>
522
523 <pre class='command'>
524 *LanguageVersion: English
525 *LanguageEncoding: ISOLatin1
526 *cupsLanguages: "de_DE fr_FR"
527 *ModelName: "Foobar Laser 9999"
528
529 <em>*% Localize ModelName for French and German</em>
530 *fr_FR.Translation ModelName/La Foobar Laser 9999: ""
531 *de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""
532
533 ...
534
535 *OpenUI *InputSlot/Paper Source: PickOne
536 *OrderDependency: 10 AnySetup *InputSlot
537 *DefaultInputSlot: Auto
538 <em>*% Localize InputSlot for French and German</em>
539 *fr_FR.Translation InputSlot/Papier source: ""
540 *de_DE.Translation InputSlot/Papiereinzug: ""
541 *InputSlot Auto/Default: "&lt;&lt;/ManualFeed false&gt;&gt;setpagedevice"
542 <em>*% Localize InputSlot=Auto for French and German</em>
543 *fr_FR.InputSlot Auto/Par Defaut: ""
544 *de_DE.InputSlot Auto/Standard: ""
545 *InputSlot Manual/Manual Feed: "&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice"
546 <em>*% Localize InputSlot=Manual for French and German</em>
547 *fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
548 *de_DE.InputSlot Manual/Manueller Einzug: ""
549 *CloseUI: *InputSlot
550 </pre>
551
552
553 <h2 class='title'><a name='HISTORY'>Change History</a></h2>
554
555 <h3>Changes in CUPS 1.2</h3>
556
557 <ul>
558
559 <li>Added globalization support attributes</li>
560
561 <li>Added custom option values support</li>
562
563 <li>Added <tt>APDuplexRequiresFlippedMargin</tt> attribute</li>
564
565 <li>Added <tt>cupsICCProfile</tt> attribute</li>
566
567 <li>Added <tt>cupsLanguages</tt> attribute</li>
568
569 <li>Added <tt>cupsPortMonitor</tt> attribute</li>
570
571 <li>Removed <tt>cupsProtocol</tt> attribute</li>
572
573 </ul>
574
575 <h3>Changes in CUPS 1.1</h3>
576
577 <ul>
578
579 <li>Added <tt>cupsFlipDuplex</tt> attribute</li>
580
581 <li>Added <tt>cupsProtocol</tt> attribute</li>
582
583 </ul>
584
585 </body>
586 </html>