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'> 6PPD-FILE = HEADER +(DATA / COMMENT / LINE-END) 7 8HEADER = "*PPD-Adobe:" *WSP DQUOTE VERSION DQUOTE LINE-END 9 10VERSION = "4.0" / "4.1" / "4.2" / "4.3" 11 12COMMENT = "*%" *TCHAR LINE-END 13 14DATA = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":" 15 1*(*WSP VALUE) LINE-END 16 17VALUE = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE 18 19KCHAR = ALPHA / DIGIT / "_" / "." / "-" 20 21SCHAR = LINE-END / WSP / %x21.23-7E.A0-FF 22 23TCHAR = %x20-7E.A0-FF 24 25LINE-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 117density adjustment function such that:</p> 118 119<pre class='command'> 120f(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 430option 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> 576operators in your option code. These operators are typically used in 577option code dating back to Level 1 PostScript printers, which did not 578support the simpler <tt><<</tt> or <tt>>></tt> operators. 579If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can 580rewrite it very easily to use the newer <tt><<</tt> and 581<tt>>></tt> operators instead. For example, the following code 582to set the page size:</p> 583 584<style type='text/css'><!-- 585PRE 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 873size 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 880custom 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 899custom 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. 920The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and 921<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords 922are 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. 943The <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a> and 944<a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a> keywords 945are 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 982when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a> 983shows the supported keyword values for this keyword and their effect 984on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt> 985is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver 986will receive print data starting at the bottom right corner of the page, with 987each 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> 993keyword - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt> 994will 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> 1071keyword.</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 1078CUPS command file filter for this device. The command names are separated 1079by 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 1094destination printer requires an even number of pages when 2-sided 1095printing 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 1121given source type to the printer's native format using the 1122filter "program". If a printer supports the source type directly, 1123the 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, 1168the <tt>cupsFlipDuplex</tt> keyword is deprecated. Instead, use 1169the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> keyword to specify 1170the coordinate system (pixel layout) of the page data on the back side of 1171duplex pages.</p> 1172 1173<p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value 1174of <code>Rotated</code> on macOS and <code>Flipped</code> with 1175Ghostscript.</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 1183new 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 1191Ghostscript 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> 1203values 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 1220the driver to human readable text. The optional URIs string 1221contains zero or more URIs separated by a newline. Each URI can 1222be a CUPS server absolute path to a help file under the 1223scheduler's <code>DocumentRoot</code> directory, a full HTTP URL 1224("http://www.domain.com/path/to/help/page.html"), or any other 1225valid URI which directs the user at additional information 1226concerning 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 1238text: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 1249help:anchor='com.vendor-error'%20bookID=Vendor%20Help 1250http://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. The following format characters are supported:</p> 1301 1302<ul> 1303 <li><code>1</code>: US ASCII digits.</li> 1304 <li><code>A</code>: US ASCII letters.</li> 1305 <li><code>C</code>: US ASCII letters, numbers, and punctuation.</li> 1306 <li><code>.</code>: Any US ASCII printable character (0x20 to 0x7e).</li> 1307 <li><code>N</code>: Any Unicode digit character.</li> 1308 <li><code>U</code>: Any Unicode letter character.</li> 1309 <li><code>*</code>: Any Unicode (utf-8) character.</li> 1310</ul> 1311 1312<p>The format characters are repeated to indicate the length of the 1313password string. For example, "1111" indicated a 4-digit US ASCII PIN code.</p> 1314 1315<p>Example:</p> 1316 1317<pre class='command'> 1318<em>*% Specify the printer supports 4-digit PIN codes.</em> 1319*cupsJobPassword: "1111" 1320</pre> 1321 1322 1323<h3><span class='info'>CUPS 1.2/macOS 10.5</span><a name='cupsLanguages'>cupsLanguages</a></h3> 1324 1325<p class='summary'>*cupsLanguages: "locale list"</p> 1326 1327<p>This keyword describes which language localizations are 1328included in the PPD. The "locale list" string is a space-delimited 1329list of locale names ("en", "en_US", "fr_CA", etc.)</p> 1330 1331<p>Example:</p> 1332 1333<pre class='command'> 1334<em>*% Specify Canadian, UK, and US English, and Canadian and French French</em> 1335*cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR" 1336</pre> 1337 1338 1339<h3><span class='info'>CUPS 1.7/macOS 10.9</span><a name='cupsMandatory'>cupsMandatory</a></h3> 1340 1341<p class='summary'>*cupsMandatory: "attribute1 attribute2 ... attributeN"</p> 1342 1343<p>This keyword defines a list of IPP attributes that must be provided when submitting a print job creation request.</p> 1344 1345<p>Example:</p> 1346 1347<pre class='command'> 1348<em>*% Specify that the user must supply a job-password</em> 1349*cupsMandatory: "job-password job-password-encryption" 1350</pre> 1351 1352 1353<h3><a name='cupsManualCopies'>cupsManualCopies</a></h3> 1354 1355<p class='summary'>*cupsManualCopies: boolean</p> 1356 1357<p>This boolean keyword notifies the RIP filters that the 1358destination printer does not support copy generation in 1359hardware. The default value is <code>false</code>.</p> 1360 1361<p>Example:</p> 1362 1363<pre class='command'> 1364<em>*% Tell the RIP filters to generate the copies for us</em> 1365*cupsManualCopies: true 1366</pre> 1367 1368<h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMarkerName'>cupsMarkerName</a></h3> 1369 1370<p class='summary'>*cupsMarkerName/Name Text: ""</p> 1371 1372<p>This optional keyword maps <code>marker-names</code> strings that are 1373generated by the driver to human readable text.</p> 1374 1375<p>Examples:</p> 1376 1377<pre class='command'> 1378<em>*% Map cyanToner to "Cyan Toner"</em> 1379*cupsMarkerName cyanToner/Cyan Toner: "" 1380</pre> 1381 1382<h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsMarkerNotice'>cupsMarkerNotice</a></h3> 1383 1384<p class='summary'>*cupsMarkerNotice: "disclaimer text"</p> 1385 1386<p>This optional keyword provides disclaimer text for the supply level 1387information provided by the driver, typically something like "supply levels 1388are approximate".</p> 1389 1390<p>Examples:</p> 1391 1392<pre class='command'> 1393*cupsMarkerNotice: "Supply levels are approximate." 1394</pre> 1395 1396<h3><span class='info'>CUPS 1.6/macOS 10.8</span><a name='cupsMaxCopies'>cupsMaxCopies</a></h3> 1397 1398<p class='summary'>*cupsMaxCopies: integer</p> 1399 1400<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> 1401 1402<p>Example:</p> 1403 1404<pre class='command'> 1405<em>*% Tell the RIP filters we can do up to 99 copies</em> 1406*cupsMaxCopies: 99 1407</pre> 1408 1409<h3><a name='cupsModelNumber'>cupsModelNumber</a></h3> 1410 1411<p class='summary'>*cupsModelNumber: number</p> 1412 1413<p>This integer keyword specifies a printer-specific model 1414number. This number can be used by a filter program to adjust 1415the output for a specific model of printer.</p> 1416 1417<p>Example:</p> 1418 1419<pre class='command'> 1420<em>*% Specify an integer for a driver-specific model number</em> 1421*cupsModelNumber: 1234 1422</pre> 1423 1424 1425<h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsPJLCharset'>cupsPJLCharset</a></h3> 1426 1427<p class='summary'>*cupsPJLCharset: "ISO character set name"</p> 1428 1429<p>This string keyword specifies the character set that is used 1430for strings in PJL commands. If not specified, US-ASCII is 1431assumed.</p> 1432 1433<p>Example:</p> 1434 1435<pre class='command'> 1436<em>*% Specify UTF-8 is used in PJL strings</em> 1437*cupsPJLCharset: "UTF-8" 1438</pre> 1439 1440<h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsPJLDisplay'>cupsPJLDisplay</a></h3> 1441 1442<p class='summary'>*cupsPJLDisplay: "what"</p> 1443 1444<p>This optional keyword specifies which command is used to display the 1445job ID, name, and user on the printer's control panel. "What" is either "none" 1446to disable this functionality, "job" to use "@PJL JOB DISPLAY", or "rdymsg" 1447to use "@PJL RDYMSG DISPLAY". The default is "job".</p> 1448 1449<p>Examples:</p> 1450 1451<pre class='command'> 1452<em>*% Display job information using @PJL SET RDYMSG DISPLAY="foo"</em> 1453*cupsPJLDisplay: "rdymsg" 1454 1455<em>*% Display job information display</em> 1456*cupsPJLDisplay: "none" 1457</pre> 1458 1459<h3><span class='info'>CUPS 1.2/macOS 10.5</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3> 1460 1461<p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p> 1462 1463<p>This string keyword specifies printer-specific "port 1464monitor" filters that may be used with the printer. The CUPS 1465scheduler also looks for the <tt>Protocols</tt> keyword to see 1466if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If 1467so, the corresponding port monitor ("bcp" and "tbcp", 1468respectively) is listed in the printer's 1469<tt>port-monitor-supported</tt> keyword.</p> 1470 1471<p>The "urischeme" portion of the keyword specifies the URI scheme 1472that this port monitor should be used for. Typically this is used to 1473pre-select a particular port monitor for each type of connection that 1474is supported by the printer. The "port monitor" string can be "none" 1475to disable the port monitor for the given URI scheme.</p> 1476 1477<p>Examples:</p> 1478 1479<pre class='command'> 1480<em>*% Specify a PostScript printer that supports the TBCP protocol</em> 1481*Protocols: TBCP PJL 1482 1483<em>*% Specify that TBCP should be used for socket connections but not USB</em> 1484*cupsPortMonitor socket/AppSocket Printing: "tbcp" 1485*cupsPortMonitor usb/USB Printing: "none" 1486 1487<em>*% Specify a printer-specific port monitor for an Epson USB printer</em> 1488*cupsPortMonitor usb/USB Status Monitor: "epson-usb" 1489</pre> 1490 1491<h3><span class='info'>CUPS 1.3/macOS 10.5</span><a name='cupsPreFilter'>cupsPreFilter</a></h3> 1492 1493<p class='summary'>*cupsPreFilter: "source/type cost program"</p> 1494 1495<p>This string keyword provides a pre-filter rule. The pre-filter 1496program will be inserted in the conversion chain immediately 1497before the filter that accepts the given MIME type.</p> 1498 1499<p>Examples:</p> 1500 1501<pre class='command'> 1502<em>*% PDF pre-filter</em> 1503*cupsPreFilter: "application/pdf 100 mypdfprefilter" 1504 1505<em>*% PNG pre-filter</em> 1506*cupsPreFilter: "image/png 0 mypngprefilter" 1507</pre> 1508 1509 1510<h3><span class='info'>CUPS 1.5</span><a name='cupsPrintQuality'>cupsPrintQuality</a></h3> 1511 1512<p class='summary'>*cupsPrintQuality keyword/text: "code"</p> 1513 1514<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> 1515 1516<blockquote><b>Note:</b> 1517 1518<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> 1519 1520</blockquote> 1521 1522<p>Examples:</p> 1523 1524<pre class='command'> 1525*OpenUI *cupsPrintQuality/Print Quality: PickOne 1526*OrderDependency: 10 AnySetup *cupsPrintQuality 1527*DefaultcupsPrintQuality: Normal 1528*cupsPrintQuality Draft/Draft: "code" 1529*cupsPrintQuality Normal/Normal: "code" 1530*cupsPrintQuality High/Photo: "code" 1531*CloseUI: *cupsPrintQuality 1532</pre> 1533 1534<h3><span class='info'>CUPS 1.5</span><a name='cupsSingleFile'>cupsSingleFile</a></h3> 1535 1536<p class='summary'>*cupsSingleFile: Boolean</p> 1537 1538<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> 1539 1540<p>Examples:</p> 1541 1542<pre class='command'> 1543<em>*% Send all print data to a single backend</em> 1544*cupsSingleFile: False 1545 1546<em>*% Send each file using a separate backend</em> 1547*cupsSingleFile: True 1548</pre> 1549 1550<h3><span class='info'>CUPS 1.4/macOS 10.6</span><a name='cupsSNMPSupplies'>cupsSNMPSupplies</a></h3> 1551 1552<p class='summary'>*cupsSNMPSupplies: boolean</p> 1553 1554<p>This keyword tells the standard network backends whether they should query 1555the standard SNMP Printer MIB OIDs for supply levels. The default value is 1556<code>True</code>. 1557 1558<p>Example:</p> 1559 1560<pre class='command'> 1561<em>*% Do not use SNMP queries to report supply levels</em> 1562*cupsSNMPSupplies: False 1563</pre> 1564 1565<h3><a name='cupsVersion'>cupsVersion</a></h3> 1566 1567<p class='summary'>*cupsVersion: major.minor</p> 1568 1569<p>This required keyword describes which version of the CUPS 1570PPD file extensions was used. Currently it must be the string 1571"1.0", "1.1", "1.2", "1.3", "1.4", "1.5", or "1.6".</p> 1572 1573<p>Example:</p> 1574 1575<pre class='command'> 1576<em>*% Specify a CUPS 1.2 driver</em> 1577*cupsVersion: "1.2" 1578</pre> 1579 1580 1581<h3><span class="info">CUPS 1.6/macOS 10.8</span><a name="JCLToPDFInterpreter">JCLToPDFInterpreter</a></h3> 1582 1583<p class="summary">*JCLToPDFInterpreter: "JCL"</p> 1584 1585<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> 1586 1587<p>Example:</p> 1588 1589<pre class='command'> 1590<em>*% PJL command to start the PDF interpreter</em> 1591*JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF<0A>" 1592</pre> 1593 1594 1595<h2 class='title'><a name='MACOSX'>macOS Attributes</a></h2> 1596 1597<h3><span class='info'>Deprecated</span><a name='APDialogExtension'>APDialogExtension</a></h3> 1598 1599<p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p> 1600 1601<p>This keyword defines additional option panes that are displayed in the 1602print dialog. Each keyword adds one or more option panes. See the "OutputBinsPDE" 1603example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple 1604Technical Q&A QA1352</a> for information on writing your own print dialog 1605plug-ins.</p> 1606 1607<blockquote><b>Note:</b> 1608 1609<p>Since 2010, AirPrint has enabled the printing of full quality photos and 1610documents from the Mac without requiring driver software. Starting with macOS 161110.12, system level security features prevent print dialog plug-ins from being 1612loaded into applications that have enabled the library validation security 1613feature. As of macOS 10.14 the <code>APDialogExtension</code> attribute used to 1614create macOS print drivers is deprecated. All new printer models should support 1615AirPrint moving forward.</p> 1616 1617</blockquote> 1618 1619<p>Examples:</p> 1620 1621<pre class='command'> 1622*% Add two panes for finishing and driver options 1623*APDialogExtension: "/Library/Printers/vendor/finishing.plugin" 1624*APDialogExtension: "/Library/Printers/vendor/options.plugin" 1625</pre> 1626 1627<h3><span class='info'>macOS 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3> 1628 1629<p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p> 1630 1631<p>This boolean keyword notifies the RIP filters that the 1632destination printer requires the top and bottom margins of the 1633<tt>ImageableArea</tt> to be swapped for the back page. The 1634default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt> 1635and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how 1636<tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt> 1637and the <tt>Tumble</tt> page attribute.</p> 1638 1639<div class='table'> 1640<table width='80%' summary='Margin Flipping Modes'> 1641<caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption> 1642<thead> 1643<tr> 1644 <th>APDuplexRequiresFlippedMargin</th> 1645 <th>cupsBackSide</th> 1646 <th>Tumble Value</th> 1647 <th>Margins</th> 1648</tr> 1649</thead> 1650<tbody> 1651<tr> 1652 <td>false</td> 1653 <td>any</td> 1654 <td>any</td> 1655 <td>Normal</td> 1656</tr> 1657<tr> 1658 <td>any</td> 1659 <td>Normal</td> 1660 <td>any</td> 1661 <td>Normal</td> 1662</tr> 1663<tr> 1664 <td>true</td> 1665 <td>ManualDuplex</td> 1666 <td>false</td> 1667 <td>Normal</td> 1668</tr> 1669<tr> 1670 <td>true</td> 1671 <td>ManualDuplex</td> 1672 <td>true</td> 1673 <td>Flipped</td> 1674</tr> 1675<tr> 1676 <td>true</td> 1677 <td>Rotated</td> 1678 <td>false</td> 1679 <td>Flipped</td> 1680</tr> 1681<tr> 1682 <td>true</td> 1683 <td>Rotated</td> 1684 <td>true</td> 1685 <td>Normal</td> 1686</tr> 1687<tr> 1688 <td>true or unspecified</td> 1689 <td>Flipped</td> 1690 <td>any</td> 1691 <td>Flipped</td> 1692</tr> 1693</tbody> 1694</table></div> 1695 1696<p>Example:</p> 1697 1698<pre class='command'> 1699<em>*% Rotate the back side images</em> 1700*cupsBackSide: Rotated 1701 1702<em>*% Don't swap the top and bottom margins for the back side</em> 1703*APDuplexRequiresFlippedMargin: false 1704</pre> 1705 1706<p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> 1707keyword.</p> 1708 1709<h3><a name='APHelpBook'>APHelpBook</a></h3> 1710 1711<p class='summary'>*APHelpBook: "bundle URL"</p> 1712 1713<p>This string keyword specifies the Apple help book bundle to use when 1714looking up IPP reason codes for this printer driver. The 1715<a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword maps 1716"help" URIs to this file.</p> 1717 1718<p>Example:</p> 1719 1720<pre class='command'> 1721*APHelpBook: "file:///Library/Printers/vendor/Help.bundle" 1722</pre> 1723 1724<h3><span class='info'>macOS 10.6</span><a name='APICADriver'>APICADriver</a></h3> 1725 1726<p class='summary'>*APICADriver: boolean</p> 1727 1728<p>This keyword specifies whether the device has a matching Image Capture 1729Architecture (ICA) driver for scanning. The default is <tt>False</tt>.</p> 1730 1731<p>Examples:</p> 1732 1733<pre class='command'> 1734*APICADriver: True 1735*APScanAppBundleID: "com.apple.ImageCaptureApp" 1736</pre> 1737 1738<h3><span class='info'>macOS 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3> 1739 1740<p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"</p> 1741 1742<p>This keyword defines the location of a printer icon file to use when 1743displaying the printer. The file must be in the Apple icon format.</p> 1744 1745<p>Examples:</p> 1746 1747<pre class='command'> 1748*% Apple icon file 1749*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns" 1750</pre> 1751 1752<h3><span class='info'>macOS 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3> 1753 1754<p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p> 1755 1756<p>This keyword defines an program that checks the ink/toner/marker levels 1757on a printer, returning an XML document with those levels. See the "InkTool" 1758example and 1759<a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple 1760Technical Note TN2144</a> for more information.</p> 1761 1762<p>Examples:</p> 1763 1764<pre class='command'> 1765*% Use a vendor monitoring program 1766*APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool" 1767</pre> 1768 1769<h3><span class='info'>macOS 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3> 1770 1771<p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p> 1772 1773<p>This keyword defines presets for multiple options that show up 1774in the print dialog of applications (such as iPhoto) that set the job 1775style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or 1776more pairs of PPD options and choices as well as providing key/value data for 1777the application. The following standard preset names are currently defined:</p> 1778 1779<ul> 1780 1781 <li><code>General_with_Paper_Auto-Detect</code>; Normal quality general printing with auto-detected media.</li> 1782 1783 <li><code>General_with_Paper_Auto-Detect_-_Draft</code>; Draft quality general printing with auto-detected media.</li> 1784 1785 <li><code>General_on_Plain_Paper</code>; Normal quality general printing on plain paper.</li> 1786 1787 <li><code>General_on_Plain_Paper_-_Draft</code>; Draft quality general printing on plain paper.</li> 1788 1789 <li><code>Photo_with_Paper_Auto-Detect</code>; Normal quality photo printing with auto-detected media.</li> 1790 1791 <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; High quality photo printing with auto-detected media.</li> 1792 1793 <li><code>Photo_on_Plain_Paper</code>; Normal quality photo printing on plain paper.</li> 1794 1795 <li><code>Photo_on_Plain_Paper_-_Fine</code>; High quality photo printing on plain paper.</li> 1796 1797 <li><code>Photo_on_Photo_Paper</code>; Normal quality photo printing on glossy photo paper.</li> 1798 1799 <li><code>Photo_on_Photo_Paper_-_Fine</code>; High quality photo printing on glossy photo paper.</li> 1800 1801 <li><code>Photo_on_Matte_Paper</code>; Normal quality photo printing on matte paper.</li> 1802 1803 <li><code>Photo_on_Matte_Paper_-_Fine</code>; High quality photo printing on matte paper.</li> 1804 1805</ul> 1806 1807<p>The value string consists of pairs of keywords, either an option name and 1808choice (*MainKeyword OptionKeyword) or a preset identifier and value 1809(com.apple.print.preset.foo value). The following preset identifiers are currently used:</p> 1810 1811<ul> 1812 1813 <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> 1814 1815 <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> 1816 1817 <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> 1818 1819 <li><code>com.apple.print.preset.quality</code>; specifies the overall print quality selected by this preset - "low" (draft), "mid" (normal), or "high".</li> 1820 1821</ul> 1822 1823<p>Presets, like options, can also be localized in multiple languages.</p> 1824 1825<p>Examples:</p> 1826 1827<pre class='command'> 1828*APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: " 1829 *MediaType Glossy 1830 *ColorModel RGB 1831 *Resolution 300dpi 1832 com.apple.print.preset.graphicsType Photo 1833 com.apple.print.preset.quality mid 1834 com.apple.print.preset.media-front-coating glossy" 1835*End 1836*fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: "" 1837</pre> 1838 1839<h3><span class='info'>macOS 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3> 1840 1841<p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p> 1842 1843<p>This keyword defines a GUI application that can be used to do printer 1844maintenance functions such as cleaning the print head(s). See ... for more 1845information.</p> 1846 1847<p>Examples:</p> 1848 1849<pre class='command'> 1850*% Define the printer utility application 1851*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app" 1852</pre> 1853 1854<h3><span class='info'>macOS 10.6</span><a name='APScannerOnly'>APScannerOnly</a></h3> 1855 1856<p class='summary'>*APScannerOnly: boolean</p> 1857 1858<p>This keyword specifies whether the device has scanning but no printing 1859capabilities. The default is <tt>False</tt>.</p> 1860 1861<p>Examples:</p> 1862 1863<pre class='command'> 1864*APICADriver: True 1865*APScannerOnly: True 1866</pre> 1867 1868<h3><span class='info'>macOS 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3> 1869 1870<p class='summary'>*APScanAppBundleID: "bundle ID"</p> 1871 1872<p>This keyword defines the application to use when scanning pages from 1873the device.</p> 1874 1875<p>Examples:</p> 1876 1877<pre class='command'> 1878*APICADriver: True 1879*APScanAppBundleID: "com.apple.ImageCaptureApp" 1880</pre> 1881 1882 1883<h2 class='title'><a name='HISTORY'>Change History</a></h2> 1884 1885<h3>Changes in CUPS 1.7</h3> 1886 1887<ul> 1888 1889 <li>Added <a href="#cupsJobAccountId"><tt>cupsJobAccountId</tt></a>, 1890 <a href="#cupsJobAccountingUserId"><tt>cupsJobAccountingUserId</tt></a>, 1891 <a href="#cupsJobPassword"><tt>cupsJobPassword</tt></a>, 1892 <a href="#cupsMandatory"><tt>cupsMandatory</tt></a> keywords.</li> 1893 1894</ul> 1895 1896 1897<h3>Changes in CUPS 1.6</h3> 1898 1899<ul> 1900 1901 <li>Added <a href="#cupsPageSizeCategory"><tt>cupsPageSizeCategory</tt></a> keyword (originally defined in CUPS 1.4).</li> 1902 1903 <li>Added <a href="#cupsMaxCopies"><tt>cupsMaxCopies</tt></a> keyword.</li> 1904 1905 <li>Documented <a href="#JCLToPDFInterpreter"><tt>JCLToPDFInterpreter</tt></a> keyword.</li> 1906 1907 <li>Updated <a href="#cupsVersion"><tt>cupsVersion</tt></a> keyword documentation to list all current releases of CUPS.</li> 1908 1909</ul> 1910 1911 1912<h3>Changes in CUPS 1.5</h3> 1913 1914<ul> 1915 1916 <li>Changes all instances of PPD attributes to PPD keywords, to be consistent with the parent specification from Adobe.</li> 1917 1918</ul> 1919 1920 1921<h3>Changes in CUPS 1.4.5</h3> 1922 1923<ul> 1924 1925 <li>Added <a href='#cupsPrintQuality'><tt>cupsPrintQuality</tt></a> UI keyword.</li> 1926 1927 <li>Added new properties and values for the <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a> keyword.</li> 1928 1929</ul> 1930 1931 1932<h3>Changes in CUPS 1.4</h3> 1933 1934<ul> 1935 1936 <li>Added <a href='#APICADriver'><tt>APICADriver</tt></a> 1937 keyword.</li> 1938 1939 <li>Added <a href='#cupsCommands'><tt>cupsCommands</tt></a> 1940 keyword.</li> 1941 1942 <li>Added <a href='#cupsMarkerName'><tt>cupsMarkerName</tt></a> 1943 keyword.</li> 1944 1945 <li>Added <a href='#cupsMarkerNotice'><tt>cupsMarkerNotice</tt></a> 1946 keyword.</li> 1947 1948 <li>Added <a href='#cupsPJLDisplay'><tt>cupsPJLDisplay</tt></a> 1949 keyword.</li> 1950 1951 <li>Added <a href='#cupsSNMPSupplies'><tt>cupsSNMPSupplies</tt></a> 1952 keyword.</li> 1953 1954 <li>Added <a href='#cupsUIResolver'><tt>cupsUIResolver</tt></a> and 1955 <a href='#cupsUIConstraints'><tt>cupsUIConstraints</tt></a> 1956 keywords.</li> 1957 1958 <li>Added 1959 <a href='#cupsMediaQualifier2'><tt>cupsMediaQualifier2</tt></a>, 1960 <a href='#cupsMediaQualifier3'><tt>cupsMediaQualifier3</tt></a>, 1961 <a href='#cupsMinSize'><tt>cupsMinSize</tt></a>, and 1962 <a href='#cupsMaxSize'><tt>cupsMaxSize</tt></a> keywords.</li> 1963 1964</ul> 1965 1966 1967<h3>Changes in CUPS 1.3.1</h3> 1968 1969<ul> 1970 1971 <li>Added missing macOS <tt>AP</tt> keywords.</li> 1972 1973 <li>Added section on auto-configuration including the 1974 <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt> 1975 keywords.</li> 1976 1977 <li>Minor reorganization.</li> 1978 1979</ul> 1980 1981 1982<h3>Changes in CUPS 1.3</h3> 1983 1984<ul> 1985 1986 <li>Added <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> and 1987 deprecated <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a>.</li> 1988 1989 <li>Added text URI information to 1990 <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> documentation.</li> 1991 1992 <li>Added <a href='#APPrinterPreset'><tt>APPrinterPreset</tt></a>, 1993 <a href='#cupsIPPFinishings'><tt>cupsIPPFinishings</tt></a>, and 1994 <a href='#cupsPreFilter'><tt>cupsPreFilter</tt></a> keywords.</li> 1995 1996 <li>Added discussion of custom option code, sample 1997 <tt>CustomPageSize</tt> code, and "do not use dict and put" note.</li> 1998 1999</ul> 2000 2001<h3>Changes in CUPS 1.2.8</h3> 2002 2003<ul> 2004 2005 <li>Added section on supported PostScript commands for raster 2006 drivers</li> 2007 2008</ul> 2009 2010<h3>Changes in CUPS 1.2</h3> 2011 2012<ul> 2013 2014 <li>Added globalization support keywords</li> 2015 2016 <li>Added custom option values support</li> 2017 2018 <li>Added <a href='#APHelpBook'><tt>APHelpBook</tt></a> keyword</li> 2019 2020 <li>Added <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a> 2021 keyword</li> 2022 2023 <li>Added <a href='#cupsICCProfile'><tt>cupsICCProfile</tt></a> keyword</li> 2024 2025 <li>Added <a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> keyword</li> 2026 2027 <li>Added <a href='#cupsLanguages'><tt>cupsLanguages</tt></a> keyword</li> 2028 2029 <li>Added <a href='#cupsPortMonitor'><tt>cupsPortMonitor</tt></a> keyword</li> 2030 2031 <li>Removed <tt>cupsProtocol</tt> keyword</li> 2032 2033</ul> 2034 2035<h3>Changes in CUPS 1.1</h3> 2036 2037<ul> 2038 2039 <li>Added <a href='#cupsFlipDuplex'><tt>cupsFlipDuplex</tt></a> keyword</li> 2040 2041 <li>Added <tt>cupsProtocol</tt> keyword</li> 2042 2043</ul> 2044
