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