doc/help/ppd-compiler.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- SECTION: Programming -->
   4 <head>
   5         <title>Introduction to the PPD Compiler </title>
   6         <meta name="keywords" content="Programming">
   7         <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
   8         <meta name="creator" content="Mini-XML v2.7">
   9 <style type="text/css"><!--
  10 BODY {
  11   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  12 }
  13
  14 H1, H2, H3, H4, H5, H6, P, TD, TH {
  15   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  16 }
  17
  18 KBD {
  19   font-family: monaco, courier, monospace;
  20   font-weight: bold;
  21 }
  22
  23 PRE {
  24   font-family: monaco, courier, monospace;
  25 }
  26
  27 PRE.command {
  28   border: dotted thin #7f7f7f;
  29   margin-left: 36pt;
  30   padding: 10px;
  31 }
  32
  33 P.compact {
  34   margin: 0;
  35 }
  36
  37 P.example {
  38   font-style: italic;
  39   margin-left: 36pt;
  40 }
  41
  42 DL.man DD {
  43   margin-left: 5em;
  44 }
  45
  46 DL.man DT {
  47   margin-left: 0;
  48 }
  49
  50 PRE.man {
  51   margin: 0;
  52 }
  53
  54 PRE.example {
  55   background: #eeeeee;
  56   border: dotted thin #999999;
  57   margin-left: 36pt;
  58   padding: 10pt;
  59 }
  60
  61 PRE.command EM, PRE.example EM {
  62   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  63 }
  64
  65 P.command {
  66   font-family: monaco, courier, monospace;
  67   margin-left: 36pt;
  68 }
  69
  70 P.formula {
  71   font-style: italic;
  72   margin-left: 36pt;
  73 }
  74
  75 BLOCKQUOTE {
  76   background: #eeeeee;
  77   border: solid thin #999999;
  78   padding: 10pt;
  79 }
  80
  81 A IMG {
  82   border: none;
  83 }
  84
  85 A:link:hover IMG {
  86   background: #f0f0f0;
  87   border-radius: 10px;
  88   -moz-border-radius: 10px;
  89 }
  90
  91 A:link, A:visited {
  92   font-weight: inherit;
  93   text-decoration: none;
  94 }
  95
  96 A:link:hover, A:visited:hover, A:active {
  97   text-decoration: underline;
  98 }
  99
 100 SUB, SUP {
 101   font-size: 50%;
 102 }
 103
 104 TR.data, TD.data, TR.data TD {
 105   margin-top: 10pt;
 106   padding: 5pt;
 107   border-bottom: solid 1pt #999999;
 108 }
 109
 110 TR.data TH {
 111   border-bottom: solid 1pt #999999;
 112   padding-top: 10pt;
 113   padding-left: 5pt;
 114   text-align: left;
 115 }
 116
 117 DIV.table TABLE {
 118   border: solid thin #999999;
 119   border-collapse: collapse;
 120   border-spacing: 0;
 121   margin-left: auto;
 122   margin-right: auto;
 123 }
 124
 125 DIV.table CAPTION {
 126   caption-side: top;
 127   font-size: 120%;
 128   font-style: italic;
 129   font-weight: bold;
 130   margin-left: auto;
 131   margin-right: auto;
 132 }
 133
 134 DIV.table TABLE TD {
 135   border: solid thin #cccccc;
 136   padding-top: 5pt;
 137 }
 138
 139 DIV.table TABLE TH {
 140   background: #cccccc;
 141   border: none;
 142   border-bottom: solid thin #999999;
 143 }
 144
 145 DIV.figure TABLE {
 146   margin-left: auto;
 147   margin-right: auto;
 148 }
 149
 150 DIV.figure CAPTION {
 151   caption-side: bottom;
 152   font-size: 120%;
 153   font-style: italic;
 154   font-weight: bold;
 155   margin-left: auto;
 156   margin-right: auto;
 157 }
 158
 159 TH.label {
 160   text-align: right;
 161   vertical-align: top;
 162 }
 163
 164 TH.sublabel {
 165   text-align: right;
 166   font-weight: normal;
 167 }
 168
 169 HR {
 170   border: solid thin;
 171 }
 172
 173 SPAN.info {
 174   background: black;
 175   border: thin solid black;
 176   color: white;
 177   font-size: 80%;
 178   font-style: italic;
 179   font-weight: bold;
 180   white-space: nowrap;
 181 }
 182
 183 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 184   float: right;
 185   font-size: 100%;
 186 }
 187
 188 H1.title {
 189 }
 190
 191 H2.title, H3.title {
 192   border-bottom: solid 2pt #000000;
 193 }
 194
 195 DIV.indent, TABLE.indent {
 196   margin-top: 2em;
 197   margin-left: auto;
 198   margin-right: auto;
 199   width: 90%;
 200 }
 201
 202 TABLE.indent {
 203   border-collapse: collapse;
 204 }
 205
 206 TABLE.indent TD, TABLE.indent TH {
 207   padding: 0;
 208 }
 209
 210 TABLE.list {
 211   border-collapse: collapse;
 212   margin-left: auto;
 213   margin-right: auto;
 214   width: 90%;
 215 }
 216
 217 TABLE.list TH {
 218   background: white;
 219   border-bottom: solid thin #cccccc;
 220   color: #444444;
 221   padding-top: 10pt;
 222   padding-left: 5pt;
 223   text-align: left;
 224   vertical-align: bottom;
 225   white-space: nowrap;
 226 }
 227
 228 TABLE.list TH A {
 229   color: #4444cc;
 230 }
 231
 232 TABLE.list TD {
 233   border-bottom: solid thin #eeeeee;
 234   padding-top: 5pt;
 235   padding-left: 5pt;
 236 }
 237
 238 TABLE.list TR:nth-child(even) {
 239   background: #f8f8f8;
 240 }
 241
 242 TABLE.list TR:nth-child(odd) {
 243   background: #f4f4f4;
 244 }
 245
 246 DT {
 247   margin-left: 36pt;
 248   margin-top: 12pt;
 249 }
 250
 251 DD {
 252   margin-left: 54pt;
 253 }
 254
 255 DL.category DT {
 256   font-weight: bold;
 257 }
 258
 259 P.summary {
 260   margin-left: 36pt;
 261   font-family: monaco, courier, monospace;
 262 }
 263
 264 DIV.summary TABLE {
 265   border: solid thin #999999;
 266   border-collapse: collapse;
 267   border-spacing: 0;
 268   margin: 10px;
 269 }
 270
 271 DIV.summary TABLE TD, DIV.summary TABLE TH {
 272   border: solid thin #999999;
 273   padding: 5px;
 274   text-align: left;
 275   vertical-align: top;
 276 }
 277
 278 DIV.summary TABLE THEAD TH {
 279   background: #eeeeee;
 280 }
 281
 282 /* API documentation styles... */
 283 div.body h1 {
 284   margin: 0;
 285 }
 286 div.body h2 {
 287   margin-top: 1.5em;
 288 }
 289 div.body h3, div.body h4, div.body h5 {
 290   margin-bottom: 0.5em;
 291   margin-top: 1.5em;
 292 }
 293 .class, .enumeration, .function, .struct, .typedef, .union {
 294   border-bottom: solid thin #999999;
 295   margin-bottom: 0;
 296   margin-top: 2em;
 297 }
 298 .description {
 299   margin-top: 0.5em;
 300 }
 301 code, p.code, pre, ul.code li {
 302   font-family: monaco, courier, monospace;
 303   font-size: 90%;
 304 }
 305 ul.code, ul.contents, ul.subcontents {
 306   list-style-type: none;
 307   margin: 0;
 308   padding-left: 0;
 309 }
 310 ul.code li {
 311   margin: 0;
 312 }
 313 ul.contents > li {
 314   margin-top: 1em;
 315 }
 316 ul.contents li ul.code, ul.contents li ul.subcontents {
 317   padding-left: 2em;
 318 }
 319 div.body dl {
 320   margin-left: 0;
 321   margin-top: 0;
 322 }
 323 div.body dt {
 324   font-style: italic;
 325   margin-left: 0;
 326   margin-top: 0;
 327 }
 328 div.body dd {
 329   margin-bottom: 0.5em;
 330 }
 331
 332 /* This is just for the HTML files generated with the framedhelp target */
 333 div.contents {
 334   background: #e8e8e8;
 335   border: solid thin black;
 336   padding: 10px;
 337 }
 338 div.contents h1 {
 339   font-size: 110%;
 340 }
 341 div.contents h2 {
 342   font-size: 100%;
 343 }
 344 div.contents ul.contents {
 345   font-size: 80%;
 346 }
 347 div.contents ul.subcontents li {
 348   margin-left: 1em;
 349   text-indent: -1em;
 350 }
 351 --></style>
 352 </head>
 353 <body>
 354 <div class='body'>
 355 <!--
 356   "$Id$"
 357
 358   PPD compiler documentation for CUPS.
 359
 360   Copyright 2007-2012 by Apple Inc.
 361   Copyright 1997-2007 by Easy Software Products.
 362
 363   These coded instructions, statements, and computer programs are the
 364   property of Apple Inc. and are protected by Federal copyright
 365   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 366   which should have been included with this file.  If this file is
 367   file is missing or damaged, see the license at "http://www.cups.org/".
 368 -->
 369
 370 <h1 class='title'>Introduction to the PPD Compiler</h1>
 371
 372 <P>This document describes how to use the CUPS PostScript Printer Description
 373 (PPD) file compiler. The PPD compiler generates PPD files from simple text files
 374 that describe the features and capabilities of one or more printers.</P>
 375
 376 <BLOCKQUOTE><B>Note:</B>
 377
 378 <P>The PPD compiler and related tools are deprecated and will be removed in a future release of CUPS.</P>
 379
 380 </BLOCKQUOTE>
 381
 382 <div class='summary'><table summary='General Information'>
 383 <tbody>
 384 <tr>
 385         <th>See Also</th>
 386         <td>Programming: <a href='raster-driver.html'>Developing Raster Printer Drivers</a><br>
 387         Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br>
 388         Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
 389         Programming: <a href='api-raster.html'>Raster API</a><br>
 390         References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br>
 391         Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td>
 392 </tr>
 393 </tbody>
 394 </table></div>
 395 <h2 class="title">Contents</h2>
 396 <ul class="contents">
 397 <li><a href="#BASICS">The Basics</a></li>
 398 <li><a href="#DRV">Driver Information Files</a><ul class="subcontents">
 399         <li><a href="#SIMPLE">A Simple Example</a></li>
 400         <li><a href="#GROUPING">Grouping and Inheritance</a></li>
 401         <li><a href="#COLOR">Color Support</a></li>
 402         <li><a href="#OPTIONS">Defining Custom Options and Option Groups</a></li>
 403         <li><a href="#DEFINE">Defining Constants</a></li>
 404         <li><a href="#CONDITIONAL">Conditional Statements</a></li>
 405         <li><a href="#CONSTRAINTS">Defining Constraints</a></li>
 406 </ul></li>
 407 <li><a href="#LOCALIZATION">Localization</a><ul class="subcontents">
 408         <li><a href="#PPDPO">The ppdpo Utility</a></li>
 409         <li><a href="#PPDC_CATALOG">Using Message Catalogs with the PPD Compiler</a></li>
 410 </ul></li>
 411 </ul>
 412 <h2 class='title'><a name='BASICS'>The Basics</a></h2>
 413
 414 <P>The PPD compiler, <a href='man-ppdc.html'><code>ppdc(1)</code></a>, is a
 415 simple command-line tool that takes a single <I>driver information file</I>,
 416 which by convention uses the extension <VAR>.drv</VAR>, and produces one or more
 417 PPD files that may be distributed with your printer drivers for use with CUPS.
 418 For example, you would run the following command to create the English language
 419 PPD files defined by the driver information file <VAR>mydrivers.drv</VAR>:</P>
 420
 421 <pre class='command'>
 422 ppdc mydrivers.drv
 423 </pre>
 424
 425 <P>The PPD files are placed in a subdirectory called
 426 <VAR>ppd</VAR>. The <TT>-d</TT> option is used to put the PPD
 427 files in a different location, for example:</p>
 428
 429 <pre class='command'>
 430 ppdc -d myppds mydrivers.drv
 431 </pre>
 432
 433 <P>places the PPD files in a subdirectory named
 434 <VAR>myppds</VAR>. Finally, use the <TT>-l</TT> option to
 435 specify the language localization for the PPD files that are
 436 created, for example:</P>
 437
 438 <pre class='command'>
 439 ppdc -d myppds/de -l de mydrivers.drv
 440 ppdc -d myppds/en -l en mydrivers.drv
 441 ppdc -d myppds/es -l es mydrivers.drv
 442 ppdc -d myppds/fr -l fr mydrivers.drv
 443 ppdc -d myppds/it -l it mydrivers.drv
 444 </pre>
 445
 446 <P>creates PPD files in German (de), English (en), Spanish (es),
 447 French (fr), and Italian (it) in the corresponding
 448 subdirectories. Specify multiple languages (separated by commas) to produce
 449 "globalized" PPD files:</p>
 450
 451 <pre class='command'>
 452 ppdc -d myppds -l de,en,es,fr,it mydrivers.drv
 453 </pre>
 454
 455
 456 <h2 class='title'><a name='DRV'>Driver Information Files</a></h2>
 457
 458 <P>The driver information files accepted by the PPD compiler are
 459 plain text files that define the various attributes and options
 460 that are included in the PPD files that are generated. A driver
 461 information file can define the information for one or more printers and
 462 their corresponding PPD files.</P>
 463
 464 <p class='example'><a name="LISTING1">Listing 1: "examples/minimum.drv"</a></p>
 465
 466 <pre class='example'>
 467 <I>// Include standard font and media definitions</I>
 468 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 469 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 470
 471 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 472 <a href='ref-ppdcfile.html#Font'>Font</a> *
 473
 474 <I>// Manufacturer, model name, and version</I>
 475 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 476 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 477 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 478
 479 <I>// Each filter provided by the driver...</I>
 480 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 481
 482 <I>// Supported page sizes</I>
 483 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 484 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 485
 486 <I>// Supported resolutions</I>
 487 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 488
 489 <I>// Specify the name of the PPD file we want to generate...</I>
 490 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 491 </pre>
 492
 493
 494 <h3><a name='SIMPLE'>A Simple Example</a></h3>
 495
 496 <P>The example in <A HREF="#LISTING1">Listing 1</A> shows a driver information
 497 file which defines the minimum required attributes to provide a valid PPD file.
 498 The first part of the file includes standard definition files for fonts and
 499 media sizes:</P>
 500
 501 <pre class='example'>
 502 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 503 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 504 </pre>
 505
 506 <P>The <TT>#include</TT> directive works just like the C/C++ include directive;
 507 files included using the angle brackets (<TT>&lt;filename&gt;</TT>) are found
 508 in any of the standard include directories and files included using quotes
 509 (<TT>"filename"</TT>) are found in the same directory as the source or include
 510 file. The <TT>&lt;font.defs&gt;</TT> include file defines the standard fonts
 511 which are included with GPL Ghostscript and the Apple PDF RIP, while the
 512 <TT>&lt;media.defs&gt;</TT> include file defines the standard media sizes
 513 listed in Appendix B of the Adobe PostScript Printer Description File Format
 514 Specification.</P>
 515
 516 <P>CUPS provides several other standard include files:</P>
 517
 518 <UL>
 519
 520         <LI><TT>&lt;epson.h&gt;</TT> - Defines all of the rastertoepson driver
 521         constants.</LI>
 522
 523         <LI><TT>&lt;escp.h&gt;</TT> - Defines all of the rastertoescpx driver
 524         constants.</LI>
 525
 526         <LI><TT>&lt;hp.h&gt;</TT> - Defines all of the rastertohp driver
 527         constants.</LI>
 528
 529         <LI><TT>&lt;label.h&gt;</TT> - Defines all of the rastertolabel driver
 530         constants.</LI>
 531
 532         <LI><TT>&lt;pcl.h&gt;</TT> - Defines all of the rastertopclx driver
 533         constants.</LI>
 534
 535         <LI><TT>&lt;raster.defs&gt;</TT> - Defines all of the CUPS raster format
 536         constants.</LI>
 537
 538 </UL>
 539
 540 <P>Next we list all of the fonts that are available in the driver; for CUPS
 541 raster drivers, the following line is all that is usually supplied:</P>
 542
 543 <pre class='example'>
 544 <a href='ref-ppdcfile.html#Font'>Font</a> *
 545 </pre>
 546
 547 <P>The <TT>Font</TT> directive specifies the name of a single font or the
 548 asterisk to specify all fonts. For example, you would use the following line to
 549 define an additional bar code font that you are supplying with your printer
 550 driver:</P>
 551
 552 <pre class='example'>
 553 <I>//   name         encoding  version  charset  status</I>
 554 <a href='ref-ppdcfile.html#Font'>Font</a> Barcode-Foo  Special   "(1.0)"  Special  ROM
 555 </pre>
 556
 557 <P>The name of the font is <TT>Barcode-Foo</TT>. Since it is not a standard
 558 text font, the encoding and charset name <TT>Special</TT> is used. The version
 559 number is <TT>1.0</TT> and the status (where the font is located) is
 560 <TT>ROM</TT> to indicate that the font does not need to be embedded in
 561 documents that use the font for this printer.</P>
 562
 563 <P>Third comes the manufacturer, model name, and version number information
 564 strings:</P>
 565
 566 <pre class='example'>
 567 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 568 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 569 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 570 </pre>
 571
 572 <P>These strings are used when the user (or auto-configuration program) selects
 573 the printer driver for a newly connected device.</p>
 574
 575 <P>The list of filters comes after the information strings; for the example in
 576 <A HREF="#LISTING1">Listing 1</A>, we have a single filter that takes CUPS
 577 raster data:</P>
 578
 579 <pre class='example'>
 580 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 581 </pre>
 582
 583 <P>Each filter specified in the driver information file is the equivalent of a
 584 printer driver for that format; if a user submits a print job in a different
 585 format, CUPS figures out the sequence of commands that will produce a supported
 586 format for the least relative cost.</P>
 587
 588 <P>Once we have defined the driver information we specify the supported options.
 589 For the example driver we support a single resolution of 600 dots per inch and
 590 two media sizes, A4 and Letter:</P>
 591
 592 <pre class='example'>
 593 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 594 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 595
 596 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 597 </pre>
 598
 599 <P>The asterisk in front of the <TT>MediaSize</TT> and <TT>Resolution</TT>
 600 directives specify that those option choices are the default. The
 601 <TT>MediaSize</TT> directive is followed by a media size name which is normally
 602 defined in the <TT>&lt;media.defs&gt;</TT> file and corresponds to a standard
 603 Adobe media size name. If the default media size is <TT>Letter</TT>, the PPD
 604 compiler will override it to be <TT>A4</TT> for non-English localizations for
 605 you automatically.</P>
 606
 607 <P>The <TT>Resolution</TT> directive accepts several values after it as
 608 follows:</P>
 609
 610 <OL>
 611
 612         <LI>Colorspace for this resolution, if any. In the example file, the
 613         colorspace <TT>k</TT> is used which corresponds to black. For printer
 614         drivers that support color printing, this field is usually specified as
 615         "-" for "no change".</LI>
 616
 617         <LI>Bits per color. In the example file, we define 8 bits per color, for
 618         a continuous-tone grayscale output. All versions of CUPS support 1 and
 619         8 bits per color.  CUPS 1.2 and higher (OS X 10.5 and higher) also
 620         supports 16 bits per color.</LI>
 621
 622         <LI>Rows per band. In the example file, we define 0 rows per band to
 623         indicate that our printer driver does not process the page in
 624         bands.</LI>
 625
 626         <LI>Row feed. In the example, we define the feed value to be 0 to
 627         indicate that our printer driver does not interleave the output.</LI>
 628
 629         <LI>Row step. In the example, we define the step value to be 0 to
 630         indicate that our printer driver does not interleave the output. This
 631         value normally indicates the spacing between the nozzles of an inkjet
 632         printer - when combined with the previous two values, it informs the
 633         driver how to stagger the output on the page to produce interleaved
 634         lines on the page for higher-resolution output.</LI>
 635
 636         <LI>Choice name and text. In the example, we define the choice name and
 637         text to be <TT>"600dpi/600 DPI"</TT>. The name and text are separated by
 638         slash (<TT>/</TT>) character; if no text is specified, then the name is
 639         used as the text. The PPD compiler parses the name to determine the
 640         actual resolution; the name can be of the form
 641         <TT><I>RESOLUTION</I>dpi</TT> for resolutions that are equal
 642         horizontally and vertically or <TT><I>HRES</I>x<I>VRES</I>dpi</TT> for
 643         isometric resolutions. Only integer resolution values are supported, so
 644         a resolution name of <TT>300dpi</TT> is valid while <TT>300.1dpi</TT> is
 645         not.</LI>
 646
 647 </OL>
 648
 649 <P>Finally, the <TT>PCFileName</TT> directive specifies that the named PPD file
 650 should be written for the current driver definitions:</P>
 651
 652 <pre class='example'>
 653 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 654 </pre>
 655
 656 <P>The filename follows the directive and <I>must</I> conform to the Adobe
 657 filename requirements in the Adobe Postscript Printer Description File Format
 658 Specification. Specifically, the filename may not exceed 8 characters followed
 659 by the extension <VAR>.ppd</VAR>. The <TT>FileName</TT> directive can be used to
 660 specify longer filenames:</P>
 661
 662 <pre class='example'>
 663 <a href='ref-ppdcfile.html#FileName'>FileName</a> "FooJet 2000"
 664 </pre>
 665
 666
 667 <h3><a name='GROUPING'>Grouping and Inheritance</a></h3>
 668
 669 <P>The previous example created a single PPD file. Driver information files can
 670 also define multiple printers by using the PPD compiler grouping functionality.
 671 Directives are grouped using the curly braces (<TT>{</TT> and <TT>}</TT>) and
 672 every group that uses the <TT>PCFileName</TT> or <TT>FileName</TT> directives
 673 produces a PPD file with that name. <A HREF="#LISTING2">Listing 2</A> shows a
 674 variation of the original example that uses two groups to define two printers
 675 that share the same printer driver filter but provide two different resolution
 676 options.</P>
 677
 678 <p class='example'><a name="LISTING2">Listing 2: "examples/grouping.drv"</a></p>
 679
 680 <pre class='example'>
 681
 682 <I>// Include standard font and media definitions</I>
 683 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 684 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 685
 686 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 687 <a href='ref-ppdcfile.html#Font'>Font</a> *
 688
 689 <I>// Manufacturer and version</I>
 690 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 691 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 692
 693 <I>// Each filter provided by the driver...</I>
 694 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 695
 696 <I>// Supported page sizes</I>
 697 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 698 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 699
 700 {
 701   <I>// Supported resolutions</I>
 702   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 703
 704   <I>// Specify the model name and filename...</I>
 705   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 706   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 707 }
 708
 709 {
 710   <I>// Supported resolutions</I>
 711   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "1200dpi/1200 DPI"
 712
 713   <I>// Specify the model name and filename...</I>
 714   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001"
 715   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojt2k1.ppd"
 716 }
 717 </pre>
 718
 719 <P>The second example is essentially the same as the first, except that each
 720 printer model is defined inside of a pair of curly braces. For example, the
 721 first printer is defined using:</P>
 722
 723 <pre class='example'>
 724 {
 725   // Supported resolutions
 726   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 727
 728   // Specify the model name and filename...
 729   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 730   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 731 }
 732 </pre>
 733
 734 <P>The printer <I>inherits</I> all of the definitions from the parent group (the
 735 top part of the file) and adds the additional definitions inside the curly
 736 braces for that printer driver. When we define the second group, it also
 737 inherits the same definitions from the parent group but <I>none</I> of the
 738 definitions from the first driver. Groups can be nested to any number of levels
 739 to support variations of similar models without duplication of information.</P>
 740
 741
 742 <h3><a name='COLOR'>Color Support</a></h3>
 743
 744 <P>For printer drivers that support color printing, the
 745 <TT>ColorDevice</TT> and <TT>ColorModel</TT> directives should be
 746 used to tell the printing system that color output is desired
 747 and in what formats. <A HREF="#LISTING3">Listing 3</A> shows a
 748 variation of the previous example which includes a color printer
 749 that supports printing at 300 and 600 DPI.</P>
 750
 751 <P>The key changes are the addition of the <TT>ColorDevice</TT>
 752 directive:</P>
 753
 754 <pre class='example'>
 755 <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true
 756 </pre>
 757
 758 <P>which tells the printing system that the printer supports
 759 color printing, and the <TT>ColorModel</TT> directives:</P>
 760
 761 <pre class='example'>
 762 <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0
 763 *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0
 764 </pre>
 765
 766 <P>which tell the printing system which colorspaces are supported by the printer
 767 driver for color printing. Each of the <TT>ColorModel</TT> directives is
 768 followed by the option name and text (<TT>Gray/Grayscale</TT> and
 769 <TT>RGB/Color</TT>), the colorspace name (<TT>w</TT> and <TT>rgb</TT>), the
 770 color organization (<TT>chunky</TT>), and the compression mode number
 771 (<TT>0</TT>) to be passed to the driver. The option name can be any of the
 772 standard Adobe <TT>ColorModel</TT> names:</P>
 773
 774 <UL>
 775
 776         <LI><TT>Gray</TT> - Grayscale output.
 777
 778         <LI><TT>RGB</TT> - Color output, typically using the RGB
 779         colorspace, but without a separate black channel.
 780
 781         <LI><TT>CMYK</TT> - Color output with a separate black
 782         channel.
 783
 784 </UL>
 785
 786 <P>Custom names can be used, however it is recommended that you use your vendor
 787 prefix for any custom names, for example "fooName".</P>
 788
 789 <P>The colorspace name can be any of the following universally supported
 790 colorspaces:</P>
 791
 792 <UL>
 793         <LI><TT>w</TT> - Luminance</LI>
 794
 795         <LI><TT>rgb</TT> - Red, green, blue</LI>
 796
 797         <LI><TT>k</TT> - Black</LI>
 798
 799         <LI><TT>cmy</TT> - Cyan, magenta, yellow</LI>
 800
 801         <LI><TT>cmyk</TT> - Cyan, magenta, yellow, black</LI>
 802
 803 </UL>
 804
 805 <P>The color organization can be any of the following values:</P>
 806
 807 <UL>
 808
 809         <LI><TT>chunky</TT> - Color values are passed together on a line
 810         as RGB RGB RGB RGB</LI>
 811
 812         <LI><TT>banded</TT> - Color values are passed separately
 813         on a line as RRRR GGGG BBBB; not supported by the Apple
 814         RIP filters</LI>
 815
 816         <LI><TT>planar</TT> - Color values are passed separately
 817         on a page as RRRR RRRR RRRR ... GGGG GGGG GGGG ... BBBB
 818         BBBB BBBB; not supported by the Apple RIP filters</LI>
 819
 820 </UL>
 821
 822 <P>The compression mode value is passed to the driver in the
 823 <TT>cupsCompression</TT> attribute. It is traditionally used to select an
 824 appropriate compression mode for the color model but can be used for any
 825 purpose, such as specifying a photo mode vs. standard mode.</P>
 826
 827 <p class='example'><a name="LISTING3">Listing 3: "examples/color.drv"</a></p>
 828
 829 <pre class='example'>
 830
 831 <I>// Include standard font and media definitions</I>
 832 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 833 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 834
 835 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 836 <a href='ref-ppdcfile.html#Font'>Font</a> *
 837
 838 <I>// Manufacturer and version</I>
 839 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 840 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 841
 842 <I>// Each filter provided by the driver...</I>
 843 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 844
 845 <I>// Supported page sizes</I>
 846 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 847 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 848
 849 {
 850   <I>// Supported resolutions</I>
 851   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 852
 853   <I>// Specify the model name and filename...</I>
 854   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 855   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 856 }
 857
 858 {
 859   <I>// Supports color printing</I>
 860   <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true
 861
 862   <I>// Supported colorspaces</I>
 863   <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0
 864   *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0
 865
 866   <I>// Supported resolutions</I>
 867   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "300dpi/300 DPI"
 868   <a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI"
 869
 870   <I>// Specify the model name and filename...</I>
 871   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet Color"
 872   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojetco.ppd"
 873 }
 874 </pre>
 875
 876
 877 <h3><a name='OPTIONS'>Defining Custom Options and Option Groups</a></h3>
 878
 879 <P>The <TT>Group</TT>, <TT>Option</TT>, and <TT>Choice</TT>
 880 directives are used to define or select a group, option, or
 881 choice. <A HREF="#LISTING4">Listing 4</A> shows a variation of
 882 the first example that provides two custom options in a group
 883 named "Footasm".</P>
 884
 885 <p class='example'><a name="LISTING4">Listing 4: "examples/custom.drv"</a></p>
 886
 887 <pre class='example'>
 888
 889 <I>// Include standard font and media definitions</I>
 890 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 891 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 892
 893 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 894 <a href='ref-ppdcfile.html#Font'>Font</a> *
 895
 896 <I>// Manufacturer, model name, and version</I>
 897 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 898 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 899 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 900
 901 <I>// Each filter provided by the driver...</I>
 902 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 903
 904 <I>// Supported page sizes</I>
 905 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 906 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 907
 908 <I>// Supported resolutions</I>
 909 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 910
 911 <I>// Option Group</I>
 912 <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm"
 913
 914   <I>// Boolean option</I>
 915   <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10
 916     *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "&lt;&lt;/cupsCompression 1&gt;&gt;setpagedevice"
 917     <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "&lt;&lt;/cupsCompression 0&gt;&gt;setpagedevice"
 918
 919   <I>// Multiple choice option</I>
 920   <a href='ref-ppdcfile.html#Option'>Option</a> "fooOutputType/Output Quality" PickOne AnySetup 10
 921     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "Auto/Automatic Selection"
 922             "&lt;&lt;/OutputType(Auto)&gt;&gt;setpagedevice""
 923     <a href='ref-ppdcfile.html#Choice'>Choice</a> "Text/Optimize for Text"
 924             "&lt;&lt;/OutputType(Text)&gt;&gt;setpagedevice""
 925     <a href='ref-ppdcfile.html#Choice'>Choice</a> "Graph/Optimize for Graphics"
 926             "&lt;&lt;/OutputType(Graph)&gt;&gt;setpagedevice""
 927     <a href='ref-ppdcfile.html#Choice'>Choice</a> "Photo/Optimize for Photos"
 928             "&lt;&lt;/OutputType(Photo)&gt;&gt;setpagedevice""
 929
 930 <I>// Specify the name of the PPD file we want to generate...</I>
 931 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 932 </pre>
 933
 934 <P>The custom group is introduced by the <TT>Group</TT>
 935 directive which is followed by the name and optionally text for
 936 the user:</P>
 937
 938 <pre class='example'>
 939 <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm/Footastic Options"
 940 </pre>
 941
 942 <P>The group name must conform to the PPD specification and
 943 cannot exceed 40 characters in length. If you specify user text,
 944 it cannot exceed 80 characters in length. The groups
 945 <TT>General</TT>, <TT>Extra</TT>, and
 946 <TT>InstallableOptions</TT> are predefined by CUPS; the general
 947 and extra groups are filled by the UI options defined by the PPD
 948 specification. The <TT>InstallableOptions</TT> group is reserved
 949 for options that define whether accessories for the printer
 950 (duplexer unit, finisher, stapler, etc.) are installed.</P>
 951
 952 <P>Once the group is specified, the <TT>Option</TT> directive is
 953 used to introduce a new option:</P>
 954
 955 <pre class='example'>
 956 <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10
 957 </pre>
 958
 959 <P>The directive is followed by the name of the option and any
 960 optional user text, the option type, the PostScript document group, and
 961 the sort order number. The option name must conform to the PPD specification
 962 and cannot exceed 40 characters in length. If you specify user text, it
 963 cannot exceed 80 characters in length.</P>
 964
 965 <P>The option type can be <TT>Boolean</TT> for true/false
 966 selections, <TT>PickOne</TT> for picking one of many choices, or
 967 <TT>PickMany</TT> for picking zero or more choices. Boolean
 968 options can have at most two choices with the names
 969 <TT>False</TT> and <TT>True</TT>. Pick options can have any
 970 number of choices, although for Windows compatibility reasons
 971 the number of choices should not exceed 255.</P>
 972
 973 <P>The PostScript document group is typically <TT>AnySetup</TT>,
 974 meaning that the option can be introduced at any point in the
 975 PostScript document. Other values include <TT>PageSetup</TT> to
 976 include the option before each page and <TT>DocumentSetup</TT>
 977 to include the option once at the beginning of the document.</P>
 978
 979 <P>The sort order number is used to sort the printer commands
 980 associated with each option choice within the PostScript
 981 document. This allows you to setup certain options before others
 982 as required by the printer. For most CUPS raster printer
 983 drivers, the value <TT>10</TT> can be used for all options.</P>
 984
 985 <P>Once the option is specified, each option choice can be
 986 listed using the <TT>Choice</TT> directive:</P>
 987
 988 <pre class='example'>
 989 *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "&lt;&lt;/cupsCompression 1&gt;&gt;setpagedevice"
 990 <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "&lt;&lt;/cupsCompression 0&gt;&gt;setpagedevice"
 991 </pre>
 992
 993 <P>The directive is followed by the choice name and optionally
 994 user text, and the PostScript commands that should be inserted
 995 when printing a file to this printer. The option name must
 996 conform to the PPD specification and cannot exceed 40 characters
 997 in length. If you specify user text, it cannot exceed 80
 998 characters in length.</P>
 999
1000 <P>The PostScript commands are also interpreted by any RIP
1001 filters, so these commands typically must be present for all
1002 option choices. Most commands take the form:</P>
1003
1004 <pre class='example'>
1005 &lt;&lt;/name value&gt;&gt;setpagedevice
1006 </pre>
1007
1008 <P>where <TT>name</TT> is the name of the PostScript page device
1009 attribute and <TT>value</TT> is the numeric or string value for
1010 that attribute.</P>
1011
1012
1013 <h3><a name='DEFINE'>Defining Constants</a></h3>
1014
1015 <P>Sometimes you will want to define constants for your drivers
1016 so that you can share values in different groups within the same
1017 driver information file, or to share values between different
1018 driver information files using the <TT>#include</TT> directive.
1019 The <TT>#define</TT> directive is used to define constants for
1020 use in your printer definitions:</P>
1021
1022 <pre class='example'>
1023 <a href='ref-ppdcfile.html#_define'>#define</a> NAME value
1024 </pre>
1025
1026 <P>The <TT>NAME</TT> is any sequence of letters, numbers, and
1027 the underscore. The <TT>value</TT> is a number or string; if the
1028 value contains spaces you must put double quotes around it, for
1029 example:</P>
1030
1031 <pre class='example'>
1032 <a href='ref-ppdcfile.html#_define'>#define</a> FOO "My String Value"
1033 </pre>
1034
1035 <P>Constants can also be defined on the command-line using the <tt>-D</tt>
1036 option:</P>
1037
1038 <pre class='command'>
1039 ppdc -DNAME="value" filename.drv
1040 </pre>
1041
1042 <P>Once defined, you use the notation <TT>$NAME</TT> to substitute the value of
1043 the constant in the file, for example:</P>
1044
1045 <pre class='example'>
1046 <a href='ref-ppdcfile.html#_define'>#define</a> MANUFACTURER "Foo"
1047 <a href='ref-ppdcfile.html#_define'>#define</a> FOO_600      0
1048 <a href='ref-ppdcfile.html#_define'>#define</a> FOO_1200     1
1049
1050 {
1051   <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER"
1052   <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_600
1053   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
1054   ...
1055 }
1056
1057 {
1058   <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER"
1059   <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_1200
1060   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001"
1061   ...
1062 }
1063 </pre>
1064
1065 <P>Numeric constants can be bitwise OR'd together by placing the constants
1066 inside parenthesis, for example:</P>
1067
1068 <pre class='example'>
1069 <I>// ModelNumber capability bits</I>
1070 <a href='ref-ppdcfile.html#_define'>#define</a> DUPLEX 1
1071 <a href='ref-ppdcfile.html#_define'>#define</a> COLOR  2
1072
1073 ...
1074
1075 {
1076   <I>// Define a model number specifying the capabilities of the printer...</I>
1077   <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($DUPLEX $COLOR)
1078   ...
1079 }
1080 </pre>
1081
1082
1083 <h3><a name='CONDITIONAL'>Conditional Statements</a></h3>
1084
1085 <p>The PPD compiler supports conditional compilation using the <tt>#if</tt>,
1086 <tt>#elif</tt>, <tt>#else</tt>, and <tt>#endif</tt> directives. The <tt>#if</tt>
1087 and <tt>#elif</tt> directives are followed by a constant name or an expression.
1088 For example, to include a group of options when "ADVANCED" is defined:</p>
1089
1090 <pre class='example'>
1091 <a href='ref-ppdcfile.html#_if'>#if</a> ADVANCED
1092 <a href='ref-ppdcfile.html#Group'>Group</a> "Advanced/Advanced Options"
1093   <a href='ref-ppdcfile.html#Option'>Option</a> "fooCyanAdjust/Cyan Adjustment"
1094     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1095     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1096     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1097     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1098     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1099   <a href='ref-ppdcfile.html#Option'>Option</a> "fooMagentaAdjust/Magenta Adjustment"
1100     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1101     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1102     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1103     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1104     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1105   <a href='ref-ppdcfile.html#Option'>Option</a> "fooYellowAdjust/Yellow Adjustment"
1106     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1107     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1108     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1109     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1110     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1111   <a href='ref-ppdcfile.html#Option'>Option</a> "fooBlackAdjust/Black Adjustment"
1112     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1113     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1114     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1115     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1116     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1117 <a href='ref-ppdcfile.html#_endif'>#endif</a>
1118 </pre>
1119
1120
1121 <h3><a name='CONSTRAINTS'>Defining Constraints</a></h3>
1122
1123 <P>Constraints are strings that are used to specify that one or more option
1124 choices are incompatible, for example two-sided printing on transparency media.
1125 Constraints are also used to prevent the use of uninstalled features such as the
1126 duplexer unit, additional media trays, and so forth.</P>
1127
1128 <P>The <TT>UIConstraints</TT> directive is used to specify a constraint that is
1129 placed in the PPD file. The directive is followed by a string using one of the
1130 following formats:</P>
1131
1132 <pre class='example'>
1133 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2"
1134 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2"
1135 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2 Choice2"
1136 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2 Choice2"
1137 </pre>
1138
1139 <P>Each option name is preceded by the asterisk (<TT>*</TT>). If no choice is
1140 given for an option, then all choices <I>except</I> <TT>False</TT> and
1141 <TT>None</TT> will conflict with the other option and choice(s). Since the PPD
1142 compiler automatically adds reciprocal constraints (option A conflicts with
1143 option B, so therefore option B conflicts with option A), you need only specify
1144 the constraint once.</P>
1145
1146 <p class='example'><a name="LISTING5">Listing 5: "examples/constraint.drv"</a></p>
1147
1148 <pre class='example'>
1149
1150 <I>// Include standard font and media definitions</I>
1151 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
1152 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
1153
1154 <I>// List the fonts that are supported, in this case all standard fonts...</I>
1155 <a href='ref-ppdcfile.html#Font'>Font</a> *
1156
1157 <I>// Manufacturer, model name, and version</I>
1158 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
1159 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
1160 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
1161
1162 <I>// Each filter provided by the driver...</I>
1163 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
1164
1165 <I>// Supported page sizes</I>
1166 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
1167 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
1168
1169 <I>// Supported resolutions</I>
1170 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
1171
1172 <I>// Installable Option Group</I>
1173 <a href='ref-ppdcfile.html#Group'>Group</a> "InstallableOptions/Options Installed"
1174
1175   <I>// Duplexing unit option</I>
1176   <a href='ref-ppdcfile.html#Option'>Option</a> "OptionDuplexer/Duplexing Unit" Boolean AnySetup 10
1177     <a href='ref-ppdcfile.html#Choice'>Choice</a> True/Installed ""
1178     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "False/Not Installed" ""
1179
1180 <I>// General Option Group</I>
1181 <a href='ref-ppdcfile.html#Group'>Group</a> General
1182
1183   <I>// Duplexing option</I>
1184   <a href='ref-ppdcfile.html#Option'>Option</a> "Duplex/Two-Sided Printing" PickOne AnySetup 10
1185     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "None/No" "&lt;&lt;/Duplex false&gt;&gt;setpagedevice""
1186     <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexNoTumble/Long Edge Binding"
1187            "&lt;&lt;/Duplex true/Tumble false&gt;&gt;setpagedevice""
1188     <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexTumble/Short Edge Binding"
1189            "&lt;&lt;/Duplex true/Tumble true&gt;&gt;setpagedevice""
1190
1191 <I>// Only allow duplexing if the duplexer is installed</I>
1192 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False"
1193
1194 <I>// Specify the name of the PPD file we want to generate...</I>
1195 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
1196 </pre>
1197
1198 <P><A HREF="#LISTING5">Listing 5</A> shows a variation of the first example with
1199 an added <TT>Duplex</TT> option and installable option for the duplexer,
1200 <TT>OptionDuplex</TT>. A constraint is added at the end to specify that any
1201 choice of the <TT>Duplex</TT> option that is not <TT>None</TT> is incompatible
1202 with the "Duplexer Installed" option set to "Not Installed"
1203 (<TT>False</TT>):</P>
1204
1205 <pre class='example'>
1206 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False"
1207 </pre>
1208
1209 <h4>Enhanced Constraints</h4>
1210
1211 <p>CUPS 1.4 supports constraints between 2 or more options using the
1212 <TT>Attribute</TT> directive. <TT>cupsUIConstraints</TT> attributes define
1213 the constraints, while <TT>cupsUIResolver</TT> attributes define option changes
1214 to resolve constraints. For example, we can specify the previous duplex
1215 constraint with a resolver that turns off duplexing with the following two
1216 lines:</p>
1217
1218 <pre class='example'>
1219 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIConstraints DuplexOff "*Duplex *OptionDuplexer False"
1220 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIResolver DuplexOff "*Duplex None"
1221 </pre>
1222
1223 <h2 class='title'><a name='LOCALIZATION'>Localization</a></h2>
1224
1225 <p>The PPD compiler provides localization of PPD files in different languages
1226 through <i>message catalog</i> files in the GNU gettext or Apple .strings
1227 formats. Each user text string and several key PPD attribute values such as
1228 <tt>LanguageVersion</tt> and <tt>LanguageEncoding</tt> are looked up in the
1229 corresponding message catalog and the translated text is substituted in the
1230 generated PPD files. One message catalog file can be used by multiple driver
1231 information files, and each file contains a single language translation.</p>
1232
1233 <h3><a name='PPDPO'>The ppdpo Utility</a></h3>
1234
1235 <p>While CUPS includes localizations of all standard media sizes and options in
1236 several languages, your driver information files may provide their own media
1237 sizes and options that need to be localized. CUPS provides a utility program to
1238 aid in the localization of drivers called <a
1239 href='man-ppdpo.html'><tt>ppdpo(1)</tt></a>. The <tt>ppdpo</tt> program creates
1240 or updates a message catalog file based upon one or more driver information
1241 files. New messages are added with the word "TRANSLATE" added to the front of
1242 the translation string to make locating new strings for translation easier. The
1243 program accepts the message catalog filename and one or more driver information
1244 files.</p>
1245
1246 <p>For example, run the following command to create a new German message catalog
1247 called <var>de.po</var> for all of the driver information files in the current
1248 directory:</p>
1249
1250 <pre class='command'>
1251 ppdpo -o de.po *.drv
1252 </pre>
1253
1254 <p>If the file <var>de.po</var> already exists, <tt>ppdpo</tt> will update the
1255 contents of the file with any new messages that need to be translated. To create
1256 an Apple .strings file instead, specify the output filename with a .strings
1257 extension, for example:</p>
1258
1259 <pre class='command'>
1260 ppdpo -o de.strings *.drv
1261 </pre>
1262
1263 <h3><a name='PPDC_CATALOG'>Using Message Catalogs with the PPD Compiler</a></h3>
1264
1265 <p>Once you have created a message catalog, use the <a
1266 href='ref-ppdcfile.html#_po'><tt>#po</tt></a> directive to declare it in each
1267 driver information file. For example, to declare the German message catalog for
1268 a driver use:</p>
1269
1270 <pre class='example'>
1271 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po"  // German
1272 </pre>
1273
1274 <p>In fact, you can use the <tt>#po</tt> directive as many times as needed:</p>
1275
1276 <pre class='example'>
1277 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po"  // German
1278 <a href='ref-ppdcfile.html#_po'>#po</a> es "es.po"  // Spanish
1279 <a href='ref-ppdcfile.html#_po'>#po</a> fr "fr.po"  // French
1280 <a href='ref-ppdcfile.html#_po'>#po</a> it "it.po"  // Italian
1281 <a href='ref-ppdcfile.html#_po'>#po</a> ja "ja.po"  // Japanese
1282 </pre>
1283
1284 <p>The filename ("de.po", etc.) can be relative to the location of the driver
1285 information file or an absolute path. Once defined, the PPD compiler will
1286 automatically generate a globalized PPD for every language declared in your
1287 driver information file. To generate a single-language PPD file, simply use the
1288 <tt>-l</tt> option to list the corresponding locale, for example:</p>
1289
1290 <pre class='command'>
1291 ppdc -l de -d ppd/de mydrivers.drv
1292 </pre>
1293
1294 <p>to generate German PPD files.</p>
1295 </div>
1296 </body>
1297 </html>