1 <h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2> 2 3 <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 [<a href="http://tools.ietf.org/html/rfc5234" target="_blank">RFC5234</a>] defines the general format of lines in a PPD file:</p> 4 5 <pre class='command'> 6 PPD-FILE = HEADER +(DATA / COMMENT / LINE-END) 7 8 HEADER = "*PPD-Adobe:" *WSP DQUOTE VERSION DQUOTE LINE-END 9 10 VERSION = "4.0" / "4.1" / "4.2" / "4.3" 11 12 COMMENT = "*%" *TCHAR LINE-END 13 14 DATA = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":" 15 1*(*WSP VALUE) LINE-END 16 17 VALUE = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE 18 19 KCHAR = ALPHA / DIGIT / "_" / "." / "-" 20 21 SCHAR = LINE-END / WSP / %x21.23-7E.A0-FF 22 23 TCHAR = %x20-7E.A0-FF 24 25 LINE-END = CR / LF / CR LF 26 </pre> 27 28 29 <h2 class='title'><a name='AUTOCONFIG'>Auto-Configuration</a></h2> 30 31 <p>CUPS supports several methods of auto-configuration via PPD keywords.</p> 32 33 <h3><span class='info'>macOS 10.5</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3> 34 35 <p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</p> 36 37 <p>This macOS keyword defines a program that sets the default option choices. It is run when a printer is added from the <var>Add Printer</var> window or the <var>Nearby Printers</var> list in the <var>Print</var> dialog.</p> 38 39 <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> 40 41 <p>Examples:</p> 42 43 <pre class='command'> 44 *% Use our setup tool when adding a printer 45 *APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool" 46 </pre> 47 48 <h3><span class='info'>macOS 10.2/CUPS 1.4</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3> 49 50 <p class='summary'>*?<i>MainKeyword</i>: "<br> 51 PostScript query code that writes a message using the = operator...<br> 52 "<br> 53 *End</p> 54 55 <p>The <tt>?<i>MainKeyword</i></tt> keyword 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> 56 57 <p>The PostScript code typically sends its response back using the <tt>=</tt> operator.</p> 58 59 <p>Example:</p> 60 61 <pre class='command'> 62 *OpenUI OptionDuplex/Duplexer Installed: Boolean 63 *DuplexOptionDuplex: False 64 *OptionDuplex False/Not Installed: "" 65 *OptionDuplex True/Installed: "" 66 67 <em>*% Query the printer for the presence of the duplexer option...</em> 68 *?OptionDuplex: " 69 currentpagedevice /Duplex known 70 {(True)} {(False)} ifelse 71 = flush 72 " 73 *End 74 *CloseUI: OptionDuplex 75 </pre> 76 77 <h3><span class='info'>macOS 10.4/CUPS 1.5</span><a name='OID'>OIDMainKeyword</a></h3> 78 79 <p class='summary'>*?OID<i>MainKeyword</i>: ".n.n.n..."<br> 80 *OID<i>MainKeyword</i> <i>OptionKeyword1</i>: "value"<br> 81 ...<br> 82 *OID<i>MainKeyword</i> <i>OptionKeywordN</i>: "value"</p> 83 84 <p>The <tt>OID<i>MainKeyword</i></tt> keyword 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 keywords 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> 85 86 <p>Examples:</p> 87 88 <pre class='command'> 89 *% Get the installed memory on the printer... 90 *?OIDInstalledMemory: ".1.3.6.1.2.1.25.2.2.0" 91 *OIDInstalledMemory 16MB: "16384 KBytes" 92 *OIDInstalledMemory 32MB: "32768 KBytes" 93 *OIDInstalledMemory 48MB: "49152 KBytes" 94 *OIDInstalledMemory 72MB: "73728 KBytes" 95 </pre> 96 97 98 <h2 class='title'><a name='PROFILES'>Color Profiles</a></h2> 99 100 <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. The final type is based on well-known colorspaces such as sRGB and Adobe RGB.</p> 101 102 <blockquote><b>Note:</b> 103 104 <p>At this time, none of the CUPS raster filters support ICC profiles. This will be addressed as time and resources permit.</p> 105 106 </blockquote> 107 108 <h3><span class='info'>Deprecated</span><a name='cupsColorProfile'>cupsColorProfile</a></h3> 109 110 <p class='summary'>*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p> 111 112 <p>This string keyword specifies an sRGB-based color profile consisting of gamma and density controls and a 3x3 CMY color transform matrix. <em>This keyword is not supported on macOS.</em></p> 113 114 <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> option keywords defined in the PPD file.</p> 115 116 <p>The <i>density</i> and <i>gamma</i> values define gamma and 117 density adjustment function such that:</p> 118 119 <pre class='command'> 120 f(x) = density * x <sup style='font-size: 100%'>gamma</sup> 121 </pre> 122 123 <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> 124 125 <pre class='command'> 126 | m00 m01 m02 | 127 | m10 m11 m12 | 128 | m20 m21 m22 | 129 </pre> 130 131 <p>Examples:</p> 132 133 <pre class='command'> 134 <em>*% Specify a profile for printing at 360dpi on all media types</em> 135 *cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" 136 137 <em>*% Specify a profile for printing at 720dpi on Glossy media</em> 138 *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" 139 140 <em>*% Specify a default profile for printing at all other resolutions and media types</em> 141 *cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0" 142 </pre> 143 144 145 <h3><span class='info'>macOS 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3> 146 147 <p class='summary'>*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"</p> 148 149 <p>This keyword 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> option keywords specify a selector for color profiles. If omitted, the color profile will match any option keyword for the corresponding main keyword.</p> 150 151 <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> 152 153 <p>Examples:</p> 154 155 <pre class='command'> 156 <em>*% Specify a profile for CMYK printing at 360dpi on all media types</em> 157 *cupsICCProfile CMYK..360dpi/360dpi CMYK: "/Library/Printers/vendor/Profiles/foo-360-cmyk.icc" 158 159 <em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em> 160 *cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "/Library/Printers/vendor/Profiles/foo-720-glossy-rgb.icc" 161 162 <em>*% Specify a default profile for printing at all other resolutions and media types</em> 163 *cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc" 164 </pre> 165 166 <h4>Customizing the Profile Selection Keywords</h4> 167 168 <p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and <tt>Resolution</tt> main keywords can be reassigned to different main keywords, allowing drivers to do color profile selection based on different parameters. The <tt>cupsICCQualifier1</tt>, <tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt> keywords define the mapping from selector to main keyword:</p> 169 170 <pre class='command'> 171 *cupsICCQualifier1: MainKeyword1 172 *cupsICCQualifier2: MainKeyword2 173 *cupsICCQualifier3: MainKeyword3 174 </pre> 175 176 <p>The default mapping is as follows:</p> 177 178 <pre class='command'> 179 *cupsICCQualifier1: ColorModel 180 *cupsICCQualifier2: MediaType 181 *cupsICCQualifier3: Resolution 182 </pre> 183 184 <h3><span class='info'>macOS 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3> 185 186 <p class='summary'>*<a href='#APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a>: true<br> 187 *<a href='#APCustomColorMatchingName'>APCustomColorMatchingName</a> name/text: ""<br> 188 *<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br> 189 *<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</p> 190 191 <p>These keywords tell the macOS 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> keywords specify alternate color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p> 192 193 <blockquote><b>Note:</b> 194 195 <p>Prior to macOS 10.6, the default RGB color space was Apple's "GenericRGB". The new default in macOS 10.6 and later is "sRGB". For more information, see <a href="http://support.apple.com/kb/HT3712">"macOS v10.6: About gamma 2.2"</a> on Apple's support site.</p> 196 197 </blockquote> 198 199 <h4><span class='info'>macOS 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4> 200 201 <p class='summary'>*APCustomColorMatchingName name/text: ""</p> 202 203 <p>This keyword 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> 204 205 <p>Examples:</p> 206 207 <pre class='command'> 208 *% Define the names for our color matching... 209 *APCustomColorMatchingName name/AcmeColor(tm): "" 210 *fr.APCustomColorMatchingName name/La AcmeColor(tm): "" 211 </pre> 212 213 <h4><span class='info'>macOS 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4> 214 215 <p class='summary'>*APCustomColorMatchingProfile: name</p> 216 217 <p>This keyword defines a supported RGB color profile that can be used when doing custom color matching. Currently only <tt>sRGB</tt>, <tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported. If not specified, RGB data will use the GenericRGB colorspace.</p> 218 219 <blockquote><b>Note:</b> 220 221 <p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> keywords, 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> 222 223 </blockquote> 224 225 <p>Examples:</p> 226 227 <pre class='command'> 228 *% Use sRGB for RGB color by default, but support both sRGB and AdobeRGB 229 *APSupportsCustomColorMatching: true 230 *APDefaultCustomColorMatchingProfile: sRGB 231 *APCustomColorMatchingProfile: sRGB 232 *APCustomColorMatchingProfile: AdobeRGB 233 </pre> 234 235 <h4><span class='info'>macOS 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4> 236 237 <p class='summary'>*APDefaultCustomColorMatchingProfile: name</p> 238 239 <p>This keyword defines the default RGB color profile that will be used when doing custom color matching. Currently only <tt>sRGB</tt>, <tt>AdobeRGB</tt>, and <tt>GenericRGB</tt> are supported.</p> 240 241 <p>Examples:</p> 242 243 <pre class='command'> 244 *% Use sRGB for RGB color by default 245 *APSupportsCustomColorMatching: true 246 *APDefaultCustomColorMatchingProfile: sRGB 247 </pre> 248 249 <h4><span class='info'>macOS 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4> 250 251 <p class='summary'>*APSupportsCustomColorMatching: boolean</p> 252 253 <p>This keyword specifies that the driver provides its own custom color matching. When <tt>true</tt>, the default hand-off colorspace will be GenericGray, GenericRGB, or GenericCMYK depending on the number of components the driver requests. The <a href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a> keyword can be used to override the default 3-component (RGB) colorspace.</p> 254 255 <p>The default for <tt>APSupportsCustomColorMatching</tt> is <tt>false</tt>.</p> 256 257 <p>Examples:</p> 258 259 <pre class='command'> 260 *APSupportsCustomColorMatching: true 261 *APDefaultCustomColorMatchingProfile: sRGB 262 </pre> 263 264 265 <h2 class='title'><a name='CONSTRAINTS'>Constraints</a></h2> 266 267 <p>Constraints are option choices that are not allowed by the driver or device, for example printing 2-sided transparencies. All versions of CUPS support constraints defined by the legacy Adobe <tt>UIConstraints</tt> and <tt>NonUIConstraints</tt> keywords which support conflicts between any two option choices, for example:</p> 268 269 <pre class='command'> 270 *% Do not allow 2-sided printing on transparency media 271 *UIConstraints: "*Duplex *MediaType Transparency" 272 *UIConstraints: "*MediaType Transparency *Duplex" 273 </pre> 274 275 <p>While nearly all constraints can be expressed using these keywords, there are valid scenarios requiring constraints between more than two option choices. In addition, resolution of constraints is problematic since users and software have to guess how a particular constraint is best resolved.</p> 276 277 <p>CUPS 1.4 and higher define two new keywords for constraints, <tt>cupsUIConstraints</tt> and <tt>cupsUIResolver</tt>. Each <tt>cupsUIConstraints</tt> keyword points to a <tt>cupsUIResolver</tt> keyword which specifies alternate options that resolve the conflict condition. The same <tt>cupsUIResolver</tt> can be used by multiple <tt>cupsUIConstraints</tt>.</p> 278 279 <blockquote><b>Note:</b> 280 281 <p>When developing PPD files that contain constraints, it is very important to use the <a href="man-cupstestppd.html">cupstestppd(1)</a> program to verify that your constraints are accurate and cannot result in unresolvable option selections.</p> 282 283 </blockquote> 284 285 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsUIConstraints'>cupsUIConstraints</a></h3> 286 287 <p class='summary'>*cupsUIConstraints resolver: "*Keyword1 *Keyword2 ..."<br> 288 *cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 ..."<br> 289 *cupsUIConstraints resolver: "*Keyword1 *Keyword2 OptionKeyword2 ..."<br> 290 *cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."<br> 291 *cupsUIConstraints: "*InstallableKeyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p> 292 293 <p>Lists two or more options which conflict. The "resolver" string is a (possibly unique) keyword which specifies which options to change when the constraint exists. When no resolver is provided, CUPS first tries the default choice followed by testing each option choice to resolve the conflict.</p> 294 295 <p>Examples:</p> 296 297 <pre class='command'> 298 <em>*% Specify that 2-sided printing cannot happen on transparencies</em> 299 *cupsUIConstraints transparency: "*Duplex *MediaType Transparency" 300 301 <em>*% Specify that envelope printing cannot happen from the paper trays</em> 302 *cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1" 303 *cupsUIConstraints envelope: "*PageSize Env10 *InputSlot Tray1" 304 *cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2" 305 *cupsUIConstraints envelope: "*PageSize EnvDL *InputSlot Tray2" 306 307 <em>*% Specify an installable option constraint for the envelope feeder</em> 308 *cupsUIConstraints: "*InputSlot EnvFeeder *InstalledEnvFeeder" 309 310 <em>*% Specify that photo printing cannot happen on plain paper or transparencies at 1200dpi</em> 311 *cupsUIConstraints photo: "*OutputMode Photo *MediaType Plain *Resolution 1200dpi" 312 *cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi" 313 </pre> 314 315 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsUIResolver'>cupsUIResolver</a></h3> 316 317 <p class='summary'>*cupsUIResolver resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."</p> 318 319 <p>Specifies two or more options to mark/select to resolve a constraint. The "resolver" string identifies a particular action to take for one or more <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a>. The same action can be used for multiple constraints. The option keyword pairs are treated as an ordered list of option selections to try - only the first N selections will be used, where N is the minimum number of selections required. Because <a href="api-ppd.html#cupsResolveConflicts"><code>cupsResolveConflicts()</code></a> will not change the most recent option selection passed to it, at least two options from the constraints must be listed to avoid situations where conflicts cannot be resolved.</p> 320 321 <p>Examples:</p> 322 323 <pre class='command'> 324 <em>*% Specify the options to change for the 2-sided transparency constraint</em> 325 *cupsUIResolver transparency: "*Duplex None *MediaType Plain" 326 327 <em>*% Specify the options to change for the envelope printing constraints. Notice 328 *% that we try to change the InputSlot to either the envelope feeder or the 329 *% manual feed first, then we change the page size...</em> 330 *cupsUIResolver envelope: "*InputSlot EnvFeeder *InputSlot ManualFeed *PageSize Letter" 331 332 <em>*% Specify the options to change for the photo printing constraints</em> 333 *cupsUIResolver photo: "*OutputMode Best *Resolution 600dpi" 334 </pre> 335 336 337 <h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2> 338 339 <p>CUPS 1.2 and higher adds support for PPD files containing multiple languages by following the following additional rules:</p> 340 341 <ol> 342 343 <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li> 344 345 <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li> 346 347 <li>The <tt>cupsLanguages</tt> keyword MUST be provided and list each of the supported locales in the PPD file</li> 348 349 <li>Main and option keywords MUST NOT exceed 34 (instead of 40) characters to allow room for the locale prefixes in translation keywords</li> 350 351 <li>The main keyword "Translation" MUST NOT be used</li> 352 353 <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 keywords for the affected keywords.</li> 354 355 <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> 356 <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li> 357 <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li> 358 </ul></li> 359 360 <li>Locale-specific translation strings MUST be encoded using UTF-8.</li> 361 362 <li>Main keywords MUST be localized using one of the following forms: 363 <p><tt>*ll.Translation MainKeyword/translation text: ""</tt><br /> 364 <tt>*ll_CC.Translation MainKeyword/translation text: ""</tt></p></li> 365 366 <li>Option keywords MUST be localized using one of the following forms: 367 <p><tt>*ll.MainKeyword OptionKeyword/translation text: ""</tt><br> 368 <tt>*ll_CC.MainKeyword OptionKeyword/translation text: ""</tt></p></li> 369 370 <li>Localization keywords MAY appear anywhere after the first line of the PPD file</li> 371 372 </ol> 373 374 <blockquote><b>Note:</b> 375 376 <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> 377 378 </blockquote> 379 380 <p>Examples:</p> 381 382 <pre class='command'> 383 *LanguageVersion: English 384 *LanguageEncoding: ISOLatin1 385 *cupsLanguages: "de fr_CA" 386 *ModelName: "Foobar Laser 9999" 387 388 <em>*% Localize ModelName for French and German</em> 389 *fr_CA.Translation ModelName/La Foobar Laser 9999: "" 390 *de.Translation ModelName/Foobar LaserDrucken 9999: "" 391 392 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html" 393 <em>*% Localize printer-state-reason for French and German</em> 394 *fr_CA.cupsIPPReason com.vendor-error/Une erreur sèrieuse s'est produite: "/help/com.vendor/error.html" 395 *de.cupsIPPReason com.vendor-error/Eine ernste Störung trat: "/help/com.vendor/error.html" 396 397 ... 398 399 *OpenUI *InputSlot/Paper Source: PickOne 400 *OrderDependency: 10 AnySetup *InputSlot 401 *DefaultInputSlot: Auto 402 <em>*% Localize InputSlot for French and German</em> 403 *fr_CA.Translation InputSlot/Papier source: "" 404 *de.Translation InputSlot/Papiereinzug: "" 405 *InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice" 406 <em>*% Localize InputSlot=Auto for French and German</em> 407 *fr_CA.InputSlot Auto/Par Defaut: "" 408 *de.InputSlot Auto/Standard: "" 409 *InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice" 410 <em>*% Localize InputSlot=Manual for French and German</em> 411 *fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: "" 412 *de.InputSlot Manual/Manueller Einzug: "" 413 *CloseUI: *InputSlot 414 </pre> 415 416 417 <h2 class='title'><a name='OPTIONS'><span class="info">CUPS 1.3/macOS 10.6</span>Custom Options</a></h2> 418 419 <p>CUPS supports custom options using an extension of the <tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt> syntax:</p> 420 421 <pre class='command'> 422 *CustomFoo True: "command" 423 *ParamCustomFoo Name1/Text 1: order type minimum maximum 424 *ParamCustomFoo Name2/Text 2: order type minimum maximum 425 ... 426 *ParamCustomFoo NameN/Text N: order type minimum maximum 427 </pre> 428 429 <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 430 option value is "1234" then CUPS will output the string "@PJL SET PASSCODE=1234".</p> 431 432 <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> 433 434 <p>The "type" is one of the following keywords:</p> 435 436 <ul> 437 438 <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> 439 440 <li><tt>int</tt> - an integer value from "minimum" to "maximum"</li> 441 442 <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> 443 444 <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> 445 446 <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> 447 448 <li><tt>points</tt> - a measurement value in points from "minimum" to "maximum"</li> 449 450 <li><tt>real</tt> - a real value from "minimum" to "maximum"</li> 451 452 <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> 453 454 </ul> 455 456 <p>Examples:</p> 457 458 <pre class='command'> 459 <em>*% Base JCL key code option</em> 460 *JCLOpenUI JCLPasscode/Key Code: PickOne 461 *OrderDependency: 10 JCLSetup *JCLPasscode 462 *DefaultJCLPasscode: None 463 *JCLPasscode None/No Code: "" 464 *JCLPasscode 1111: "@PJL SET PASSCODE = 1111<0A>" 465 *JCLPasscode 2222: "@PJL SET PASSCODE = 2222<0A>" 466 *JCLPasscode 3333: "@PJL SET PASSCODE = 3333<0A>" 467 *JCLCloseUI: *JCLPasscode 468 469 <em>*% Custom JCL key code option</em> 470 *CustomJCLPasscode True: "@PJL SET PASSCODE = \1<0A>" 471 *ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4 472 473 474 <em>*% Base PostScript watermark option</em> 475 *OpenUI WatermarkText/Watermark Text: PickOne 476 *OrderDependency: 10 AnySetup *WatermarkText 477 *DefaultWatermarkText: None 478 *WatermarkText None: "" 479 *WatermarkText Draft: "<</cupsString1(Draft)>>setpagedevice" 480 *CloseUI: *WatermarkText 481 482 <em>*% Custom PostScript watermark option</em> 483 *CustomWatermarkText True: "<</cupsString1 3 -1 roll>>setpagedevice" 484 *ParamCustomWatermarkText Text: 1 string 0 32 485 486 487 <em>*% Base PostScript gamma/density option</em> 488 *OpenUI GammaDensity/Gamma and Density: PickOne 489 *OrderDependency: 10 AnySetup *GammaDensity 490 *DefaultGammaDensity: Normal 491 *GammaDensity Normal/Normal: "<</cupsReal1 1.0/cupsReal2 1.0>>setpagedevice" 492 *GammaDensity Light/Lighter: "<</cupsReal1 0.9/cupsReal2 0.67>>setpagedevice" 493 *GammaDensity Dark/Darker: "<</cupsReal1 1.1/cupsReal2 1.5>>setpagedevice" 494 *CloseUI: *GammaDensity 495 496 <em>*% Custom PostScript gamma/density option</em> 497 *CustomGammaDensity True: "<</cupsReal1 3 -1 roll/cupsReal2 5 -1>>setpagedevice" 498 *ParamCustomGammaDensity Gamma: 1 curve 0.1 10 499 *ParamCustomGammaDensity Density: 2 real 0 2 500 </pre> 501 502 503 <h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2> 504 505 <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 keywords such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p> 506 507 <pre class='command'> 508 *PageSize A4: "<</PageSize[595 842]>>setpagedevice" 509 </pre> 510 511 <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> 512 513 <pre class='command'> 514 *CustomWatermarkText True: "<</cupsString1 3 -1 roll>>setpagedevice" 515 </pre> 516 517 <p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p> 518 519 <pre class='command'> 520 (My Watermark) 521 <</cupsString1 3 -1 roll>>setpagedevice 522 </pre> 523 524 <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> 525 526 <pre class='command'> 527 <</cupsString1(My Watermark)>>setpagedevice 528 </pre> 529 530 <p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p> 531 532 <h3>Custom Page Size Code</h3> 533 534 <p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p> 535 536 <pre class='command'> 537 *ParamCustomPageSize Width: 1 points <i>min-width max-width</i> 538 *ParamCustomPageSize Height: 2 points <i>min-height max-height</i> 539 *ParamCustomPageSize WidthOffset: 3 points 0 0 540 *ParamCustomPageSize HeightOffset: 4 points 0 0 541 *ParamCustomPageSize Orientation: 5 int 0 0 542 *CustomPageSize True: "pop pop pop <</PageSize[5 -2 roll]/ImagingBBox null>>setpagedevice" 543 </pre> 544 545 <h3>Supported PostScript Operators</h3> 546 547 <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> 548 549 <ul> 550 551 <li><tt><<</tt> - Start a dictionary.</li> 552 553 <li><tt>>></tt> - End a dictionary.</li> 554 555 <li><tt>[</tt> - Start an array.</li> 556 557 <li><tt>]</tt> - End an array.</li> 558 559 <li><tt>copy</tt> - Copy the top N objects on the stack.</li> 560 561 <li><tt>dup</tt> - Copy the top object on the stack.</li> 562 563 <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li> 564 565 <li><tt>pop</tt> - Pop the top object on the stack.</li> 566 567 <li><tt>roll</tt> - Shift the top N objects on the stack.</li> 568 569 <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li> 570 571 </ul> 572 573 <blockquote><b>Note:</b> 574 575 <p><em>Never</em> use the unsupported <tt>dict</tt> or <tt>put</tt> 576 operators in your option code. These operators are typically used in 577 option code dating back to Level 1 PostScript printers, which did not 578 support the simpler <tt><<</tt> or <tt>>></tt> operators. 579 If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can 580 rewrite it very easily to use the newer <tt><<</tt> and 581 <tt>>></tt> operators instead. For example, the following code 582 to set the page size:</p> 583 584 <style type='text/css'><!-- 585 PRE B { 586 background: #000000; 587 color: #ffffff; 588 padding: 2px 5px; 589 } 590 --></style> 591 592 <pre class='command'> 593 <b>1 dict dup</b> /PageSize [612 792] <b>put</b> setpagedevice 594 </pre> 595 596 <p>can be rewritten as:</p> 597 598 <pre class='command'> 599 <b><<</b> /PageSize [612 792] <b>>></b> setpagedevice 600 </pre> 601 602 </blockquote> 603 604 <h3>Supported Page Device Attributes</h3> 605 606 <p>Table 2 shows the supported page device attributes along with PostScript code examples.</p> 607 608 <div class='table'> 609 <table summary='Supported Page Device Attributes'> 610 <caption>Table 2: <a name='TABLE_2'>Supported Page Device Attributes</a></caption> 611 <thead> 612 <tr> 613 <th>Name(s)</th> 614 <th>Type</th> 615 <th>Description</th> 616 <th>Example(s)</th> 617 </tr> 618 </thead> 619 <tbody> 620 <tr valign='top'> 621 <td><tt>AdvanceDistance</tt></td> 622 <td>Integer</td> 623 <td>Specifies the number of points to advance roll media after printing.</td> 624 <td><tt><</AdvanceDistance 18>>setpagedevice</tt></td> 625 </tr> 626 <tr valign='top'> 627 <td><tt>AdvanceMedia</tt></td> 628 <td>Integer</td> 629 <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> 630 <td><tt><</AdvanceMedia 4>>setpagedevice</tt></td> 631 </tr> 632 <tr valign='top'> 633 <td><tt>Collate</tt></td> 634 <td>Boolean</td> 635 <td>Specifies whether collated copies are required.</td> 636 <td><tt><</Collate true>>setpagedevice</tt></td> 637 </tr> 638 <tr valign='top'> 639 <td><tt>CutMedia</tt></td> 640 <td>Integer</td> 641 <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> 642 <td><tt><</CutMedia 1>>setpagedevice</tt></td> 643 </tr> 644 <tr valign='top'> 645 <td><tt>Duplex</tt></td> 646 <td>Boolean</td> 647 <td>Specifies whether 2-sided printing is required.</td> 648 <td><tt><</Duplex true>>setpagedevice</tt></td> 649 </tr> 650 <tr valign='top'> 651 <td><tt>HWResolution</tt></td> 652 <td>Integer Array</td> 653 <td>Specifies the resolution of the page image in pixels per inch.</td> 654 <td><tt><</HWResolution[1200 1200]>>setpagedevice</tt></td> 655 </tr> 656 <tr valign='top'> 657 <td><tt>InsertSheet</tt></td> 658 <td>Boolean</td> 659 <td>Specifies whether to insert a blank sheet before the job.</td> 660 <td><tt><</InsertSheet true>>setpagedevice</tt></td> 661 </tr> 662 <tr valign='top'> 663 <td><tt>Jog</tt></td> 664 <td>Integer</td> 665 <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> 666 <td><tt><</Jog 2>>setpagedevice</tt></td> 667 </tr> 668 <tr valign='top'> 669 <td><tt>LeadingEdge</tt></td> 670 <td>Integer</td> 671 <td>Specifies the leading edge of the media: 0 = top, 1 = right, 2 = bottom, 3 = left.</td> 672 <td><tt><</LeadingEdge 0>>setpagedevice</tt></td> 673 </tr> 674 <tr valign='top'> 675 <td><tt>ManualFeed</tt></td> 676 <td>Boolean</td> 677 <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> 678 <td><tt><</ManualFeed true>>setpagedevice</tt></td> 679 </tr> 680 <tr valign='top'> 681 <td><tt>MediaClass</tt></td> 682 <td>String</td> 683 <td>Specifies a named media.</td> 684 <td><tt><</MediaClass (Invoices)>>setpagedevice</tt></td> 685 </tr> 686 <tr valign='top'> 687 <td><tt>MediaColor</tt></td> 688 <td>String</td> 689 <td>Specifies the color of the media.</td> 690 <td><tt><</MediaColor >>setpagedevice</tt></td> 691 </tr> 692 <tr valign='top'> 693 <td><tt>MediaPosition</tt></td> 694 <td>Integer</td> 695 <td>Specifies the tray or source of the media.</td> 696 <td><tt><</MediaPosition 12>>setpagedevice</tt></td> 697 </tr> 698 <tr valign='top'> 699 <td><tt>MediaType</tt></td> 700 <td>String</td> 701 <td>Specifies the general media type.</td> 702 <td><tt><</MediaType (Glossy)>>setpagedevice</tt></td> 703 </tr> 704 <tr valign='top'> 705 <td><tt>MediaWeight</tt></td> 706 <td>Integer</td> 707 <td>Specifies the media weight in grams per meter<sup>2</sup>.</td> 708 <td><tt><</MediaWeight 100>>setpagedevice</tt></td> 709 </tr> 710 <tr valign='top'> 711 <td><tt>MirrorPrint</tt></td> 712 <td>Boolean</td> 713 <td>Specifies whether to flip the output image horizontally.</td> 714 <td><tt><</MirrorPrint true>>setpagedevice</tt></td> 715 </tr> 716 <tr valign='top'> 717 <td><tt>NegativePrint</tt></td> 718 <td>Boolean</td> 719 <td>Specifies whether to invert the output image.</td> 720 <td><tt><</NegativePrint true>>setpagedevice</tt></td> 721 </tr> 722 <tr valign='top'> 723 <td><tt>NumCopies</tt></td> 724 <td>Integer</td> 725 <td>Specifies the number of copies to produce of each page.</td> 726 <td><tt><</NumCopies 100>>setpagedevice</tt></td> 727 </tr> 728 <tr valign='top'> 729 <td><tt>Orientation</tt></td> 730 <td>Integer</td> 731 <td>Specifies the orientation of the output: 0 = portrait, 1 = landscape rotated counter-clockwise, 2 = upside-down, 3 = landscape rotated clockwise.</td> 732 <td><tt><</Orientation 3>>setpagedevice</tt></td> 733 </tr> 734 <tr valign='top'> 735 <td><tt>OutputFaceUp</tt></td> 736 <td>Boolean</td> 737 <td>Specifies whether to place the media face-up in the output bin/tray.</td> 738 <td><tt><</OutputFaceUp true>>setpagedevice</tt></td> 739 </tr> 740 <tr valign='top'> 741 <td><tt>OutputType</tt></td> 742 <td>String</td> 743 <td>Specifies the output type name.</td> 744 <td><tt><</OutputType (Photo)>>setpagedevice</tt></td> 745 </tr> 746 <tr valign='top'> 747 <td><tt>PageSize</tt></td> 748 <td>Integer/Real Array</td> 749 <td>Specifies the width and length/height of the page in points.</td> 750 <td><tt><</PageSize[595 842]>>setpagedevice</tt></td> 751 </tr> 752 <tr valign='top'> 753 <td><tt>Separations</tt></td> 754 <td>Boolean</td> 755 <td>Specifies whether to produce color separations.</td> 756 <td><tt><</Separations true>>setpagedevice</tt></td> 757 </tr> 758 <tr valign='top'> 759 <td><tt>TraySwitch</tt></td> 760 <td>Boolean</td> 761 <td>Specifies whether to switch trays automatically.</td> 762 <td><tt><</TraySwitch true>>setpagedevice</tt></td> 763 </tr> 764 <tr valign='top'> 765 <td><tt>Tumble</tt></td> 766 <td>Boolean</td> 767 <td>Specifies whether the back sides of pages are rotated 180 degrees.</td> 768 <td><tt><</Tumble true>>setpagedevice</tt></td> 769 </tr> 770 <tr valign='top'> 771 <td><tt>cupsBorderlessScalingFactor</tt></td> 772 <td>Real</td> 773 <td>Specifies the amount to scale the page image dimensions.</td> 774 <td><tt><</cupsBorderlessScalingFactor 1.01>>setpagedevice</tt></td> 775 </tr> 776 <tr valign='top'> 777 <td><tt>cupsColorOrder</tt></td> 778 <td>Integer</td> 779 <td>Specifies the order of colors: 0 = chunked, 1 = banded, 2 = planar.</td> 780 <td><tt><</cupsColorOrder 0>>setpagedevice</tt></td> 781 </tr> 782 <tr valign='top'> 783 <td><tt>cupsColorSpace</tt></td> 784 <td>Integer</td> 785 <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> 786 <td><tt><</cupsColorSpace 1 >>setpagedevice</tt></td> 787 </tr> 788 <tr valign='top'> 789 <td><tt>cupsCompression</tt></td> 790 <td>Integer</td> 791 <td>Specifies a driver compression type/mode.</td> 792 <td><tt><</cupsCompression 2>>setpagedevice</tt></td> 793 </tr> 794 <tr valign='top'> 795 <td><tt>cupsInteger0<br> 796 ...<br> 797 cupsInteger15</tt></td> 798 <td>Integer</td> 799 <td>Specifies driver integer values.</td> 800 <td><tt><</cupsInteger11 1234>>setpagedevice</tt></td> 801 </tr> 802 <tr valign='top'> 803 <td><tt>cupsMarkerType</tt></td> 804 <td>String</td> 805 <td>Specifies the type of ink/toner to use.</td> 806 <td><tt><</cupsMarkerType (Black+Color)>>setpagedevice</tt></td> 807 </tr> 808 <tr valign='top'> 809 <td><tt>cupsMediaType</tt></td> 810 <td>Integer</td> 811 <td>Specifies a numeric media type.</td> 812 <td><tt><</cupsMediaType 999>>setpagedevice</tt></td> 813 </tr> 814 <tr valign='top'> 815 <td><tt>cupsPageSizeName</tt></td> 816 <td>String</td> 817 <td>Specifies the name of the page size.</td> 818 <td><tt><</cupsPageSizeName (A4.Full)>>setpagedevice</tt></td> 819 </tr> 820 <tr valign='top'> 821 <td><tt>cupsPreferredBitsPerColor</tt></td> 822 <td>Integer</td> 823 <td>Specifies the preferred number of bits per color, typically 8 or 16.</td> 824 <td><tt><</cupsPreferredBitsPerColor 16>>setpagedevice</tt></td> 825 </tr> 826 <tr valign='top'> 827 <td><tt>cupsReal0<br> 828 ...<br> 829 cupsReal15</tt></td> 830 <td>Real</td> 831 <td>Specifies driver real number values.</td> 832 <td><tt><</cupsReal15 1.234>>setpagedevice</tt></td> 833 </tr> 834 <tr valign='top'> 835 <td><tt>cupsRenderingIntent</tt></td> 836 <td>String</td> 837 <td>Specifies the color rendering intent.</td> 838 <td><tt><</cupsRenderingIntent (AbsoluteColorimetric)>>setpagedevice</tt></td> 839 </tr> 840 <tr valign='top'> 841 <td><tt>cupsRowCount</tt></td> 842 <td>Integer</td> 843 <td>Specifies the number of rows of raster data to print on each line for some drivers.</td> 844 <td><tt><</cupsRowCount 24>>setpagedevice</tt></td> 845 </tr> 846 <tr valign='top'> 847 <td><tt>cupsRowFeed</tt></td> 848 <td>Integer</td> 849 <td>Specifies the number of rows to feed between passes for some drivers.</td> 850 <td><tt><</cupsRowFeed 17>>setpagedevice</tt></td> 851 </tr> 852 <tr valign='top'> 853 <td><tt>cupsRowStep</tt></td> 854 <td>Integer</td> 855 <td>Specifies the number of lines between columns/rows on the print head for some drivers.</td> 856 <td><tt><</cupsRowStep 2>>setpagedevice</tt></td> 857 </tr> 858 <tr valign='top'> 859 <td><tt>cupsString0<br> 860 ...<br> 861 cupsString15</tt></td> 862 <td>String</td> 863 <td>Specifies driver string values.</td> 864 <td><tt><</cupsString0(String Value)>>setpagedevice</tt></td> 865 </tr> 866 </tbody> 867 </table></div> 868 869 870 <h2 class='title'><a name='MEDIA'>Media Keywords</a></h2> 871 872 <p>The CUPS media keywords allow drivers to specify alternate custom page 873 size limits based on up to two options.</p> 874 875 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMediaQualifier2'>cupsMediaQualifier2</a></h3> 876 877 <p class='summary'>*cupsMediaQualifier2: MainKeyword</p> 878 879 <p>This keyword specifies the second option to use for overriding the 880 custom page size limits.</p> 881 882 <p>Example:</p> 883 884 <pre class='command'> 885 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em> 886 *cupsMediaQualifier2: InputSlot 887 *cupsMediaQualifier3: Quality 888 *cupsMaxSize .Manual.: "1000 1000" 889 *cupsMinSize .Manual.: "100 100" 890 *cupsMinSize .Manual.Photo: "200 200" 891 *cupsMinSize ..Photo: "300 300" 892 </pre> 893 894 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMediaQualifier3'>cupsMediaQualifier3</a></h3> 895 896 <p class='summary'>*cupsMediaQualifier3: MainKeyword</p> 897 898 <p>This keyword specifies the third option to use for overriding the 899 custom page size limits.</p> 900 901 <p>Example:</p> 902 903 <pre class='command'> 904 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em> 905 *cupsMediaQualifier2: InputSlot 906 *cupsMediaQualifier3: Quality 907 *cupsMaxSize .Manual.: "1000 1000" 908 *cupsMinSize .Manual.: "100 100" 909 *cupsMinSize .Manual.Photo: "200 200" 910 *cupsMinSize ..Photo: "300 300" 911 </pre> 912 913 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMinSize'>cupsMinSize</a></h3> 914 915 <p class='summary'>*cupsMinSize .Qualifier2.Qualifier3: "width length"<br> 916 *cupsMinSize .Qualifier2.: "width length"<br> 917 *cupsMinSize ..Qualifier3: "width length"</p> 918 919 <p>This keyword specifies alternate minimum custom page sizes in points. 920 The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and 921 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords 922 are used to identify options to use for matching.</p> 923 924 <p>Example:</p> 925 926 <pre class='command'> 927 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em> 928 *cupsMediaQualifier2: InputSlot 929 *cupsMediaQualifier3: Quality 930 *cupsMaxSize .Manual.: "1000 1000" 931 *cupsMinSize .Manual.: "100 100" 932 *cupsMinSize .Manual.Photo: "200 200" 933 *cupsMinSize ..Photo: "300 300" 934 </pre> 935 936 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMaxSize'>cupsMaxSize</a></h3> 937 938 <p class='summary'>*cupsMaxSize .Qualifier2.Qualifier3: "width length"<br> 939 *cupsMaxSize .Qualifier2.: "width length"<br> 940 *cupsMaxSize ..Qualifier3: "width length"</p> 941 942 <p>This keyword specifies alternate maximum custom page sizes in points. 943 The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and 944 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords 945 are used to identify options to use for matching.</p> 946 947 <p>Example:</p> 948 949 <pre class='command'> 950 <em>*% Specify alternate custom page size limits based on InputSlot and Quality</em> 951 *cupsMediaQualifier2: InputSlot 952 *cupsMediaQualifier3: Quality 953 *cupsMaxSize .Manual.: "1000 1000" 954 *cupsMinSize .Manual.: "100 100" 955 *cupsMinSize .Manual.Photo: "200 200" 956 *cupsMinSize ..Photo: "300 300" 957 </pre> 958 959 960 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsPageSizeCategory'>cupsPageSizeCategory</a></h3> 961 962 <p class="summary">*cupsPageSizeCategory name/text: "name name2 ... nameN"</p> 963 964 <p>This keyword lists related paper size names that should be grouped together in the Print or Page Setup dialogs. The "name" portion of the keyword specifies the root/default size for the grouping. On macOS the grouped paper sizes are shown in a submenu of the main paper size. When omitted, sizes with the same dimensions are automatically grouped together, for example "Letter" and "Letter.Borderless".</p> 965 966 <p>Example:</p> 967 968 <pre class="command"> 969 <em>*% Specify grouping of borderless/non-borderless sizes</em> 970 *cupsPageSizeCategory Letter/US Letter: "Letter Letter.Borderless" 971 *cupsPageSizeCategory A4/A4: "A4 A4.Borderless" 972 </pre> 973 974 975 <h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2> 976 977 <h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsBackSide'>cupsBackSide</a></h3> 978 979 <p class='summary'>*cupsBackSide: keyword</p> 980 981 <p>This keyword requests special handling of the back side of pages 982 when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a> 983 shows the supported keyword values for this keyword and their effect 984 on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt> 985 is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver 986 will receive print data starting at the bottom right corner of the page, with 987 each line going right-to-left instead of left-to-right. The default value is 988 <code>Normal</code>.</p> 989 990 <blockquote><b>Note:</b> 991 992 <p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt> 993 keyword - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt> 994 will be ignored.</p> 995 996 </blockquote> 997 998 <div class='table'> 999 <table width='80%' summary='Back Side Raster Coordinate System'> 1000 <caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption> 1001 <thead> 1002 <tr> 1003 <th>cupsBackSide</th> 1004 <th>Tumble Value</th> 1005 <th>Image Presentation</th> 1006 </tr> 1007 </thead> 1008 <tbody> 1009 <tr> 1010 <td><code>Normal</code></td> 1011 <td><code>false</code></td> 1012 <td>Left-to-right, top-to-bottom</td> 1013 </tr> 1014 <tr> 1015 <td><code>Normal</code></td> 1016 <td><code>true</code></td> 1017 <td>Left-to-right, top-to-bottom</td> 1018 </tr> 1019 <tr> 1020 <td><code>ManualTumble</code></td> 1021 <td><code>false</code></td> 1022 <td>Left-to-right, top-to-bottom</td> 1023 </tr> 1024 <tr> 1025 <td><code>ManualTumble</code></td> 1026 <td><code>true</code></td> 1027 <td>Right-to-left, bottom-to-top</td> 1028 </tr> 1029 <tr> 1030 <td><code>Rotated</code></td> 1031 <td><code>false</code></td> 1032 <td>Right-to-left, bottom-to-top</td> 1033 </tr> 1034 <tr> 1035 <td><code>Rotated</code></td> 1036 <td><code>true</code></td> 1037 <td>Right-to-left, top-to-bottom</td> 1038 </tr> 1039 <tr> 1040 <td><code>Flipped</code> *</td> 1041 <td><code>false</code></td> 1042 <td>Left-to-right, bottom-to-top</td> 1043 </tr> 1044 <tr> 1045 <td><code>Flipped</code> *</td> 1046 <td><code>true</code></td> 1047 <td>Right-to-left, top-to-bottom</td> 1048 </tr> 1049 </tbody> 1050 </table> 1051 </div> 1052 1053 <p><em>* - Not supported in macOS 10.5.x and earlier</em></p> 1054 1055 <div class='figure'><table summary='Back side images'> 1056 <caption>Figure 1: Back side images</caption> 1057 <tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr> 1058 </table></div> 1059 1060 <p>Examples:</p> 1061 1062 <pre class='command'> 1063 <em>*% Flip the page image for the back side of duplexed output</em> 1064 *cupsBackSide: Flipped 1065 1066 <em>*% Rotate the page image for the back side of duplexed output</em> 1067 *cupsBackSide: Rotated 1068 </pre> 1069 1070 <p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> 1071 keyword.</p> 1072 1073 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsCommands'>cupsCommands</a></h3> 1074 1075 <p class='summary'>*cupsCommands: "name name2 ... nameN"</p> 1076 1077 <p>This string keyword specifies the commands that are supported by the 1078 CUPS command file filter for this device. The command names are separated 1079 by whitespace.</p> 1080 1081 <p>Example:</p> 1082 1083 <pre class='command'> 1084 <em>*% Specify the list of commands we support</em> 1085 *cupsCommands: "AutoConfigure Clean PrintSelfTestPage ReportLevels com.vendor.foo" 1086 </pre> 1087 1088 1089 <h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></h3> 1090 1091 <p class='summary'>*cupsEvenDuplex: boolean</p> 1092 1093 <p>This boolean keyword notifies the RIP filters that the 1094 destination printer requires an even number of pages when 2-sided 1095 printing is selected. The default value is <code>false</code>.</p> 1096 1097 <p>Example:</p> 1098 1099 <pre class='command'> 1100 <em>*% Always send an even number of pages when duplexing</em> 1101 *cupsEvenDuplex: true 1102 </pre> 1103 1104 <h3><a name='cupsFax'>cupsFax</a></h3> 1105 1106 <p class='summary'>*cupsFax: boolean</p> 1107 1108 <p>This boolean keyword specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p> 1109 1110 <p>Examples:</p> 1111 1112 <pre class='command'> 1113 *cupsFax: true 1114 </pre> 1115 1116 <h3><a name='cupsFilter'>cupsFilter</a></h3> 1117 1118 <p class='summary'>*cupsFilter: "source/type cost program"</p> 1119 1120 <p>This string keyword provides a conversion rule from the 1121 given source type to the printer's native format using the 1122 filter "program". If a printer supports the source type directly, 1123 the special filter program "-" may be specified.</p> 1124 1125 <p>Examples:</p> 1126 1127 <pre class='command'> 1128 <em>*% Standard raster printer driver filter</em> 1129 *cupsFilter: "application/vnd.cups-raster 100 rastertofoo" 1130 1131 <em>*% Plain text filter</em> 1132 *cupsFilter: "text/plain 10 texttofoo" 1133 1134 <em>*% Pass-through filter for PostScript printers</em> 1135 *cupsFilter: "application/vnd.cups-postscript 0 -" 1136 </pre> 1137 1138 <h3><span class='info'>CUPS 1.5</span><a name='cupsFilter2'>cupsFilter2</a></h3> 1139 1140 <p class='summary'>*cupsFilter2: "source/type destination/type cost program"</p> 1141 1142 <p>This string keyword 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. The destination type is automatically created as needed and is passed to the filters and backend as the FINAL_CONTENT_TYPE value.</p> 1143 1144 <blockquote><b>Note:</b> 1145 1146 <p>The presence of a single <code>cupsFilter2</code> keyword in the PPD file will hide any <code>cupsFilter</code> keywords from the CUPS scheduler. When using <code>cupsFilter2</code> to provide filters specific for CUPS 1.5 and later, provide a <code>cupsFilter2</code> line for every filter and a <code>cupsFilter</code> line for each filter that is compatible with older versions of CUPS.</p> 1147 1148 </blockquote> 1149 1150 <p>Examples:</p> 1151 1152 <pre class='command'> 1153 <em>*% Standard raster printer driver filter</em> 1154 *cupsFilter2: "application/vnd.cups-raster application/vnd.foo 100 rastertofoo" 1155 1156 <em>*% Plain text filter</em> 1157 *cupsFilter2: "text/plain application/vnd.foo 10 texttofoo" 1158 1159 <em>*% Pass-through filter for PostScript printers</em> 1160 *cupsFilter2: "application/vnd.cups-postscript application/postscript 0 -" 1161 </pre> 1162 1163 <h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3> 1164 1165 <p class='summary'>*cupsFlipDuplex: boolean</p> 1166 1167 <p>Due to implementation differences between macOS and Ghostscript, 1168 the <tt>cupsFlipDuplex</tt> keyword is deprecated. Instead, use 1169 the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> keyword to specify 1170 the coordinate system (pixel layout) of the page data on the back side of 1171 duplex pages.</p> 1172 1173 <p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value 1174 of <code>Rotated</code> on macOS and <code>Flipped</code> with 1175 Ghostscript.</p> 1176 1177 <p>The default value is <code>false</code>.</p> 1178 1179 <blockquote><b>Note:</b> 1180 1181 <p>macOS drivers that previously used 1182 <tt>cupsFlipDuplex</tt> may wish to provide both the old and 1183 new keywords for maximum compatibility, for example:</p> 1184 1185 <pre class='command'> 1186 *cupsBackSide: Rotated 1187 *cupsFlipDuplex: true 1188 </pre> 1189 1190 <p>Similarly, drivers written for other operating systems using 1191 Ghostscript can use:</p> 1192 1193 <pre class='command'> 1194 *cupsBackSide: Flipped 1195 *cupsFlipDuplex: true 1196 </pre></blockquote> 1197 1198 <h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3> 1199 1200 <p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p> 1201 1202 <p>This keyword defines a mapping from IPP <code>finishings</code> 1203 values to PPD options and choices.</p> 1204 1205 <p>Examples:</p> 1206 1207 <pre class='command'> 1208 *cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait" 1209 *cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide" 1210 *cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait" 1211 *cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape" 1212 </pre> 1213 1214 <h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsIPPReason'>cupsIPPReason</a></h3> 1215 1216 <p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p> 1217 1218 <p>This optional keyword maps custom 1219 <code>printer-state-reasons</code> keywords that are generated by 1220 the driver to human readable text. The optional URIs string 1221 contains zero or more URIs separated by a newline. Each URI can 1222 be a CUPS server absolute path to a help file under the 1223 scheduler's <code>DocumentRoot</code> directory, a full HTTP URL 1224 ("http://www.domain.com/path/to/help/page.html"), or any other 1225 valid URI which directs the user at additional information 1226 concerning the condition that is being reported.</p> 1227 1228 <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 by the <tt>ppdLocalizeIPPReason</tt> into a single string that can be displayed to the user.</p> 1229 1230 <p>Examples:</p> 1231 1232 <pre class='command'> 1233 <em>*% Map com.vendor-error to text but no page</em> 1234 *cupsIPPReason com.vendor-error/A serious error occurred: "" 1235 1236 <em>*% Map com.vendor-error to more than 80 characters of text but no page</em> 1237 *cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time 1238 text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country." 1239 1240 <em>*% Map com.vendor-error to text and a local page</em> 1241 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html" 1242 1243 <em>*% Map com.vendor-error to text and a remote page</em> 1244 *cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help" 1245 1246 <em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em> 1247 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle" 1248 *cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html 1249 help:anchor='com.vendor-error'%20bookID=Vendor%20Help 1250 http://www.vendor.com/help" 1251 *End 1252 </pre> 1253 1254 <h3><span class='info'>CUPS 1.5</span><a name='cupsIPPSupplies'>cupsIPPSupplies</a></h3> 1255 1256 <p class='summary'>*cupsIPPSupplies: boolean</p> 1257 1258 <p>This keyword tells the IPP backend whether it should report the current marker-xxx supply attribute values. The default value is <code>True</code>. 1259 1260 <p>Example:</p> 1261 1262 <pre class='command'> 1263 <em>*% Do not use IPP marker-xxx attributes to report supply levels</em> 1264 *cupsIPPSupplies: False 1265 </pre> 1266 1267 1268 <h3><span class='info'>CUPS 1.7/macOS 10.9</span><a name='cupsJobAccountId'>cupsJobAccountId</a></h3> 1269 1270 <p class='summary'>*cupsJobAccountId: boolean</p> 1271 1272 <p>This keyword defines whether the printer accepts the job-account-id IPP attribute.</p> 1273 1274 <p>Example:</p> 1275 1276 <pre class='command'> 1277 <em>*% Specify the printer accepts the job-account-id IPP attribute.</em> 1278 *cupsJobAccountId: True 1279 </pre> 1280 1281 1282 <h3><span class='info'>CUPS 1.7/macOS 10.9</span><a name='cupsJobAccountingUserId'>cupsJobAccountingUserId</a></h3> 1283 1284 <p class='summary'>*cupsJobAccountingUserId: boolean</p> 1285 1286 <p>This keyword defines whether the printer accepts the job-accounting-user-id IPP attribute.</p> 1287 1288 <p>Example:</p> 1289 1290 <pre class='command'> 1291 <em>*% Specify the printer accepts the job-accounting-user-id IPP attribute.</em> 1292 *cupsJobAccountingUserId: True 1293 </pre> 1294 1295 1296 <h3><span class='info'>CUPS 1.7/macOS 10.9</span><a name='cupsJobPassword'>cupsJobPassword</a></h3> 1297 1298 <p class='summary'>*cupsJobPassword: "format"</p> 1299 1300 <p>This keyword defines the format of the job-password IPP attribute, if supported by the printer. Currently the only supported format is "1111" indicating a 4-digit PIN code.</p> 1301 1302 <p>Example:</p> 1303 1304 <pre class='command'> 1305 <em>*% Specify the printer supports 4-digit PIN codes.</em> 1306 *cupsJobPassword: "1111" 1307 </pre> 1308 1309 1310 <h3><span class='info'>CUPS 1.2/macOS 10.5</span><a name='cupsLanguages'>cupsLanguages</a></h3> 1311 1312 <p class='summary'>*cupsLanguages: "locale list"</p> 1313 1314 <p>This keyword describes which language localizations are 1315 included in the PPD. The "locale list" string is a space-delimited 1316 list of locale names ("en", "en_US", "fr_CA", etc.)</p> 1317 1318 <p>Example:</p> 1319 1320 <pre class='command'> 1321 <em>*% Specify Canadian, UK, and US English, and Canadian and French French</em> 1322 *cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR" 1323 </pre> 1324 1325 1326 <h3><span class='info'>CUPS 1.7/macOS 10.9</span><a name='cupsMandatory'>cupsMandatory</a></h3> 1327 1328 <p class='summary'>*cupsMandatory: "attribute1 attribute2 ... attributeN"</p> 1329 1330 <p>This keyword defines a list of IPP attributes that must be provided when submitting a print job creation request.</p> 1331 1332 <p>Example:</p> 1333 1334 <pre class='command'> 1335 <em>*% Specify that the user must supply a job-password</em> 1336 *cupsMandatory: "job-password job-password-encryption" 1337 </pre> 1338 1339 1340 <h3><a name='cupsManualCopies'>cupsManualCopies</a></h3> 1341 1342 <p class='summary'>*cupsManualCopies: boolean</p> 1343 1344 <p>This boolean keyword notifies the RIP filters that the 1345 destination printer does not support copy generation in 1346 hardware. The default value is <code>false</code>.</p> 1347 1348 <p>Example:</p> 1349 1350 <pre class='command'> 1351 <em>*% Tell the RIP filters to generate the copies for us</em> 1352 *cupsManualCopies: true 1353 </pre> 1354 1355 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMarkerName'>cupsMarkerName</a></h3> 1356 1357 <p class='summary'>*cupsMarkerName/Name Text: ""</p> 1358 1359 <p>This optional keyword maps <code>marker-names</code> strings that are 1360 generated by the driver to human readable text.</p> 1361 1362 <p>Examples:</p> 1363 1364 <pre class='command'> 1365 <em>*% Map cyanToner to "Cyan Toner"</em> 1366 *cupsMarkerName cyanToner/Cyan Toner: "" 1367 </pre> 1368 1369 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3> 1370 1371 <p class='summary'>*cupsMarkerNotice: "disclaimer text"</p> 1372 1373 <p>This optional keyword provides disclaimer text for the supply level 1374 information provided by the driver, typically something like "supply levels 1375 are approximate".</p> 1376 1377 <p>Examples:</p> 1378 1379 <pre class='command'> 1380 *cupsMarkerNotice: "Supply levels are approximate." 1381 </pre> 1382 1383 <h3><span class='info'>CUPS 1.6/macOS 10.8</span><a name='cupsMaxCopies'>cupsMaxCopies</a></h3> 1384 1385 <p class='summary'>*cupsMaxCopies: integer</p> 1386 1387 <p>This integer keyword notifies the filters that the destination printer supports up to N copies in hardware. The default value is <code>9999</code>.</p> 1388 1389 <p>Example:</p> 1390 1391 <pre class='command'> 1392 <em>*% Tell the RIP filters we can do up to 99 copies</em> 1393 *cupsMaxCopies: 99 1394 </pre> 1395 1396 <h3><a name='cupsModelNumber'>cupsModelNumber</a></h3> 1397 1398 <p class='summary'>*cupsModelNumber: number</p> 1399 1400 <p>This integer keyword specifies a printer-specific model 1401 number. This number can be used by a filter program to adjust 1402 the output for a specific model of printer.</p> 1403 1404 <p>Example:</p> 1405 1406 <pre class='command'> 1407 <em>*% Specify an integer for a driver-specific model number</em> 1408 *cupsModelNumber: 1234 1409 </pre> 1410 1411 1412 <h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3> 1413 1414 <p class='summary'>*cupsPJLCharset: "ISO character set name"</p> 1415 1416 <p>This string keyword specifies the character set that is used 1417 for strings in PJL commands. If not specified, US-ASCII is 1418 assumed.</p> 1419 1420 <p>Example:</p> 1421 1422 <pre class='command'> 1423 <em>*% Specify UTF-8 is used in PJL strings</em> 1424 *cupsPJLCharset: "UTF-8" 1425 </pre> 1426 1427 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3> 1428 1429 <p class='summary'>*cupsPJLDisplay: "what"</p> 1430 1431 <p>This optional keyword specifies which command is used to display the 1432 job ID, name, and user on the printer's control panel. "What" is either "none" 1433 to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg" 1434 to use "@PJL RDYMSG DISPLAY". The default is "job".</p> 1435 1436 <p>Examples:</p> 1437 1438 <pre class='command'> 1439 <em>*% Display job information using @PJL SET RDYMSG DISPLAY="foo"</em> 1440 *cupsPJLDisplay: "rdymsg" 1441 1442 <em>*% Display job information display</em> 1443 *cupsPJLDisplay: "none" 1444 </pre> 1445 1446 <h3><span class='info'>CUPS 1.2/macOS 10.5</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3> 1447 1448 <p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p> 1449 1450 <p>This string keyword specifies printer-specific "port 1451 monitor" filters that may be used with the printer. The CUPS 1452 scheduler also looks for the <tt>Protocols</tt> keyword to see 1453 if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If 1454 so, the corresponding port monitor ("bcp" and "tbcp", 1455 respectively) is listed in the printer's 1456 <tt>port-monitor-supported</tt> keyword.</p> 1457 1458 <p>The "urischeme" portion of the keyword specifies the URI scheme 1459 that this port monitor should be used for. Typically this is used to 1460 pre-select a particular port monitor for each type of connection that 1461 is supported by the printer. The "port monitor" string can be "none" 1462 to disable the port monitor for the given URI scheme.</p> 1463 1464 <p>Examples:</p> 1465 1466 <pre class='command'> 1467 <em>*% Specify a PostScript printer that supports the TBCP protocol</em> 1468 *Protocols: TBCP PJL 1469 1470 <em>*% Specify that TBCP should be used for socket connections but not USB</em> 1471 *cupsPortMonitor socket/AppSocket Printing: "tbcp" 1472 *cupsPortMonitor usb/USB Printing: "none" 1473 1474 <em>*% Specify a printer-specific port monitor for an Epson USB printer</em> 1475 *cupsPortMonitor usb/USB Status Monitor: "epson-usb" 1476 </pre> 1477 1478 <h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsPreFilter'>cupsPreFilter</a></h3> 1479 1480 <p class='summary'>*cupsPreFilter: "source/type cost program"</p> 1481 1482 <p>This string keyword provides a pre-filter rule. The pre-filter 1483 program will be inserted in the conversion chain immediately 1484 before the filter that accepts the given MIME type.</p> 1485 1486 <p>Examples:</p> 1487 1488 <pre class='command'> 1489 <em>*% PDF pre-filter</em> 1490 *cupsPreFilter: "application/pdf 100 mypdfprefilter" 1491 1492 <em>*% PNG pre-filter</em> 1493 *cupsPreFilter: "image/png 0 mypngprefilter" 1494 </pre> 1495 1496 1497 <h3><span class='info'>CUPS 1.5</span><a name='cupsPrintQuality'>cupsPrintQuality</a></h3> 1498 1499 <p class='summary'>*cupsPrintQuality keyword/text: "code"</p> 1500 1501 <p>This UI keyword defines standard print qualities that directly map from the IPP "print-quality" job template keyword. Standard keyword values are "Draft", "Normal", and "High" which are mapped from the IPP "print-quality" values 3, 4, and 5 respectively. Each <code>cupsPrintQuality</code> option typically sets output mode and resolution parameters in the page device dictionary, eliminating the need for separate (and sometimes confusing) output mode and resolution options.</p> 1502 1503 <blockquote><b>Note:</b> 1504 1505 <p>Unlike all of the other keywords defined in this document, <code>cupsPrintQuality</code> is a UI keyword that MUST be enclosed inside the PPD <code>OpenUI</code> and <code>CloseUI</code> keywords.</p> 1506 1507 </blockquote> 1508 1509 <p>Examples:</p> 1510 1511 <pre class='command'> 1512 *OpenUI *cupsPrintQuality/Print Quality: PickOne 1513 *OrderDependency: 10 AnySetup *cupsPrintQuality 1514 *DefaultcupsPrintQuality: Normal 1515 *cupsPrintQuality Draft/Draft: "code" 1516 *cupsPrintQuality Normal/Normal: "code" 1517 *cupsPrintQuality High/Photo: "code" 1518 *CloseUI: *cupsPrintQuality 1519 </pre> 1520 1521 <h3><span class='info'>CUPS 1.5</span><a name='cupsSingleFile'>cupsSingleFile</a></h3> 1522 1523 <p class='summary'>*cupsSingleFile: Boolean</p> 1524 1525 <p>This boolean keyword tells the scheduler whether to print multiple files in a job together or singly. The default is "False" which uses a single instance of the backend for all files in the print job. Setting this keyword to "True" will result in separate instances of the backend for each file in the print job.</p> 1526 1527 <p>Examples:</p> 1528 1529 <pre class='command'> 1530 <em>*% Send all print data to a single backend</em> 1531 *cupsSingleFile: False 1532 1533 <em>*% Send each file using a separate backend</em> 1534 *cupsSingleFile: True 1535 </pre> 1536 1537 <h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3> 1538 1539 <p class='summary'>*cupsSNMPSupplies: boolean</p> 1540 1541 <p>This keyword tells the standard network backends whether they should query 1542 the standard SNMP Printer MIB OIDs for supply levels. The default value is 1543 <code>True</code>. 1544 1545 <p>Example:</p> 1546 1547 <pre class='command'> 1548 <em>*% Do not use SNMP queries to report supply levels</em> 1549 *cupsSNMPSupplies: False 1550 </pre> 1551 1552 <h3><a name='cupsVersion'>cupsVersion</a></h3> 1553 1554 <p class='summary'>*cupsVersion: major.minor</p> 1555 1556 <p>This required keyword describes which version of the CUPS 1557 PPD file extensions was used. Currently it must be the string 1558 "1.0", "1.1", "1.2", "1.3", "1.4", "1.5", or "1.6".</p> 1559 1560 <p>Example:</p> 1561 1562 <pre class='command'> 1563 <em>*% Specify a CUPS 1.2 driver</em> 1564 *cupsVersion: "1.2" 1565 </pre> 1566 1567 1568 <h3><span class="info">CUPS 1.6/macOS 10.8</span><a name="JCLToPDFInterpreter">JCLToPDFInterpreter</a></h3> 1569 1570 <p class="summary">*JCLToPDFInterpreter: "JCL"</p> 1571 1572 <p>This keyword provides the JCL command to insert a PDF job file into a printer-ready data stream. The JCL command is added after the <tt>JCLBegin</tt> value and any commands for JCL options in the PPD file.</p> 1573 1574 <p>Example:</p> 1575 1576 <pre class='command'> 1577 <em>*% PJL command to start the PDF interpreter</em> 1578 *JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF<0A>" 1579 </pre> 1580 1581 1582 <h2 class='title'><a name='MACOSX'>macOS Attributes</a></h2> 1583 1584 <h3><span class='info'>macOS 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3> 1585 1586 <p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p> 1587 1588 <p>This keyword defines additional option panes that are displayed in the 1589 print dialog. Each keyword adds one or more option panes. See the "OutputBinsPDE" 1590 example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple 1591 Technical Q&A QA1352</a> for information on writing your own print dialog 1592 plug-ins.</p> 1593 1594 <blockquote><b>Note:</b> 1595 1596 <p>Starting with macOS 10.5, each plug-in must be compiled "4-way fat" 1597 (32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled 1598 in order to be usable with all applications.</p> 1599 1600 </blockquote> 1601 1602 <p>Examples:</p> 1603 1604 <pre class='command'> 1605 *% Add two panes for finishing and driver options 1606 *APDialogExtension: "/Library/Printers/vendor/finishing.plugin" 1607 *APDialogExtension: "/Library/Printers/vendor/options.plugin" 1608 </pre> 1609 1610 <h3><span class='info'>macOS 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3> 1611 1612 <p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p> 1613 1614 <p>This boolean keyword notifies the RIP filters that the 1615 destination printer requires the top and bottom margins of the 1616 <tt>ImageableArea</tt> to be swapped for the back page. The 1617 default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt> 1618 and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how 1619 <tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt> 1620 and the <tt>Tumble</tt> page attribute.</p> 1621 1622 <div class='table'> 1623 <table width='80%' summary='Margin Flipping Modes'> 1624 <caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption> 1625 <thead> 1626 <tr> 1627 <th>APDuplexRequiresFlippedMargin</th> 1628 <th>cupsBackSide</th> 1629 <th>Tumble Value</th> 1630 <th>Margins</th> 1631 </tr> 1632 </thead> 1633 <tbody> 1634 <tr> 1635 <td>false</td> 1636 <td>any</td> 1637 <td>any</td> 1638 <td>Normal</td> 1639 </tr> 1640 <tr> 1641 <td>any</td> 1642 <td>Normal</td> 1643 <td>any</td> 1644 <td>Normal</td> 1645 </tr> 1646 <tr> 1647 <td>true</td> 1648 <td>ManualDuplex</td> 1649 <td>false</td> 1650 <td>Normal</td> 1651 </tr> 1652 <tr> 1653 <td>true</td> 1654 <td>ManualDuplex</td> 1655 <td>true</td> 1656 <td>Flipped</td> 1657 </tr> 1658 <tr> 1659 <td>true</td> 1660 <td>Rotated</td> 1661 <td>false</td> 1662 <td>Flipped</td> 1663 </tr> 1664 <tr> 1665 <td>true</td> 1666 <td>Rotated</td> 1667 <td>true</td> 1668 <td>Normal</td> 1669 </tr> 1670 <tr> 1671 <td>true or unspecified</td> 1672 <td>Flipped</td> 1673 <td>any</td> 1674 <td>Flipped</td> 1675 </tr> 1676 </tbody> 1677 </table></div> 1678 1679 <p>Example:</p> 1680 1681 <pre class='command'> 1682 <em>*% Rotate the back side images</em> 1683 *cupsBackSide: Rotated 1684 1685 <em>*% Don't swap the top and bottom margins for the back side</em> 1686 *APDuplexRequiresFlippedMargin: false 1687 </pre> 1688 1689 <p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> 1690 keyword.</p> 1691 1692 <h3><a name='APHelpBook'>APHelpBook</a></h3> 1693 1694 <p class='summary'>*APHelpBook: "bundle URL"</p> 1695 1696 <p>This string keyword specifies the Apple help book bundle to use when 1697 looking up IPP reason codes for this printer driver. The 1698 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword maps 1699 "help" URIs to this file.</p> 1700 1701 <p>Example:</p> 1702 1703 <pre class='command'> 1704 *APHelpBook: "file:///Library/Printers/vendor/Help.bundle" 1705 </pre> 1706 1707 <h3><span class='info'>macOS 10.6</span><a name='APICADriver'>APICADriver</a></h3> 1708 1709 <p class='summary'>*APICADriver: boolean</p> 1710 1711 <p>This keyword specifies whether the device has a matching Image Capture 1712 Architecture (ICA) driver for scanning. The default is <tt>False</tt>.</p> 1713 1714 <p>Examples:</p> 1715 1716 <pre class='command'> 1717 *APICADriver: True 1718 *APScanAppBundleID: "com.apple.ImageCaptureApp" 1719 </pre> 1720 1721 <h3><span class='info'>macOS 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3> 1722 1723 <p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"</p> 1724 1725 <p>This keyword defines the location of a printer icon file to use when 1726 displaying the printer. The file must be in the Apple icon format.</p> 1727 1728 <p>Examples:</p> 1729 1730 <pre class='command'> 1731 *% Apple icon file 1732 *APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns" 1733 </pre> 1734 1735 <h3><span class='info'>macOS 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3> 1736 1737 <p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p> 1738 1739 <p>This keyword defines an program that checks the ink/toner/marker levels 1740 on a printer, returning an XML document with those levels. See the "InkTool" 1741 example and 1742 <a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple 1743 Technical Note TN2144</a> for more information.</p> 1744 1745 <p>Examples:</p> 1746 1747 <pre class='command'> 1748 *% Use a vendor monitoring program 1749 *APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool" 1750 </pre> 1751 1752 <h3><span class='info'>macOS 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3> 1753 1754 <p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p> 1755 1756 <p>This keyword defines presets for multiple options that show up 1757 in the print dialog of applications (such as iPhoto) that set the job 1758 style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or 1759 more pairs of PPD options and choices as well as providing key/value data for 1760 the application. The following standard preset names are currently defined:</p> 1761 1762 <ul> 1763 1764 <li><code>General_with_Paper_Auto-Detect</code>; Normal quality general printing with auto-detected media.</li> 1765 1766 <li><code>General_with_Paper_Auto-Detect_-_Draft</code>; Draft quality general printing with auto-detected media.</li> 1767 1768 <li><code>General_on_Plain_Paper</code>; Normal quality general printing on plain paper.</li> 1769 1770 <li><code>General_on_Plain_Paper_-_Draft</code>; Draft quality general printing on plain paper.</li> 1771 1772 <li><code>Photo_with_Paper_Auto-Detect</code>; Normal quality photo printing with auto-detected media.</li> 1773 1774 <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; High quality photo printing with auto-detected media.</li> 1775 1776 <li><code>Photo_on_Plain_Paper</code>; Normal quality photo printing on plain paper.</li> 1777 1778 <li><code>Photo_on_Plain_Paper_-_Fine</code>; High quality photo printing on plain paper.</li> 1779 1780 <li><code>Photo_on_Photo_Paper</code>; Normal quality photo printing on glossy photo paper.</li> 1781 1782 <li><code>Photo_on_Photo_Paper_-_Fine</code>; High quality photo printing on glossy photo paper.</li> 1783 1784 <li><code>Photo_on_Matte_Paper</code>; Normal quality photo printing on matte paper.</li> 1785 1786 <li><code>Photo_on_Matte_Paper_-_Fine</code>; High quality photo printing on matte paper.</li> 1787 1788 </ul> 1789 1790 <p>The value string consists of pairs of keywords, either an option name and 1791 choice (*MainKeyword OptionKeyword) or a preset identifier and value 1792 (com.apple.print.preset.foo value). The following preset identifiers are currently used:</p> 1793 1794 <ul> 1795 1796 <li><code>com.apple.print.preset.graphicsType</code>; specifies the type of printing used for this printing - "General" for general purpose printing and "Photo" for photo printing.</li> 1797 1798 <li><code>com.apple.print.preset.media-front-coating</code>; specifies the media type selected by this preset - "none" (plain paper), "glossy", "high-gloss", "semi-gloss", "satin", "matte", and "autodetect".</li> 1799 1800 <li><code>com.apple.print.preset.output-mode</code>; specifies the output mode for this preset - "color" (default for color printers) or "monochrome" (grayscale, default for B&W printers).</li> 1801 1802 <li><code>com.apple.print.preset.quality</code>; specifies the overall print quality selected by this preset - "low" (draft), "mid" (normal), or "high".</li> 1803 1804 </ul> 1805 1806 <p>Presets, like options, can also be localized in multiple languages.</p> 1807 1808 <p>Examples:</p> 1809 1810 <pre class='command'> 1811 *APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: " 1812 *MediaType Glossy 1813 *ColorModel RGB 1814 *Resolution 300dpi 1815 com.apple.print.preset.graphicsType Photo 1816 com.apple.print.preset.quality mid 1817 com.apple.print.preset.media-front-coating glossy" 1818 *End 1819 *fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: "" 1820 </pre> 1821 1822 <h3><span class='info'>macOS 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3> 1823 1824 <p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p> 1825 1826 <p>This keyword defines a GUI application that can be used to do printer 1827 maintenance functions such as cleaning the print head(s). See ... for more 1828 information.</p> 1829 1830 <p>Examples:</p> 1831 1832 <pre class='command'> 1833 *% Define the printer utility application 1834 *APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app" 1835 </pre> 1836 1837 <h3><span class='info'>macOS 10.6</span><a name='APScannerOnly'>APScannerOnly</a></h3> 1838 1839 <p class='summary'>*APScannerOnly: boolean</p> 1840 1841 <p>This keyword specifies whether the device has scanning but no printing 1842 capabilities. The default is <tt>False</tt>.</p> 1843 1844 <p>Examples:</p> 1845 1846 <pre class='command'> 1847 *APICADriver: True 1848 *APScannerOnly: True 1849 </pre> 1850 1851 <h3><span class='info'>macOS 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3> 1852 1853 <p class='summary'>*APScanAppBundleID: "bundle ID"</p> 1854 1855 <p>This keyword defines the application to use when scanning pages from 1856 the device.</p> 1857 1858 <p>Examples:</p> 1859 1860 <pre class='command'> 1861 *APICADriver: True 1862 *APScanAppBundleID: "com.apple.ImageCaptureApp" 1863 </pre> 1864 1865 1866 <h2 class='title'><a name='HISTORY'>Change History</a></h2> 1867 1868 <h3>Changes in CUPS 1.7</h3> 1869 1870 <ul> 1871 1872 <li>Added <a href="#cupsJobAccountId"><tt>cupsJobAccountId</tt></a>, 1873 <a href="#cupsJobAccountingUserId"><tt>cupsJobAccountingUserId</tt></a>, 1874 <a href="#cupsJobPassword"><tt>cupsJobPassword</tt></a>, 1875 <a href="#cupsMandatory"><tt>cupsMandatory</tt></a> keywords.</li> 1876 1877 </ul> 1878 1879 1880 <h3>Changes in CUPS 1.6</h3> 1881 1882 <ul> 1883 1884 <li>Added <a href="#cupsPageSizeCategory"><tt>cupsPageSizeCategory</tt></a> keyword (originally defined in CUPS 1.4).</li> 1885 1886 <li>Added <a href="#cupsMaxCopies"><tt>cupsMaxCopies</tt></a> keyword.</li> 1887 1888 <li>Documented <a href="#JCLToPDFInterpreter"><tt>JCLToPDFInterpreter</tt></a> keyword.</li> 1889 1890 <li>Updated <a href="#cupsVersion"><tt>cupsVersion</tt></a> keyword documentation to list all current releases of CUPS.</li> 1891 1892 </ul> 1893 1894 1895 <h3>Changes in CUPS 1.5</h3> 1896 1897 <ul> 1898 1899 <li>Changes all instances of PPD attributes to PPD keywords, to be consistent with the parent specification from Adobe.</li> 1900 1901 </ul> 1902 1903 1904 <h3>Changes in CUPS 1.4.5</h3> 1905 1906 <ul> 1907 1908 <li>Added <a href='#cupsPrintQuality'><tt>cupsPrintQuality</tt></a> UI keyword.</li> 1909 1910 <li>Added new properties and values for the <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a> keyword.</li> 1911 1912 </ul> 1913 1914 1915 <h3>Changes in CUPS 1.4</h3> 1916 1917 <ul> 1918 1919 <li>Added <a href='#APICADriver'><tt>APICADriver</tt></a> 1920 keyword.</li> 1921 1922 <li>Added <a href='#cupsCommands'><tt>cupsCommands</tt></a> 1923 keyword.</li> 1924 1925 <li>Added <a href='#cupsMarkerName'><tt>cupsMarkerName</tt></a> 1926 keyword.</li> 1927 1928 <li>Added <a href='#cupsMarkerNotice'><tt>cupsMarkerNotice</tt></a> 1929 keyword.</li> 1930 1931 <li>Added <a href='#cupsPJLDisplay'><tt>cupsPJLDisplay</tt></a> 1932 keyword.</li> 1933 1934 <li>Added <a href='#cupsSNMPSupplies'><tt>cupsSNMPSupplies</tt></a> 1935 keyword.</li> 1936 1937 <li>Added <a href='#cupsUIResolver'><tt>cupsUIResolver</tt></a> and 1938 <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a> 1939 keywords.</li> 1940 1941 <li>Added 1942 <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a>, 1943 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a>, 1944 <a href='#cupsMinSize'><tt>cupsMinSize</tt></a>, and 1945 <a href='#cupsMaxSize'><tt>cupsMaxSize</tt></a> keywords.</li> 1946 1947 </ul> 1948 1949 1950 <h3>Changes in CUPS 1.3.1</h3> 1951 1952 <ul> 1953 1954 <li>Added missing macOS <tt>AP</tt> keywords.</li> 1955 1956 <li>Added section on auto-configuration including the 1957 <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt> 1958 keywords.</li> 1959 1960 <li>Minor reorganization.</li> 1961 1962 </ul> 1963 1964 1965 <h3>Changes in CUPS 1.3</h3> 1966 1967 <ul> 1968 1969 <li>Added <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> and 1970 deprecated <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a>.</li> 1971 1972 <li>Added text URI information to 1973 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> documentation.</li> 1974 1975 <li>Added <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a>, 1976 <a href='#cupsIPPFinishings'><tt>cupsIPPFinishings</tt></a>, and 1977 <a href='#cupsPreFilter'><tt>cupsPreFilter</tt></a> keywords.</li> 1978 1979 <li>Added discussion of custom option code, sample 1980 <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li> 1981 1982 </ul> 1983 1984 <h3>Changes in CUPS 1.2.8</h3> 1985 1986 <ul> 1987 1988 <li>Added section on supported PostScript commands for raster 1989 drivers</li> 1990 1991 </ul> 1992 1993 <h3>Changes in CUPS 1.2</h3> 1994 1995 <ul> 1996 1997 <li>Added globalization support keywords</li> 1998 1999 <li>Added custom option values support</li> 2000 2001 <li>Added <a href='#APHelpBook'><tt>APHelpBook</tt></a> keyword</li> 2002 2003 <li>Added <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> 2004 keyword</li> 2005 2006 <li>Added <a href='#cupsICCProfile'><tt>cupsICCProfile</tt></a> keyword</li> 2007 2008 <li>Added <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword</li> 2009 2010 <li>Added <a href='#cupsLanguages'><tt>cupsLanguages</tt></a> keyword</li> 2011 2012 <li>Added <a href='#cupsPortMonitor'><tt>cupsPortMonitor</tt></a> keyword</li> 2013 2014 <li>Removed <tt>cupsProtocol</tt> keyword</li> 2015 2016 </ul> 2017 2018 <h3>Changes in CUPS 1.1</h3> 2019 2020 <ul> 2021 2022 <li>Added <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a> keyword</li> 2023 2024 <li>Added <tt>cupsProtocol</tt> keyword</li> 2025 2026 </ul> 2027
