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;
44 border: dotted thin #999999;
49 PRE.command EM, PRE.example EM {
50 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
54 font-family: monaco, courier, monospace;
65 border: solid thin #999999;
76 -moz-border-radius: 10px;
81 text-decoration: none;
84 A:link:hover, A:visited:hover, A:active {
85 text-decoration: underline;
92 TR.data, TD.data, TR.data TD {
95 border-bottom: solid 1pt #999999;
99 border-bottom: solid 1pt #999999;
106 border: solid thin #999999;
107 border-collapse: collapse;
123 border: solid thin #cccccc;
130 border-bottom: solid thin #999999;
139 caption-side: bottom;
163 border: thin solid black;
171 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
180 border-bottom: solid 2pt #000000;
183 DIV.indent, TABLE.indent {
191 border-collapse: collapse;
194 TABLE.indent TD, TABLE.indent TH {
199 border-collapse: collapse;
207 border-bottom: solid thin #cccccc;
212 vertical-align: bottom;
221 border-bottom: solid thin #eeeeee;
226 TABLE.list TR:nth-child(even) {
230 TABLE.list TR:nth-child(odd) {
249 font-family: monaco, courier, monospace;
253 border: solid thin #999999;
254 border-collapse: collapse;
259 DIV.summary TABLE TD, DIV.summary TABLE TH {
260 border: solid thin #999999;
266 DIV.summary TABLE THEAD TH {
270 /* API documentation styles... */
277 div.body h3, div.body h4, div.body h5 {
278 margin-bottom: 0.5em;
281 .class, .enumeration, .function, .struct, .typedef, .union {
282 border-bottom: solid thin #999999;
289 code, p.code, pre, ul.code li {
290 font-family: monaco, courier, monospace;
293 ul.code, ul.contents, ul.subcontents {
294 list-style-type: none;
304 ul.contents li ul.code, ul.contents li ul.subcontents {
317 margin-bottom: 0.5em;
320 /* This is just for the HTML files generated with the framedhelp target */
323 border: solid thin black;
332 div.contents ul.contents {
335 div.contents ul.subcontents li {
346 PPD compiler documentation for CUPS.
348 Copyright 2007-2012 by Apple Inc.
349 Copyright 1997-2007 by Easy Software Products.
351 These coded instructions, statements, and computer programs are the
352 property of Apple Inc. and are protected by Federal copyright
353 law. Distribution and use rights are outlined in the file "LICENSE.txt"
354 which should have been included with this file. If this file is
355 file is missing or damaged, see the license at "http://www.cups.org/".
358 <h1 class='title'
>Introduction to the PPD Compiler
</h1>
360 <P>This document describes how to use the CUPS PostScript Printer Description
361 (PPD) file compiler. The PPD compiler generates PPD files from simple text files
362 that describe the features and capabilities of one or more printers.
</P>
364 <BLOCKQUOTE><B>Note:
</B>
366 <P>The PPD compiler and related tools are deprecated and will be removed in a future release of CUPS.
</P>
370 <div class='summary'
><table summary='General Information'
>
374 <td>Programming:
<a href='raster-driver.html'
>Developing Raster Printer Drivers
</a><br>
375 Programming:
<a href='postscript-driver.html'
>Developing PostScript Printer Drivers
</a><br>
376 Programming:
<a href='api-filter.html'
>Filter and Backend Programming
</a><br>
377 Programming:
<a href='api-raster.html'
>Raster API
</a><br>
378 References:
<a href='ref-ppdcfile.html'
>PPD Compiler Driver Information File Reference
</a><br>
379 Specifications:
<a href='spec-ppd.html'
>CUPS PPD Extensions
</a></td>
383 <h2 class=
"title">Contents
</h2>
384 <ul class=
"contents">
385 <li><a href=
"#BASICS">The Basics
</a></li>
386 <li><a href=
"#DRV">Driver Information Files
</a><ul class=
"subcontents">
387 <li><a href=
"#SIMPLE">A Simple Example
</a></li>
388 <li><a href=
"#GROUPING">Grouping and Inheritance
</a></li>
389 <li><a href=
"#COLOR">Color Support
</a></li>
390 <li><a href=
"#OPTIONS">Defining Custom Options and Option Groups
</a></li>
391 <li><a href=
"#DEFINE">Defining Constants
</a></li>
392 <li><a href=
"#CONDITIONAL">Conditional Statements
</a></li>
393 <li><a href=
"#CONSTRAINTS">Defining Constraints
</a></li>
395 <li><a href=
"#LOCALIZATION">Localization
</a><ul class=
"subcontents">
396 <li><a href=
"#PPDPO">The ppdpo Utility
</a></li>
397 <li><a href=
"#PPDC_CATALOG">Using Message Catalogs with the PPD Compiler
</a></li>
400 <h2 class='title'
><a name='BASICS'
>The Basics
</a></h2>
402 <P>The PPD compiler,
<a href='man-ppdc.html'
><code>ppdc(
1)
</code></a>, is a
403 simple command-line tool that takes a single
<I>driver information file
</I>,
404 which by convention uses the extension
<VAR>.drv
</VAR>, and produces one or more
405 PPD files that may be distributed with your printer drivers for use with CUPS.
406 For example, you would run the following command to create the English language
407 PPD files defined by the driver information file
<VAR>mydrivers.drv
</VAR>:
</P>
409 <pre class='command'
>
413 <P>The PPD files are placed in a subdirectory called
414 <VAR>ppd
</VAR>. The
<TT>-d
</TT> option is used to put the PPD
415 files in a different location, for example:
</p>
417 <pre class='command'
>
418 ppdc -d myppds mydrivers.drv
421 <P>places the PPD files in a subdirectory named
422 <VAR>myppds
</VAR>. Finally, use the
<TT>-l
</TT> option to
423 specify the language localization for the PPD files that are
424 created, for example:
</P>
426 <pre class='command'
>
427 ppdc -d myppds/de -l de mydrivers.drv
428 ppdc -d myppds/en -l en mydrivers.drv
429 ppdc -d myppds/es -l es mydrivers.drv
430 ppdc -d myppds/fr -l fr mydrivers.drv
431 ppdc -d myppds/it -l it mydrivers.drv
434 <P>creates PPD files in German (de), English (en), Spanish (es),
435 French (fr), and Italian (it) in the corresponding
436 subdirectories. Specify multiple languages (separated by commas) to produce
437 "globalized" PPD files:
</p>
439 <pre class='command'
>
440 ppdc -d myppds -l de,en,es,fr,it mydrivers.drv
444 <h2 class='title'
><a name='DRV'
>Driver Information Files
</a></h2>
446 <P>The driver information files accepted by the PPD compiler are
447 plain text files that define the various attributes and options
448 that are included in the PPD files that are generated. A driver
449 information file can define the information for one or more printers and
450 their corresponding PPD files.
</P>
452 <p class='example'
><a name=
"LISTING1">Listing
1:
"examples/minimum.drv"</a></p>
454 <pre class='example'
>
455 <I>// Include standard font and media definitions
</I>
456 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
457 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
459 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
460 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
462 <I>// Manufacturer, model name, and version
</I>
463 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "Foo"
464 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
465 <a href='ref-ppdcfile.html#Version'
>Version
</a> 1.0
467 <I>// Each filter provided by the driver...
</I>
468 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
470 <I>// Supported page sizes
</I>
471 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
472 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
474 <I>// Supported resolutions
</I>
475 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
477 <I>// Specify the name of the PPD file we want to generate...
</I>
478 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
482 <h3><a name='SIMPLE'
>A Simple Example
</a></h3>
484 <P>The example in
<A HREF=
"#LISTING1">Listing
1</A> shows a driver information
485 file which defines the minimum required attributes to provide a valid PPD file.
486 The first part of the file includes standard definition files for fonts and
489 <pre class='example'
>
490 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
491 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
494 <P>The
<TT>#include
</TT> directive works just like the C/C++ include directive;
495 files included using the angle brackets (
<TT><filename
></TT>) are found
496 in any of the standard include directories and files included using quotes
497 (
<TT>"filename"</TT>) are found in the same directory as the source or include
498 file. The
<TT><font.defs
></TT> include file defines the standard fonts
499 which are included with GPL Ghostscript and the Apple PDF RIP, while the
500 <TT><media.defs
></TT> include file defines the standard media sizes
501 listed in Appendix B of the Adobe PostScript Printer Description File Format
504 <P>CUPS provides several other standard include files:
</P>
508 <LI><TT><epson.h
></TT> - Defines all of the rastertoepson driver
511 <LI><TT><escp.h
></TT> - Defines all of the rastertoescpx driver
514 <LI><TT><hp.h
></TT> - Defines all of the rastertohp driver
517 <LI><TT><label.h
></TT> - Defines all of the rastertolabel driver
520 <LI><TT><pcl.h
></TT> - Defines all of the rastertopclx driver
523 <LI><TT><raster.defs
></TT> - Defines all of the CUPS raster format
528 <P>Next we list all of the fonts that are available in the driver; for CUPS
529 raster drivers, the following line is all that is usually supplied:
</P>
531 <pre class='example'
>
532 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
535 <P>The
<TT>Font
</TT> directive specifies the name of a single font or the
536 asterisk to specify all fonts. For example, you would use the following line to
537 define an additional bar code font that you are supplying with your printer
540 <pre class='example'
>
541 <I>// name encoding version charset status
</I>
542 <a href='ref-ppdcfile.html#Font'
>Font
</a> Barcode-Foo Special
"(1.0)" Special ROM
545 <P>The name of the font is
<TT>Barcode-Foo
</TT>. Since it is not a standard
546 text font, the encoding and charset name
<TT>Special
</TT> is used. The version
547 number is
<TT>1.0</TT> and the status (where the font is located) is
548 <TT>ROM
</TT> to indicate that the font does not need to be embedded in
549 documents that use the font for this printer.
</P>
551 <P>Third comes the manufacturer, model name, and version number information
554 <pre class='example'
>
555 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "Foo"
556 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
557 <a href='ref-ppdcfile.html#Version'
>Version
</a> 1.0
560 <P>These strings are used when the user (or auto-configuration program) selects
561 the printer driver for a newly connected device.
</p>
563 <P>The list of filters comes after the information strings; for the example in
564 <A HREF=
"#LISTING1">Listing
1</A>, we have a single filter that takes CUPS
567 <pre class='example'
>
568 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
571 <P>Each filter specified in the driver information file is the equivalent of a
572 printer driver for that format; if a user submits a print job in a different
573 format, CUPS figures out the sequence of commands that will produce a supported
574 format for the least relative cost.
</P>
576 <P>Once we have defined the driver information we specify the supported options.
577 For the example driver we support a single resolution of
600 dots per inch and
578 two media sizes, A4 and Letter:
</P>
580 <pre class='example'
>
581 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
582 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
584 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
587 <P>The asterisk in front of the
<TT>MediaSize
</TT> and
<TT>Resolution
</TT>
588 directives specify that those option choices are the default. The
589 <TT>MediaSize
</TT> directive is followed by a media size name which is normally
590 defined in the
<TT><media.defs
></TT> file and corresponds to a standard
591 Adobe media size name. If the default media size is
<TT>Letter
</TT>, the PPD
592 compiler will override it to be
<TT>A4
</TT> for non-English localizations for
593 you automatically.
</P>
595 <P>The
<TT>Resolution
</TT> directive accepts several values after it as
600 <LI>Colorspace for this resolution, if any. In the example file, the
601 colorspace
<TT>k
</TT> is used which corresponds to black. For printer
602 drivers that support color printing, this field is usually specified as
603 "-" for
"no change".
</LI>
605 <LI>Bits per color. In the example file, we define
8 bits per color, for
606 a continuous-tone grayscale output. All versions of CUPS support
1 and
607 8 bits per color. CUPS
1.2 and higher (OS X
10.5 and higher) also
608 supports
16 bits per color.
</LI>
610 <LI>Rows per band. In the example file, we define
0 rows per band to
611 indicate that our printer driver does not process the page in
614 <LI>Row feed. In the example, we define the feed value to be
0 to
615 indicate that our printer driver does not interleave the output.
</LI>
617 <LI>Row step. In the example, we define the step value to be
0 to
618 indicate that our printer driver does not interleave the output. This
619 value normally indicates the spacing between the nozzles of an inkjet
620 printer - when combined with the previous two values, it informs the
621 driver how to stagger the output on the page to produce interleaved
622 lines on the page for higher-resolution output.
</LI>
624 <LI>Choice name and text. In the example, we define the choice name and
625 text to be
<TT>"600dpi/600 DPI"</TT>. The name and text are separated by
626 slash (
<TT>/
</TT>) character; if no text is specified, then the name is
627 used as the text. The PPD compiler parses the name to determine the
628 actual resolution; the name can be of the form
629 <TT><I>RESOLUTION
</I>dpi
</TT> for resolutions that are equal
630 horizontally and vertically or
<TT><I>HRES
</I>x
<I>VRES
</I>dpi
</TT> for
631 isometric resolutions. Only integer resolution values are supported, so
632 a resolution name of
<TT>300dpi
</TT> is valid while
<TT>300.1dpi
</TT> is
637 <P>Finally, the
<TT>PCFileName
</TT> directive specifies that the named PPD file
638 should be written for the current driver definitions:
</P>
640 <pre class='example'
>
641 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
644 <P>The filename follows the directive and
<I>must
</I> conform to the Adobe
645 filename requirements in the Adobe Postscript Printer Description File Format
646 Specification. Specifically, the filename may not exceed
8 characters followed
647 by the extension
<VAR>.ppd
</VAR>. The
<TT>FileName
</TT> directive can be used to
648 specify longer filenames:
</P>
650 <pre class='example'
>
651 <a href='ref-ppdcfile.html#FileName'
>FileName
</a> "FooJet 2000"
655 <h3><a name='GROUPING'
>Grouping and Inheritance
</a></h3>
657 <P>The previous example created a single PPD file. Driver information files can
658 also define multiple printers by using the PPD compiler grouping functionality.
659 Directives are grouped using the curly braces (
<TT>{
</TT> and
<TT>}
</TT>) and
660 every group that uses the
<TT>PCFileName
</TT> or
<TT>FileName
</TT> directives
661 produces a PPD file with that name.
<A HREF=
"#LISTING2">Listing
2</A> shows a
662 variation of the original example that uses two groups to define two printers
663 that share the same printer driver filter but provide two different resolution
666 <p class='example'
><a name=
"LISTING2">Listing
2:
"examples/grouping.drv"</a></p>
668 <pre class='example'
>
670 <I>// Include standard font and media definitions
</I>
671 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
672 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
674 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
675 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
677 <I>// Manufacturer and version
</I>
678 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "Foo"
679 <a href='ref-ppdcfile.html#Version'
>Version
</a> 1.0
681 <I>// Each filter provided by the driver...
</I>
682 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
684 <I>// Supported page sizes
</I>
685 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
686 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
689 <I>// Supported resolutions
</I>
690 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
692 <I>// Specify the model name and filename...
</I>
693 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
694 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
698 <I>// Supported resolutions
</I>
699 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "1200dpi/1200 DPI"
701 <I>// Specify the model name and filename...
</I>
702 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2001"
703 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojt2k1.ppd"
707 <P>The second example is essentially the same as the first, except that each
708 printer model is defined inside of a pair of curly braces. For example, the
709 first printer is defined using:
</P>
711 <pre class='example'
>
713 // Supported resolutions
714 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
716 // Specify the model name and filename...
717 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
718 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
722 <P>The printer
<I>inherits
</I> all of the definitions from the parent group (the
723 top part of the file) and adds the additional definitions inside the curly
724 braces for that printer driver. When we define the second group, it also
725 inherits the same definitions from the parent group but
<I>none
</I> of the
726 definitions from the first driver. Groups can be nested to any number of levels
727 to support variations of similar models without duplication of information.
</P>
730 <h3><a name='COLOR'
>Color Support
</a></h3>
732 <P>For printer drivers that support color printing, the
733 <TT>ColorDevice
</TT> and
<TT>ColorModel
</TT> directives should be
734 used to tell the printing system that color output is desired
735 and in what formats.
<A HREF=
"#LISTING3">Listing
3</A> shows a
736 variation of the previous example which includes a color printer
737 that supports printing at
300 and
600 DPI.
</P>
739 <P>The key changes are the addition of the
<TT>ColorDevice
</TT>
742 <pre class='example'
>
743 <a href='ref-ppdcfile.html#ColorDevice'
>ColorDevice
</a> true
746 <P>which tells the printing system that the printer supports
747 color printing, and the
<TT>ColorModel
</TT> directives:
</P>
749 <pre class='example'
>
750 <a href='ref-ppdcfile.html#ColorModel'
>ColorModel
</a> Gray/Grayscale w chunky
0
751 *
<a href='ref-ppdcfile.html#ColorModel'
>ColorModel
</a> RGB/Color rgb chunky
0
754 <P>which tell the printing system which colorspaces are supported by the printer
755 driver for color printing. Each of the
<TT>ColorModel
</TT> directives is
756 followed by the option name and text (
<TT>Gray/Grayscale
</TT> and
757 <TT>RGB/Color
</TT>), the colorspace name (
<TT>w
</TT> and
<TT>rgb
</TT>), the
758 color organization (
<TT>chunky
</TT>), and the compression mode number
759 (
<TT>0</TT>) to be passed to the driver. The option name can be any of the
760 standard Adobe
<TT>ColorModel
</TT> names:
</P>
764 <LI><TT>Gray
</TT> - Grayscale output.
766 <LI><TT>RGB
</TT> - Color output, typically using the RGB
767 colorspace, but without a separate black channel.
769 <LI><TT>CMYK
</TT> - Color output with a separate black
774 <P>Custom names can be used, however it is recommended that you use your vendor
775 prefix for any custom names, for example
"fooName".
</P>
777 <P>The colorspace name can be any of the following universally supported
781 <LI><TT>w
</TT> - Luminance
</LI>
783 <LI><TT>rgb
</TT> - Red, green, blue
</LI>
785 <LI><TT>k
</TT> - Black
</LI>
787 <LI><TT>cmy
</TT> - Cyan, magenta, yellow
</LI>
789 <LI><TT>cmyk
</TT> - Cyan, magenta, yellow, black
</LI>
793 <P>The color organization can be any of the following values:
</P>
797 <LI><TT>chunky
</TT> - Color values are passed together on a line
798 as RGB RGB RGB RGB
</LI>
800 <LI><TT>banded
</TT> - Color values are passed separately
801 on a line as RRRR GGGG BBBB; not supported by the Apple
804 <LI><TT>planar
</TT> - Color values are passed separately
805 on a page as RRRR RRRR RRRR ... GGGG GGGG GGGG ... BBBB
806 BBBB BBBB; not supported by the Apple RIP filters
</LI>
810 <P>The compression mode value is passed to the driver in the
811 <TT>cupsCompression
</TT> attribute. It is traditionally used to select an
812 appropriate compression mode for the color model but can be used for any
813 purpose, such as specifying a photo mode vs. standard mode.
</P>
815 <p class='example'
><a name=
"LISTING3">Listing
3:
"examples/color.drv"</a></p>
817 <pre class='example'
>
819 <I>// Include standard font and media definitions
</I>
820 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
821 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
823 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
824 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
826 <I>// Manufacturer and version
</I>
827 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "Foo"
828 <a href='ref-ppdcfile.html#Version'
>Version
</a> 1.0
830 <I>// Each filter provided by the driver...
</I>
831 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
833 <I>// Supported page sizes
</I>
834 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
835 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
838 <I>// Supported resolutions
</I>
839 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
841 <I>// Specify the model name and filename...
</I>
842 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
843 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
847 <I>// Supports color printing
</I>
848 <a href='ref-ppdcfile.html#ColorDevice'
>ColorDevice
</a> true
850 <I>// Supported colorspaces
</I>
851 <a href='ref-ppdcfile.html#ColorModel'
>ColorModel
</a> Gray/Grayscale w chunky
0
852 *
<a href='ref-ppdcfile.html#ColorModel'
>ColorModel
</a> RGB/Color rgb chunky
0
854 <I>// Supported resolutions
</I>
855 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> -
8 0 0 0 "300dpi/300 DPI"
856 <a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> -
8 0 0 0 "600dpi/600 DPI"
858 <I>// Specify the model name and filename...
</I>
859 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet Color"
860 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojetco.ppd"
865 <h3><a name='OPTIONS'
>Defining Custom Options and Option Groups
</a></h3>
867 <P>The
<TT>Group
</TT>,
<TT>Option
</TT>, and
<TT>Choice
</TT>
868 directives are used to define or select a group, option, or
869 choice.
<A HREF=
"#LISTING4">Listing
4</A> shows a variation of
870 the first example that provides two custom options in a group
873 <p class='example'
><a name=
"LISTING4">Listing
4:
"examples/custom.drv"</a></p>
875 <pre class='example'
>
877 <I>// Include standard font and media definitions
</I>
878 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
879 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
881 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
882 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
884 <I>// Manufacturer, model name, and version
</I>
885 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "Foo"
886 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
887 <a href='ref-ppdcfile.html#Version'
>Version
</a> 1.0
889 <I>// Each filter provided by the driver...
</I>
890 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
892 <I>// Supported page sizes
</I>
893 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
894 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
896 <I>// Supported resolutions
</I>
897 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
899 <I>// Option Group
</I>
900 <a href='ref-ppdcfile.html#Group'
>Group
</a> "Footasm"
902 <I>// Boolean option
</I>
903 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup
10
904 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> True/Yes
"<</cupsCompression 1>>setpagedevice"
905 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> False/No
"<</cupsCompression 0>>setpagedevice"
907 <I>// Multiple choice option
</I>
908 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooOutputType/Output Quality" PickOne AnySetup
10
909 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "Auto/Automatic Selection"
910 "<</OutputType(Auto)>>setpagedevice""
911 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Text/Optimize for Text
"
912 "<</OutputType(Text)
>>setpagedevice
""
913 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "Graph/Optimize for Graphics"
914 "<</OutputType(Graph)>>setpagedevice""
915 <a href='ref-ppdcfile.html#Choice'>Choice</a> "Photo/Optimize for Photos
"
916 "<</OutputType(Photo)
>>setpagedevice
""
918 <I>// Specify the name of the PPD file we want to generate...
</I>
919 <a href='ref-ppdcfile.html#PCFileName'
>PCFileName
</a> "foojet2k.ppd"
922 <P>The custom group is introduced by the
<TT>Group
</TT>
923 directive which is followed by the name and optionally text for
926 <pre class='example'
>
927 <a href='ref-ppdcfile.html#Group'
>Group
</a> "Footasm/Footastic Options"
930 <P>The group name must conform to the PPD specification and
931 cannot exceed
40 characters in length. If you specify user text,
932 it cannot exceed
80 characters in length. The groups
933 <TT>General
</TT>,
<TT>Extra
</TT>, and
934 <TT>InstallableOptions
</TT> are predefined by CUPS; the general
935 and extra groups are filled by the UI options defined by the PPD
936 specification. The
<TT>InstallableOptions
</TT> group is reserved
937 for options that define whether accessories for the printer
938 (duplexer unit, finisher, stapler, etc.) are installed.
</P>
940 <P>Once the group is specified, the
<TT>Option
</TT> directive is
941 used to introduce a new option:
</P>
943 <pre class='example'
>
944 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup
10
947 <P>The directive is followed by the name of the option and any
948 optional user text, the option type, the PostScript document group, and
949 the sort order number. The option name must conform to the PPD specification
950 and cannot exceed
40 characters in length. If you specify user text, it
951 cannot exceed
80 characters in length.
</P>
953 <P>The option type can be
<TT>Boolean
</TT> for true/false
954 selections,
<TT>PickOne
</TT> for picking one of many choices, or
955 <TT>PickMany
</TT> for picking zero or more choices. Boolean
956 options can have at most two choices with the names
957 <TT>False
</TT> and
<TT>True
</TT>. Pick options can have any
958 number of choices, although for Windows compatibility reasons
959 the number of choices should not exceed
255.
</P>
961 <P>The PostScript document group is typically
<TT>AnySetup
</TT>,
962 meaning that the option can be introduced at any point in the
963 PostScript document. Other values include
<TT>PageSetup
</TT> to
964 include the option before each page and
<TT>DocumentSetup
</TT>
965 to include the option once at the beginning of the document.
</P>
967 <P>The sort order number is used to sort the printer commands
968 associated with each option choice within the PostScript
969 document. This allows you to setup certain options before others
970 as required by the printer. For most CUPS raster printer
971 drivers, the value
<TT>10</TT> can be used for all options.
</P>
973 <P>Once the option is specified, each option choice can be
974 listed using the
<TT>Choice
</TT> directive:
</P>
976 <pre class='example'
>
977 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> True/Yes
"<</cupsCompression 1>>setpagedevice"
978 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> False/No
"<</cupsCompression 0>>setpagedevice"
981 <P>The directive is followed by the choice name and optionally
982 user text, and the PostScript commands that should be inserted
983 when printing a file to this printer. The option name must
984 conform to the PPD specification and cannot exceed
40 characters
985 in length. If you specify user text, it cannot exceed
80
986 characters in length.
</P>
988 <P>The PostScript commands are also interpreted by any RIP
989 filters, so these commands typically must be present for all
990 option choices. Most commands take the form:
</P>
992 <pre class='example'
>
993 <</name value
>>setpagedevice
996 <P>where
<TT>name
</TT> is the name of the PostScript page device
997 attribute and
<TT>value
</TT> is the numeric or string value for
1001 <h3><a name='DEFINE'
>Defining Constants
</a></h3>
1003 <P>Sometimes you will want to define constants for your drivers
1004 so that you can share values in different groups within the same
1005 driver information file, or to share values between different
1006 driver information files using the
<TT>#include
</TT> directive.
1007 The
<TT>#define
</TT> directive is used to define constants for
1008 use in your printer definitions:
</P>
1010 <pre class='example'
>
1011 <a href='ref-ppdcfile.html#_define'
>#define
</a> NAME value
1014 <P>The
<TT>NAME
</TT> is any sequence of letters, numbers, and
1015 the underscore. The
<TT>value
</TT> is a number or string; if the
1016 value contains spaces you must put double quotes around it, for
1019 <pre class='example'
>
1020 <a href='ref-ppdcfile.html#_define'
>#define
</a> FOO
"My String Value"
1023 <P>Constants can also be defined on the command-line using the
<tt>-D
</tt>
1026 <pre class='command'
>
1027 ppdc
-DNAME=
"value" filename.drv
1030 <P>Once defined, you use the notation
<TT>$NAME
</TT> to substitute the value of
1031 the constant in the file, for example:
</P>
1033 <pre class='example'
>
1034 <a href='ref-ppdcfile.html#_define'
>#define
</a> MANUFACTURER
"Foo"
1035 <a href='ref-ppdcfile.html#_define'
>#define
</a> FOO_600
0
1036 <a href='ref-ppdcfile.html#_define'
>#define
</a> FOO_1200
1
1039 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "$MANUFACTURER"
1040 <a href='ref-ppdcfile.html#ModelNumber'
>ModelNumber
</a> $FOO_600
1041 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
1046 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "$MANUFACTURER"
1047 <a href='ref-ppdcfile.html#ModelNumber'
>ModelNumber
</a> $FOO_1200
1048 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2001"
1053 <P>Numeric constants can be bitwise OR'd together by placing the constants
1054 inside parenthesis, for example:
</P>
1056 <pre class='example'
>
1057 <I>// ModelNumber capability bits
</I>
1058 <a href='ref-ppdcfile.html#_define'
>#define
</a> DUPLEX
1
1059 <a href='ref-ppdcfile.html#_define'
>#define
</a> COLOR
2
1064 <I>// Define a model number specifying the capabilities of the printer...
</I>
1065 <a href='ref-ppdcfile.html#ModelNumber'
>ModelNumber
</a> ($DUPLEX $COLOR)
1071 <h3><a name='CONDITIONAL'
>Conditional Statements
</a></h3>
1073 <p>The PPD compiler supports conditional compilation using the
<tt>#if
</tt>,
1074 <tt>#elif
</tt>,
<tt>#else
</tt>, and
<tt>#endif
</tt> directives. The
<tt>#if
</tt>
1075 and
<tt>#elif
</tt> directives are followed by a constant name or an expression.
1076 For example, to include a group of options when
"ADVANCED" is defined:
</p>
1078 <pre class='example'
>
1079 <a href='ref-ppdcfile.html#_if'
>#if
</a> ADVANCED
1080 <a href='ref-ppdcfile.html#Group'
>Group
</a> "Advanced/Advanced Options"
1081 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooCyanAdjust/Cyan Adjustment"
1082 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus10/+10%" ""
1083 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus5/+5%" ""
1084 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "none/No Adjustment" ""
1085 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus5/-5%" ""
1086 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus10/-10%" ""
1087 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooMagentaAdjust/Magenta Adjustment"
1088 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus10/+10%" ""
1089 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus5/+5%" ""
1090 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "none/No Adjustment" ""
1091 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus5/-5%" ""
1092 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus10/-10%" ""
1093 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooYellowAdjust/Yellow Adjustment"
1094 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus10/+10%" ""
1095 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus5/+5%" ""
1096 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "none/No Adjustment" ""
1097 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus5/-5%" ""
1098 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus10/-10%" ""
1099 <a href='ref-ppdcfile.html#Option'
>Option
</a> "fooBlackAdjust/Black Adjustment"
1100 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus10/+10%" ""
1101 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "plus5/+5%" ""
1102 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "none/No Adjustment" ""
1103 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus5/-5%" ""
1104 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "minus10/-10%" ""
1105 <a href='ref-ppdcfile.html#_endif'
>#endif
</a>
1109 <h3><a name='CONSTRAINTS'
>Defining Constraints
</a></h3>
1111 <P>Constraints are strings that are used to specify that one or more option
1112 choices are incompatible, for example two-sided printing on transparency media.
1113 Constraints are also used to prevent the use of uninstalled features such as the
1114 duplexer unit, additional media trays, and so forth.
</P>
1116 <P>The
<TT>UIConstraints
</TT> directive is used to specify a constraint that is
1117 placed in the PPD file. The directive is followed by a string using one of the
1118 following formats:
</P>
1120 <pre class='example'
>
1121 <a href='ref-ppdcfile.html#UIConstraints'
>UIConstraints
</a> "*Option1 *Option2"
1122 <a href='ref-ppdcfile.html#UIConstraints'
>UIConstraints
</a> "*Option1 Choice1 *Option2"
1123 <a href='ref-ppdcfile.html#UIConstraints'
>UIConstraints
</a> "*Option1 *Option2 Choice2"
1124 <a href='ref-ppdcfile.html#UIConstraints'
>UIConstraints
</a> "*Option1 Choice1 *Option2 Choice2"
1127 <P>Each option name is preceded by the asterisk (
<TT>*
</TT>). If no choice is
1128 given for an option, then all choices
<I>except
</I> <TT>False
</TT> and
1129 <TT>None
</TT> will conflict with the other option and choice(s). Since the PPD
1130 compiler automatically adds reciprocal constraints (option A conflicts with
1131 option B, so therefore option B conflicts with option A), you need only specify
1132 the constraint once.
</P>
1134 <p class='example'
><a name=
"LISTING5">Listing
5:
"examples/constraint.drv"</a></p>
1136 <pre class='example'
>
1138 <I>// Include standard font and media definitions
</I>
1139 <a href='ref-ppdcfile.html#_include'
>#include
</a> <font.defs
>
1140 <a href='ref-ppdcfile.html#_include'
>#include
</a> <media.defs
>
1142 <I>// List the fonts that are supported, in this case all standard fonts...
</I>
1143 <a href='ref-ppdcfile.html#Font'
>Font
</a> *
1145 <I>// Manufacturer, model name, and version
</I>
1146 <a href='ref-ppdcfile.html#Manufacturer'
>Manufacturer
</a> "Foo"
1147 <a href='ref-ppdcfile.html#ModelName'
>ModelName
</a> "FooJet 2000"
1148 <a href='ref-ppdcfile.html#Version'
>Version
</a> 1.0
1150 <I>// Each filter provided by the driver...
</I>
1151 <a href='ref-ppdcfile.html#Filter'
>Filter
</a> application/vnd.cups-raster
100 rastertofoo
1153 <I>// Supported page sizes
</I>
1154 *
<a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> Letter
1155 <a href='ref-ppdcfile.html#MediaSize'
>MediaSize
</a> A4
1157 <I>// Supported resolutions
</I>
1158 *
<a href='ref-ppdcfile.html#Resolution'
>Resolution
</a> k
8 0 0 0 "600dpi/600 DPI"
1160 <I>// Installable Option Group
</I>
1161 <a href='ref-ppdcfile.html#Group'
>Group
</a> "InstallableOptions/Options Installed"
1163 <I>// Duplexing unit option
</I>
1164 <a href='ref-ppdcfile.html#Option'
>Option
</a> "OptionDuplexer/Duplexing Unit" Boolean AnySetup
10
1165 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> True/Installed
""
1166 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "False/Not Installed" ""
1168 <I>// General Option Group
</I>
1169 <a href='ref-ppdcfile.html#Group'
>Group
</a> General
1171 <I>// Duplexing option
</I>
1172 <a href='ref-ppdcfile.html#Option'
>Option
</a> "Duplex/Two-Sided Printing" PickOne AnySetup
10
1173 *
<a href='ref-ppdcfile.html#Choice'
>Choice
</a> "None/No" "<</Duplex false>>setpagedevice""
1174 <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexNoTumble/Long Edge Binding
"
1175 "<</Duplex true/Tumble false
>>setpagedevice
""
1176 <a href='ref-ppdcfile.html#Choice'
>Choice
</a> "DuplexTumble/Short Edge Binding"
1177 "<</Duplex true/Tumble true>>setpagedevice""
1179 <I>// Only allow duplexing if the duplexer is installed</I>
1180 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False
"
1182 <I>// Specify the name of the PPD file we want to generate...</I>
1183 <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd
"
1186 <P><A HREF="#LISTING5
">Listing 5</A> shows a variation of the first example with
1187 an added <TT>Duplex</TT> option and installable option for the duplexer,
1188 <TT>OptionDuplex</TT>. A constraint is added at the end to specify that any
1189 choice of the <TT>Duplex</TT> option that is not <TT>None</TT> is incompatible
1190 with the "Duplexer Installed
" option set to "Not Installed
"
1191 (<TT>False</TT>):</P>
1193 <pre class='example'>
1194 <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False
"
1197 <h4>Enhanced Constraints</h4>
1199 <p>CUPS 1.4 supports constraints between 2 or more options using the
1200 <TT>Attribute</TT> directive. <TT>cupsUIConstraints</TT> attributes define
1201 the constraints, while <TT>cupsUIResolver</TT> attributes define option changes
1202 to resolve constraints. For example, we can specify the previous duplex
1203 constraint with a resolver that turns off duplexing with the following two
1206 <pre class='example'>
1207 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIConstraints DuplexOff "*Duplex *OptionDuplexer False
"
1208 <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIResolver DuplexOff "*Duplex None
"
1211 <h2 class='title'><a name='LOCALIZATION'>Localization</a></h2>
1213 <p>The PPD compiler provides localization of PPD files in different languages
1214 through <i>message catalog</i> files in the GNU gettext or Apple .strings
1215 formats. Each user text string and several key PPD attribute values such as
1216 <tt>LanguageVersion</tt> and <tt>LanguageEncoding</tt> are looked up in the
1217 corresponding message catalog and the translated text is substituted in the
1218 generated PPD files. One message catalog file can be used by multiple driver
1219 information files, and each file contains a single language translation.</p>
1221 <h3><a name='PPDPO'>The ppdpo Utility</a></h3>
1223 <p>While CUPS includes localizations of all standard media sizes and options in
1224 several languages, your driver information files may provide their own media
1225 sizes and options that need to be localized. CUPS provides a utility program to
1226 aid in the localization of drivers called <a
1227 href='man-ppdpo.html'><tt>ppdpo(1)</tt></a>. The <tt>ppdpo</tt> program creates
1228 or updates a message catalog file based upon one or more driver information
1229 files. New messages are added with the word "TRANSLATE
" added to the front of
1230 the translation string to make locating new strings for translation easier. The
1231 program accepts the message catalog filename and one or more driver information
1234 <p>For example, run the following command to create a new German message catalog
1235 called <var>de.po</var> for all of the driver information files in the current
1238 <pre class='command'>
1239 ppdpo -o de.po *.drv
1242 <p>If the file <var>de.po</var> already exists, <tt>ppdpo</tt> will update the
1243 contents of the file with any new messages that need to be translated. To create
1244 an Apple .strings file instead, specify the output filename with a .strings
1245 extension, for example:</p>
1247 <pre class='command'>
1248 ppdpo -o de.strings *.drv
1251 <h3><a name='PPDC_CATALOG'>Using Message Catalogs with the PPD Compiler</a></h3>
1253 <p>Once you have created a message catalog, use the <a
1254 href='ref-ppdcfile.html#_po'><tt>#po</tt></a> directive to declare it in each
1255 driver information file. For example, to declare the German message catalog for
1258 <pre class='example'>
1259 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po
" // German
1262 <p>In fact, you can use the <tt>#po</tt> directive as many times as needed:</p>
1264 <pre class='example'>
1265 <a href='ref-ppdcfile.html#_po'>#po</a> de "de.po
" // German
1266 <a href='ref-ppdcfile.html#_po'>#po</a> es "es.po
" // Spanish
1267 <a href='ref-ppdcfile.html#_po'>#po</a> fr "fr.po
" // French
1268 <a href='ref-ppdcfile.html#_po'>#po</a> it "it.po
" // Italian
1269 <a href='ref-ppdcfile.html#_po'>#po</a> ja "ja.po
" // Japanese
1272 <p>The filename ("de.po
", etc.) can be relative to the location of the driver
1273 information file or an absolute path. Once defined, the PPD compiler will
1274 automatically generate a globalized PPD for every language declared in your
1275 driver information file. To generate a single-language PPD file, simply use the
1276 <tt>-l</tt> option to list the corresponding locale, for example:</p>
1278 <pre class='command'>
1279 ppdc -l de -d ppd/de mydrivers.drv
1282 <p>to generate German PPD files.</p>