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   PPD compiler documentation for CUPS.
 357
 358   Copyright 2007-2012 by Apple Inc.
 359   Copyright 1997-2007 by Easy Software Products.
 360
 361   These coded instructions, statements, and computer programs are the
 362   property of Apple Inc. and are protected by Federal copyright
 363   law.  Distribution and use rights are outlined in the file "LICENSE.txt"
 364   which should have been included with this file.  If this file is
 365   file is missing or damaged, see the license at "http://www.cups.org/".
 366 -->
 367
 368 <h1 class='title'>Introduction to the PPD Compiler</h1>
 369
 370 <P>This document describes how to use the CUPS PostScript Printer Description
 371 (PPD) file compiler. The PPD compiler generates PPD files from simple text files
 372 that describe the features and capabilities of one or more printers.</P>
 373
 374 <BLOCKQUOTE><B>Note:</B>
 375
 376 <P>The PPD compiler and related tools are deprecated and will be removed in a future release of CUPS.</P>
 377
 378 </BLOCKQUOTE>
 379
 380 <div class='summary'><table summary='General Information'>
 381 <tbody>
 382 <tr>
 383         <th>See Also</th>
 384         <td>Programming: <a href='raster-driver.html'>Developing Raster Printer Drivers</a><br>
 385         Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br>
 386         Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
 387         Programming: <a href='api-raster.html'>Raster API</a><br>
 388         References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br>
 389         Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td>
 390 </tr>
 391 </tbody>
 392 </table></div>
 393 <h2 class="title">Contents</h2>
 394 <ul class="contents">
 395 <li><a href="#BASICS">The Basics</a></li>
 396 <li><a href="#DRV">Driver Information Files</a><ul class="subcontents">
 397         <li><a href="#SIMPLE">A Simple Example</a></li>
 398         <li><a href="#GROUPING">Grouping and Inheritance</a></li>
 399         <li><a href="#COLOR">Color Support</a></li>
 400         <li><a href="#OPTIONS">Defining Custom Options and Option Groups</a></li>
 401         <li><a href="#DEFINE">Defining Constants</a></li>
 402         <li><a href="#CONDITIONAL">Conditional Statements</a></li>
 403         <li><a href="#CONSTRAINTS">Defining Constraints</a></li>
 404 </ul></li>
 405 <li><a href="#LOCALIZATION">Localization</a><ul class="subcontents">
 406         <li><a href="#PPDPO">The ppdpo Utility</a></li>
 407         <li><a href="#PPDC_CATALOG">Using Message Catalogs with the PPD Compiler</a></li>
 408 </ul></li>
 409 </ul>
 410 <h2 class='title'><a name='BASICS'>The Basics</a></h2>
 411
 412 <P>The PPD compiler, <a href='man-ppdc.html'><code>ppdc(1)</code></a>, is a
 413 simple command-line tool that takes a single <I>driver information file</I>,
 414 which by convention uses the extension <VAR>.drv</VAR>, and produces one or more
 415 PPD files that may be distributed with your printer drivers for use with CUPS.
 416 For example, you would run the following command to create the English language
 417 PPD files defined by the driver information file <VAR>mydrivers.drv</VAR>:</P>
 418
 419 <pre class='command'>
 420 ppdc mydrivers.drv
 421 </pre>
 422
 423 <P>The PPD files are placed in a subdirectory called
 424 <VAR>ppd</VAR>. The <TT>-d</TT> option is used to put the PPD
 425 files in a different location, for example:</p>
 426
 427 <pre class='command'>
 428 ppdc -d myppds mydrivers.drv
 429 </pre>
 430
 431 <P>places the PPD files in a subdirectory named
 432 <VAR>myppds</VAR>. Finally, use the <TT>-l</TT> option to
 433 specify the language localization for the PPD files that are
 434 created, for example:</P>
 435
 436 <pre class='command'>
 437 ppdc -d myppds/de -l de mydrivers.drv
 438 ppdc -d myppds/en -l en mydrivers.drv
 439 ppdc -d myppds/es -l es mydrivers.drv
 440 ppdc -d myppds/fr -l fr mydrivers.drv
 441 ppdc -d myppds/it -l it mydrivers.drv
 442 </pre>
 443
 444 <P>creates PPD files in German (de), English (en), Spanish (es),
 445 French (fr), and Italian (it) in the corresponding
 446 subdirectories. Specify multiple languages (separated by commas) to produce
 447 "globalized" PPD files:</p>
 448
 449 <pre class='command'>
 450 ppdc -d myppds -l de,en,es,fr,it mydrivers.drv
 451 </pre>
 452
 453
 454 <h2 class='title'><a name='DRV'>Driver Information Files</a></h2>
 455
 456 <P>The driver information files accepted by the PPD compiler are
 457 plain text files that define the various attributes and options
 458 that are included in the PPD files that are generated. A driver
 459 information file can define the information for one or more printers and
 460 their corresponding PPD files.</P>
 461
 462 <p class='example'><a name="LISTING1">Listing 1: "examples/minimum.drv"</a></p>
 463
 464 <pre class='example'>
 465 <I>// Include standard font and media definitions</I>
 466 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 467 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 468
 469 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 470 <a href='ref-ppdcfile.html#Font'>Font</a> *
 471
 472 <I>// Manufacturer, model name, and version</I>
 473 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 474 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 475 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 476
 477 <I>// Each filter provided by the driver...</I>
 478 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 479
 480 <I>// Supported page sizes</I>
 481 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 482 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 483
 484 <I>// Supported resolutions</I>
 485 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 486
 487 <I>// Specify the name of the PPD file we want to generate...</I>
 488 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 489 </pre>
 490
 491
 492 <h3><a name='SIMPLE'>A Simple Example</a></h3>
 493
 494 <P>The example in <A HREF="#LISTING1">Listing 1</A> shows a driver information
 495 file which defines the minimum required attributes to provide a valid PPD file.
 496 The first part of the file includes standard definition files for fonts and
 497 media sizes:</P>
 498
 499 <pre class='example'>
 500 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 501 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 502 </pre>
 503
 504 <P>The <TT>#include</TT> directive works just like the C/C++ include directive;
 505 files included using the angle brackets (<TT>&lt;filename&gt;</TT>) are found
 506 in any of the standard include directories and files included using quotes
 507 (<TT>"filename"</TT>) are found in the same directory as the source or include
 508 file. The <TT>&lt;font.defs&gt;</TT> include file defines the standard fonts
 509 which are included with GPL Ghostscript and the Apple PDF RIP, while the
 510 <TT>&lt;media.defs&gt;</TT> include file defines the standard media sizes
 511 listed in Appendix B of the Adobe PostScript Printer Description File Format
 512 Specification.</P>
 513
 514 <P>CUPS provides several other standard include files:</P>
 515
 516 <UL>
 517
 518         <LI><TT>&lt;epson.h&gt;</TT> - Defines all of the rastertoepson driver
 519         constants.</LI>
 520
 521         <LI><TT>&lt;escp.h&gt;</TT> - Defines all of the rastertoescpx driver
 522         constants.</LI>
 523
 524         <LI><TT>&lt;hp.h&gt;</TT> - Defines all of the rastertohp driver
 525         constants.</LI>
 526
 527         <LI><TT>&lt;label.h&gt;</TT> - Defines all of the rastertolabel driver
 528         constants.</LI>
 529
 530         <LI><TT>&lt;pcl.h&gt;</TT> - Defines all of the rastertopclx driver
 531         constants.</LI>
 532
 533         <LI><TT>&lt;raster.defs&gt;</TT> - Defines all of the CUPS raster format
 534         constants.</LI>
 535
 536 </UL>
 537
 538 <P>Next we list all of the fonts that are available in the driver; for CUPS
 539 raster drivers, the following line is all that is usually supplied:</P>
 540
 541 <pre class='example'>
 542 <a href='ref-ppdcfile.html#Font'>Font</a> *
 543 </pre>
 544
 545 <P>The <TT>Font</TT> directive specifies the name of a single font or the
 546 asterisk to specify all fonts. For example, you would use the following line to
 547 define an additional bar code font that you are supplying with your printer
 548 driver:</P>
 549
 550 <pre class='example'>
 551 <I>//   name         encoding  version  charset  status</I>
 552 <a href='ref-ppdcfile.html#Font'>Font</a> Barcode-Foo  Special   "(1.0)"  Special  ROM
 553 </pre>
 554
 555 <P>The name of the font is <TT>Barcode-Foo</TT>. Since it is not a standard
 556 text font, the encoding and charset name <TT>Special</TT> is used. The version
 557 number is <TT>1.0</TT> and the status (where the font is located) is
 558 <TT>ROM</TT> to indicate that the font does not need to be embedded in
 559 documents that use the font for this printer.</P>
 560
 561 <P>Third comes the manufacturer, model name, and version number information
 562 strings:</P>
 563
 564 <pre class='example'>
 565 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 566 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 567 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 568 </pre>
 569
 570 <P>These strings are used when the user (or auto-configuration program) selects
 571 the printer driver for a newly connected device.</p>
 572
 573 <P>The list of filters comes after the information strings; for the example in
 574 <A HREF="#LISTING1">Listing 1</A>, we have a single filter that takes CUPS
 575 raster data:</P>
 576
 577 <pre class='example'>
 578 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 579 </pre>
 580
 581 <P>Each filter specified in the driver information file is the equivalent of a
 582 printer driver for that format; if a user submits a print job in a different
 583 format, CUPS figures out the sequence of commands that will produce a supported
 584 format for the least relative cost.</P>
 585
 586 <P>Once we have defined the driver information we specify the supported options.
 587 For the example driver we support a single resolution of 600 dots per inch and
 588 two media sizes, A4 and Letter:</P>
 589
 590 <pre class='example'>
 591 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 592 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 593
 594 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 595 </pre>
 596
 597 <P>The asterisk in front of the <TT>MediaSize</TT> and <TT>Resolution</TT>
 598 directives specify that those option choices are the default. The
 599 <TT>MediaSize</TT> directive is followed by a media size name which is normally
 600 defined in the <TT>&lt;media.defs&gt;</TT> file and corresponds to a standard
 601 Adobe media size name. If the default media size is <TT>Letter</TT>, the PPD
 602 compiler will override it to be <TT>A4</TT> for non-English localizations for
 603 you automatically.</P>
 604
 605 <P>The <TT>Resolution</TT> directive accepts several values after it as
 606 follows:</P>
 607
 608 <OL>
 609
 610         <LI>Colorspace for this resolution, if any. In the example file, the
 611         colorspace <TT>k</TT> is used which corresponds to black. For printer
 612         drivers that support color printing, this field is usually specified as
 613         "-" for "no change".</LI>
 614
 615         <LI>Bits per color. In the example file, we define 8 bits per color, for
 616         a continuous-tone grayscale output. All versions of CUPS support 1 and
 617         8 bits per color.  CUPS 1.2 and higher (OS X 10.5 and higher) also
 618         supports 16 bits per color.</LI>
 619
 620         <LI>Rows per band. In the example file, we define 0 rows per band to
 621         indicate that our printer driver does not process the page in
 622         bands.</LI>
 623
 624         <LI>Row feed. In the example, we define the feed value to be 0 to
 625         indicate that our printer driver does not interleave the output.</LI>
 626
 627         <LI>Row step. In the example, we define the step value to be 0 to
 628         indicate that our printer driver does not interleave the output. This
 629         value normally indicates the spacing between the nozzles of an inkjet
 630         printer - when combined with the previous two values, it informs the
 631         driver how to stagger the output on the page to produce interleaved
 632         lines on the page for higher-resolution output.</LI>
 633
 634         <LI>Choice name and text. In the example, we define the choice name and
 635         text to be <TT>"600dpi/600 DPI"</TT>. The name and text are separated by
 636         slash (<TT>/</TT>) character; if no text is specified, then the name is
 637         used as the text. The PPD compiler parses the name to determine the
 638         actual resolution; the name can be of the form
 639         <TT><I>RESOLUTION</I>dpi</TT> for resolutions that are equal
 640         horizontally and vertically or <TT><I>HRES</I>x<I>VRES</I>dpi</TT> for
 641         isometric resolutions. Only integer resolution values are supported, so
 642         a resolution name of <TT>300dpi</TT> is valid while <TT>300.1dpi</TT> is
 643         not.</LI>
 644
 645 </OL>
 646
 647 <P>Finally, the <TT>PCFileName</TT> directive specifies that the named PPD file
 648 should be written for the current driver definitions:</P>
 649
 650 <pre class='example'>
 651 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 652 </pre>
 653
 654 <P>The filename follows the directive and <I>must</I> conform to the Adobe
 655 filename requirements in the Adobe Postscript Printer Description File Format
 656 Specification. Specifically, the filename may not exceed 8 characters followed
 657 by the extension <VAR>.ppd</VAR>. The <TT>FileName</TT> directive can be used to
 658 specify longer filenames:</P>
 659
 660 <pre class='example'>
 661 <a href='ref-ppdcfile.html#FileName'>FileName</a> "FooJet 2000"
 662 </pre>
 663
 664
 665 <h3><a name='GROUPING'>Grouping and Inheritance</a></h3>
 666
 667 <P>The previous example created a single PPD file. Driver information files can
 668 also define multiple printers by using the PPD compiler grouping functionality.
 669 Directives are grouped using the curly braces (<TT>{</TT> and <TT>}</TT>) and
 670 every group that uses the <TT>PCFileName</TT> or <TT>FileName</TT> directives
 671 produces a PPD file with that name. <A HREF="#LISTING2">Listing 2</A> shows a
 672 variation of the original example that uses two groups to define two printers
 673 that share the same printer driver filter but provide two different resolution
 674 options.</P>
 675
 676 <p class='example'><a name="LISTING2">Listing 2: "examples/grouping.drv"</a></p>
 677
 678 <pre class='example'>
 679
 680 <I>// Include standard font and media definitions</I>
 681 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 682 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 683
 684 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 685 <a href='ref-ppdcfile.html#Font'>Font</a> *
 686
 687 <I>// Manufacturer and version</I>
 688 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 689 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 690
 691 <I>// Each filter provided by the driver...</I>
 692 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 693
 694 <I>// Supported page sizes</I>
 695 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 696 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 697
 698 {
 699   <I>// Supported resolutions</I>
 700   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 701
 702   <I>// Specify the model name and filename...</I>
 703   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 704   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 705 }
 706
 707 {
 708   <I>// Supported resolutions</I>
 709   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "1200dpi/1200 DPI"
 710
 711   <I>// Specify the model name and filename...</I>
 712   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001"
 713   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojt2k1.ppd"
 714 }
 715 </pre>
 716
 717 <P>The second example is essentially the same as the first, except that each
 718 printer model is defined inside of a pair of curly braces. For example, the
 719 first printer is defined using:</P>
 720
 721 <pre class='example'>
 722 {
 723   // Supported resolutions
 724   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 725
 726   // Specify the model name and filename...
 727   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 728   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 729 }
 730 </pre>
 731
 732 <P>The printer <I>inherits</I> all of the definitions from the parent group (the
 733 top part of the file) and adds the additional definitions inside the curly
 734 braces for that printer driver. When we define the second group, it also
 735 inherits the same definitions from the parent group but <I>none</I> of the
 736 definitions from the first driver. Groups can be nested to any number of levels
 737 to support variations of similar models without duplication of information.</P>
 738
 739
 740 <h3><a name='COLOR'>Color Support</a></h3>
 741
 742 <P>For printer drivers that support color printing, the
 743 <TT>ColorDevice</TT> and <TT>ColorModel</TT> directives should be
 744 used to tell the printing system that color output is desired
 745 and in what formats. <A HREF="#LISTING3">Listing 3</A> shows a
 746 variation of the previous example which includes a color printer
 747 that supports printing at 300 and 600 DPI.</P>
 748
 749 <P>The key changes are the addition of the <TT>ColorDevice</TT>
 750 directive:</P>
 751
 752 <pre class='example'>
 753 <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true
 754 </pre>
 755
 756 <P>which tells the printing system that the printer supports
 757 color printing, and the <TT>ColorModel</TT> directives:</P>
 758
 759 <pre class='example'>
 760 <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0
 761 *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0
 762 </pre>
 763
 764 <P>which tell the printing system which colorspaces are supported by the printer
 765 driver for color printing. Each of the <TT>ColorModel</TT> directives is
 766 followed by the option name and text (<TT>Gray/Grayscale</TT> and
 767 <TT>RGB/Color</TT>), the colorspace name (<TT>w</TT> and <TT>rgb</TT>), the
 768 color organization (<TT>chunky</TT>), and the compression mode number
 769 (<TT>0</TT>) to be passed to the driver. The option name can be any of the
 770 standard Adobe <TT>ColorModel</TT> names:</P>
 771
 772 <UL>
 773
 774         <LI><TT>Gray</TT> - Grayscale output.
 775
 776         <LI><TT>RGB</TT> - Color output, typically using the RGB
 777         colorspace, but without a separate black channel.
 778
 779         <LI><TT>CMYK</TT> - Color output with a separate black
 780         channel.
 781
 782 </UL>
 783
 784 <P>Custom names can be used, however it is recommended that you use your vendor
 785 prefix for any custom names, for example "fooName".</P>
 786
 787 <P>The colorspace name can be any of the following universally supported
 788 colorspaces:</P>
 789
 790 <UL>
 791         <LI><TT>w</TT> - Luminance</LI>
 792
 793         <LI><TT>rgb</TT> - Red, green, blue</LI>
 794
 795         <LI><TT>k</TT> - Black</LI>
 796
 797         <LI><TT>cmy</TT> - Cyan, magenta, yellow</LI>
 798
 799         <LI><TT>cmyk</TT> - Cyan, magenta, yellow, black</LI>
 800
 801 </UL>
 802
 803 <P>The color organization can be any of the following values:</P>
 804
 805 <UL>
 806
 807         <LI><TT>chunky</TT> - Color values are passed together on a line
 808         as RGB RGB RGB RGB</LI>
 809
 810         <LI><TT>banded</TT> - Color values are passed separately
 811         on a line as RRRR GGGG BBBB; not supported by the Apple
 812         RIP filters</LI>
 813
 814         <LI><TT>planar</TT> - Color values are passed separately
 815         on a page as RRRR RRRR RRRR ... GGGG GGGG GGGG ... BBBB
 816         BBBB BBBB; not supported by the Apple RIP filters</LI>
 817
 818 </UL>
 819
 820 <P>The compression mode value is passed to the driver in the
 821 <TT>cupsCompression</TT> attribute. It is traditionally used to select an
 822 appropriate compression mode for the color model but can be used for any
 823 purpose, such as specifying a photo mode vs. standard mode.</P>
 824
 825 <p class='example'><a name="LISTING3">Listing 3: "examples/color.drv"</a></p>
 826
 827 <pre class='example'>
 828
 829 <I>// Include standard font and media definitions</I>
 830 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 831 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 832
 833 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 834 <a href='ref-ppdcfile.html#Font'>Font</a> *
 835
 836 <I>// Manufacturer and version</I>
 837 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 838 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 839
 840 <I>// Each filter provided by the driver...</I>
 841 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 842
 843 <I>// Supported page sizes</I>
 844 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 845 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 846
 847 {
 848   <I>// Supported resolutions</I>
 849   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 850
 851   <I>// Specify the model name and filename...</I>
 852   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 853   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 854 }
 855
 856 {
 857   <I>// Supports color printing</I>
 858   <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true
 859
 860   <I>// Supported colorspaces</I>
 861   <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0
 862   *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0
 863
 864   <I>// Supported resolutions</I>
 865   *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "300dpi/300 DPI"
 866   <a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI"
 867
 868   <I>// Specify the model name and filename...</I>
 869   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet Color"
 870   <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojetco.ppd"
 871 }
 872 </pre>
 873
 874
 875 <h3><a name='OPTIONS'>Defining Custom Options and Option Groups</a></h3>
 876
 877 <P>The <TT>Group</TT>, <TT>Option</TT>, and <TT>Choice</TT>
 878 directives are used to define or select a group, option, or
 879 choice. <A HREF="#LISTING4">Listing 4</A> shows a variation of
 880 the first example that provides two custom options in a group
 881 named "Footasm".</P>
 882
 883 <p class='example'><a name="LISTING4">Listing 4: "examples/custom.drv"</a></p>
 884
 885 <pre class='example'>
 886
 887 <I>// Include standard font and media definitions</I>
 888 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 889 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 890
 891 <I>// List the fonts that are supported, in this case all standard fonts...</I>
 892 <a href='ref-ppdcfile.html#Font'>Font</a> *
 893
 894 <I>// Manufacturer, model name, and version</I>
 895 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 896 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
 897 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 898
 899 <I>// Each filter provided by the driver...</I>
 900 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
 901
 902 <I>// Supported page sizes</I>
 903 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 904 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 905
 906 <I>// Supported resolutions</I>
 907 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
 908
 909 <I>// Option Group</I>
 910 <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm"
 911
 912   <I>// Boolean option</I>
 913   <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10
 914     *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "&lt;&lt;/cupsCompression 1&gt;&gt;setpagedevice"
 915     <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "&lt;&lt;/cupsCompression 0&gt;&gt;setpagedevice"
 916
 917   <I>// Multiple choice option</I>
 918   <a href='ref-ppdcfile.html#Option'>Option</a> "fooOutputType/Output Quality" PickOne AnySetup 10
 919     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "Auto/Automatic Selection"
 920             "&lt;&lt;/OutputType(Auto)&gt;&gt;setpagedevice""
 921     <a href='ref-ppdcfile.html#Choice'>Choice</a> "Text/Optimize for Text"
 922             "&lt;&lt;/OutputType(Text)&gt;&gt;setpagedevice""
 923     <a href='ref-ppdcfile.html#Choice'>Choice</a> "Graph/Optimize for Graphics"
 924             "&lt;&lt;/OutputType(Graph)&gt;&gt;setpagedevice""
 925     <a href='ref-ppdcfile.html#Choice'>Choice</a> "Photo/Optimize for Photos"
 926             "&lt;&lt;/OutputType(Photo)&gt;&gt;setpagedevice""
 927
 928 <I>// Specify the name of the PPD file we want to generate...</I>
 929 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
 930 </pre>
 931
 932 <P>The custom group is introduced by the <TT>Group</TT>
 933 directive which is followed by the name and optionally text for
 934 the user:</P>
 935
 936 <pre class='example'>
 937 <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm/Footastic Options"
 938 </pre>
 939
 940 <P>The group name must conform to the PPD specification and
 941 cannot exceed 40 characters in length. If you specify user text,
 942 it cannot exceed 80 characters in length. The groups
 943 <TT>General</TT>, <TT>Extra</TT>, and
 944 <TT>InstallableOptions</TT> are predefined by CUPS; the general
 945 and extra groups are filled by the UI options defined by the PPD
 946 specification. The <TT>InstallableOptions</TT> group is reserved
 947 for options that define whether accessories for the printer
 948 (duplexer unit, finisher, stapler, etc.) are installed.</P>
 949
 950 <P>Once the group is specified, the <TT>Option</TT> directive is
 951 used to introduce a new option:</P>
 952
 953 <pre class='example'>
 954 <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10
 955 </pre>
 956
 957 <P>The directive is followed by the name of the option and any
 958 optional user text, the option type, the PostScript document group, and
 959 the sort order number. The option name must conform to the PPD specification
 960 and cannot exceed 40 characters in length. If you specify user text, it
 961 cannot exceed 80 characters in length.</P>
 962
 963 <P>The option type can be <TT>Boolean</TT> for true/false
 964 selections, <TT>PickOne</TT> for picking one of many choices, or
 965 <TT>PickMany</TT> for picking zero or more choices. Boolean
 966 options can have at most two choices with the names
 967 <TT>False</TT> and <TT>True</TT>. Pick options can have any
 968 number of choices, although for Windows compatibility reasons
 969 the number of choices should not exceed 255.</P>
 970
 971 <P>The PostScript document group is typically <TT>AnySetup</TT>,
 972 meaning that the option can be introduced at any point in the
 973 PostScript document. Other values include <TT>PageSetup</TT> to
 974 include the option before each page and <TT>DocumentSetup</TT>
 975 to include the option once at the beginning of the document.</P>
 976
 977 <P>The sort order number is used to sort the printer commands
 978 associated with each option choice within the PostScript
 979 document. This allows you to setup certain options before others
 980 as required by the printer. For most CUPS raster printer
 981 drivers, the value <TT>10</TT> can be used for all options.</P>
 982
 983 <P>Once the option is specified, each option choice can be
 984 listed using the <TT>Choice</TT> directive:</P>
 985
 986 <pre class='example'>
 987 *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "&lt;&lt;/cupsCompression 1&gt;&gt;setpagedevice"
 988 <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "&lt;&lt;/cupsCompression 0&gt;&gt;setpagedevice"
 989 </pre>
 990
 991 <P>The directive is followed by the choice name and optionally
 992 user text, and the PostScript commands that should be inserted
 993 when printing a file to this printer. The option name must
 994 conform to the PPD specification and cannot exceed 40 characters
 995 in length. If you specify user text, it cannot exceed 80
 996 characters in length.</P>
 997
 998 <P>The PostScript commands are also interpreted by any RIP
 999 filters, so these commands typically must be present for all
1000 option choices. Most commands take the form:</P>
1001
1002 <pre class='example'>
1003 &lt;&lt;/name value&gt;&gt;setpagedevice
1004 </pre>
1005
1006 <P>where <TT>name</TT> is the name of the PostScript page device
1007 attribute and <TT>value</TT> is the numeric or string value for
1008 that attribute.</P>
1009
1010
1011 <h3><a name='DEFINE'>Defining Constants</a></h3>
1012
1013 <P>Sometimes you will want to define constants for your drivers
1014 so that you can share values in different groups within the same
1015 driver information file, or to share values between different
1016 driver information files using the <TT>#include</TT> directive.
1017 The <TT>#define</TT> directive is used to define constants for
1018 use in your printer definitions:</P>
1019
1020 <pre class='example'>
1021 <a href='ref-ppdcfile.html#_define'>#define</a> NAME value
1022 </pre>
1023
1024 <P>The <TT>NAME</TT> is any sequence of letters, numbers, and
1025 the underscore. The <TT>value</TT> is a number or string; if the
1026 value contains spaces you must put double quotes around it, for
1027 example:</P>
1028
1029 <pre class='example'>
1030 <a href='ref-ppdcfile.html#_define'>#define</a> FOO "My String Value"
1031 </pre>
1032
1033 <P>Constants can also be defined on the command-line using the <tt>-D</tt>
1034 option:</P>
1035
1036 <pre class='command'>
1037 ppdc -DNAME="value" filename.drv
1038 </pre>
1039
1040 <P>Once defined, you use the notation <TT>$NAME</TT> to substitute the value of
1041 the constant in the file, for example:</P>
1042
1043 <pre class='example'>
1044 <a href='ref-ppdcfile.html#_define'>#define</a> MANUFACTURER "Foo"
1045 <a href='ref-ppdcfile.html#_define'>#define</a> FOO_600      0
1046 <a href='ref-ppdcfile.html#_define'>#define</a> FOO_1200     1
1047
1048 {
1049   <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER"
1050   <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_600
1051   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
1052   ...
1053 }
1054
1055 {
1056   <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER"
1057   <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_1200
1058   <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001"
1059   ...
1060 }
1061 </pre>
1062
1063 <P>Numeric constants can be bitwise OR'd together by placing the constants
1064 inside parenthesis, for example:</P>
1065
1066 <pre class='example'>
1067 <I>// ModelNumber capability bits</I>
1068 <a href='ref-ppdcfile.html#_define'>#define</a> DUPLEX 1
1069 <a href='ref-ppdcfile.html#_define'>#define</a> COLOR  2
1070
1071 ...
1072
1073 {
1074   <I>// Define a model number specifying the capabilities of the printer...</I>
1075   <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($DUPLEX $COLOR)
1076   ...
1077 }
1078 </pre>
1079
1080
1081 <h3><a name='CONDITIONAL'>Conditional Statements</a></h3>
1082
1083 <p>The PPD compiler supports conditional compilation using the <tt>#if</tt>,
1084 <tt>#elif</tt>, <tt>#else</tt>, and <tt>#endif</tt> directives. The <tt>#if</tt>
1085 and <tt>#elif</tt> directives are followed by a constant name or an expression.
1086 For example, to include a group of options when "ADVANCED" is defined:</p>
1087
1088 <pre class='example'>
1089 <a href='ref-ppdcfile.html#_if'>#if</a> ADVANCED
1090 <a href='ref-ppdcfile.html#Group'>Group</a> "Advanced/Advanced Options"
1091   <a href='ref-ppdcfile.html#Option'>Option</a> "fooCyanAdjust/Cyan Adjustment"
1092     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1093     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1094     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1095     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1096     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1097   <a href='ref-ppdcfile.html#Option'>Option</a> "fooMagentaAdjust/Magenta Adjustment"
1098     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1099     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1100     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1101     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1102     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1103   <a href='ref-ppdcfile.html#Option'>Option</a> "fooYellowAdjust/Yellow Adjustment"
1104     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1105     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1106     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1107     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1108     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1109   <a href='ref-ppdcfile.html#Option'>Option</a> "fooBlackAdjust/Black Adjustment"
1110     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" ""
1111     <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" ""
1112     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" ""
1113     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" ""
1114     <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" ""
1115 <a href='ref-ppdcfile.html#_endif'>#endif</a>
1116 </pre>
1117
1118
1119 <h3><a name='CONSTRAINTS'>Defining Constraints</a></h3>
1120
1121 <P>Constraints are strings that are used to specify that one or more option
1122 choices are incompatible, for example two-sided printing on transparency media.
1123 Constraints are also used to prevent the use of uninstalled features such as the
1124 duplexer unit, additional media trays, and so forth.</P>
1125
1126 <P>The <TT>UIConstraints</TT> directive is used to specify a constraint that is
1127 placed in the PPD file. The directive is followed by a string using one of the
1128 following formats:</P>
1129
1130 <pre class='example'>
1131 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2"
1132 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2"
1133 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2 Choice2"
1134 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2 Choice2"
1135 </pre>
1136
1137 <P>Each option name is preceded by the asterisk (<TT>*</TT>). If no choice is
1138 given for an option, then all choices <I>except</I> <TT>False</TT> and
1139 <TT>None</TT> will conflict with the other option and choice(s). Since the PPD
1140 compiler automatically adds reciprocal constraints (option A conflicts with
1141 option B, so therefore option B conflicts with option A), you need only specify
1142 the constraint once.</P>
1143
1144 <p class='example'><a name="LISTING5">Listing 5: "examples/constraint.drv"</a></p>
1145
1146 <pre class='example'>
1147
1148 <I>// Include standard font and media definitions</I>
1149 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
1150 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
1151
1152 <I>// List the fonts that are supported, in this case all standard fonts...</I>
1153 <a href='ref-ppdcfile.html#Font'>Font</a> *
1154
1155 <I>// Manufacturer, model name, and version</I>
1156 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
1157 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000"
1158 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
1159
1160 <I>// Each filter provided by the driver...</I>
1161 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo
1162
1163 <I>// Supported page sizes</I>
1164 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
1165 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
1166
1167 <I>// Supported resolutions</I>
1168 *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI"
1169
1170 <I>// Installable Option Group</I>
1171 <a href='ref-ppdcfile.html#Group'>Group</a> "InstallableOptions/Options Installed"
1172
1173   <I>// Duplexing unit option</I>
1174   <a href='ref-ppdcfile.html#Option'>Option</a> "OptionDuplexer/Duplexing Unit" Boolean AnySetup 10
1175     <a href='ref-ppdcfile.html#Choice'>Choice</a> True/Installed ""
1176     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "False/Not Installed" ""
1177
1178 <I>// General Option Group</I>
1179 <a href='ref-ppdcfile.html#Group'>Group</a> General
1180
1181   <I>// Duplexing option</I>
1182   <a href='ref-ppdcfile.html#Option'>Option</a> "Duplex/Two-Sided Printing" PickOne AnySetup 10
1183     *<a href='ref-ppdcfile.html#Choice'>Choice</a> "None/No" "&lt;&lt;/Duplex false&gt;&gt;setpagedevice""
1184     <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexNoTumble/Long Edge Binding"
1185            "&lt;&lt;/Duplex true/Tumble false&gt;&gt;setpagedevice""
1186     <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexTumble/Short Edge Binding"
1187            "&lt;&lt;/Duplex true/Tumble true&gt;&gt;setpagedevice""
1188
1189 <I>// Only allow duplexing if the duplexer is installed</I>
1190 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False"
1191
1192 <I>// Specify the name of the PPD file we want to generate...</I>
1193 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd"
1194 </pre>
1195
1196 <P><A HREF="#LISTING5">Listing 5</A> shows a variation of the first example with
1197 an added <TT>Duplex</TT> option and installable option for the duplexer,
1198 <TT>OptionDuplex</TT>. A constraint is added at the end to specify that any
1199 choice of the <TT>Duplex</TT> option that is not <TT>None</TT> is incompatible
1200 with the "Duplexer Installed" option set to "Not Installed"
1201 (<TT>False</TT>):</P>
1202
1203 <pre class='example'>
1204 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False"
1205 </pre>
1206
1207 <h4>Enhanced Constraints</h4>
1208
1209 <p>CUPS 1.4 supports constraints between 2 or more options using the
1210 <TT>Attribute</TT> directive. <TT>cupsUIConstraints</TT> attributes define
1211 the constraints, while <TT>cupsUIResolver</TT> attributes define option changes
1212 to resolve constraints. For example, we can specify the previous duplex
1213 constraint with a resolver that turns off duplexing with the following two
1214 lines:</p>
1215
1216 <pre class='example'>
1217 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIConstraints DuplexOff "*Duplex *OptionDuplexer False"
1218 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIResolver DuplexOff "*Duplex None"
1219 </pre>
1220
1221 <h2 class='title'><a name='LOCALIZATION'>Localization</a></h2>
1222
1223 <p>The PPD compiler provides localization of PPD files in different languages
1224 through <i>message catalog</i> files in the GNU gettext or Apple .strings
1225 formats. Each user text string and several key PPD attribute values such as
1226 <tt>LanguageVersion</tt> and <tt>LanguageEncoding</tt> are looked up in the
1227 corresponding message catalog and the translated text is substituted in the
1228 generated PPD files. One message catalog file can be used by multiple driver
1229 information files, and each file contains a single language translation.</p>
1230
1231 <h3><a name='PPDPO'>The ppdpo Utility</a></h3>
1232
1233 <p>While CUPS includes localizations of all standard media sizes and options in
1234 several languages, your driver information files may provide their own media
1235 sizes and options that need to be localized. CUPS provides a utility program to
1236 aid in the localization of drivers called <a
1237 href='man-ppdpo.html'><tt>ppdpo(1)</tt></a>. The <tt>ppdpo</tt> program creates
1238 or updates a message catalog file based upon one or more driver information
1239 files. New messages are added with the word "TRANSLATE" added to the front of
1240 the translation string to make locating new strings for translation easier. The
1241 program accepts the message catalog filename and one or more driver information
1242 files.</p>
1243
1244 <p>For example, run the following command to create a new German message catalog
1245 called <var>de.po</var> for all of the driver information files in the current
1246 directory:</p>
1247
1248 <pre class='command'>
1249 ppdpo -o de.po *.drv
1250 </pre>
1251
1252 <p>If the file <var>de.po</var> already exists, <tt>ppdpo</tt> will update the
1253 contents of the file with any new messages that need to be translated. To create
1254 an Apple .strings file instead, specify the output filename with a .strings
1255 extension, for example:</p>
1256
1257 <pre class='command'>
1258 ppdpo -o de.strings *.drv
1259 </pre>
1260
1261 <h3><a name='PPDC_CATALOG'>Using Message Catalogs with the PPD Compiler</a></h3>
1262
1263 <p>Once you have created a message catalog, use the <a
1264 href='ref-ppdcfile.html#_po'><tt>#po</tt></a> directive to declare it in each
1265 driver information file. For example, to declare the German message catalog for
1266 a driver use:</p>
1267
1268 <pre class='example'>
1269 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po"  // German
1270 </pre>
1271
1272 <p>In fact, you can use the <tt>#po</tt> directive as many times as needed:</p>
1273
1274 <pre class='example'>
1275 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po"  // German
1276 <a href='ref-ppdcfile.html#_po'>#po</a> es "es.po"  // Spanish
1277 <a href='ref-ppdcfile.html#_po'>#po</a> fr "fr.po"  // French
1278 <a href='ref-ppdcfile.html#_po'>#po</a> it "it.po"  // Italian
1279 <a href='ref-ppdcfile.html#_po'>#po</a> ja "ja.po"  // Japanese
1280 </pre>
1281
1282 <p>The filename ("de.po", etc.) can be relative to the location of the driver
1283 information file or an absolute path. Once defined, the PPD compiler will
1284 automatically generate a globalized PPD for every language declared in your
1285 driver information file. To generate a single-language PPD file, simply use the
1286 <tt>-l</tt> option to list the corresponding locale, for example:</p>
1287
1288 <pre class='command'>
1289 ppdc -l de -d ppd/de mydrivers.drv
1290 </pre>
1291
1292 <p>to generate German PPD files.</p>
1293 </div>
1294 </body>
1295 </html>