doc/help/ppd-compiler.html

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