| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> |
| <html> |
| <!-- SECTION: Specifications --> |
| <head> |
| <title>CUPS PPD Extensions</title> |
| <meta name='keywords' content='Programming, PostScript Printer Description'> |
| <link rel='stylesheet' type='text/css' href='../cups-printable.css'> |
| </head> |
| <body> |
| <!-- |
| "$Id: spec-ppd.html 6993 2007-09-28 18:05:28Z mike $" |
| |
| CUPS PPD extensions specification for the Common UNIX Printing System (CUPS). |
| |
| Copyright 2007 by Apple Inc. |
| Copyright 1997-2007 by Easy Software Products. |
| |
| These coded instructions, statements, and computer programs are the |
| property of Apple Inc. and are protected by Federal copyright |
| law. Distribution and use rights are outlined in the file "LICENSE.txt" |
| which should have been included with this file. If this file is |
| file is missing or damaged, see the license at "http://www.cups.org/". |
| --> |
| |
| <h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2> |
| |
| <p>This specification describes the attributes and extensions |
| that CUPS adds to <a |
| 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 |
| used by CUPS to support printer-specific features and intelligent |
| filtering.</p> |
| |
| <h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2> |
| |
| <p>The PPD format is text-based and uses lines of up to 255 |
| characters terminated by a carriage return, linefeed, or |
| combination of carriage return and line feed. The following ABNF |
| definition [RFC2234] defines the general format of lines in a PPD |
| file:</p> |
| |
| <pre class='command'> |
| PPD-FILE = HEADER +(DATA / COMMENT / LINE-END) |
| |
| HEADER = "*" 0x50.50.44.2D.41.64.6F.62.65 ":" ; *PPD-Adobe: |
| *WSP DQUOTE "4.3" DQUOTE LINE-END |
| |
| COMMENT = "*%" *TCHAR LINE-END |
| |
| DATA = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":" |
| 1*(*WSP VALUE) LINE-END |
| |
| VALUE = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE |
| |
| KCHAR = ALPHA / DIGIT / "_" / "." / "-" |
| |
| SCHAR = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF |
| |
| TCHAR = %x20-7E / %xA0-FF |
| |
| LINE-END = CR / LF / CR LF |
| </pre> |
| |
| |
| <h2 class='title'><a name='AUTOCONFIG'>Auto-Configuration</a></h2> |
| |
| <p>CUPS supports several methods of auto-configuration via PPD attributes. |
| <em>Currently these methods are only implemented on Mac OS X.</em></p> |
| |
| <h3><span class='info'>Mac OS X 10.5</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3> |
| |
| <p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</p> |
| |
| <p>This attribute defines a program that sets the default option choices. It |
| is run when a printer is added from the printer browser instead of the |
| normal PostScript query and SNMP OID attribute lookups.</p> |
| |
| <p>The program is provided with two arguments: the printer's device URI and |
| the PPD file to be used for the printer. The program must write an updated |
| PPD file to stdout.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Use our setup tool when adding a printer |
| *APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.2</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3> |
| |
| <p class='summary'>*?<i>MainKeyword</i>: "<br> |
| PostScript query code that writes a message using the = operator...<br> |
| "<br> |
| *End</p> |
| |
| <p>The <tt>?<i>MainKeyword</i></tt> attribute defines PostScript code that |
| determines the currently selected/enabled option keyword (choice) for the |
| main keyword (option). It is typically used when communicating with USB, |
| serial, Appletalk, and AppSocket (port 9100) printers.</p> |
| |
| <p>The PostScript code typically sends its response back using the <tt>=</tt> |
| operator.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| *OpenUI OptionDuplex/Duplexer Installed: Boolean |
| *DuplexOptionDuplex: False |
| *OptionDuplex False/Not Installed: "" |
| *OptionDuplex True/Installed: "" |
| |
| <em>*% Query the printer for the presence of the duplexer option...</em> |
| *?OptionDuplex: " |
| currentpagedevice /Duplex known |
| {(True)} {(False)} ifelse |
| = flush |
| " |
| *End |
| *CloseUI: OptionDuplex |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.4</span><a name='OID'>OIDMainKeyword</a></h3> |
| |
| <p class='summary'>*?OID<i>MainKeyword</i>: ".n.n.n..."<br> |
| *OID<i>MainKeyword</i> <i>OptionKeyword1</i>: "value"<br> |
| ...<br> |
| *OID<i>MainKeyword</i> <i>OptionKeywordN</i>: "value"</p> |
| |
| <p>The <tt>OID<i>MainKeyword</i></tt> attribute is used to define |
| SNMP OIDs that map to installable options. The first (query) line |
| defines the OID to lookup on the network device. The second and |
| subsequent attributes define a mapping from OID value to option |
| keyword. Since SNMP is an IP-based network protocol, this method |
| is typically only used to configure AppSocket, IPP, and LPD network |
| printers.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Get the installed memory on the printer... |
| *?OIDInstalledMemory: ".1.3.6.1.2.1.25.2.2.0" |
| *OIDInstalledMemory 16MB: "16384 KBytes" |
| *OIDInstalledMemory 32MB: "32768 KBytes" |
| *OIDInstalledMemory 48MB: "49152 KBytes" |
| *OIDInstalledMemory 72MB: "73728 KBytes" |
| </pre> |
| |
| |
| <h2 class='title'><a name='PROFILES'>Color Profiles</a></h2> |
| |
| <p>CUPS supports three types of color profiles. The first type is |
| based on sRGB and is used by the standard CUPS raster filters and |
| GPL Ghostscript. The second type is based on ICC profiles and is |
| used by the Quartz-based filters on MacOS X. The final type is |
| based on well-known colorspaces such as sRGB and Adobe RGB.</p> |
| |
| <blockquote><b>Note:</b> |
| |
| <p>At this time, none of the CUPS raster |
| filters support ICC profiles. This will be addressed as time |
| and resources permit.</p> |
| |
| </blockquote> |
| |
| <h3><a name='cupsColorProfile'>cupsColorProfile</a></h3> |
| |
| <p class='summary'>*cupsColorProfile Resolution/MediaType: "density |
| gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p> |
| |
| <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 |
| <tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in |
| the PPD file.</p> |
| |
| <p>The <i>density</i> and <i>gamma</i> values define gamma and |
| density adjustment function such that:</p> |
| |
| <pre class='command'> |
| f(x) = density * x <sup style='font-size: 100%'>gamma</sup> |
| </pre> |
| |
| <p>The <i>m00</i> through <i>m22</i> values define a 3x3 |
| transformation matrix for the CMY color values. The density |
| function is applied <i>after</i> the CMY transformation:</p> |
| |
| <pre class='command'> |
| | m00 m01 m02 | |
| | m10 m11 m12 | |
| | m20 m21 m22 | |
| </pre> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| <em>*% Specify a profile for printing at 360dpi on all media types</em> |
| *cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" |
| |
| <em>*% Specify a profile for printing at 720dpi on Glossy media</em> |
| *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" |
| |
| <em>*% Specify a default profile for printing at all other resolutions and media types</em> |
| *cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3> |
| |
| <p class='summary'>*cupsICCProfile |
| ColorModel.MediaType.Resolution/Description: "filename"</p> |
| |
| <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> |
| |
| <p>The <tt>Description</tt> specifies human-readable text that |
| is associated with the color profile. The <tt>filename</tt> |
| portion specifies the ICC color profile to use; if the filename |
| is not absolute, it is loaded relative to the |
| <var>/usr/share/cups/profiles</var> directory.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| <em>*% Specify a profile for CMYK printing at 360dpi on all media types</em> |
| *cupsICCProfile CMYK..360dpi/360dpi CMYK: "/Library/Printers/vendor/Profiles/foo-360-cmyk.icc" |
| |
| <em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em> |
| *cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "/Library/Printers/vendor/Profiles/foo-720-glossy-rgb.icc" |
| |
| <em>*% Specify a default profile for printing at all other resolutions and media types</em> |
| *cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc" |
| </pre> |
| |
| <h4>Customizing the Profile Selection Keywords</h4> |
| |
| <p>The <tt>MediaType</tt> and <tt>Resolution</tt> keywords can be |
| reassigned to different main keywords, allowing drivers to do |
| color profile selection based on different parameters. The |
| <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> |
| attributes define the mapping from selector to main keyword:</p> |
| |
| <pre class='command'> |
| *cupsICCQualifier2: MainKeyword2 |
| *cupsICCQualifier3: MainKeyword3 |
| </pre> |
| |
| <p>The default mapping is as follows:</p> |
| |
| <pre class='command'> |
| *cupsICCQualifier2: MediaType |
| *cupsICCQualifier3: Resolution |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3> |
| |
| <p class='summary'>*<a href='#APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a>: true<br> |
| *<a href='#APCustomColorMatchingName'>APCustomColorMatchingName</a> name/text: ""<br> |
| *<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br> |
| *<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</p> |
| |
| <p>These attributes tell the Mac OS X raster filters that the printer |
| driver provides its own custom color matching and that generic color |
| profiles should be used when generating 1-, 3-, and 4-component raster |
| data as requested by the driver. The <tt>APCustomColorMatchingProfile</tt> |
| and <tt>APDefaultColorMatchingProfile</tt> attributes specify alternate |
| color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p> |
| |
| <h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4> |
| |
| <p class='summary'>*APCustomColorMatchingName name/text: ""</p> |
| |
| <p>This attribute defines an alternate name for the color matching |
| provided by a driver in the <var>Color Matching</var> print panel. |
| The default is to use the name "Vendor Matching" or its localized |
| equivalent.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Define the names for our color matching... |
| *APCustomColorMatchingName name/AcmeColor(tm): "" |
| *fr.APCustomColorMatchingName name/La AcmeColor(tm): "" |
| </pre> |
| |
| <h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4> |
| |
| <p class='summary'>*APCustomColorMatchingProfile: name</p> |
| |
| <p>This attribute defines a supported RGB color profile that can be used |
| when doing custom color matching. Currently only <tt>sRGB</tt> and |
| <tt>AdobeRGB</tt> are supported. If not specified, RGB data will use the |
| Generic RGB colorspace.</p> |
| |
| <blockquote><b>Note:</b> |
| |
| <p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> attributes, |
| you are responsible for providing the necessary user interface controls to |
| select the profile in a <a href='#APDialogExtension'>print dialog pane</a>. |
| Add the named profile to the print settings using the key |
| <tt>kPMCustomColorMatchingProfileKey</tt>.</p> |
| |
| </blockquote> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Use sRGB for RGB color by default, but support both sRGB and AdobeRGB |
| *APSupportsCustomColorMatching: true |
| *APDefaultCustomColorMatchingProfile: sRGB |
| *APCustomColorMatchingProfile: sRGB |
| *APCustomColorMatchingProfile: AdobeRGB |
| </pre> |
| |
| <h4><span class='info'>Mac OS X 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4> |
| |
| <p class='summary'>*APDefaultCustomColorMatchingProfile: name</p> |
| |
| <p>This attribute defines the default RGB color profile that will be used |
| when doing custom color matching. Currently only <tt>sRGB</tt> and |
| <tt>AdobeRGB</tt> are supported.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Use sRGB for RGB color by default |
| *APSupportsCustomColorMatching: true |
| *APDefaultCustomColorMatchingProfile: sRGB |
| </pre> |
| |
| <h4><span class='info'>Mac OS X 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4> |
| |
| <p class='summary'>*APSupportsCustomColorMatching: boolean</p> |
| |
| <p>This attribute specifies that the driver provides its own custom color |
| matching. When <tt>true</tt>, the default hand-off colorspace will be |
| Generic Gray, Generic RGB, or Generic CMYK depending on the number of |
| components the driver requests. The <a |
| href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a> |
| attribute can be used to override the default 3-component (RGB) colorspace.</p> |
| |
| <p>The default for <tt>APSupportsCustomColorMatching</tt> is <tt>false</tt>.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *APSupportsCustomColorMatching: true |
| *APDefaultCustomColorMatchingProfile: sRGB |
| </pre> |
| |
| |
| <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 additional rules:</p> |
| |
| <ol> |
| |
| <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 main keyword "Translation" MUST NOT be used</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>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<ul> |
| <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li> |
| <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li> |
| </ul></li> |
| |
| <li>Locale-specific translation strings MUST be encoded |
| using UTF-8.</li> |
| |
| <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 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> |
| |
| <blockquote><b>Note:</b> |
| |
| <p>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.</p> |
| |
| </blockquote> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *LanguageVersion: English |
| *LanguageEncoding: ISOLatin1 |
| *cupsLanguages: "de fr_CA" |
| *ModelName: "Foobar Laser 9999" |
| |
| <em>*% Localize ModelName for French and German</em> |
| *fr_CA.Translation ModelName/La Foobar Laser 9999: "" |
| *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_CA.cupsIPPReason com.vendor-error/Une erreur sèrieuse s'est produite: "/help/com.vendor/error.html" |
| *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 InputSlot for French and German</em> |
| *fr_CA.Translation InputSlot/Papier source: "" |
| *de.Translation InputSlot/Papiereinzug: "" |
| *InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice" |
| <em>*% Localize InputSlot=Auto for French and German</em> |
| *fr_CA.InputSlot Auto/Par Defaut: "" |
| *de.InputSlot Auto/Standard: "" |
| *InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice" |
| <em>*% Localize InputSlot=Manual for French and German</em> |
| *fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: "" |
| *de.InputSlot Manual/Manueller Einzug: "" |
| *CloseUI: *InputSlot |
| </pre> |
| |
| |
| <h2 class='title'><a name='OPTIONS'>Custom Options</a></h2> |
| |
| <p>CUPS supports custom options using an extension of the |
| <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt> |
| syntax:</p> |
| |
| <pre class='command'> |
| *CustomFoo True: "command" |
| *ParamCustomFoo Name1/Text 1: order type minimum maximum |
| *ParamCustomFoo Name2/Text 2: order type minimum maximum |
| ... |
| *ParamCustomFoo NameN/Text N: order type minimum maximum |
| </pre> |
| |
| <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. 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. 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> |
| |
| <ul> |
| |
| <li><tt>curve</tt> - a real value from "minimum" to |
| "maximum" representing a gamma correction curve using the |
| function: f(x) = x <sup>value</sup></li> |
| |
| <li><tt>int</tt> - an integer value from "minimum" to |
| "maximum"</li> |
| |
| <li><tt>invcurve</tt> - a real value from "minimum" to |
| "maximum" representing a gamma correction curve using the |
| function: f(x) = x <sup>1 / value</sup></li> |
| |
| <li><tt>passcode</tt> - a string of numbers value with a |
| minimum of "minimum" numbers and a maximum of "maximum" |
| 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 ("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>real</tt> - a real value from "minimum" to |
| "maximum"</li> |
| |
| <li><tt>string</tt> - a string value with a minimum of |
| "minimum" characters and a maximum of "maximum" |
| characters ("minimum" and "maximum" are numbers)</li> |
| |
| </ul> |
| |
| <blockquote><b>Note:</b> |
| |
| <p>Custom options are not directly supported by the Mac OS X Print Dialog |
| nor by the CUPS web interface at this time. Vendors that use custom |
| options on Mac OS X must provide their own user interface via the |
| <a href='#APDialogExtension'><tt>APDialogExtension</tt></a> attribute.</p> |
| |
| </blockquote> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| <em>*% Base JCL key code option</em> |
| *OpenUI JCLPasscode/Key Code: PickOne |
| *OrderDependency: 10 JCLSetup *JCLPasscode |
| *DefaultJCLPasscode: None |
| *JCLPasscode None/No Code: "" |
| *JCLPasscode 1111: "@PJL SET PASSCODE = 1111<0A>" |
| *JCLPasscode 2222: "@PJL SET PASSCODE = 2222<0A>" |
| *JCLPasscode 3333: "@PJL SET PASSCODE = 3333<0A>" |
| *JCLCloseUI: *JCLPasscode |
| |
| <em>*% Custom JCL key code option</em> |
| *CustomJCLPasscode True: "@PJL SET PASSCODE = \1<0A>" |
| *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 3 -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 |
| *DefaultGammaDensity: Normal |
| *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" |
| *CloseUI: *GammaDensity |
| |
| <em>*% Custom PostScript gamma/density option</em> |
| *CustomGammaDensity True: "<</cupsReal1 3 -1 roll/cupsReal2 5 -1>>setpagedevice" |
| *ParamCustomGammaDensity Gamma: 1 curve 0.1 10 |
| *ParamCustomGammaDensity Density: 2 real 0 2 |
| </pre> |
| |
| |
| <h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2> |
| |
| <p>PPD files are used for both PostScript and non-PostScript printers. For CUPS raster drivers, you use a subset of the PostScript language to set page device attributes such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p> |
| |
| <pre class='command'> |
| *PageSize A4: "<</PageSize[595 842]>>setpagedevice" |
| </pre> |
| |
| <p>Custom options typically use other operators to organize the values into a key/value dictionary for <tt>setpagedevice</tt>. For example, our previous <tt>CustomWatermarkText</tt> option code uses the <tt>roll</tt> operator to move the custom string value into the dictionary for <tt>setpagedevice</tt>:</p> |
| |
| <pre class='command'> |
| *CustomWatermarkText True: "<</cupsString1 3 -1 roll>>setpagedevice" |
| </pre> |
| |
| <p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p> |
| |
| <pre class='command'> |
| (My Watermark) |
| <</cupsString1 3 -1 roll>>setpagedevice |
| </pre> |
| |
| <p>The code moves the string value ("My Watermark") from the bottom of the stack to the top, creating a dictionary that looks like:</p> |
| |
| <pre class='command'> |
| <</cupsString1(My Watermark)>>setpagedevice |
| </pre> |
| |
| <p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p> |
| |
| <h3>Custom Page Size Code</a></h3> |
| |
| <p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p> |
| |
| <pre class='command'> |
| *ParamCustomPageSize Width: 1 points <i>min-width max-width</i> |
| *ParamCustomPageSize Height: 2 points <i>min-height max-height</i> |
| *ParamCustomPageSize WidthOffset: 3 points 0 0 |
| *ParamCustomPageSize HeightOffset: 4 points 0 0 |
| *ParamCustomPageSize Orientation: 5 int 0 0 |
| *CustomPageSize True: "pop pop pop <</PageSize[5 -2 roll]/ImagingBBox null>>setpagedevice" |
| </pre> |
| |
| <h3>Supported PostScript Operators</a></h3> |
| |
| <p>CUPS supports the following PostScript operators in addition to the usual PostScript number, string (literal and hex-encoded), boolean, null, and name values:</p> |
| |
| <ul> |
| |
| <li><tt><<</tt> - Start a dictionary.</li> |
| |
| <li><tt>>></tt> - End a dictionary.</li> |
| |
| <li><tt>[</tt> - Start an array.</li> |
| |
| <li><tt>]</tt> - End an array.</li> |
| |
| <li><tt>copy</tt> - Copy the top N objects on the stack.</li> |
| |
| <li><tt>dup</tt> - Copy the top object on the stack.</li> |
| |
| <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li> |
| |
| <li><tt>pop</tt> - Pop the top object on the stack.</li> |
| |
| <li><tt>roll</tt> - Shift the top N objects on the stack.</li> |
| |
| <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li> |
| |
| </ul> |
| |
| <blockquote><b>Note:</b> |
| |
| <p><em>Never</em> use the unsupported <tt>dict</tt> or <tt>put</tt> |
| operators in your option code. These operators are typically used in |
| option code dating back to Level 1 PostScript printers, which did not |
| support the simpler <tt><<</tt> or <tt>>></tt> operators. |
| If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can |
| rewrite it very easily to use the newer <tt><<</tt> and |
| <tt>>></tt> operators instead. For example, the following code |
| to set the page size:</p> |
| |
| <style type='text/css'><!-- |
| PRE B { |
| background: #000000; |
| color: #ffffff; |
| padding: 2px 5px; |
| } |
| --></style> |
| |
| <pre class='command'> |
| <b>1 dict dup</b> /PageSize [612 792] <b>put</b> setpagedevice |
| </pre> |
| |
| <p>can be rewritten as:</p> |
| |
| <pre class='command'> |
| <b><<</b> /PageSize [612 792] <b>>></b> setpagedevice |
| </pre> |
| |
| </blockquote> |
| |
| <h3>Supported Page Device Attributes</a></h3> |
| |
| <p>Table 2 shows the supported page device attributes along with PostScript code examples.</p> |
| |
| <div class='table'> |
| <table summary='Supported Page Device Attributes'> |
| <caption>Table 2: <a name='TABLE_2'>Supported Page Device Attributes</a></caption> |
| <thead> |
| <tr> |
| <th>Name(s)</th> |
| <th>Type</th> |
| <th>Description</th> |
| <th>Example(s)</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr valign='top'> |
| <td><tt>AdvanceDistance</tt></td> |
| <td>Integer</td> |
| <td>Specifies the number of points to advance roll media after printing.</td> |
| <td><tt><</AdvanceDistance 18>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>AdvanceMedia</tt></td> |
| <td>Integer</td> |
| <td>Specifies when to advance the media: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td> |
| <td><tt><</AdvanceMedia 4>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>Collate</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether collated copies are required.</td> |
| <td><tt><</Collate true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>CutMedia</tt></td> |
| <td>Integer</td> |
| <td>Specifies when to cut the media: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td> |
| <td><tt><</CutMedia 1>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>Duplex</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether 2-sided printing is required.</td> |
| <td><tt><</Duplex true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>HWResolution</tt></td> |
| <td>Integer Array</td> |
| <td>Specifies the resolution of the page image in pixels per inch.</td> |
| <td><tt><</HWResolution[1200 1200]>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>InsertSheet</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether to insert a blank sheet before the job.</td> |
| <td><tt><</InsertSheet true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>Jog</tt></td> |
| <td>Integer</td> |
| <td>Specifies when to shift the media in the output bin: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td> |
| <td><tt><</Jog 2>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>LeadingEdge</tt></td> |
| <td>Integer</td> |
| <td>Specifies the leading edge of the media: 0 = top, 1 = right, 2 = bottom, 3 = left.</td> |
| <td><tt><</LeadingEdge 0>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>ManualFeed</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether media should be drawn from the manual feed tray. Note: The <tt>MediaPosition</tt> attribute is preferred over the <tt>ManualFeed</tt> attribute.</td> |
| <td><tt><</ManualFeed true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>MediaClass</tt></td> |
| <td>String</td> |
| <td>Specifies a named media.</td> |
| <td><tt><</MediaClass (Invoices)>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>MediaColor</tt></td> |
| <td>String</td> |
| <td>Specifies the color of the media.</td> |
| <td><tt><</MediaColor >>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>MediaPosition</tt></td> |
| <td>Integer</td> |
| <td>Specifies the tray or source of the media.</td> |
| <td><tt><</MediaPosition 12>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>MediaType</tt></td> |
| <td>String</td> |
| <td>Specifies the general media type.</td> |
| <td><tt><</MediaType (Glossy)>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>MediaWeight</tt></td> |
| <td>Integer</td> |
| <td>Specifies the media weight in grams per meter<sup>2</sup>.</td> |
| <td><tt><</MediaWeight 100>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>MirrorPrint</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether to flip the output image horizontally.</td> |
| <td><tt><</MirrorPrint true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>NegativePrint</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether to invert the output image.</td> |
| <td><tt><</NegativePrint true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>NumCopies</tt></td> |
| <td>Integer</td> |
| <td>Specifies the number of copies to produce of each page.</td> |
| <td><tt><</NumCopies 100>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>Orientation</tt></td> |
| <td>Integer</td> |
| <td>Specifies the orientation of the output: 0 = portrait, 1 = landscape rotated counter-clockwise, 2 = upside-down, 3 = landscape rotated clockwise.</td> |
| <td><tt><</Orientation 3>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>OutputFaceUp</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether to place the media face-up in the output bin/tray.</td> |
| <td><tt><</OutputFaceUp true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>OutputType</tt></td> |
| <td>String</td> |
| <td>Specifies the output type name.</td> |
| <td><tt><</OutputType (Photo)>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>PageSize</tt></td> |
| <td>Integer/Real Array</td> |
| <td>Specifies the width and length/height of the page in points.</td> |
| <td><tt><</PageSize[595 842]>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>Separations</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether to produce color separations.</td> |
| <td><tt><</Separations true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>TraySwitch</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether to switch trays automatically.</td> |
| <td><tt><</TraySwitch true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>Tumble</tt></td> |
| <td>Boolean</td> |
| <td>Specifies whether the back sides of pages are rotated 180 degrees.</td> |
| <td><tt><</Tumble true>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsBorderlessScalingFactor</tt></td> |
| <td>Real</td> |
| <td>Specifies the amount to scale the page image dimensions.</td> |
| <td><tt><</cupsBorderlessScalingFactor 1.01>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsColorOrder</tt></td> |
| <td>Integer</td> |
| <td>Specifies the order of colors: 0 = chunked, 1 = banded, 2 = planar.</td> |
| <td><tt><</cupsColorOrder 0>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsColorSpace</tt></td> |
| <td>Integer</td> |
| <td>Specifies the page image colorspace: 0 = W, 1 = RGB, 2 = RGBA, 3 = K, 4 = CMY, 5 = YMC, 6 = CMYK, 7 = YMCK, 8 = KCMY, 9 = KCMYcm, 10 = GMCK, 11 = GMCS, 12 = White, 13 = Gold, 14 = Silver, 15 = CIE XYZ, 16 = CIE Lab, 17 = RGBW, 32 to 46 = CIE Lab (1 to 15 inks)</td> |
| <td><tt><</cupsColorSpace 1 >>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsCompression</tt></td> |
| <td>Integer</td> |
| <td>Specifies a driver compression type/mode.</td> |
| <td><tt><</cupsCompression 2>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsInteger0<br> |
| ...<br> |
| cupsInteger15</tt></td> |
| <td>Integer</td> |
| <td>Specifies driver integer values.</td> |
| <td><tt><</cupsInteger11 1234>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsMarkerType</tt></td> |
| <td>String</td> |
| <td>Specifies the type of ink/toner to use.</td> |
| <td><tt><</cupsMarkerType (Black+Color)>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsMediaType</tt></td> |
| <td>Integer</td> |
| <td>Specifies a numeric media type.</td> |
| <td><tt><</cupsMediaType 999>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsPageSizeName</tt></td> |
| <td>String</td> |
| <td>Specifies the name of the page size.</td> |
| <td><tt><</cupsPageSizeName (A4.Full)>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsPreferredBitsPerColor</tt></td> |
| <td>Integer</td> |
| <td>Specifies the preferred number of bits per color, typically 8 or 16.</td> |
| <td><tt><</cupsPreferredBitsPerColor 16>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsReal0<br> |
| ...<br> |
| cupsReal15</tt></td> |
| <td>Real</td> |
| <td>Specifies driver real number values.</td> |
| <td><tt><</cupsReal15 1.234>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsRenderingIntent</tt></td> |
| <td>String</td> |
| <td>Specifies the color rendering intent.</td> |
| <td><tt><</cupsRenderingIntent (AbsoluteColorimetric)>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsRowCount</tt></td> |
| <td>Integer</td> |
| <td>Specifies the number of rows of raster data to print on each line for some drivers.</td> |
| <td><tt><</cupsRowCount 24>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsRowFeed</tt></td> |
| <td>Integer</td> |
| <td>Specifies the number of rows to feed between passes for some drivers.</td> |
| <td><tt><</cupsRowFeed 17>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsRowStep</tt></td> |
| <td>Integer</td> |
| <td>Specifies the number of lines between columns/rows on the print head for some drivers.</td> |
| <td><tt><</cupsRowStep 2>>setpagedevice</tt></td> |
| </tr> |
| <tr valign='top'> |
| <td><tt>cupsString0<br> |
| ...<br> |
| cupsString15</tt></td> |
| <td>String</td> |
| <td>Specifies driver string values.</td> |
| <td><tt><</cupsString0(String Value)>>setpagedevice</tt></td> |
| </tr> |
| </tbody> |
| </table></div> |
| |
| |
| <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2> |
| |
| <h3><span class='info'>CUPS 1.3</span><a name='cupsBackSide'>cupsBackSide</a></h3> |
| |
| <p class='summary'>*cupsBackSide: keyword</p> |
| |
| <p>This attribute requests special handling of the back side of pages |
| when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a> |
| shows the supported keyword values for this attribute and their effect |
| on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt> |
| is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver |
| will receive print data starting at the bottom right corner of the page, with |
| each line going right-to-left instead of left-to-right. The default value is |
| <code>Normal</code>.</p> |
| |
| <blockquote><b>Note:</b> |
| |
| <p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt> |
| attribute - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt> |
| will be ignored.</p> |
| |
| </blockquote> |
| |
| <div class='table'> |
| <table width='80%' summary='Back Side Raster Coordinate System'> |
| <caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption> |
| <thead> |
| <tr> |
| <th>cupsBackSide</th> |
| <th>Tumble Value</th> |
| <th>Image Presentation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code>Normal</code></td> |
| <td><code>false</code></td> |
| <td>Left-to-right, top-to-bottom</td> |
| </tr> |
| <tr> |
| <td><code>Normal</code></td> |
| <td><code>true</code></td> |
| <td>Left-to-right, top-to-bottom</td> |
| </tr> |
| <tr> |
| <td><code>ManualTumble</code></td> |
| <td><code>false</code></td> |
| <td>Left-to-right, top-to-bottom</td> |
| </tr> |
| <tr> |
| <td><code>ManualTumble</code></td> |
| <td><code>true</code></td> |
| <td>Right-to-left, bottom-to-top</td> |
| </tr> |
| <tr> |
| <td><code>Rotated</code></td> |
| <td><code>false</code></td> |
| <td>Right-to-left, bottom-to-top</td> |
| </tr> |
| <tr> |
| <td><code>Rotated</code></td> |
| <td><code>true</code></td> |
| <td>Right-to-left, top-to-bottom</td> |
| </tr> |
| <tr> |
| <td><code>Flipped</code> *</td> |
| <td><code>false</code></td> |
| <td>Left-to-right, bottom-to-top</td> |
| </tr> |
| <tr> |
| <td><code>Flipped</code> *</td> |
| <td><code>true</code></td> |
| <td>Right-to-left, top-to-bottom</td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p> |
| |
| <div class='figure'><table summary='Back side images'> |
| <caption>Figure 1: Back side images</caption> |
| <tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr> |
| </table></div> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| <em>*% Flip the page image for the back side of duplexed output</em> |
| *cupsBackSide: Flipped |
| |
| <em>*% Rotate the page image for the back side of duplexed output</em> |
| *cupsBackSide: Rotated |
| </pre> |
| |
| <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> |
| attribute.</p> |
| |
| <h3><span class='info'>CUPS 1.3</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3> |
| |
| <p class='summary'>*cupsEvenDuplex: boolean</p> |
| |
| <p>This boolean attribute notifies the RIP filters that the |
| destination printer requires an even number of pages when 2-sided |
| printing is selected. The default value is <code>false</code>.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| <em>*% Always send an even number of pages when duplexing</em> |
| *cupsEvenDuplex: true |
| </pre> |
| |
| <h3><a name='cupsFax'>cupsFax</a></h3> |
| |
| <p class='summary'>*cupsFax: boolean</p> |
| |
| <p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *cupsFax: true |
| </pre> |
| |
| <h3><a name='cupsFilter'>cupsFilter</a></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> |
| |
| <pre class='command'> |
| <em>*% Standard raster printer driver filter</em> |
| *cupsFilter: "application/vnd.cups-raster 100 rastertofoo" |
| |
| <em>*% Plain text filter</em> |
| *cupsFilter: "text/plain 10 texttofoo" |
| |
| <em>*% Pass-through filter for PostScript printers</em> |
| *cupsFilter: "application/vnd.cups-postscript 0 -" |
| </pre> |
| |
| <h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3> |
| |
| <p class='summary'>*cupsFlipDuplex: boolean</p> |
| |
| <p>Due to implementation differences between Mac OS X and Ghostscript, |
| the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use |
| the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> attribute to specify |
| the coordinate system (pixel layout) of the page data on the back side of |
| duplex pages.</p> |
| |
| <p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value |
| of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with |
| Ghostscript.</p> |
| |
| <p>The default value is <code>false</code>.</p> |
| |
| <blockquote><b>Note:</b> |
| |
| <p>Mac OS X drivers that previously used |
| <tt>cupsFlipDuplex</tt> may wish to provide both the old and |
| new attributes for maximum compatibility, for example:</p> |
| |
| <pre class='command'> |
| *cupsBackSide: Rotated |
| *cupsFlipDuplex: true |
| </pre> |
| |
| <p>Similarly, drivers written for other operating systems using |
| Ghostscript can use:</p> |
| |
| <pre class='command'> |
| *cupsBackSide: Flipped |
| *cupsFlipDuplex: true |
| </pre></blockquote> |
| |
| <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3> |
| |
| <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p> |
| |
| <p>This attribute defines a mapping from IPP <code>finishings</code> |
| values to PPD options and choices.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait" |
| *cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide" |
| *cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait" |
| *cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape" |
| </pre> |
| |
| <h3><span class='info'>CUPS 1.3</span><a name='cupsIPPReason'>cupsIPPReason</a></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>Since the reason text is limited to 80 characters by the PPD specification, |
| longer text strings can be included by URI-encoding the text with the "text" |
| scheme, for example "text:some%20text". Multiple <code>text</code> URIs are |
| combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt> |
| into a single string that can be displayed to the user.</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 more than 80 characters of text but no page</em> |
| *cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time |
| text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country." |
| |
| <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><span class='info'>CUPS 1.2</span><a name='cupsLanguages'>cupsLanguages</a></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_CA", 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_CA" |
| </pre> |
| |
| <h3><a name='cupsManualCopies'>cupsManualCopies</a></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 <code>false</code>.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| <em>*% Tell the RIP filters to generate the copies for us</em> |
| *cupsManualCopies: true |
| </pre> |
| |
| <h3><a name='cupsModelNumber'>cupsModelNumber</a></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> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| <em>*% Specify an integer for a driver-specific model number</em> |
| *cupsModelNumber: 1234 |
| </pre> |
| |
| |
| <h3><span class='info'>CUPS 1.3</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3> |
| |
| <p class='summary'>*cupsPJLCharset: "ISO character set name"</p> |
| |
| <p>This string attribute specifies the character set that is used |
| for strings in PJL commands. If not specified, US-ASCII is |
| assumed.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| <em>*% Specify UTF-8 is used in PJL strings</em> |
| *cupsPJLCharset: "UTF-8" |
| </pre> |
| |
| |
| <h3><span class='info'>CUPS 1.2</span><a name='cupsPortMonitor'>cupsPortMonitor</a></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 |
| if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If |
| so, the corresponding port monitor ("bcp" and "tbcp", |
| 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 usb/USB Status Monitor: "epson-usb" |
| </pre> |
| |
| <h3><span class='info'>CUPS 1.3</span><a name='cupsPreFilter'>cupsPreFilter</a></h3> |
| |
| <p class='summary'>*cupsPreFilter: "source/type cost program"</p> |
| |
| <p>This string attribute provides a pre-filter rule. The pre-filter |
| program will be inserted in the conversion chain immediately |
| before the filter that accepts the given MIME type.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| <em>*% PDF pre-filter</em> |
| *cupsPreFilter: "application/pdf 100 mypdfprefilter" |
| |
| <em>*% PNG pre-filter</em> |
| *cupsPreFilter: "image/png 0 mypngprefilter" |
| </pre> |
| |
| <h3><a name='cupsVersion'>cupsVersion</a></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", "1.2", or "1.3".</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| <em>*% Specify a CUPS 1.2 driver</em> |
| *cupsVersion: "1.2" |
| </pre> |
| |
| |
| <h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2> |
| |
| <h3><a name='APBookFile'>APBookFile</a></h3> |
| |
| <p class='summary'>*APBookFile: "file URL"</p> |
| |
| <p>This string attribute specifies the Apple help book file to use when |
| looking up IPP reason codes for this printer driver. The |
| <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute maps |
| "help" URIs to this file.</p> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| *APBookFile: "file:///Library/Printers/vendor/Help/filename" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3> |
| |
| <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p> |
| |
| <p>This attribute defines additional option panes that are displayed in the |
| print dialog. Each attribute adds one or more option panes. See the "OutputBinsPDE" |
| example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple |
| Technical Q&A QA1352</a> for information on writing your own print dialog |
| plug-ins.</p> |
| |
| <blockquote><b>Note:</b> |
| |
| <p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat" |
| (32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled |
| in order to be usable with all applications.</p> |
| |
| </blockquote> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Add two panes for finishing and driver options |
| *APDialogExtension: "/Library/Printers/vendor/finishing.plugin" |
| *APDialogExtension: "/Library/Printers/vendor/options.plugin" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3> |
| |
| <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p> |
| |
| <p>This boolean attribute notifies the RIP filters that the |
| destination printer requires the top and bottom margins of the |
| <tt>ImageableArea</tt> to be swapped for the back page. The |
| default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt> |
| and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how |
| <tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt> |
| and the <tt>Tumble</tt> page attribute.</p> |
| |
| <div class='table'> |
| <table width='80%' summary='Margin Flipping Modes'> |
| <caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption> |
| <thead> |
| <tr> |
| <th>APDuplexRequiresFlippedMargin</th> |
| <th>cupsBackSide</th> |
| <th>Tumble Value</th> |
| <th>Margins</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>false</td> |
| <td>any</td> |
| <td>any</td> |
| <td>Normal</td> |
| </tr> |
| <tr> |
| <td>any</td> |
| <td>Normal</td> |
| <td>any</td> |
| <td>Normal</td> |
| </tr> |
| <tr> |
| <td>true</td> |
| <td>ManualDuplex</td> |
| <td>false</td> |
| <td>Normal</td> |
| </tr> |
| <tr> |
| <td>true</td> |
| <td>ManualDuplex</td> |
| <td>true</td> |
| <td>Flipped</td> |
| </tr> |
| <tr> |
| <td>true</td> |
| <td>Rotated</td> |
| <td>false</td> |
| <td>Flipped</td> |
| </tr> |
| <tr> |
| <td>true</td> |
| <td>Rotated</td> |
| <td>true</td> |
| <td>Normal</td> |
| </tr> |
| <tr> |
| <td>true or unspecified</td> |
| <td>Flipped</td> |
| <td>any</td> |
| <td>Flipped</td> |
| </tr> |
| </tbody> |
| </table></div> |
| |
| <p>Example:</p> |
| |
| <pre class='command'> |
| <em>*% Rotate the back side images</em> |
| *cupsBackSide: Rotated |
| |
| <em>*% Don't swap the top and bottom margins for the back side</em> |
| *APDuplexRequiresFlippedMargin: false |
| </pre> |
| |
| <p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> |
| attribute.</p> |
| |
| <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3> |
| |
| <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename"</p> |
| |
| <p>This attribute defines the location of a printer icon file to use when |
| displaying the printer.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Apple icon file |
| *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns" |
| |
| *% TIFF icon file |
| *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.tiff" |
| |
| *% PNG icon file |
| *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.png" |
| |
| *% JPEG icon file |
| *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.jpg" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3> |
| |
| <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p> |
| |
| <p>This attribute defines an program that checks the ink/toner/marker levels |
| on a printer, returning an XML document with those levels. See the "InkTool" |
| example and |
| <a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple |
| Technical Note TN2144</a> for more information.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Use a vendor monitoring program |
| *APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3> |
| |
| <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p> |
| |
| <p>This attribute defines presets for multiple options that show up |
| in the print dialog of applications (such as iPhoto) that set the job |
| style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or |
| more pairs of PPD options and choices as well as providing key/value data for |
| the application. The following preset names are currently defined:</p> |
| |
| <ul> |
| |
| <li><code>Photo_with_Paper_Auto-Detect</code>; Photo printing |
| with paper auto-detect</li> |
| |
| <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; Photo printing |
| with paper auto-detect - fine</li> |
| |
| <li><code>Photo_on_Plain_Paper</code>; Photo printing on plain paper</li> |
| |
| <li><code>Photo_on_Plain_Paper_-_Fine</code>; Photo printing on plain |
| paper - fine</li> |
| |
| <li><code>Photo_on_Photo_Paper</code>; Photo printing on photo paper</li> |
| |
| <li><code>Photo_on_Photo_Paper_-_Fine</code>; Photo printing on photo |
| paper - fine</li> |
| |
| <li><code>Photo_on_Matte_Paper</code>; Photo printing on matte paper</li> |
| |
| <li><code>Photo_on_Matte_Paper_-_Fine</code>; Photo printing on matte |
| paper - fine</li> |
| |
| </ul> |
| |
| <p>The value string consists of pairs of keywords, either an option name and |
| choice (*MainKeyword OptionKeyword) or a preset identifier and value |
| (com.apple.print.preset.foo value). Preset identifiers and their supported |
| values are documented in "<a |
| href='http://developer.apple.com/documentation/Printing/Conceptual/PresetDraft/presets_intro/chapter_1_section_2.html' |
| >Creating Printing Presets for iPhoto: Printing Presets File Format</a>".</p> |
| |
| <p>Presets, like options, can also be localized in multiple languages.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: " |
| *MediaType Glossy |
| *ColorModel RGB |
| *Resolution 300dpi |
| com.apple.print.preset.graphicsType Photo |
| com.apple.print.preset.quality mid |
| com.apple.print.preset.media-front-coating glossy" |
| *End |
| *fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: "" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3> |
| |
| <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p> |
| |
| <p>This attribute defines a GUI application that can be used to do printer |
| maintenance functions such as cleaning the print head(s). See ... for more |
| information.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *% Define the printer utility application |
| *APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app" |
| </pre> |
| |
| <h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3> |
| |
| <p class='summary'>*APScanAppBundleID: "bundle ID"</p> |
| |
| <p>This attribute defines the application to use when scanning pages from |
| the device.</p> |
| |
| <p>Examples:</p> |
| |
| <pre class='command'> |
| *APScanAppBundleID: "com.apple.ImageCaptureApp" |
| </pre> |
| |
| |
| <h2 class='title'><a name='HISTORY'>Change History</a></h2> |
| |
| <h3>Changes in CUPS 1.3.1</a></h3> |
| |
| <ul> |
| |
| <li>Added missing Mac OS X <tt>AP</tt> attributes.</li> |
| |
| <li>Added section on auto-configuration including the |
| <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt> |
| attributes.</li> |
| |
| <li>Minor reorganization.</li> |
| |
| </ul> |
| |
| |
| <h3>Changes in CUPS 1.3</a></h3> |
| |
| <ul> |
| |
| <li>Added <tt>cupsBackSide</tt> and deprecated <tt>cupsFlipDuplex</tt>.</li> |
| |
| <li>Added text URI information to <tt>cupsIPPReason</tt> documentation.</li> |
| |
| <li>Added <tt>APPrinterPreset</tt>, <tt>cupsIPPFinishings</tt>, and <tt>cupsPreFilter</tt> attributes.</li> |
| |
| <li>Added discussion of custom option code, sample <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li> |
| |
| </ul> |
| |
| <h3>Changes in CUPS 1.2.8</a></h3> |
| |
| <ul> |
| |
| <li>Added section on supported PostScript commands for raster |
| drivers</li> |
| |
| </ul> |
| |
| <h3>Changes in CUPS 1.2</a></h3> |
| |
| <ul> |
| |
| <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> |
| |
| </ul> |
| |
| <h3>Changes in CUPS 1.1</a></h3> |
| |
| <ul> |
| |
| <li>Added <tt>cupsFlipDuplex</tt> attribute</li> |
| |
| <li>Added <tt>cupsProtocol</tt> attribute</li> |
| |
| </ul> |
| |
| </body> |
| </html> |