doc/help/postscript-driver.html

   1 <!DOCTYPE html>
   2 <html>
   3 <!-- SECTION: Programming -->
   4   <head>
   5     <title>Developing PostScript Printer Drivers</title>
   6     <meta name="keywords" content="Programming">
   7     <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
   8     <meta name="creator" content="codedoc v3.1">
   9     <meta name="author" content="Unknown">
  10     <meta name="copyright" content="Unknown">
  11     <meta name="version" content="0.0">
  12     <style type="text/css"><!--
  13 BODY {
  14   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  15 }
  16
  17 H1, H2, H3, H4, H5, H6, P, TD, TH {
  18   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  19 }
  20
  21 H1 { font-size: 2em; }
  22 H2 { font-size: 1.75em; }
  23 H3 { font-size: 1.5em; }
  24 H4 { font-size: 1.25em; }
  25
  26 KBD {
  27   font-family: monaco, courier, monospace;
  28   font-weight: bold;
  29 }
  30
  31 PRE {
  32   font-family: monaco, courier, monospace;
  33 }
  34
  35 BLOCKQUOTE {
  36   border-left: solid 2px #777;
  37   margin: 1em 0;
  38   padding: 10px;
  39 }
  40
  41 BLOCKQUOTE OL LI {
  42   margin-left: -1em;
  43 }
  44
  45 PRE.command, PRE.example {
  46   background: #eee;
  47   margin: 0 36pt;
  48   padding: 10px;
  49 }
  50
  51 P.compact {
  52   margin: 0;
  53 }
  54
  55 P.example {
  56   font-style: italic;
  57   margin-left: 36pt;
  58 }
  59
  60 DL.man DD {
  61   margin-left: 5em;
  62 }
  63
  64 DL.man DT {
  65   margin-left: 0;
  66 }
  67
  68 PRE.man {
  69   margin: 0;
  70 }
  71
  72 PRE.command EM, PRE.example EM {
  73   font-family: lucida grande, geneva, helvetica, arial, sans-serif;
  74 }
  75
  76 P.command {
  77   font-family: monaco, courier, monospace;
  78   margin-left: 36pt;
  79 }
  80
  81 P.formula {
  82   font-style: italic;
  83   margin-left: 36pt;
  84 }
  85
  86 A IMG {
  87   border: none;
  88 }
  89
  90 A:link:hover IMG {
  91   background: #f0f0f0;
  92   border-radius: 10px;
  93   -moz-border-radius: 10px;
  94 }
  95
  96 A:link, A:visited {
  97   font-weight: inherit;
  98   text-decoration: none;
  99 }
 100
 101 A:link:hover, A:visited:hover, A:active {
 102   text-decoration: underline;
 103 }
 104
 105 SUB, SUP {
 106   font-size: 50%;
 107 }
 108
 109 TR.data, TD.data, TR.data TD {
 110   margin-top: 10pt;
 111   padding: 5pt;
 112   border-bottom: solid 1pt #999999;
 113 }
 114
 115 TR.data TH {
 116   border-bottom: solid 1pt #999999;
 117   padding-top: 10pt;
 118   padding-left: 5pt;
 119   text-align: left;
 120 }
 121
 122 DIV.table TABLE {
 123   border: solid thin #999999;
 124   border-collapse: collapse;
 125   border-spacing: 0;
 126   margin-left: auto;
 127   margin-right: auto;
 128 }
 129
 130 DIV.table CAPTION {
 131   caption-side: top;
 132   font-size: 120%;
 133   font-style: italic;
 134   font-weight: bold;
 135   margin-left: auto;
 136   margin-right: auto;
 137 }
 138
 139 DIV.table TABLE TD {
 140   border: solid thin #cccccc;
 141   padding: 5pt 10pt 0;
 142 }
 143
 144 DIV.table TABLE TH {
 145   background: #cccccc;
 146   border: none;
 147   border-bottom: solid thin #999999;
 148 }
 149
 150 DIV.figure TABLE {
 151   margin-left: auto;
 152   margin-right: auto;
 153 }
 154
 155 DIV.figure CAPTION {
 156   caption-side: bottom;
 157   font-size: 120%;
 158   font-style: italic;
 159   font-weight: bold;
 160   margin-left: auto;
 161   margin-right: auto;
 162 }
 163
 164 TH.label {
 165   text-align: right;
 166   vertical-align: top;
 167 }
 168
 169 TH.sublabel {
 170   text-align: right;
 171   font-weight: normal;
 172 }
 173
 174 HR {
 175   border: solid thin;
 176 }
 177
 178 SPAN.info {
 179   background: black;
 180   border: thin solid black;
 181   color: white;
 182   font-size: 80%;
 183   font-style: italic;
 184   font-weight: bold;
 185   white-space: nowrap;
 186 }
 187
 188 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
 189   float: right;
 190   font-size: 100%;
 191 }
 192
 193 H1.title {
 194 }
 195
 196 H2.title, H3.title {
 197   border-bottom: solid 2pt #000000;
 198 }
 199
 200 DIV.indent, TABLE.indent {
 201   margin-top: 2em;
 202   margin-left: auto;
 203   margin-right: auto;
 204   width: 90%;
 205 }
 206
 207 TABLE.indent {
 208   border-collapse: collapse;
 209 }
 210
 211 TABLE.indent TD, TABLE.indent TH {
 212   padding: 0;
 213 }
 214
 215 TABLE.list {
 216   border-collapse: collapse;
 217   margin-left: auto;
 218   margin-right: auto;
 219   width: 90%;
 220 }
 221
 222 TABLE.list TH {
 223   background: white;
 224   border-bottom: solid thin #cccccc;
 225   color: #444444;
 226   padding-top: 10pt;
 227   padding-left: 5pt;
 228   text-align: left;
 229   vertical-align: bottom;
 230   white-space: nowrap;
 231 }
 232
 233 TABLE.list TH A {
 234   color: #4444cc;
 235 }
 236
 237 TABLE.list TD {
 238   border-bottom: solid thin #eeeeee;
 239   padding-top: 5pt;
 240   padding-left: 5pt;
 241 }
 242
 243 TABLE.list TR:nth-child(even) {
 244   background: #f8f8f8;
 245 }
 246
 247 TABLE.list TR:nth-child(odd) {
 248   background: #f4f4f4;
 249 }
 250
 251 DT {
 252   margin-left: 36pt;
 253   margin-top: 12pt;
 254 }
 255
 256 DD {
 257   margin-left: 54pt;
 258 }
 259
 260 DL.category DT {
 261   font-weight: bold;
 262 }
 263
 264 P.summary {
 265   margin-left: 36pt;
 266   font-family: monaco, courier, monospace;
 267 }
 268
 269 DIV.summary TABLE {
 270   border: solid thin #999999;
 271   border-collapse: collapse;
 272   border-spacing: 0;
 273   margin: 10px;
 274 }
 275
 276 DIV.summary TABLE TD, DIV.summary TABLE TH {
 277   border: solid thin #999999;
 278   padding: 5px;
 279   text-align: left;
 280   vertical-align: top;
 281 }
 282
 283 DIV.summary TABLE THEAD TH {
 284   background: #eeeeee;
 285 }
 286
 287 /* API documentation styles... */
 288 div.body h1 {
 289   font-size: 250%;
 290   font-weight: bold;
 291   margin: 0;
 292 }
 293 div.body h2 {
 294   font-size: 250%;
 295   margin-top: 1.5em;
 296 }
 297 div.body h3 {
 298   font-size: 150%;
 299   margin-bottom: 0.5em;
 300   margin-top: 1.5em;
 301 }
 302 div.body h4 {
 303   font-size: 110%;
 304   margin-bottom: 0.5em;
 305   margin-top: 1.5em;
 306 }
 307 div.body h5 {
 308   font-size: 100%;
 309   margin-bottom: 0.5em;
 310   margin-top: 1.5em;
 311 }
 312 div.contents {
 313   background: #e8e8e8;
 314   border: solid thin black;
 315   padding: 10px;
 316 }
 317 div.contents h1 {
 318   font-size: 110%;
 319 }
 320 div.contents h2 {
 321   font-size: 100%;
 322 }
 323 div.contents ul.contents {
 324   font-size: 80%;
 325 }
 326 .class {
 327   border-bottom: solid 2px gray;
 328 }
 329 .constants {
 330 }
 331 .description {
 332   margin-top: 0.5em;
 333 }
 334 .discussion {
 335 }
 336 .enumeration {
 337   border-bottom: solid 2px gray;
 338 }
 339 .function {
 340   border-bottom: solid 2px gray;
 341   margin-bottom: 0;
 342 }
 343 .members {
 344 }
 345 .method {
 346 }
 347 .parameters {
 348 }
 349 .returnvalue {
 350 }
 351 .struct {
 352   border-bottom: solid 2px gray;
 353 }
 354 .typedef {
 355   border-bottom: solid 2px gray;
 356 }
 357 .union {
 358   border-bottom: solid 2px gray;
 359 }
 360 .variable {
 361 }
 362 h1, h2, h3, h4, h5, h6 {
 363   page-break-inside: avoid;
 364 }
 365 blockquote {
 366   border: solid thin gray;
 367   box-shadow: 3px 3px 5px rgba(0,0,0,0.5);
 368   padding: 10px 10px 0px;
 369   page-break-inside: avoid;
 370 }
 371 p code, li code, p.code, pre, ul.code li {
 372   background: rgba(127,127,127,0.1);
 373   border: thin dotted gray;
 374   font-family: monospace;
 375   hyphens: manual;
 376   -webkit-hyphens: manual;
 377   page-break-inside: avoid;
 378 }
 379 p.code, pre, ul.code li {
 380   padding: 10px;
 381 }
 382 p code, li code {
 383   padding: 2px 5px;
 384 }
 385 a:link, a:visited {
 386   text-decoration: none;
 387 }
 388 span.info {
 389   background: black;
 390   border: solid thin black;
 391   color: white;
 392   font-size: 80%;
 393   font-style: italic;
 394   font-weight: bold;
 395   white-space: nowrap;
 396 }
 397 h2 span.info, h3 span.info, h4 span.info {
 398   border-radius: 10px;
 399   float: right;
 400   font-size: 80%;
 401   padding: 3px 6px;
 402 }
 403 h2.title span.info, h3.title span.info, h4.title span.info {
 404   border-bottom-left-radius: 0px;
 405   border-bottom-right-radius: 0px;
 406 }
 407 h2.title span.info {
 408   padding: 4px 6px;
 409 }
 410 ul.code, ul.contents, ul.subcontents {
 411   list-style-type: none;
 412   margin: 0;
 413   padding-left: 0;
 414 }
 415 ul.code li {
 416   margin: 0;
 417 }
 418 ul.contents > li {
 419   margin-top: 1em;
 420 }
 421 ul.contents li ul.code, ul.contents li ul.subcontents {
 422   padding-left: 2em;
 423 }
 424 table.list {
 425   border-collapse: collapse;
 426   width: 100%;
 427 }
 428 table.list tr:nth-child(even) {
 429   background: rgba(127,127,127,0.1);]n}
 430 table.list th {
 431   border-right: 2px solid gray;
 432   font-family: monospace;
 433   padding: 5px 10px 5px 2px;
 434   text-align: right;
 435   vertical-align: top;
 436 }
 437 table.list td {
 438   padding: 5px 2px 5px 10px;
 439   text-align: left;
 440   vertical-align: top;
 441 }
 442 h1.title {
 443 }
 444 h2.title {
 445   border-bottom: solid 2px black;
 446 }
 447 h3.title {
 448   border-bottom: solid 2px black;
 449 }
 450 --></style>
 451   </head>
 452   <body>
 453 <!--
 454   PostScript printer driver documentation for CUPS.
 455
 456   Copyright © 2007-2012 by Apple Inc.
 457   Copyright © 1997-2007 by Easy Software Products.
 458
 459   Licensed under Apache License v2.0.  See the file "LICENSE" for more
 460   information.
 461 -->
 462
 463 <h1 class='title'>Developing PostScript Printer Drivers</h1>
 464
 465 <p>This document describes how to develop printer drivers for PostScript printers. Topics include: <a href='#BASICS'>printer driver basics</a>, <a href='#CREATE'>creating new PPD files</a>, <a href='#IMPORT'>importing existing PPD files</a>, <a href='#FILTERS'>using custom filters</a>, <a href='#COLOR'>implementing color management</a>, and <a href='#MACOSX'>adding macOS features</a>.</p>
 466
 467 <div class='summary'><table summary='General Information'>
 468 <tbody>
 469 <tr>
 470         <th>See Also</th>
 471         <td>Programming: <a href='raster-driver.html'>Developing Raster Printer Drivers</a><br>
 472         Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br>
 473         Programming: <a href='ppd-compiler.html'>Introduction to the PPD Compiler</a><br>
 474         Programming: <a href='api-raster.html'>Raster API</a><br>
 475         References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br>
 476         Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td>
 477 </tr>
 478 </tbody>
 479 </table></div>
 480     <div class="contents">
 481       <h2 class="title">Contents</h2>
 482       <ul class="contents">
 483         <li><a href="#BASICS">Printer Driver Basics</a></li>
 484         <li><a href="#CREATING">Creating New PPD Files</a><ul class="subcontents">
 485           <li><a href="#IMPORT">Importing Existing PPD Files</a></li>
 486         </ul></li>
 487         <li><a href="#FILTERS">Using Custom Filters</a></li>
 488         <li><a href="#COLOR">Implementing Color Management</a></li>
 489         <li><a href="#MACOSX">Adding macOS Features</a></li>
 490       </ul>
 491     </div>
 492     <div class="body">
 493 <h2 class='title'><a name='BASICS'>Printer Driver Basics</a></h2>
 494
 495 <p>A CUPS PostScript printer driver consists of a PostScript Printer Description (PPD) file that describes the features and capabilities of the device, zero or more <em>filter</em> programs that prepare print data for the device, and zero or more support files for color management, online help, and so forth. The PPD file includes references to all of the filters and support files used by the driver.</p>
 496
 497 <p>Every time a user prints something the scheduler program, <a href='man-cupsd.html'>cupsd(8)</a>, determines the format of the print job and the programs required to convert that job into something the printer understands. CUPS includes filter programs for many common formats, for example to convert Portable Document Format (PDF) files into device-independent PostScript, and then from device-independent PostScript to device-dependent PostScript. <a href='#FIGURE_1'>Figure 1</a> shows the data flow of a typical print job.</p>
 498
 499 <div class='figure'><table summary='PostScript Filter Chain'>
 500 <caption>Figure 1: <a name='FIGURE_1'>PostScript Filter Chain</a></caption>
 501 <tr><td><img src='../images/cups-postscript-chain.png' width='700' height='150' alt='PostScript Filter Chain'></td></tr>
 502 </table></div>
 503
 504 <p>The optional PostScript filter can be provided to add printer-specific commands to the PostScript output that cannot be represented in the PPD file or to reorganize the output for special printer features. Typically this is used to support advanced job management or finishing functions on the printer. CUPS includes a generic PostScript filter that handles all PPD-defined commands.</p>
 505
 506 <p>The optional port monitor handles interface-specific protocol or encoding issues. For example, many PostScript printers support the Binary Communications Protocol (BCP) and Tagged Binary Communications Protocol (TBCP) to allow applications to print 8-bit ("binary") PostScript jobs. CUPS includes port monitors for BCP and TBCP, and you can supply your own port monitors as needed.</p>
 507
 508 <p>The backend handles communications with the printer, sending print data from the last filter to the printer and relaying back-channel data from the printer to the upstream filters. CUPS includes backend programs for common direct-connect interfaces and network protocols, and you can provide your own backend to support custom interfaces and protocols.</p>
 509
 510 <p>The scheduler also supports a special "command" file format for sending maintenance commands and status queries to a printer or printer driver. Command print jobs typically use a single command filter program defined in the PPD file to generate the appropriate printer commands and handle any responses from the printer. <a href='#FIGURE_2'>Figure 2</a> shows the data flow of a typical command job.</p>
 511
 512 <div class='figure'><table summary='Command Filter Chain'>
 513 <caption>Figure 2: <a name='FIGURE_2'>Command Filter Chain</a></caption>
 514 <tr><td><img src='../images/cups-command-chain.png' width='575' height='150' alt='Command Filter Chain'></td></tr>
 515 </table></div>
 516
 517 <p>PostScript printer drivers typically do not require their own command filter since CUPS includes a generic PostScript command filter that supports all of the standard functions using PPD-defined commands.</p>
 518
 519
 520 <h2 class='title'><a name='CREATING'>Creating New PPD Files</a></h2>
 521
 522 <p>We recommend using the CUPS PPD compiler, <a href='man-ppdc.html'>ppdc(1)</a>, to create new PPD files since it manages many of the tedious (and error-prone!) details of paper sizes and localization for you. It also allows you to easily support multiple devices from a single source file. For more information see the "<a href='ppd-compiler.html'>Introduction to the PPD Compiler</a>" document. <a href='#LISTING_1'>Listing 1</a> shows a driver information file for a black-and-white PostScript printer.</p>
 523
 524 <p class='example'>Listing 1: <a name='LISTING_1'>"examples/postscript.drv"</a></p>
 525
 526 <pre class='example'>
 527 // Include standard font and media definitions
 528 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;font.defs&gt;
 529 <a href='ref-ppdcfile.html#_include'>#include</a> &lt;media.defs&gt;
 530
 531 // Specify this is a PostScript printer driver
 532 <a href='ref-ppdcfile.html#DriverType'>DriverType</a> ps
 533
 534 // List the fonts that are supported, in this case all standard fonts
 535 <a href='ref-ppdcfile.html#Font'>Font</a> *
 536
 537 // Manufacturer, model name, and version
 538 <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo"
 539 <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "Foo LaserProofer 2000"
 540 <a href='ref-ppdcfile.html#Version'>Version</a> 1.0
 541
 542 // PostScript printer attributes
 543 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> DefaultColorSpace "" Gray
 544 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LandscapeOrientation "" Minus90
 545 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LanguageLevel "" "3"
 546 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> Product "" "(Foo LaserProofer 2000)"
 547 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> PSVersion "" "(3010) 0"
 548 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> TTRasterizer "" Type42
 549
 550 // Supported page sizes
 551 *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter
 552 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Legal
 553 <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4
 554
 555 // Query command for page size
 556 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> "?PageSize" "" "
 557       save
 558       currentpagedevice /PageSize get aload pop
 559       2 copy gt {exch} if (Unknown)
 560       23 dict
 561               dup [612 792] (Letter) put
 562               dup [612 1008] (Legal) put
 563               dup [595 842] (A4) put
 564               {exch aload pop 4 index sub abs 5 le exch
 565                5 index sub abs 5 le and
 566               {exch pop exit} {pop} ifelse
 567       } bind forall = flush pop pop
 568       restore"
 569
 570 // Specify the name of the PPD file we want to generate
 571 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "fooproof.ppd"
 572 </pre>
 573
 574 <h3>Required Attributes</h3>
 575
 576 <p>PostScript drivers require the attributes listed in <a href='#TABLE_1'>Table 1</a>. If not specified, the defaults for CUPS drivers are used. A typical PostScript driver information file would include the following attributes:</p>
 577
 578 <pre class='example'>
 579 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> DefaultColorSpace "" Gray
 580 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LandscapeOrientation "" Minus90
 581 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> LanguageLevel "" "3"
 582 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> Product "" "(Foo LaserProofer 2000)"
 583 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> PSVersion "" "(3010) 0"
 584 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> TTRasterizer "" Type42
 585 </pre>
 586
 587 <div class='table'><table summary='Required PostScript Printer Driver Attributes'>
 588 <caption>Table 1: <a name='TABLE_1'>Required PostScript Printer Driver Attributes</a></caption>
 589 <thead>
 590 <tr>
 591         <th>Attribute</th>
 592         <th>Description</th>
 593 </tr>
 594 </thead>
 595 <tbody>
 596 <tr>
 597         <td><tt>DefaultColorSpace</tt></td>
 598         <td>The default colorspace:
 599         <tt>Gray</tt>, <tt>RGB</tt>, <tt>CMY</tt>, or
 600         <tt>CMYK</tt>. If not specified, then <tt>RGB</tt> is
 601         assumed.</td>
 602 </tr>
 603 <tr>
 604         <td><tt>LandscapeOrientation</tt></td>
 605         <td>The preferred landscape
 606         orientation: <tt>Plus90</tt>, <tt>Minus90</tt>, or
 607         <tt>Any</tt>. If not specified, <tt>Plus90</tt> is
 608         assumed.</td>
 609 </tr>
 610 <tr>
 611         <td><tt>LanguageLevel</tt></td>
 612         <td>The PostScript language
 613         level supported by the device: 1, 2, or 3. If not
 614         specified, 2 is assumed.</td>
 615 </tr>
 616 <tr>
 617         <td><tt>Product</tt></td>
 618         <td>The string returned by
 619         the PostScript <tt>product</tt> operator, which
 620         <i>must</i> include parenthesis to conform with
 621         PostScript syntax rules for strings. Multiple
 622         <tt>Product</tt> attributes may be specified to support
 623         multiple products with the same PPD file. If not
 624         specified, "(ESP Ghostscript)" and "(GNU Ghostscript)"
 625         are assumed.</td>
 626 </tr>
 627 <tr>
 628         <td><tt>PSVersion</tt></td>
 629         <td>The PostScript
 630         interpreter version numbers as returned by the
 631         <tt>version</tt> and <tt>revision</tt> operators. The
 632         required format is "(version) revision". Multiple
 633         <tt>PSVersion</tt> attributes may be specified to
 634         support multiple interpreter version numbers. If not
 635         specified, "(3010) 705" and "(3010) 707" are
 636         assumed.</td>
 637 </tr>
 638 <tr>
 639         <td><tt>TTRasterizer</tt></td>
 640         <td>The type of TrueType
 641         font rasterizer supported by the device, if any. The
 642         supported values are <tt>None</tt>, <tt>Accept68k</tt>,
 643         <tt>Type42</tt>, and <tt>TrueImage</tt>. If not
 644         specified, <tt>None</tt> is assumed.</td>
 645 </tr>
 646 </table></div>
 647
 648 <h3>Query Commands</h3>
 649
 650 <p>Most PostScript printer PPD files include query commands (<tt>?PageSize</tt>, etc.) that allow applications to query the printer for its current settings and configuration. Query commands are included in driver information files as attributes. For example, the example in <a href='#LISTING_1'>Listing 1</a> uses the following definition for the <tt>PageSize</tt> query command:</p>
 651
 652 <pre class='example'>
 653 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> "?PageSize" "" "
 654       save
 655       currentpagedevice /PageSize get aload pop
 656       2 copy gt {exch} if (Unknown)
 657       23 dict
 658               dup [612 792] (Letter) put
 659               dup [612 1008] (Legal) put
 660               dup [595 842] (A4) put
 661               {exch aload pop 4 index sub abs 5 le exch
 662                5 index sub abs 5 le and
 663               {exch pop exit} {pop} ifelse
 664       } bind forall = flush pop pop
 665       restore"
 666 </pre>
 667
 668 <p>Query commands can span multiple lines, however no single line may contain more than 255 characters.</p>
 669
 670 <h3><a name='IMPORT'>Importing Existing PPD Files</a></h3>
 671
 672 <P>CUPS includes a utility called <a href='man-ppdi.html'>ppdi(1)</a>
 673 which allows you to import existing PPD files into the driver information file
 674 format used by the PPD compiler <a href='man-ppdc.html'>ppdc(1)</a>. Once
 675 imported, you can modify, localize, and regenerate the PPD files easily. Type
 676 the following command to import the PPD file <VAR>mydevice.ppd</VAR> into the
 677 driver information file <VAR>mydevice.drv</VAR>:</P>
 678
 679 <pre class='command'>
 680 ppdi -o mydevice.drv mydevice.ppd
 681 </pre>
 682
 683 <P>If you have a whole directory of PPD files that you would like to import,
 684 you can list multiple filenames or use shell wildcards to import more than one
 685 PPD file on the command-line:</P>
 686
 687 <pre class='command'>
 688 ppdi -o mydevice.drv mydevice1.ppd mydevice2.ppd
 689 ppdi -o mydevice.drv *.ppd
 690 </pre>
 691
 692 <P>If the driver information file already exists, the new PPD
 693 file entries are appended to the end of the file. Each PPD file
 694 is placed in its own group of curly braces within the driver
 695 information file.</P>
 696
 697
 698 <h2 class='title'><a name='FILTERS'>Using Custom Filters</a></h2>
 699
 700 <p>Normally a PostScript printer driver will not utilize any additional print filters. For drivers that provide additional filters such as a CUPS command file filter for doing printer maintenance, you must also list the following <tt>Filter</tt> directive to handle printing PostScript files:</p>
 701
 702 <pre class='example'>
 703 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-postscript 0 -
 704 </pre>
 705
 706 <h3>Custom Command Filters</h3>
 707
 708 <p>The <tt>application/vnd.cups-command</tt> file type is used for CUPS command files. Use the following <tt>Filter</tt> directive to handle CUPS command files:</p>
 709
 710 <pre class='example'>
 711 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-command 100 /path/to/command/filter
 712 </pre>
 713
 714 <p>To use the standard PostScript command filter, specify <var>commandtops</var> as the path to the command filter.</p>
 715
 716 <h3>Custom PDF Filters</h3>
 717
 718 <p>The <tt>application/pdf</tt> file type is used for unfiltered PDF files while the <tt>application/vnd.cups-pdf</tt> file type is used for filtered PDF files. Use the following <tt>Filter</tt> directive to handle filtered PDF files:</p>
 719
 720 <pre class='example'>
 721 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-pdf 100 /path/to/pdf/filter
 722 </pre>
 723
 724 <p>For unfiltered PDF files, use:</p>
 725
 726 <pre class='example'>
 727 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/pdf 100 /path/to/pdf/filter
 728 </pre>
 729
 730 <p>Custom PDF filters that accept filtered data do not need to perform number-up processing and other types of page imposition, while those that accept unfiltered data MUST do the number-up processing themselves.</p>
 731
 732 <h3>Custom PostScript Filters</h3>
 733
 734 <p>The <tt>application/vnd.cups-postscript</tt> file type is used for filtered PostScript files. Use the following <tt>Filter</tt> directive to handle PostScript files:</p>
 735
 736 <pre class='example'>
 737 <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-postscript 100 /path/to/postscript/filter
 738 </pre>
 739
 740
 741 <h2 class='title'><a name='COLOR'>Implementing Color Management</a></h2>
 742
 743 <p>CUPS uses ICC color profiles to provide more accurate color reproduction. The <a href='spec-ppd.html#cupsICCProfile'><tt>cupsICCProfile</tt></a> attribute defines the color profiles that are available for a given printer, for example:</p>
 744
 745 <pre class='example'>
 746 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "ColorModel.MediaType.Resolution/Description" /path/to/ICC/profile
 747 </pre>
 748
 749 <p>where "ColorModel.MediaType.Resolution" defines a selector based on the corresponding option selections. A simple driver might only define profiles for the color models that are supported, for example a printer supporting Gray and RGB might use:</p>
 750
 751 <pre class='example'>
 752 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "Gray../Grayscale Profile" /path/to/ICC/gray-profile
 753 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsICCProfile "RGB../Full Color Profile" /path/to/ICC/rgb-profile
 754 </pre>
 755
 756 <p>The options used for profile selection can be customized using the <tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt> attributes.</p>
 757
 758
 759 <h2 class='title'><a name='MACOSX'>Adding macOS Features</a></h2>
 760
 761 <p>macOS printer drivers can provide <a href='spec-ppd.html#MACOSX'>additional attributes</a> to specify additional option panes in the print dialog, an image of the printer, a help book, and option presets for the driver software:</p>
 762
 763 <pre class='example'>
 764 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APDialogExtension "" /Library/Printers/Vendor/filename.plugin
 765 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APHelpBook "" /Library/Printers/Vendor/filename.bundle
 766 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APPrinterIconPath "" /Library/Printers/Vendor/filename.icns
 767 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> APPrinterPreset "name/text" "*option choice ..."
 768 </pre>
 769     </div>
 770   </body>
 771 </html>