1 <h2 class='title'><a name='BASICS'>The Basics</a></h2> 2 3 <P>The PPD compiler, <a href='man-ppdc.html'><code>ppdc(1)</code></a>, is a 4 simple command-line tool that takes a single <I>driver information file</I>, 5 which by convention uses the extension <VAR>.drv</VAR>, and produces one or more 6 PPD files that may be distributed with your printer drivers for use with CUPS. 7 For example, you would run the following command to create the English language 8 PPD files defined by the driver information file <VAR>mydrivers.drv</VAR>:</P> 9 10 <pre class='command'> 11 ppdc mydrivers.drv 12 </pre> 13 14 <P>The PPD files are placed in a subdirectory called 15 <VAR>ppd</VAR>. The <TT>-d</TT> option is used to put the PPD 16 files in a different location, for example:</p> 17 18 <pre class='command'> 19 ppdc -d myppds mydrivers.drv 20 </pre> 21 22 <P>places the PPD files in a subdirectory named 23 <VAR>myppds</VAR>. Finally, use the <TT>-l</TT> option to 24 specify the language localization for the PPD files that are 25 created, for example:</P> 26 27 <pre class='command'> 28 ppdc -d myppds/de -l de mydrivers.drv 29 ppdc -d myppds/en -l en mydrivers.drv 30 ppdc -d myppds/es -l es mydrivers.drv 31 ppdc -d myppds/fr -l fr mydrivers.drv 32 ppdc -d myppds/it -l it mydrivers.drv 33 </pre> 34 35 <P>creates PPD files in German (de), English (en), Spanish (es), 36 French (fr), and Italian (it) in the corresponding 37 subdirectories. Specify multiple languages (separated by commas) to produce 38 "globalized" PPD files:</p> 39 40 <pre class='command'> 41 ppdc -d myppds -l de,en,es,fr,it mydrivers.drv 42 </pre> 43 44 45 <h2 class='title'><a name='DRV'>Driver Information Files</a></h2> 46 47 <P>The driver information files accepted by the PPD compiler are 48 plain text files that define the various attributes and options 49 that are included in the PPD files that are generated. A driver 50 information file can define the information for one or more printers and 51 their corresponding PPD files.</P> 52 53 <p class='example'><a name="LISTING1">Listing 1: "examples/minimum.drv"</a></p> 54 55 <pre class='example'> 56 <I>// Include standard font and media definitions</I> 57 <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> 58 <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> 59 60 <I>// List the fonts that are supported, in this case all standard fonts...</I> 61 <a href='ref-ppdcfile.html#Font'>Font</a> * 62 63 <I>// Manufacturer, model name, and version</I> 64 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" 65 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 66 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 67 68 <I>// Each filter provided by the driver...</I> 69 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo 70 71 <I>// Supported page sizes</I> 72 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter 73 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 74 75 <I>// Supported resolutions</I> 76 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 77 78 <I>// Specify the name of the PPD file we want to generate...</I> 79 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 80 </pre> 81 82 83 <h3><a name='SIMPLE'>A Simple Example</a></h3> 84 85 <P>The example in <A HREF="#LISTING1">Listing 1</A> shows a driver information 86 file which defines the minimum required attributes to provide a valid PPD file. 87 The first part of the file includes standard definition files for fonts and 88 media sizes:</P> 89 90 <pre class='example'> 91 <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> 92 <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> 93 </pre> 94 95 <P>The <TT>#include</TT> directive works just like the C/C++ include directive; 96 files included using the angle brackets (<TT><filename></TT>) are found 97 in any of the standard include directories and files included using quotes 98 (<TT>"filename"</TT>) are found in the same directory as the source or include 99 file. The <TT><font.defs></TT> include file defines the standard fonts 100 which are included with GPL Ghostscript and the Apple PDF RIP, while the 101 <TT><media.defs></TT> include file defines the standard media sizes 102 listed in Appendix B of the Adobe PostScript Printer Description File Format 103 Specification.</P> 104 105 <P>CUPS provides several other standard include files:</P> 106 107 <UL> 108 109 <LI><TT><epson.h></TT> - Defines all of the rastertoepson driver 110 constants.</LI> 111 112 <LI><TT><escp.h></TT> - Defines all of the rastertoescpx driver 113 constants.</LI> 114 115 <LI><TT><hp.h></TT> - Defines all of the rastertohp driver 116 constants.</LI> 117 118 <LI><TT><label.h></TT> - Defines all of the rastertolabel driver 119 constants.</LI> 120 121 <LI><TT><pcl.h></TT> - Defines all of the rastertopclx driver 122 constants.</LI> 123 124 <LI><TT><raster.defs></TT> - Defines all of the CUPS raster format 125 constants.</LI> 126 127 </UL> 128 129 <P>Next we list all of the fonts that are available in the driver; for CUPS 130 raster drivers, the following line is all that is usually supplied:</P> 131 132 <pre class='example'> 133 <a href='ref-ppdcfile.html#Font'>Font</a> * 134 </pre> 135 136 <P>The <TT>Font</TT> directive specifies the name of a single font or the 137 asterisk to specify all fonts. For example, you would use the following line to 138 define an additional bar code font that you are supplying with your printer 139 driver:</P> 140 141 <pre class='example'> 142 <I>// name encoding version charset status</I> 143 <a href='ref-ppdcfile.html#Font'>Font</a> Barcode-Foo Special "(1.0)" Special ROM 144 </pre> 145 146 <P>The name of the font is <TT>Barcode-Foo</TT>. Since it is not a standard 147 text font, the encoding and charset name <TT>Special</TT> is used. The version 148 number is <TT>1.0</TT> and the status (where the font is located) is 149 <TT>ROM</TT> to indicate that the font does not need to be embedded in 150 documents that use the font for this printer.</P> 151 152 <P>Third comes the manufacturer, model name, and version number information 153 strings:</P> 154 155 <pre class='example'> 156 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" 157 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 158 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 159 </pre> 160 161 <P>These strings are used when the user (or auto-configuration program) selects 162 the printer driver for a newly connected device.</p> 163 164 <P>The list of filters comes after the information strings; for the example in 165 <A HREF="#LISTING1">Listing 1</A>, we have a single filter that takes CUPS 166 raster data:</P> 167 168 <pre class='example'> 169 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo 170 </pre> 171 172 <P>Each filter specified in the driver information file is the equivalent of a 173 printer driver for that format; if a user submits a print job in a different 174 format, CUPS figures out the sequence of commands that will produce a supported 175 format for the least relative cost.</P> 176 177 <P>Once we have defined the driver information we specify the supported options. 178 For the example driver we support a single resolution of 600 dots per inch and 179 two media sizes, A4 and Letter:</P> 180 181 <pre class='example'> 182 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter 183 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 184 185 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 186 </pre> 187 188 <P>The asterisk in front of the <TT>MediaSize</TT> and <TT>Resolution</TT> 189 directives specify that those option choices are the default. The 190 <TT>MediaSize</TT> directive is followed by a media size name which is normally 191 defined in the <TT><media.defs></TT> file and corresponds to a standard 192 Adobe media size name. If the default media size is <TT>Letter</TT>, the PPD 193 compiler will override it to be <TT>A4</TT> for non-English localizations for 194 you automatically.</P> 195 196 <P>The <TT>Resolution</TT> directive accepts several values after it as 197 follows:</P> 198 199 <OL> 200 201 <LI>Colorspace for this resolution, if any. In the example file, the 202 colorspace <TT>k</TT> is used which corresponds to black. For printer 203 drivers that support color printing, this field is usually specified as 204 "-" for "no change".</LI> 205 206 <LI>Bits per color. In the example file, we define 8 bits per color, for 207 a continuous-tone grayscale output. All versions of CUPS support 1 and 208 8 bits per color. CUPS 1.2 and higher (macOS 10.5 and higher) also 209 supports 16 bits per color.</LI> 210 211 <LI>Rows per band. In the example file, we define 0 rows per band to 212 indicate that our printer driver does not process the page in 213 bands.</LI> 214 215 <LI>Row feed. In the example, we define the feed value to be 0 to 216 indicate that our printer driver does not interleave the output.</LI> 217 218 <LI>Row step. In the example, we define the step value to be 0 to 219 indicate that our printer driver does not interleave the output. This 220 value normally indicates the spacing between the nozzles of an inkjet 221 printer - when combined with the previous two values, it informs the 222 driver how to stagger the output on the page to produce interleaved 223 lines on the page for higher-resolution output.</LI> 224 225 <LI>Choice name and text. In the example, we define the choice name and 226 text to be <TT>"600dpi/600 DPI"</TT>. The name and text are separated by 227 slash (<TT>/</TT>) character; if no text is specified, then the name is 228 used as the text. The PPD compiler parses the name to determine the 229 actual resolution; the name can be of the form 230 <TT><I>RESOLUTION</I>dpi</TT> for resolutions that are equal 231 horizontally and vertically or <TT><I>HRES</I>x<I>VRES</I>dpi</TT> for 232 isometric resolutions. Only integer resolution values are supported, so 233 a resolution name of <TT>300dpi</TT> is valid while <TT>300.1dpi</TT> is 234 not.</LI> 235 236 </OL> 237 238 <P>Finally, the <TT>PCFileName</TT> directive specifies that the named PPD file 239 should be written for the current driver definitions:</P> 240 241 <pre class='example'> 242 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 243 </pre> 244 245 <P>The filename follows the directive and <I>must</I> conform to the Adobe 246 filename requirements in the Adobe Postscript Printer Description File Format 247 Specification. Specifically, the filename may not exceed 8 characters followed 248 by the extension <VAR>.ppd</VAR>. The <TT>FileName</TT> directive can be used to 249 specify longer filenames:</P> 250 251 <pre class='example'> 252 <a href='ref-ppdcfile.html#FileName'>FileName</a> "FooJet 2000" 253 </pre> 254 255 256 <h3><a name='GROUPING'>Grouping and Inheritance</a></h3> 257 258 <P>The previous example created a single PPD file. Driver information files can 259 also define multiple printers by using the PPD compiler grouping functionality. 260 Directives are grouped using the curly braces (<TT>{</TT> and <TT>}</TT>) and 261 every group that uses the <TT>PCFileName</TT> or <TT>FileName</TT> directives 262 produces a PPD file with that name. <A HREF="#LISTING2">Listing 2</A> shows a 263 variation of the original example that uses two groups to define two printers 264 that share the same printer driver filter but provide two different resolution 265 options.</P> 266 267 <p class='example'><a name="LISTING2">Listing 2: "examples/grouping.drv"</a></p> 268 269 <pre class='example'> 270 271 <I>// Include standard font and media definitions</I> 272 <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> 273 <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> 274 275 <I>// List the fonts that are supported, in this case all standard fonts...</I> 276 <a href='ref-ppdcfile.html#Font'>Font</a> * 277 278 <I>// Manufacturer and version</I> 279 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" 280 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 281 282 <I>// Each filter provided by the driver...</I> 283 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo 284 285 <I>// Supported page sizes</I> 286 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter 287 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 288 289 { 290 <I>// Supported resolutions</I> 291 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 292 293 <I>// Specify the model name and filename...</I> 294 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 295 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 296 } 297 298 { 299 <I>// Supported resolutions</I> 300 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "1200dpi/1200 DPI" 301 302 <I>// Specify the model name and filename...</I> 303 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001" 304 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojt2k1.ppd" 305 } 306 </pre> 307 308 <P>The second example is essentially the same as the first, except that each 309 printer model is defined inside of a pair of curly braces. For example, the 310 first printer is defined using:</P> 311 312 <pre class='example'> 313 { 314 // Supported resolutions 315 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 316 317 // Specify the model name and filename... 318 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 319 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 320 } 321 </pre> 322 323 <P>The printer <I>inherits</I> all of the definitions from the parent group (the 324 top part of the file) and adds the additional definitions inside the curly 325 braces for that printer driver. When we define the second group, it also 326 inherits the same definitions from the parent group but <I>none</I> of the 327 definitions from the first driver. Groups can be nested to any number of levels 328 to support variations of similar models without duplication of information.</P> 329 330 331 <h3><a name='COLOR'>Color Support</a></h3> 332 333 <P>For printer drivers that support color printing, the 334 <TT>ColorDevice</TT> and <TT>ColorModel</TT> directives should be 335 used to tell the printing system that color output is desired 336 and in what formats. <A HREF="#LISTING3">Listing 3</A> shows a 337 variation of the previous example which includes a color printer 338 that supports printing at 300 and 600 DPI.</P> 339 340 <P>The key changes are the addition of the <TT>ColorDevice</TT> 341 directive:</P> 342 343 <pre class='example'> 344 <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true 345 </pre> 346 347 <P>which tells the printing system that the printer supports 348 color printing, and the <TT>ColorModel</TT> directives:</P> 349 350 <pre class='example'> 351 <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0 352 *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0 353 </pre> 354 355 <P>which tell the printing system which colorspaces are supported by the printer 356 driver for color printing. Each of the <TT>ColorModel</TT> directives is 357 followed by the option name and text (<TT>Gray/Grayscale</TT> and 358 <TT>RGB/Color</TT>), the colorspace name (<TT>w</TT> and <TT>rgb</TT>), the 359 color organization (<TT>chunky</TT>), and the compression mode number 360 (<TT>0</TT>) to be passed to the driver. The option name can be any of the 361 standard Adobe <TT>ColorModel</TT> names:</P> 362 363 <UL> 364 365 <LI><TT>Gray</TT> - Grayscale output. 366 367 <LI><TT>RGB</TT> - Color output, typically using the RGB 368 colorspace, but without a separate black channel. 369 370 <LI><TT>CMYK</TT> - Color output with a separate black 371 channel. 372 373 </UL> 374 375 <P>Custom names can be used, however it is recommended that you use your vendor 376 prefix for any custom names, for example "fooName".</P> 377 378 <P>The colorspace name can be any of the following universally supported 379 colorspaces:</P> 380 381 <UL> 382 <LI><TT>w</TT> - Luminance</LI> 383 384 <LI><TT>rgb</TT> - Red, green, blue</LI> 385 386 <LI><TT>k</TT> - Black</LI> 387 388 <LI><TT>cmy</TT> - Cyan, magenta, yellow</LI> 389 390 <LI><TT>cmyk</TT> - Cyan, magenta, yellow, black</LI> 391 392 </UL> 393 394 <P>The color organization can be any of the following values:</P> 395 396 <UL> 397 398 <LI><TT>chunky</TT> - Color values are passed together on a line 399 as RGB RGB RGB RGB</LI> 400 401 <LI><TT>banded</TT> - Color values are passed separately 402 on a line as RRRR GGGG BBBB; not supported by the Apple 403 RIP filters</LI> 404 405 <LI><TT>planar</TT> - Color values are passed separately 406 on a page as RRRR RRRR RRRR ... GGGG GGGG GGGG ... BBBB 407 BBBB BBBB; not supported by the Apple RIP filters</LI> 408 409 </UL> 410 411 <P>The compression mode value is passed to the driver in the 412 <TT>cupsCompression</TT> attribute. It is traditionally used to select an 413 appropriate compression mode for the color model but can be used for any 414 purpose, such as specifying a photo mode vs. standard mode.</P> 415 416 <p class='example'><a name="LISTING3">Listing 3: "examples/color.drv"</a></p> 417 418 <pre class='example'> 419 420 <I>// Include standard font and media definitions</I> 421 <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> 422 <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> 423 424 <I>// List the fonts that are supported, in this case all standard fonts...</I> 425 <a href='ref-ppdcfile.html#Font'>Font</a> * 426 427 <I>// Manufacturer and version</I> 428 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" 429 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 430 431 <I>// Each filter provided by the driver...</I> 432 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo 433 434 <I>// Supported page sizes</I> 435 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter 436 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 437 438 { 439 <I>// Supported resolutions</I> 440 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 441 442 <I>// Specify the model name and filename...</I> 443 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 444 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 445 } 446 447 { 448 <I>// Supports color printing</I> 449 <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true 450 451 <I>// Supported colorspaces</I> 452 <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0 453 *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0 454 455 <I>// Supported resolutions</I> 456 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "300dpi/300 DPI" 457 <a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI" 458 459 <I>// Specify the model name and filename...</I> 460 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet Color" 461 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojetco.ppd" 462 } 463 </pre> 464 465 466 <h3><a name='OPTIONS'>Defining Custom Options and Option Groups</a></h3> 467 468 <P>The <TT>Group</TT>, <TT>Option</TT>, and <TT>Choice</TT> 469 directives are used to define or select a group, option, or 470 choice. <A HREF="#LISTING4">Listing 4</A> shows a variation of 471 the first example that provides two custom options in a group 472 named "Footasm".</P> 473 474 <p class='example'><a name="LISTING4">Listing 4: "examples/custom.drv"</a></p> 475 476 <pre class='example'> 477 478 <I>// Include standard font and media definitions</I> 479 <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> 480 <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> 481 482 <I>// List the fonts that are supported, in this case all standard fonts...</I> 483 <a href='ref-ppdcfile.html#Font'>Font</a> * 484 485 <I>// Manufacturer, model name, and version</I> 486 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" 487 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 488 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 489 490 <I>// Each filter provided by the driver...</I> 491 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo 492 493 <I>// Supported page sizes</I> 494 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter 495 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 496 497 <I>// Supported resolutions</I> 498 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 499 500 <I>// Option Group</I> 501 <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm" 502 503 <I>// Boolean option</I> 504 <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10 505 *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "<</cupsCompression 1>>setpagedevice" 506 <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "<</cupsCompression 0>>setpagedevice" 507 508 <I>// Multiple choice option</I> 509 <a href='ref-ppdcfile.html#Option'>Option</a> "fooOutputType/Output Quality" PickOne AnySetup 10 510 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "Auto/Automatic Selection" 511 "<</OutputType(Auto)>>setpagedevice"" 512 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Text/Optimize for Text" 513 "<</OutputType(Text)>>setpagedevice"" 514 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Graph/Optimize for Graphics" 515 "<</OutputType(Graph)>>setpagedevice"" 516 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Photo/Optimize for Photos" 517 "<</OutputType(Photo)>>setpagedevice"" 518 519 <I>// Specify the name of the PPD file we want to generate...</I> 520 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 521 </pre> 522 523 <P>The custom group is introduced by the <TT>Group</TT> 524 directive which is followed by the name and optionally text for 525 the user:</P> 526 527 <pre class='example'> 528 <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm/Footastic Options" 529 </pre> 530 531 <P>The group name must conform to the PPD specification and 532 cannot exceed 40 characters in length. If you specify user text, 533 it cannot exceed 80 characters in length. The groups 534 <TT>General</TT>, <TT>Extra</TT>, and 535 <TT>InstallableOptions</TT> are predefined by CUPS; the general 536 and extra groups are filled by the UI options defined by the PPD 537 specification. The <TT>InstallableOptions</TT> group is reserved 538 for options that define whether accessories for the printer 539 (duplexer unit, finisher, stapler, etc.) are installed.</P> 540 541 <P>Once the group is specified, the <TT>Option</TT> directive is 542 used to introduce a new option:</P> 543 544 <pre class='example'> 545 <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10 546 </pre> 547 548 <P>The directive is followed by the name of the option and any 549 optional user text, the option type, the PostScript document group, and 550 the sort order number. The option name must conform to the PPD specification 551 and cannot exceed 40 characters in length. If you specify user text, it 552 cannot exceed 80 characters in length.</P> 553 554 <P>The option type can be <TT>Boolean</TT> for true/false 555 selections, <TT>PickOne</TT> for picking one of many choices, or 556 <TT>PickMany</TT> for picking zero or more choices. Boolean 557 options can have at most two choices with the names 558 <TT>False</TT> and <TT>True</TT>. Pick options can have any 559 number of choices, although for Windows compatibility reasons 560 the number of choices should not exceed 255.</P> 561 562 <P>The PostScript document group is typically <TT>AnySetup</TT>, 563 meaning that the option can be introduced at any point in the 564 PostScript document. Other values include <TT>PageSetup</TT> to 565 include the option before each page and <TT>DocumentSetup</TT> 566 to include the option once at the beginning of the document.</P> 567 568 <P>The sort order number is used to sort the printer commands 569 associated with each option choice within the PostScript 570 document. This allows you to setup certain options before others 571 as required by the printer. For most CUPS raster printer 572 drivers, the value <TT>10</TT> can be used for all options.</P> 573 574 <P>Once the option is specified, each option choice can be 575 listed using the <TT>Choice</TT> directive:</P> 576 577 <pre class='example'> 578 *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "<</cupsCompression 1>>setpagedevice" 579 <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "<</cupsCompression 0>>setpagedevice" 580 </pre> 581 582 <P>The directive is followed by the choice name and optionally 583 user text, and the PostScript commands that should be inserted 584 when printing a file to this printer. The option name must 585 conform to the PPD specification and cannot exceed 40 characters 586 in length. If you specify user text, it cannot exceed 80 587 characters in length.</P> 588 589 <P>The PostScript commands are also interpreted by any RIP 590 filters, so these commands typically must be present for all 591 option choices. Most commands take the form:</P> 592 593 <pre class='example'> 594 <</name value>>setpagedevice 595 </pre> 596 597 <P>where <TT>name</TT> is the name of the PostScript page device 598 attribute and <TT>value</TT> is the numeric or string value for 599 that attribute.</P> 600 601 602 <h3><a name='DEFINE'>Defining Constants</a></h3> 603 604 <P>Sometimes you will want to define constants for your drivers 605 so that you can share values in different groups within the same 606 driver information file, or to share values between different 607 driver information files using the <TT>#include</TT> directive. 608 The <TT>#define</TT> directive is used to define constants for 609 use in your printer definitions:</P> 610 611 <pre class='example'> 612 <a href='ref-ppdcfile.html#_define'>#define</a> NAME value 613 </pre> 614 615 <P>The <TT>NAME</TT> is any sequence of letters, numbers, and 616 the underscore. The <TT>value</TT> is a number or string; if the 617 value contains spaces you must put double quotes around it, for 618 example:</P> 619 620 <pre class='example'> 621 <a href='ref-ppdcfile.html#_define'>#define</a> FOO "My String Value" 622 </pre> 623 624 <P>Constants can also be defined on the command-line using the <tt>-D</tt> 625 option:</P> 626 627 <pre class='command'> 628 ppdc -DNAME="value" filename.drv 629 </pre> 630 631 <P>Once defined, you use the notation <TT>$NAME</TT> to substitute the value of 632 the constant in the file, for example:</P> 633 634 <pre class='example'> 635 <a href='ref-ppdcfile.html#_define'>#define</a> MANUFACTURER "Foo" 636 <a href='ref-ppdcfile.html#_define'>#define</a> FOO_600 0 637 <a href='ref-ppdcfile.html#_define'>#define</a> FOO_1200 1 638 639 { 640 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER" 641 <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_600 642 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 643 ... 644 } 645 646 { 647 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER" 648 <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_1200 649 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001" 650 ... 651 } 652 </pre> 653 654 <P>Numeric constants can be bitwise OR'd together by placing the constants 655 inside parenthesis, for example:</P> 656 657 <pre class='example'> 658 <I>// ModelNumber capability bits</I> 659 <a href='ref-ppdcfile.html#_define'>#define</a> DUPLEX 1 660 <a href='ref-ppdcfile.html#_define'>#define</a> COLOR 2 661 662 ... 663 664 { 665 <I>// Define a model number specifying the capabilities of the printer...</I> 666 <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($DUPLEX $COLOR) 667 ... 668 } 669 </pre> 670 671 672 <h3><a name='CONDITIONAL'>Conditional Statements</a></h3> 673 674 <p>The PPD compiler supports conditional compilation using the <tt>#if</tt>, 675 <tt>#elif</tt>, <tt>#else</tt>, and <tt>#endif</tt> directives. The <tt>#if</tt> 676 and <tt>#elif</tt> directives are followed by a constant name or an expression. 677 For example, to include a group of options when "ADVANCED" is defined:</p> 678 679 <pre class='example'> 680 <a href='ref-ppdcfile.html#_if'>#if</a> ADVANCED 681 <a href='ref-ppdcfile.html#Group'>Group</a> "Advanced/Advanced Options" 682 <a href='ref-ppdcfile.html#Option'>Option</a> "fooCyanAdjust/Cyan Adjustment" 683 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" 684 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" 685 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" 686 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" 687 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" 688 <a href='ref-ppdcfile.html#Option'>Option</a> "fooMagentaAdjust/Magenta Adjustment" 689 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" 690 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" 691 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" 692 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" 693 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" 694 <a href='ref-ppdcfile.html#Option'>Option</a> "fooYellowAdjust/Yellow Adjustment" 695 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" 696 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" 697 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" 698 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" 699 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" 700 <a href='ref-ppdcfile.html#Option'>Option</a> "fooBlackAdjust/Black Adjustment" 701 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" 702 <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" 703 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" 704 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" 705 <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" 706 <a href='ref-ppdcfile.html#_endif'>#endif</a> 707 </pre> 708 709 710 <h3><a name='CONSTRAINTS'>Defining Constraints</a></h3> 711 712 <P>Constraints are strings that are used to specify that one or more option 713 choices are incompatible, for example two-sided printing on transparency media. 714 Constraints are also used to prevent the use of uninstalled features such as the 715 duplexer unit, additional media trays, and so forth.</P> 716 717 <P>The <TT>UIConstraints</TT> directive is used to specify a constraint that is 718 placed in the PPD file. The directive is followed by a string using one of the 719 following formats:</P> 720 721 <pre class='example'> 722 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2" 723 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2" 724 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2 Choice2" 725 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2 Choice2" 726 </pre> 727 728 <P>Each option name is preceded by the asterisk (<TT>*</TT>). If no choice is 729 given for an option, then all choices <I>except</I> <TT>False</TT> and 730 <TT>None</TT> will conflict with the other option and choice(s). Since the PPD 731 compiler automatically adds reciprocal constraints (option A conflicts with 732 option B, so therefore option B conflicts with option A), you need only specify 733 the constraint once.</P> 734 735 <p class='example'><a name="LISTING5">Listing 5: "examples/constraint.drv"</a></p> 736 737 <pre class='example'> 738 739 <I>// Include standard font and media definitions</I> 740 <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> 741 <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> 742 743 <I>// List the fonts that are supported, in this case all standard fonts...</I> 744 <a href='ref-ppdcfile.html#Font'>Font</a> * 745 746 <I>// Manufacturer, model name, and version</I> 747 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" 748 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" 749 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 750 751 <I>// Each filter provided by the driver...</I> 752 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo 753 754 <I>// Supported page sizes</I> 755 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter 756 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 757 758 <I>// Supported resolutions</I> 759 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" 760 761 <I>// Installable Option Group</I> 762 <a href='ref-ppdcfile.html#Group'>Group</a> "InstallableOptions/Options Installed" 763 764 <I>// Duplexing unit option</I> 765 <a href='ref-ppdcfile.html#Option'>Option</a> "OptionDuplexer/Duplexing Unit" Boolean AnySetup 10 766 <a href='ref-ppdcfile.html#Choice'>Choice</a> True/Installed "" 767 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "False/Not Installed" "" 768 769 <I>// General Option Group</I> 770 <a href='ref-ppdcfile.html#Group'>Group</a> General 771 772 <I>// Duplexing option</I> 773 <a href='ref-ppdcfile.html#Option'>Option</a> "Duplex/Two-Sided Printing" PickOne AnySetup 10 774 *<a href='ref-ppdcfile.html#Choice'>Choice</a> "None/No" "<</Duplex false>>setpagedevice"" 775 <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexNoTumble/Long Edge Binding" 776 "<</Duplex true/Tumble false>>setpagedevice"" 777 <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexTumble/Short Edge Binding" 778 "<</Duplex true/Tumble true>>setpagedevice"" 779 780 <I>// Only allow duplexing if the duplexer is installed</I> 781 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False" 782 783 <I>// Specify the name of the PPD file we want to generate...</I> 784 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" 785 </pre> 786 787 <P><A HREF="#LISTING5">Listing 5</A> shows a variation of the first example with 788 an added <TT>Duplex</TT> option and installable option for the duplexer, 789 <TT>OptionDuplex</TT>. A constraint is added at the end to specify that any 790 choice of the <TT>Duplex</TT> option that is not <TT>None</TT> is incompatible 791 with the "Duplexer Installed" option set to "Not Installed" 792 (<TT>False</TT>):</P> 793 794 <pre class='example'> 795 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False" 796 </pre> 797 798 <h4>Enhanced Constraints</h4> 799 800 <p>CUPS 1.4 supports constraints between 2 or more options using the 801 <TT>Attribute</TT> directive. <TT>cupsUIConstraints</TT> attributes define 802 the constraints, while <TT>cupsUIResolver</TT> attributes define option changes 803 to resolve constraints. For example, we can specify the previous duplex 804 constraint with a resolver that turns off duplexing with the following two 805 lines:</p> 806 807 <pre class='example'> 808 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIConstraints DuplexOff "*Duplex *OptionDuplexer False" 809 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIResolver DuplexOff "*Duplex None" 810 </pre> 811 812 <h2 class='title'><a name='LOCALIZATION'>Localization</a></h2> 813 814 <p>The PPD compiler provides localization of PPD files in different languages 815 through <i>message catalog</i> files in the GNU gettext or Apple .strings 816 formats. Each user text string and several key PPD attribute values such as 817 <tt>LanguageVersion</tt> and <tt>LanguageEncoding</tt> are looked up in the 818 corresponding message catalog and the translated text is substituted in the 819 generated PPD files. One message catalog file can be used by multiple driver 820 information files, and each file contains a single language translation.</p> 821 822 <h3><a name='PPDPO'>The ppdpo Utility</a></h3> 823 824 <p>While CUPS includes localizations of all standard media sizes and options in 825 several languages, your driver information files may provide their own media 826 sizes and options that need to be localized. CUPS provides a utility program to 827 aid in the localization of drivers called <a 828 href='man-ppdpo.html'><tt>ppdpo(1)</tt></a>. The <tt>ppdpo</tt> program creates 829 or updates a message catalog file based upon one or more driver information 830 files. New messages are added with the word "TRANSLATE" added to the front of 831 the translation string to make locating new strings for translation easier. The 832 program accepts the message catalog filename and one or more driver information 833 files.</p> 834 835 <p>For example, run the following command to create a new German message catalog 836 called <var>de.po</var> for all of the driver information files in the current 837 directory:</p> 838 839 <pre class='command'> 840 ppdpo -o de.po *.drv 841 </pre> 842 843 <p>If the file <var>de.po</var> already exists, <tt>ppdpo</tt> will update the 844 contents of the file with any new messages that need to be translated. To create 845 an Apple .strings file instead, specify the output filename with a .strings 846 extension, for example:</p> 847 848 <pre class='command'> 849 ppdpo -o de.strings *.drv 850 </pre> 851 852 <h3><a name='PPDC_CATALOG'>Using Message Catalogs with the PPD Compiler</a></h3> 853 854 <p>Once you have created a message catalog, use the <a 855 href='ref-ppdcfile.html#_po'><tt>#po</tt></a> directive to declare it in each 856 driver information file. For example, to declare the German message catalog for 857 a driver use:</p> 858 859 <pre class='example'> 860 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po" // German 861 </pre> 862 863 <p>In fact, you can use the <tt>#po</tt> directive as many times as needed:</p> 864 865 <pre class='example'> 866 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po" // German 867 <a href='ref-ppdcfile.html#_po'>#po</a> es "es.po" // Spanish 868 <a href='ref-ppdcfile.html#_po'>#po</a> fr "fr.po" // French 869 <a href='ref-ppdcfile.html#_po'>#po</a> it "it.po" // Italian 870 <a href='ref-ppdcfile.html#_po'>#po</a> ja "ja.po" // Japanese 871 </pre> 872 873 <p>The filename ("de.po", etc.) can be relative to the location of the driver 874 information file or an absolute path. Once defined, the PPD compiler will 875 automatically generate a globalized PPD for every language declared in your 876 driver information file. To generate a single-language PPD file, simply use the 877 <tt>-l</tt> option to list the corresponding locale, for example:</p> 878 879 <pre class='command'> 880 ppdc -l de -d ppd/de mydrivers.drv 881 </pre> 882 883 <p>to generate German PPD files.</p> 884
