<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
-<!-- SECTION: Programming -->
+<!-- SECTION: Specifications -->
<head>
<title>CUPS PPD Extensions</title>
<meta name='keywords' content='Programming, PostScript Printer Description'>
+ <link rel='stylesheet' type='text/css' href='../cups.css'>
</head>
<body>
<!--
- "$Id: spec-ppd.html 4918 2006-01-12 05:14:40Z mike $"
+ "$Id: spec-ppd.html 5217 2006-03-02 21:24:01Z mike $"
CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
<p>This specification describes the attributes and extensions
that CUPS adds to <a
-href="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
+href="http://partners.adobe.com/public/developer/en/ps/5003.PPD_Spec_v4.3.pdf">
Adobe TechNote #5003: PostScript Printer Description File Format
Specification Version 4.3</a>. PostScript Printer Description
("PPD") files describe the capabilities of each printer and are
<h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
-<h3>cupsFilter</h3>
+<h3>APBookFile</h3>
+
+<p class='summary'>*APBookFile: "file URL"</p>
-<p>This string attribute provides a conversion rule of the
-form:</p>
+<p>This string attribute specifies the Apple help book file to use
+for this printer driver.</p>
+
+<p>Example:</p>
<pre class='command'>
-source/type cost program
+*APBookFile: "file:///Library/Printers/vendor/Help/filename"
</pre>
-<p>The destination type is assumed to the printer's type. If a
-printer supports the source type directly, the special filter
-program "-" may be specified.</p>
+<h3>APDuplexRequiresFlippedMargin</h3>
+
+<p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
+
+<p>This boolean attribute notifies the RIP filters that the
+destination printer does not require the top and bottom margins
+of the <tt>ImageableArea</tt> swapped for the back page. The
+default value is <code>true</code>.</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Don't swap the top and bottom margins for the back side</em>
+*APDuplexRequiresFlippedMargin: false
+</pre>
+
+<p>Also see the related <tt>cupsFlipDuplex</tt> attribute.</p>
+
+<h3>cupsFilter</h3>
+
+<p class='summary'>*cupsFilter: "source/type cost program"</p>
+
+<p>This string attribute provides a conversion rule from the
+given source type to the printer's native format using the
+filter "program". If a printer supports the source type directly,
+the special filter program "-" may be specified.</p>
<p>Examples:</p>
<h3>cupsFlipDuplex</h3>
+<p class='summary'>*cupsFlipDuplex: boolean</p>
+
<p>This boolean attribute notifies the RIP filters that the
destination printer requires an upside-down image for the back
-page. The default value is false.</p>
+page. The default value is <code>false</code>.</p>
<p>Example:</p>
*cupsFlipDuplex: true
</pre>
+<p>Also see the related <tt>APDuplexRequiresFlippedMargins</tt> attribute.</p>
+
+<h3>cupsIPPReason</h3>
+
+<p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
+
+<p>This optional attribute maps custom
+<code>printer-state-reasons</code> keywords that are generated by
+the driver to human readable text. The optional URIs string
+contains zero or more URIs separated by a newline. Each URI can
+be a CUPS server absolute path to a help file under the
+scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
+("http://www.domain.com/path/to/help/page.html"), or any other
+valid URI which directs the user at additional information
+concerning the condition that is being reported.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+<em>*% Map com.vendor-error to text but no page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: ""
+
+<em>*% Map com.vendor-error to text and a local page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
+
+<em>*% Map com.vendor-error to text and a remote page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
+
+<em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
+*APHelpBook: "file:///Library/Printers/vendor/Help/filename"
+*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
+help:anchor='com.vendor-error'%20bookID=Vendor%20Help
+http://www.vendor.com/help"
+*End
+</pre>
+
+<h3>cupsLanguages</h3>
+
+<p class='summary'>*cupsLanguages: "locale list"</p>
+
+<p>This attribute describes which language localizations are
+included in the PPD. The "locale list" string is a space-delimited
+list of locale names ("en", "en_US", "fr_FR", etc.)</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
+*cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
+</pre>
+
<h3>cupsManualCopies</h3>
+<p class='summary'>*cupsManualCopies: boolean</p>
+
<p>This boolean attribute notifies the RIP filters that the
destination printer does not support copy generation in
-hardware. The default value is false.</p>
+hardware. The default value is <code>false</code>.</p>
<p>Example:</p>
<h3>cupsModelNumber</h3>
+<p class='summary'>*cupsModelNumber: number</p>
+
<p>This integer attribute specifies a printer-specific model
number. This number can be used by a filter program to adjust
the output for a specific model of printer.</p>
<h3>cupsPortMonitor</h3>
+<p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
+
<p>This string attribute specifies printer-specific "port
monitor" filters that may be used with the printer. The CUPS
scheduler also looks for the <tt>Protocols</tt> attribute to see
respectively) is listed in the printer's
<tt>port-monitor-supported</tt> attribute.</p>
+<p>The "urischeme" portion of the attribute specifies the URI scheme
+that this port monitor should be used for. Typically this is used to
+pre-select a particular port monitor for each type of connection that
+is supported by the printer. The "port monitor" string can be "none"
+to disable the port monitor for the given URI scheme.</p>
+
<p>Examples:</p>
<pre class='command'>
<em>*% Specify a PostScript printer that supports the TBCP protocol</em>
*Protocols: TBCP PJL
+<em>*% Specify that TBCP should be used for socket connections but not USB</em>
+*cupsPortMonitor socket/AppSocket Printing: "tbcp"
+*cupsPortMonitor usb/USB Printing: "none"
+
<em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
-*cupsPortMonitor epson-usb/USB Status Monitor: "epson-usb"
+*cupsPortMonitor usb/USB Status Monitor: "epson-usb"
</pre>
<h3>cupsVersion</h3>
+<p class='summary'>*cupsVersion: major.minor</p>
+
<p>This required attribute describes which version of the CUPS
PPD file extensions was used. Currently it must be the string
"1.0", "1.1", or "1.2".</p>
*cupsVersion: "1.2"
</pre>
-
<h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
<p>CUPS supports custom options using an extension of the
<p>When the base option is part of the <tt>JCLSetup</tt> section,
the "command" string contains JCL commands with "\order"
placeholders for each numbered parameter. The CUPS API handles
-any necessary value quoting for HP-PJL commands.</p>
+any necessary value quoting for HP-PJL commands. For example, if
+the JCL command string is "@PJL SET PASSCODE=\1" and the first
+option value is "1234" then CUPS will output the string
+"@PJL SET PASSCODE=1234".</p>
<p>For non-<tt>JCLSetup</tt> options, the "order" value is a
number from 1 to N and specifies the order of values as they are
-placed on the stack before the command.</p>
+placed on the stack before the command. For example, if the
+PostScript command string is
+"<</cupsReal1 2 1 roll>>setpagedevice" and the
+option value is "2.0" then CUPS will output the string
+"2.0 <</cupsReal1 2 1 roll>>setpagedevice".</p>
<p>The "type" is one of the following keywords:</p>
<li><tt>passcode</tt> - a string of numbers value with a
minimum of "minimum" numbers and a maximum of "maximum"
- numbers (passcode strings are not displayed in the user
- interface)</li>
+ numbers ("minimum" and "maximum" are numbers and passcode
+ strings are not displayed in the user interface)</li>
<li><tt>password</tt> - a string value with a minimum of
"minimum" characters and a maximum of "maximum"
- characters (password strings are not displayed in the
- user interface)</li>
+ characters ("minimum" and "maximum" are numbers and password
+ strings are not displayed in the user interface)</li>
<li><tt>points</tt> - a measurement value in points from
"minimum" to "maximum"</li>
<li><tt>string</tt> - a string value with a minimum of
"minimum" characters and a maximum of "maximum"
- characters</li>
+ characters ("minimum" and "maximum" are numbers)</li>
</ul>
*ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
+<em>*% Base PostScript watermark option</em>
+*OpenUI WatermarkText/Watermark Text: PickOne
+*OrderDependency: 10 AnySetup *WatermarkText
+*DefaultWatermarkText: None
+*WatermarkText None: ""
+*WatermarkText Draft: "<</cupsString1(Draft)>>setpagedevice"
+*CloseUI: *WatermarkText
+
+<em>*% Custom PostScript watermark option</em>
+*CustomWatermarkText True: "<</cupsString1 2 1 roll>>setpagedevice"
+*ParamCustomWatermarkText Text: 1 string 0 32
+
+
<em>*% Base PostScript gamma/density option</em>
*OpenUI GammaDensity/Gamma and Density: PickOne
*OrderDependency: 10 AnySetup *GammaDensity
*GammaDensity Normal/Normal: "<</cupsReal1 1.0/cupsReal2 1.0>>setpagedevice"
*GammaDensity Light/Lighter: "<</cupsReal1 0.9/cupsReal2 0.67>>setpagedevice"
*GammaDensity Dark/Darker: "<</cupsReal1 1.1/cupsReal2 1.5>>setpagedevice"
-*JCLCloseUI: *GammaDensity
+*CloseUI: *GammaDensity
<em>*% Custom PostScript gamma/density option</em>
*CustomGammaDensity True: "<</cupsReal1 3 1 roll/cupsReal2 3 1>>setpagedevice"
<h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
+<p>CUPS supports two types of color profiles. The first type is
+based on sRGB and is used by the standard CUPS raster filters and
+ESP Ghostscript. The second type is based on ICC profiles and is
+used by the Core Graphics-based filters on MacOS X.</p>
+
+<blockquote><b>Note:</b> At this time, none of the CUPS raster
+filters support ICC profiles. This will be addressed as time
+and resources permit.</blockquote>
+
<h3>cupsColorProfile</h3>
-<p>This string attribute specifies a color profile of the
-form:</p>
+<p class='summary'>*cupsColorProfile Resolution/MediaType: "density
+gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
-<pre class='command'>
-*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
-</pre>
+<p>This string attribute specifies an sRGB-based color profile
+consisting of gamma and density controls and a 3x3 CMY color
+transform matrix.</p>
<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
to act as a wildcard. Otherwise they must match one of the
<h3>cupsICCProfile</h3>
-<p>This attribute specifies an ICC color profile of the
-form:</p>
-
-<pre class='command'>
-*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
-</pre>
+<p class='summary'>*cupsICCProfile
+ColorModel.MediaType.Resolution/Description: "filename"</p>
-<p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
+<p>This attribute specifies an ICC color profile that is
+used to convert the document colors to the device
+colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
<tt>Resolution</tt> keywords specify a selector for color
profiles. If omitted, the color profile will match any option
keyword for the corresponding main keyword.</p>
*cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "vendor/foo-720-glossy-rgb.icc"
<em>*% Specify a default profile for printing at all other resolutions and media types</em>
-*cupsICCProfile .../Default: "vendor/foo-default.icc"
+*cupsICCProfile ../Default: "vendor/foo-default.icc"
</pre>
<h4>Customizing the Profile Selection Keywords</h4>
</pre>
-<h2 class='title'><a name='I18N'>I18N Support</a></h2>
+<h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
<p>CUPS 1.2 and higher adds support for PPD files containing multiple
-languages by following the following rules:</p>
+languages by following the following additional rules:</p>
<ol>
- <li>The <tt>LanguageVersion</tt> is <tt>English</tt></li>
+ <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
+
+ <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
+
+ <li>The <tt>cupsLanguages</tt> attribute MUST be provided and
+ list each of the supported locales in the PPD file</li>
+
+ <li>Main and option keywords MUST NOT exceed 34 (instead of 40)
+ characters to allow room for the locale prefixes in translation
+ attributes</li>
- <li>The <tt>LanguageEncoding</tt> is <tt>ISOLatin1</tt></li>
+ <li>The main keyword "Translation" MUST NOT be used</li>
- <li>Main and option keywords may not exceed 34
- characters, which is a subset of what the Adobe PPD spec
- allows.</li>
+ <li>Translation strings included with the main and option
+ keywords MUST NOT contain characters outside the ASCII
+ subset of ISOLatin1 and UTF-8; developers wishing to use
+ characters outside ASCII MUST provide a separate set of
+ English localization attributes for the affected keywords.</li>
- <li>Translations are specified using a locale prefix of
+ <li>Localizations are specified using a locale prefix of
the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
language code and "CC" is the 2-letter ISO country
code</li>
- <li>Translation strings are encoded using UTF-8.</li>
+ <li>Locale-specific translation strings MUST be encoded
+ using UTF-8.</li>
- <li>Main keywords are translated using any of the
+ <li>Main keywords MUST be localized using one of the
following forms:
<p><tt>*ll.Translation MainKeyword/translation
text: ""</tt><br />
<tt>*ll_CC.Translation MainKeyword/translation
text: ""</tt></p></li>
- <li>Option keywords are translated using any of the
+ <li>Option keywords MUST be localized using one of the
following forms:
<p><tt>*ll.MainKeyword OptionKeyword/translation
text: ""</tt><br />
<tt>*ll_CC.MainKeyword OptionKeyword/translation
text: ""</tt></p></li>
+ <li>Localization attributes MAY appear anywhere after the
+ first line of the PPD file</li>
+
</ol>
-<p>Examples:</p>
+<blockquote><b>Note:</b>
+We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt>
+and limit the allowed base translation strings to ASCII to avoid
+character coding issues that would otherwise occur. In addition,
+requiring the base translation strings to be in English allows
+for easier fallback translation when no localization is provided
+in the PPD file for a given locale.</blockquote>
+<p>Examples:</p>
<pre class='command'>
*LanguageVersion: English
*LanguageEncoding: ISOLatin1
+*cupsLanguages: "de_DE fr_FR"
*ModelName: "Foobar Laser 9999"
-<em>*% Localize for French and German</em>
+<em>*% Localize ModelName for French and German</em>
*fr_FR.Translation ModelName/La Foobar Laser 9999: ""
*de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""
+*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
+<em>*% Localize printer-state-reason for French and German</em>
+*fr_FR.cupsIPPReason com.vendor-error/Une erreur sèrieuse s'est produite: "/help/com.vendor/error.html"
+*de_DE.cupsIPPReason com.vendor-error/Eine ernste Störung trat: "/help/com.vendor/error.html"
+
...
*OpenUI *InputSlot/Paper Source: PickOne
*OrderDependency: 10 AnySetup *InputSlot
*DefaultInputSlot: Auto
-<em>*% Localize for French and German</em>
+<em>*% Localize InputSlot for French and German</em>
*fr_FR.Translation InputSlot/Papier source: ""
*de_DE.Translation InputSlot/Papiereinzug: ""
*InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice"
-<em>*% Localize for French and German</em>
+<em>*% Localize InputSlot=Auto for French and German</em>
*fr_FR.InputSlot Auto/Par Defaut: ""
*de_DE.InputSlot Auto/Standard: ""
*InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice"
-<em>*% Localize for French and German</em>
+<em>*% Localize InputSlot=Manual for French and German</em>
*fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
*de_DE.InputSlot Manual/Manueller Einzug: ""
*CloseUI: *InputSlot
<ul>
- <li>Added I18N support attributes</li>
+ <li>Added globalization support attributes</li>
<li>Added custom option values support</li>
+ <li>Added <tt>APBookFile</tt> attribute</li>
+
+ <li>Added <tt>APDuplexRequiresFlippedMargin</tt> attribute</li>
+
<li>Added <tt>cupsICCProfile</tt> attribute</li>
+ <li>Added <tt>cupsIPPReason</tt> attribute</li>
+
+ <li>Added <tt>cupsLanguages</tt> attribute</li>
+
<li>Added <tt>cupsPortMonitor</tt> attribute</li>
<li>Removed <tt>cupsProtocol</tt> attribute</li>
projects / thirdparty / cups.git / blobdiff