1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
3 <!-- SECTION: Programming -->
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"><!--
11 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
14 H1, H2, H3, H4, H5, H6, P, TD, TH {
15 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
19 font-family: monaco, courier, monospace;
24 font-family: monaco, courier, monospace;
28 border: dotted thin #7f7f7f;
56 border: dotted thin #999999;
61 PRE.command EM, PRE.example EM {
62 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
66 font-family: monaco, courier, monospace;
77 border: solid thin #999999;
88 -moz-border-radius: 10px;
93 text-decoration: none;
96 A:link:hover, A:visited:hover, A:active {
97 text-decoration: underline;
104 TR.data, TD.data, TR.data TD {
107 border-bottom: solid 1pt #999999;
111 border-bottom: solid 1pt #999999;
118 border: solid thin #999999;
119 border-collapse: collapse;
135 border: solid thin #cccccc;
142 border-bottom: solid thin #999999;
151 caption-side: bottom;
175 border: thin solid black;
183 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
192 border-bottom: solid 2pt #000000;
195 DIV.indent, TABLE.indent {
203 border-collapse: collapse;
206 TABLE.indent TD, TABLE.indent TH {
211 border-collapse: collapse;
219 border-bottom: solid thin #cccccc;
224 vertical-align: bottom;
233 border-bottom: solid thin #eeeeee;
238 TABLE.list TR:nth-child(even) {
242 TABLE.list TR:nth-child(odd) {
261 font-family: monaco, courier, monospace;
265 border: solid thin #999999;
266 border-collapse: collapse;
271 DIV.summary TABLE TD, DIV.summary TABLE TH {
272 border: solid thin #999999;
278 DIV.summary TABLE THEAD TH {
282 /* API documentation styles... */
289 div.body h3, div.body h4, div.body h5 {
290 margin-bottom: 0.5em;
293 .class, .enumeration, .function, .struct, .typedef, .union {
294 border-bottom: solid thin #999999;
301 code, p.code, pre, ul.code li {
302 font-family: monaco, courier, monospace;
305 ul.code, ul.contents, ul.subcontents {
306 list-style-type: none;
316 ul.contents li ul.code, ul.contents li ul.subcontents {
329 margin-bottom: 0.5em;
332 /* This is just for the HTML files generated with the framedhelp target */
335 border: solid thin black;
344 div.contents ul.contents {
347 div.contents ul.subcontents li {
356 PPD compiler documentation for CUPS.
358 Copyright 2007-2012 by Apple Inc.
359 Copyright 1997-2007 by Easy Software Products.
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/".
368 <h1 class='title'
>Introduction to the PPD Compiler
</h1>
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>
374 <BLOCKQUOTE><B>Note:
</B>
376 <P>The PPD compiler and related tools are deprecated and will be removed in a future release of CUPS.
</P>
380 <div class='summary'
><table summary='General Information'
>
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>
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>
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>
410 <h2 class='title'
><a name='BASICS'
>The Basics
</a></h2>
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>
419 <pre class='command'
>
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>
427 <pre class='command'
>
428 ppdc -d myppds mydrivers.drv
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>
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
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>
449 <pre class='command'
>
450 ppdc -d myppds -l de,en,es,fr,it mydrivers.drv
454 <h2 class='title'
><a name='DRV'
>Driver Information Files
</a></h2>
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>
462 <p class='example'
><a name=
"LISTING1">Listing
1:
"examples/minimum.drv"</a></p>
464 <pre class='example'
>
465 <I>// Include standard font and media definitions
</I>
466 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
467 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
469 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
470 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
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
477 <I>// Each filter provided by the driver...
</I>
478 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
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
484 <I>// Supported resolutions
</I>
485 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
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"
492 <h3><a name='SIMPLE'
>A Simple Example
</a></h3>
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
499 <pre class='example'
>
500 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
501 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
504 <P>The
<TT>#include
</TT> directive works just like the C/C++ include directive;
505 files included using the angle brackets (
<TT><filename
></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><font.defs
></TT> include file defines the standard fonts
509 which are included with GPL Ghostscript and the Apple PDF RIP, while the
510 <TT><media.defs
></TT> include file defines the standard media sizes
511 listed in Appendix B of the Adobe PostScript Printer Description File Format
514 <P>CUPS provides several other standard include files:
</P>
518 <LI><TT><epson.h
></TT> - Defines all of the rastertoepson driver
521 <LI><TT><escp.h
></TT> - Defines all of the rastertoescpx driver
524 <LI><TT><hp.h
></TT> - Defines all of the rastertohp driver
527 <LI><TT><label.h
></TT> - Defines all of the rastertolabel driver
530 <LI><TT><pcl.h
></TT> - Defines all of the rastertopclx driver
533 <LI><TT><raster.defs
></TT> - Defines all of the CUPS raster format
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>
541 <pre class='example'
>
542 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
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
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
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>
561 <P>Third comes the manufacturer, model name, and version number information
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
570 <P>These strings are used when the user (or auto-configuration program) selects
571 the printer driver for a newly connected device.
</p>
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
577 <pre class='example'
>
578 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
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>
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>
590 <pre class='example'
>
591 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
592 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
594 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
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><media.defs
></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>
605 <P>The
<TT>Resolution
</TT> directive accepts several values after it as
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>
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>
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
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>
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>
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
647 <P>Finally, the
<TT>PCFileName
</TT> directive specifies that the named PPD file
648 should be written for the current driver definitions:
</P>
650 <pre class='example'
>
651 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
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>
660 <pre class='example'
>
661 <a href='ref-ppdcfile.html#FileName'
>FileName
</a> "FooJet 2000"
665 <h3><a name='GROUPING'
>Grouping and Inheritance
</a></h3>
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
676 <p class='example'
><a name=
"LISTING2">Listing
2:
"examples/grouping.drv"</a></p>
678 <pre class='example'
>
680 <I>// Include standard font and media definitions
</I>
681 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
682 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
684 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
685 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
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
691 <I>// Each filter provided by the driver...
</I>
692 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
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
699 <I>// Supported resolutions
</I>
700 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
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"
708 <I>// Supported resolutions
</I>
709 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "1200dpi/1200 DPI"
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"
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>
721 <pre class='example'
>
723 // Supported resolutions
724 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
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"
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>
740 <h3><a name='COLOR'
>Color Support
</a></h3>
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>
749 <P>The key changes are the addition of the
<TT>ColorDevice
</TT>
752 <pre class='example'
>
753 <a href='ref-ppdcfile.html#ColorDevice'
>ColorDevice
</a> true
756 <P>which tells the printing system that the printer supports
757 color printing, and the
<TT>ColorModel
</TT> directives:
</P>
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
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>
774 <LI><TT>Gray
</TT> - Grayscale output.
776 <LI><TT>RGB
</TT> - Color output, typically using the RGB
777 colorspace, but without a separate black channel.
779 <LI><TT>CMYK
</TT> - Color output with a separate black
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>
787 <P>The colorspace name can be any of the following universally supported
791 <LI><TT>w
</TT> - Luminance
</LI>
793 <LI><TT>rgb
</TT> - Red, green, blue
</LI>
795 <LI><TT>k
</TT> - Black
</LI>
797 <LI><TT>cmy
</TT> - Cyan, magenta, yellow
</LI>
799 <LI><TT>cmyk
</TT> - Cyan, magenta, yellow, black
</LI>
803 <P>The color organization can be any of the following values:
</P>
807 <LI><TT>chunky
</TT> - Color values are passed together on a line
808 as RGB RGB RGB RGB
</LI>
810 <LI><TT>banded
</TT> - Color values are passed separately
811 on a line as RRRR GGGG BBBB; not supported by the Apple
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>
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>
825 <p class='example'
><a name=
"LISTING3">Listing
3:
"examples/color.drv"</a></p>
827 <pre class='example'
>
829 <I>// Include standard font and media definitions
</I>
830 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
831 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
833 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
834 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
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
840 <I>// Each filter provided by the driver...
</I>
841 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
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
848 <I>// Supported resolutions
</I>
849 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
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"
857 <I>// Supports color printing
</I>
858 <a href='ref-ppdcfile.html#ColorDevice'
>ColorDevice
</a> true
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
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"
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"
875 <h3><a name='OPTIONS'
>Defining Custom Options and Option Groups
</a></h3>
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
883 <p class='example'
><a name=
"LISTING4">Listing
4:
"examples/custom.drv"</a></p>
885 <pre class='example'
>
887 <I>// Include standard font and media definitions
</I>
888 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
889 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
891 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
892 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
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
899 <I>// Each filter provided by the driver...
</I>
900 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
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
906 <I>// Supported resolutions
</I>
907 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
909 <I>// Option Group
</I>
910 <a href='ref-ppdcfile.html#Group'
>Group
</a> "Footasm"
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
"<</cupsCompression 1>>setpagedevice"
915 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> False/No
"<</cupsCompression 0>>setpagedevice"
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 "<</OutputType(Auto)>>setpagedevice""
921 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Text/Optimize for Text
"
922 "<</OutputType(Text)
>>setpagedevice
""
923 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "Graph/Optimize for Graphics"
924 "<</OutputType(Graph)>>setpagedevice""
925 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Photo/Optimize for Photos
"
926 "<</OutputType(Photo)
>>setpagedevice
""
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"
932 <P>The custom group is introduced by the
<TT>Group
</TT>
933 directive which is followed by the name and optionally text for
936 <pre class='example'
>
937 <a href='ref-ppdcfile.html#Group'
>Group
</a> "Footasm/Footastic Options"
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>
950 <P>Once the group is specified, the
<TT>Option
</TT> directive is
951 used to introduce a new option:
</P>
953 <pre class='example'
>
954 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup
10
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>
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>
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>
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>
983 <P>Once the option is specified, each option choice can be
984 listed using the
<TT>Choice
</TT> directive:
</P>
986 <pre class='example'
>
987 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> True/Yes
"<</cupsCompression 1>>setpagedevice"
988 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> False/No
"<</cupsCompression 0>>setpagedevice"
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>
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>
1002 <pre class='example'
>
1003 <</name value
>>setpagedevice
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
1011 <h3><a name='DEFINE'
>Defining Constants
</a></h3>
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>
1020 <pre class='example'
>
1021 <a href='ref-ppdcfile.html#_define'
>#define
</a> NAME value
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
1029 <pre class='example'
>
1030 <a href='ref-ppdcfile.html#_define'
>#define
</a> FOO
"My String Value"
1033 <P>Constants can also be defined on the command-line using the
<tt>-D
</tt>
1036 <pre class='command'
>
1037 ppdc
-DNAME=
"value" filename.drv
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>
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
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"
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"
1063 <P>Numeric constants can be bitwise OR'd together by placing the constants
1064 inside parenthesis, for example:
</P>
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
1074 <I>// Define a model number specifying the capabilities of the printer...
</I>
1075 <a href='ref-ppdcfile.html#ModelNumber'
>ModelNumber
</a> ($DUPLEX $COLOR)
1081 <h3><a name='CONDITIONAL'
>Conditional Statements
</a></h3>
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>
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>
1119 <h3><a name='CONSTRAINTS'
>Defining Constraints
</a></h3>
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>
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>
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"
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>
1144 <p class='example'
><a name=
"LISTING5">Listing
5:
"examples/constraint.drv"</a></p>
1146 <pre class='example'
>
1148 <I>// Include standard font and media definitions
</I>
1149 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
1150 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
1152 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
1153 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
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
1160 <I>// Each filter provided by the driver...
</I>
1161 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
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
1167 <I>// Supported resolutions
</I>
1168 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
1170 <I>// Installable Option Group
</I>
1171 <a href='ref-ppdcfile.html#Group'
>Group
</a> "InstallableOptions/Options Installed"
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" ""
1178 <I>// General Option Group
</I>
1179 <a href='ref-ppdcfile.html#Group'
>Group
</a> General
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" "<</Duplex false>>setpagedevice""
1184 <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexNoTumble/Long Edge Binding
"
1185 "<</Duplex true/Tumble false
>>setpagedevice
""
1186 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "DuplexTumble/Short Edge Binding"
1187 "<</Duplex true/Tumble true>>setpagedevice""
1189 <I>// Only allow duplexing if the duplexer is installed</I>
1190 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False
"
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
"
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>
1203 <pre class='example'>
1204 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False
"
1207 <h4>Enhanced Constraints</h4>
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
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
"
1221 <h2 class='title'><a name='LOCALIZATION'>Localization</a></h2>
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>
1231 <h3><a name='PPDPO'>The ppdpo Utility</a></h3>
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
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
1248 <pre class='command'>
1249 ppdpo -o de.po *.drv
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>
1257 <pre class='command'>
1258 ppdpo -o de.strings *.drv
1261 <h3><a name='PPDC_CATALOG'>Using Message Catalogs with the PPD Compiler</a></h3>
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
1268 <pre class='example'>
1269 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po
" // German
1272 <p>In fact, you can use the <tt>#po</tt> directive as many times as needed:</p>
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
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>
1288 <pre class='command'>
1289 ppdc -l de -d ppd/de mydrivers.drv
1292 <p>to generate German PPD files.</p>