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 4simple command-line tool that takes a single <I>driver information file</I>, 5which by convention uses the extension <VAR>.drv</VAR>, and produces one or more 6PPD files that may be distributed with your printer drivers for use with CUPS. 7For example, you would run the following command to create the English language 8PPD files defined by the driver information file <VAR>mydrivers.drv</VAR>:</P> 9 10<pre class='command'> 11ppdc 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 16files in a different location, for example:</p> 17 18<pre class='command'> 19ppdc -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 24specify the language localization for the PPD files that are 25created, for example:</P> 26 27<pre class='command'> 28ppdc -d myppds/de -l de mydrivers.drv 29ppdc -d myppds/en -l en mydrivers.drv 30ppdc -d myppds/es -l es mydrivers.drv 31ppdc -d myppds/fr -l fr mydrivers.drv 32ppdc -d myppds/it -l it mydrivers.drv 33</pre> 34 35<P>creates PPD files in German (de), English (en), Spanish (es), 36French (fr), and Italian (it) in the corresponding 37subdirectories. Specify multiple languages (separated by commas) to produce 38"globalized" PPD files:</p> 39 40<pre class='command'> 41ppdc -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 48plain text files that define the various attributes and options 49that are included in the PPD files that are generated. A driver 50information file can define the information for one or more printers and 51their 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 86file which defines the minimum required attributes to provide a valid PPD file. 87The first part of the file includes standard definition files for fonts and 88media 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; 96files included using the angle brackets (<TT><filename></TT>) are found 97in 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 99file. The <TT><font.defs></TT> include file defines the standard fonts 100which are included with GPL Ghostscript and the Apple PDF RIP, while the 101<TT><media.defs></TT> include file defines the standard media sizes 102listed in Appendix B of the Adobe PostScript Printer Description File Format 103Specification.</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 130raster 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 137asterisk to specify all fonts. For example, you would use the following line to 138define an additional bar code font that you are supplying with your printer 139driver:</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 147text font, the encoding and charset name <TT>Special</TT> is used. The version 148number 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 150documents that use the font for this printer.</P> 151 152<P>Third comes the manufacturer, model name, and version number information 153strings:</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 162the 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 166raster 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 173printer driver for that format; if a user submits a print job in a different 174format, CUPS figures out the sequence of commands that will produce a supported 175format for the least relative cost.</P> 176 177<P>Once we have defined the driver information we specify the supported options. 178For the example driver we support a single resolution of 600 dots per inch and 179two 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> 189directives specify that those option choices are the default. The 190<TT>MediaSize</TT> directive is followed by a media size name which is normally 191defined in the <TT><media.defs></TT> file and corresponds to a standard 192Adobe media size name. If the default media size is <TT>Letter</TT>, the PPD 193compiler will override it to be <TT>A4</TT> for non-English localizations for 194you automatically.</P> 195 196<P>The <TT>Resolution</TT> directive accepts several values after it as 197follows:</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 239should 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 246filename requirements in the Adobe Postscript Printer Description File Format 247Specification. Specifically, the filename may not exceed 8 characters followed 248by the extension <VAR>.ppd</VAR>. The <TT>FileName</TT> directive can be used to 249specify 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 259also define multiple printers by using the PPD compiler grouping functionality. 260Directives are grouped using the curly braces (<TT>{</TT> and <TT>}</TT>) and 261every group that uses the <TT>PCFileName</TT> or <TT>FileName</TT> directives 262produces a PPD file with that name. <A HREF="#LISTING2">Listing 2</A> shows a 263variation of the original example that uses two groups to define two printers 264that share the same printer driver filter but provide two different resolution 265options.</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 309printer model is defined inside of a pair of curly braces. For example, the 310first 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 324top part of the file) and adds the additional definitions inside the curly 325braces for that printer driver. When we define the second group, it also 326inherits the same definitions from the parent group but <I>none</I> of the 327definitions from the first driver. Groups can be nested to any number of levels 328to 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 335used to tell the printing system that color output is desired 336and in what formats. <A HREF="#LISTING3">Listing 3</A> shows a 337variation of the previous example which includes a color printer 338that supports printing at 300 and 600 DPI.</P> 339 340<P>The key changes are the addition of the <TT>ColorDevice</TT> 341directive:</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 348color 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 356driver for color printing. Each of the <TT>ColorModel</TT> directives is 357followed 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 359color 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 361standard 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 376prefix for any custom names, for example "fooName".</P> 377 378<P>The colorspace name can be any of the following universally supported 379colorspaces:</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 413appropriate compression mode for the color model but can be used for any 414purpose, 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> 469directives are used to define or select a group, option, or 470choice. <A HREF="#LISTING4">Listing 4</A> shows a variation of 471the first example that provides two custom options in a group 472named "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> 524directive which is followed by the name and optionally text for 525the 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 532cannot exceed 40 characters in length. If you specify user text, 533it 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 536and extra groups are filled by the UI options defined by the PPD 537specification. The <TT>InstallableOptions</TT> group is reserved 538for 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 542used 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 549optional user text, the option type, the PostScript document group, and 550the sort order number. The option name must conform to the PPD specification 551and cannot exceed 40 characters in length. If you specify user text, it 552cannot exceed 80 characters in length.</P> 553 554<P>The option type can be <TT>Boolean</TT> for true/false 555selections, <TT>PickOne</TT> for picking one of many choices, or 556<TT>PickMany</TT> for picking zero or more choices. Boolean 557options can have at most two choices with the names 558<TT>False</TT> and <TT>True</TT>. Pick options can have any 559number of choices, although for Windows compatibility reasons 560the number of choices should not exceed 255.</P> 561 562<P>The PostScript document group is typically <TT>AnySetup</TT>, 563meaning that the option can be introduced at any point in the 564PostScript document. Other values include <TT>PageSetup</TT> to 565include the option before each page and <TT>DocumentSetup</TT> 566to 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 569associated with each option choice within the PostScript 570document. This allows you to setup certain options before others 571as required by the printer. For most CUPS raster printer 572drivers, 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 575listed 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 583user text, and the PostScript commands that should be inserted 584when printing a file to this printer. The option name must 585conform to the PPD specification and cannot exceed 40 characters 586in length. If you specify user text, it cannot exceed 80 587characters in length.</P> 588 589<P>The PostScript commands are also interpreted by any RIP 590filters, so these commands typically must be present for all 591option 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 598attribute and <TT>value</TT> is the numeric or string value for 599that 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 605so that you can share values in different groups within the same 606driver information file, or to share values between different 607driver information files using the <TT>#include</TT> directive. 608The <TT>#define</TT> directive is used to define constants for 609use 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 616the underscore. The <TT>value</TT> is a number or string; if the 617value contains spaces you must put double quotes around it, for 618example:</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> 625option:</P> 626 627<pre class='command'> 628ppdc -DNAME="value" filename.drv 629</pre> 630 631<P>Once defined, you use the notation <TT>$NAME</TT> to substitute the value of 632the 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 655inside 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> 676and <tt>#elif</tt> directives are followed by a constant name or an expression. 677For 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 713choices are incompatible, for example two-sided printing on transparency media. 714Constraints are also used to prevent the use of uninstalled features such as the 715duplexer unit, additional media trays, and so forth.</P> 716 717<P>The <TT>UIConstraints</TT> directive is used to specify a constraint that is 718placed in the PPD file. The directive is followed by a string using one of the 719following 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 729given 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 731compiler automatically adds reciprocal constraints (option A conflicts with 732option B, so therefore option B conflicts with option A), you need only specify 733the 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 788an 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 790choice of the <TT>Duplex</TT> option that is not <TT>None</TT> is incompatible 791with 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 802the constraints, while <TT>cupsUIResolver</TT> attributes define option changes 803to resolve constraints. For example, we can specify the previous duplex 804constraint with a resolver that turns off duplexing with the following two 805lines:</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 815through <i>message catalog</i> files in the GNU gettext or Apple .strings 816formats. 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 818corresponding message catalog and the translated text is substituted in the 819generated PPD files. One message catalog file can be used by multiple driver 820information 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 825several languages, your driver information files may provide their own media 826sizes and options that need to be localized. CUPS provides a utility program to 827aid in the localization of drivers called <a 828href='man-ppdpo.html'><tt>ppdpo(1)</tt></a>. The <tt>ppdpo</tt> program creates 829or updates a message catalog file based upon one or more driver information 830files. New messages are added with the word "TRANSLATE" added to the front of 831the translation string to make locating new strings for translation easier. The 832program accepts the message catalog filename and one or more driver information 833files.</p> 834 835<p>For example, run the following command to create a new German message catalog 836called <var>de.po</var> for all of the driver information files in the current 837directory:</p> 838 839<pre class='command'> 840ppdpo -o de.po *.drv 841</pre> 842 843<p>If the file <var>de.po</var> already exists, <tt>ppdpo</tt> will update the 844contents of the file with any new messages that need to be translated. To create 845an Apple .strings file instead, specify the output filename with a .strings 846extension, for example:</p> 847 848<pre class='command'> 849ppdpo -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 855href='ref-ppdcfile.html#_po'><tt>#po</tt></a> directive to declare it in each 856driver information file. For example, to declare the German message catalog for 857a 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 874information file or an absolute path. Once defined, the PPD compiler will 875automatically generate a globalized PPD for every language declared in your 876driver 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'> 880ppdc -l de -d ppd/de mydrivers.drv 881</pre> 882 883<p>to generate German PPD files.</p> 884