1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
3 <!-- SECTION: Programming -->
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'
>
11 "$Id: spec-ppd.html 5138 2006-02-21 10:49:06Z mike $"
13 CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
15 Copyright 1997-2006 by Easy Software Products.
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
24 Attn: CUPS Licensing Information
25 Easy Software Products
26 44141 Airport View Drive, Suite 204
27 Hollywood, Maryland 20636 USA
30 EMail: cups-info@cups.org
31 WWW: http://www.cups.org
34 <h2 class='title'
><a name='INTRODUCTION'
>Introduction
</a></h2>
36 <p>This specification describes the attributes and extensions
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
45 <h2 class='title'
><a name='SYNTAX'
>PPD File Syntax
</a></h2>
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
54 PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
56 HEADER =
"*" 0x50.50.44.2D
.41.64.6F
.62.65 ":" ; *PPD-Adobe:
57 *WSP DQUOTE
"4.3" DQUOTE LINE-END
59 COMMENT =
"*%" *TCHAR LINE-END
61 DATA =
"*" 1*KCHAR [ WSP
1*KCHAR [
"/" 1*TCHAR ] ]
":"
62 1*(*WSP VALUE) LINE-END
64 VALUE =
1*TCHAR / DQUOTE
1*SCHAR DQUOTE
66 KCHAR = ALPHA / DIGIT /
"_" /
"." /
"-"
68 SCHAR = LINE-END / WSP / %x21 / %x23-
7E / %xA0-FF
70 TCHAR = %x20-
7E / %xA0-FF
72 LINE-END = CR / LF / CR LF
76 <h2 class='title'
><a name='ATTRIBUTES'
>General Attributes
</a></h2>
78 <h3>APDuplexRequiresFlippedMargin
</h3>
80 <p class='summary'
>*APDuplexRequiresFlippedMargin: boolean
</p>
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>
90 <em>*% Don't swap the top and bottom margins for the back side
</em>
91 *APDuplexRequiresFlippedMargin: false
94 <p>Also see the related
<tt>cupsFlipDuplex
</tt> attribute.
</p>
98 <p class='summary'
>*cupsFilter:
"source/type cost program"</p>
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>
107 <pre class='command'
>
108 <em>*% Standard raster printer driver filter
</em>
109 *cupsFilter:
"application/vnd.cups-raster 100 rastertofoo"
111 <em>*% Plain text filter
</em>
112 *cupsFilter:
"text/plain 10 texttofoo"
114 <em>*% Pass-through filter for PostScript printers
</em>
115 *cupsFilter:
"application/vnd.cups-postscript 0 -"
118 <h3>cupsFlipDuplex
</h3>
120 <p class='summary'
>*cupsFlipDuplex: boolean
</p>
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>
128 <pre class='command'
>
129 <em>*% Flip the page image for the back side of duplexed output
</em>
130 *cupsFlipDuplex: true
133 <p>Also see the related
<tt>APDuplexRequiresFlippedMargins
</tt> attribute.
</p>
135 <h3>cupsLanguages
</h3>
137 <p class='summary'
>*cupsLanguages:
"locale list"</p>
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>
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"
150 <h3>cupsManualCopies
</h3>
152 <p class='summary'
>*cupsManualCopies: boolean
</p>
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>
160 <pre class='command'
>
161 <em>*% Tell the RIP filters to generate the copies for us
</em>
162 *cupsManualCopies: true
165 <h3>cupsModelNumber
</h3>
167 <p class='summary'
>*cupsModelNumber: number
</p>
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>
175 <pre class='command'
>
176 <em>*% Specify an integer for a driver-specific model number
</em>
177 *cupsModelNumber:
1234
180 <h3>cupsPortMonitor
</h3>
182 <p class='summary'
>*cupsPortMonitor urischeme/Descriptive Text:
"port monitor"</p>
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>
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>
200 <pre class='command'
>
201 <em>*% Specify a PostScript printer that supports the TBCP protocol
</em>
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"
208 <em>*% Specify a printer-specific port monitor for an Epson USB printer
</em>
209 *cupsPortMonitor usb/USB Status Monitor:
"epson-usb"
214 <p class='summary'
>*cupsVersion: major.minor
</p>
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>
222 <pre class='command'
>
223 <em>*% Specify a CUPS
1.2 driver
</em>
228 <h2 class='title'
><a name='OPTIONS'
>Custom Options
</a></h2>
230 <p>CUPS supports custom options using an extension of the
231 <tt>CustomPageSize
</tt> and
<tt>ParamCustomPageSize
</tt>
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
239 *ParamCustomFoo NameN/Text N: order type minimum maximum
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>
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 "<</cupsReal1 2 1 roll>>setpagedevice" and the
255 option value is
"2.0" then CUPS will output the string
256 "2.0 <</cupsReal1 2 1 roll>>setpagedevice".
</p>
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>
266 <p>The
"type" is one of the following keywords:
</p>
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>
274 <li><tt>int
</tt> - an integer value from
"minimum" to
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>
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>
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>
291 <li><tt>points
</tt> - a measurement value in points from
292 "minimum" to
"maximum"</li>
294 <li><tt>real
</tt> - a real value from
"minimum" to
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>
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<0A>"
312 *JCLPasscode
2222:
"@PJL SET PASSCODE = 2222<0A>"
313 *JCLPasscode
3333:
"@PJL SET PASSCODE = 3333<0A>"
314 *JCLCloseUI: *JCLPasscode
316 <em>*% Custom JCL key code option
</em>
317 *CustomJCLPasscode True:
"@PJL SET PASSCODE = \1<0A>"
318 *ParamCustomJCLPasscode Code/Key Code:
1 passcode
4 4
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:
"<</cupsString1(Draft)>>setpagedevice"
327 *CloseUI: *WatermarkText
329 <em>*% Custom PostScript watermark option
</em>
330 *CustomWatermarkText True:
"<</cupsString1 2 1 roll>>setpagedevice"
331 *ParamCustomWatermarkText Text:
1 string
0 32
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:
"<</cupsReal1 1.0/cupsReal2 1.0>>setpagedevice"
339 *GammaDensity Light/Lighter:
"<</cupsReal1 0.9/cupsReal2 0.67>>setpagedevice"
340 *GammaDensity Dark/Darker:
"<</cupsReal1 1.1/cupsReal2 1.5>>setpagedevice"
341 *CloseUI: *GammaDensity
343 <em>*% Custom PostScript gamma/density option
</em>
344 *CustomGammaDensity True:
"<</cupsReal1 3 1 roll/cupsReal2 3 1>>setpagedevice"
345 *ParamCustomGammaDensity Gamma:
1 curve
0.1 10
346 *ParamCustomGammaDensity Density:
2 real
0 2
350 <h2 class='title'
><a name='PROFILES'
>Color Profiles
</a></h2>
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>
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>
361 <h3>cupsColorProfile
</h3>
363 <p class='summary'
>*cupsColorProfile Resolution/MediaType:
"density
364 gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
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>
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
375 <p>The
<i>density
</i> and
<i>gamma
</i> values define gamma and
376 density adjustment function such that:
</p>
378 <pre class='command'
>
379 f(x) = density * x
<sup style='font-size:
100%'
>gamma
</sup>
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>
386 <pre class='command'
>
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"
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"
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"
405 <h3>cupsICCProfile
</h3>
407 <p class='summary'
>*cupsICCProfile
408 ColorModel.MediaType.Resolution/Description:
"filename"</p>
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>
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>
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"
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"
432 <em>*% Specify a default profile for printing at all other resolutions and media types
</em>
433 *cupsICCProfile ../Default:
"vendor/foo-default.icc"
436 <h4>Customizing the Profile Selection Keywords
</h4>
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>
445 <pre class='command'
>
446 *cupsICCQualifier1: MainKeyword
447 *cupsICCQualifier2: MainKeyword
448 *cupsICCQualifier3: MainKeyword
451 <p>The default mapping is as follows:
</p>
453 <pre class='command'
>
454 *cupsICCQualifier1: ColorModel
455 *cupsICCQualifier2: MediaType
456 *cupsICCQualifier3: Resolution
460 <h2 class='title'
><a name='I18N'
>Globalized PPD Support
</a></h2>
462 <p>CUPS
1.2 and higher adds support for PPD files containing multiple
463 languages by following the following additional rules:
</p>
467 <li>The
<tt>LanguageVersion
</tt> MUST be
<tt>English
</tt></li>
469 <li>The
<tt>LanguageEncoding
</tt> MUST be
<tt>ISOLatin1
</tt></li>
471 <li>The
<tt>cupsLanguages
</tt> attribute MUST be provided and
472 list each of the supported locales in the PPD file
</li>
474 <li>Main and option keywords MUST NOT exceed
34 (instead of
40)
475 characters to allow room for the locale prefixes in translation
478 <li>The main keyword
"Translation" MUST NOT be used
</li>
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>
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
491 <li>Locale-specific translation strings MUST be encoded
494 <li>Main keywords MUST be localized using one of the
496 <p><tt>*ll.Translation MainKeyword/translation
498 <tt>*ll_CC.Translation MainKeyword/translation
499 text:
""</tt></p></li>
501 <li>Option keywords MUST be localized using one of the
503 <p><tt>*ll.MainKeyword OptionKeyword/translation
505 <tt>*ll_CC.MainKeyword OptionKeyword/translation
506 text:
""</tt></p></li>
508 <li>Localization attributes MAY appear anywhere after the
509 first line of the PPD file
</li>
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>
523 <pre class='command'
>
524 *LanguageVersion: English
525 *LanguageEncoding: ISOLatin1
526 *cupsLanguages:
"de_DE fr_FR"
527 *ModelName:
"Foobar Laser 9999"
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:
""
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:
"<</ManualFeed false>>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:
"<</ManualFeed true>>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:
""
553 <h2 class='title'
><a name='HISTORY'
>Change History
</a></h2>
555 <h3>Changes in CUPS
1.2</h3>
559 <li>Added globalization support attributes
</li>
561 <li>Added custom option values support
</li>
563 <li>Added
<tt>APDuplexRequiresFlippedMargin
</tt> attribute
</li>
565 <li>Added
<tt>cupsICCProfile
</tt> attribute
</li>
567 <li>Added
<tt>cupsLanguages
</tt> attribute
</li>
569 <li>Added
<tt>cupsPortMonitor
</tt> attribute
</li>
571 <li>Removed
<tt>cupsProtocol
</tt> attribute
</li>
575 <h3>Changes in CUPS
1.1</h3>
579 <li>Added
<tt>cupsFlipDuplex
</tt> attribute
</li>
581 <li>Added
<tt>cupsProtocol
</tt> attribute
</li>