]>
Commit | Line | Data |
---|---|---|
28b9d139 MS |
1 | <HTML> |
2 | <!-- SECTION: Programming --> | |
3 | <HEAD> | |
4 | <TITLE>Introduction to the PPD Compiler</TITLE> | |
5 | </HEAD> | |
6 | <BODY> | |
7 | ||
8 | <P>This document describes how to use the CUPS PostScript Printer Description | |
9 | (PPD) file compiler. The PPD compiler generates PPD files from simple text files | |
10 | that describe the features and capabilities of one or more printers.</P> | |
11 | ||
12 | <div class='summary'><table summary='General Information'> | |
13 | <tbody> | |
14 | <tr> | |
15 | <th>See Also</th> | |
16 | <td>Programming: <a href='raster-driver.html'>Developing Raster Printer Drivers</a><br> | |
17 | Programming: <a href='postscript-driver.html'>Developing PostScript Printer Drivers</a><br> | |
18 | Programming: <a href='api-filter.html'>Filter and Backend Programming</a><br> | |
19 | Programming: <a href='api-raster.html'>Raster API</a><br> | |
20 | References: <a href='ref-ppdcfile.html'>PPD Compiler Driver Information File Reference</a><br> | |
21 | Specifications: <a href='spec-ppd.html'>CUPS PPD Extensions</a></td> | |
22 | </tr> | |
23 | </tbody> | |
24 | </table></div> | |
25 | ||
26 | ||
27 | <h2 class='title'><a name='BASICS'>The Basics</a></h2> | |
28 | ||
29 | <P>The PPD compiler, <a href='man-ppdc.html'><code>ppdc(1)</code></a>, is a | |
30 | simple command-line tool that takes a single <I>driver information file</I>, | |
31 | which by convention uses the extension <VAR>.drv</VAR>, and produces one or more | |
32 | PPD files that may be distributed with your printer drivers for use with CUPS. | |
33 | For example, you would run the following command to create the English language | |
34 | PPD files defined by the driver information file <VAR>mydrivers.drv</VAR>:</P> | |
35 | ||
36 | <pre class='command'> | |
37 | ppdc mydrivers.drv | |
38 | </pre> | |
39 | ||
40 | <P>The PPD files are placed in a subdirectory called | |
41 | <VAR>ppd</VAR>. The <TT>-d</TT> option is used to put the PPD | |
42 | files in a different location, for example:</p> | |
43 | ||
44 | <pre class='command'> | |
45 | ppdc -d myppds mydrivers.drv | |
46 | </pre> | |
47 | ||
48 | <P>places the PPD files in a subdirectory named | |
49 | <VAR>myppds</VAR>. Finally, use the <TT>-l</TT> option to | |
50 | specify the language localization for the PPD files that are | |
51 | created, for example:</P> | |
52 | ||
53 | <pre class='command'> | |
54 | ppdc -d myppds/de -l de mydrivers.drv | |
55 | ppdc -d myppds/en -l en mydrivers.drv | |
56 | ppdc -d myppds/es -l es mydrivers.drv | |
57 | ppdc -d myppds/fr -l fr mydrivers.drv | |
58 | ppdc -d myppds/it -l it mydrivers.drv | |
59 | </pre> | |
60 | ||
61 | <P>creates PPD files in German (de), English (en), Spanish (es), | |
62 | French (fr), and Italian (it) in the corresponding | |
63 | subdirectories. Specify multiple languages (separated by commas) to produce | |
64 | "globalized" PPD files:</p> | |
65 | ||
66 | <pre class='command'> | |
67 | ppdc -d myppds -l de,en,es,fr,it mydrivers.drv | |
68 | </pre> | |
69 | ||
70 | ||
71 | <h2 class='title'><a name='DRV'>Driver Information Files</a></h2> | |
72 | ||
73 | <P>The driver information files accepted by the PPD compiler are | |
74 | plain text files that define the various attributes and options | |
75 | that are included in the PPD files that are generated. A driver | |
76 | information file can define the information for one or more printers and | |
77 | their corresponding PPD files.</P> | |
78 | ||
79 | <p class='example'><a name="LISTING1">Listing 1: "examples/minimum.drv"</a></p> | |
80 | ||
81 | <pre class='example'> | |
82 | <I>// Include standard font and media definitions</I> | |
83 | <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> | |
84 | <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> | |
85 | ||
86 | <I>// List the fonts that are supported, in this case all standard fonts...</I> | |
87 | <a href='ref-ppdcfile.html#Font'>Font</a> * | |
88 | ||
89 | <I>// Manufacturer, model name, and version</I> | |
90 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" | |
91 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
92 | <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 | |
93 | ||
94 | <I>// Each filter provided by the driver...</I> | |
95 | <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo | |
96 | ||
97 | <I>// Supported page sizes</I> | |
98 | *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter | |
99 | <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 | |
100 | ||
101 | <I>// Supported resolutions</I> | |
102 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
103 | ||
104 | <I>// Specify the name of the PPD file we want to generate...</I> | |
105 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
106 | </pre> | |
107 | ||
108 | ||
109 | <h3><a name='SIMPLE'>A Simple Example</a></h3> | |
110 | ||
111 | <P>The example in <A HREF="#LISTING1">Listing 1</A> shows a driver information | |
112 | file which defines the minimum required attributes to provide a valid PPD file. | |
113 | The first part of the file includes standard definition files for fonts and | |
114 | media sizes:</P> | |
115 | ||
116 | <pre class='example'> | |
117 | <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> | |
118 | <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> | |
119 | </pre> | |
120 | ||
121 | <P>The <TT>#include</TT> directive works just like the C/C++ include directive; | |
122 | files included using the angle brackets (<TT><filename></TT>) are found | |
123 | in any of the standard include directories and files included using quotes | |
124 | (<TT>"filename"</TT>) are found in the same directory as the source or include | |
125 | file. The <TT><font.defs></TT> include file defines the standard fonts | |
126 | which are included with GPL Ghostscript and the Apple PDF RIP, while the | |
127 | <TT><media.defs></TT> include file defines the standard media sizes | |
128 | listed in Appendix B of the Adobe PostScript Printer Description File Format | |
129 | Specification.</P> | |
130 | ||
131 | <P>CUPS provides several other standard include files:</P> | |
132 | ||
133 | <UL> | |
134 | ||
135 | <LI><TT><epson.h></TT> - Defines all of the rastertoepson driver | |
136 | constants.</LI> | |
137 | ||
138 | <LI><TT><escp.h></TT> - Defines all of the rastertoescpx driver | |
139 | constants.</LI> | |
140 | ||
141 | <LI><TT><hp.h></TT> - Defines all of the rastertohp driver | |
142 | constants.</LI> | |
143 | ||
144 | <LI><TT><label.h></TT> - Defines all of the rastertolabel driver | |
145 | constants.</LI> | |
146 | ||
147 | <LI><TT><pcl.h></TT> - Defines all of the rastertopclx driver | |
148 | constants.</LI> | |
149 | ||
150 | <LI><TT><raster.defs></TT> - Defines all of the CUPS raster format | |
151 | constants.</LI> | |
152 | ||
153 | </UL> | |
154 | ||
155 | <P>Next we list all of the fonts that are available in the driver; for CUPS | |
156 | raster drivers, the following line is all that is usually supplied:</P> | |
157 | ||
158 | <pre class='example'> | |
159 | <a href='ref-ppdcfile.html#Font'>Font</a> * | |
160 | </pre> | |
161 | ||
162 | <P>The <TT>Font</TT> directive specifies the name of a single font or the | |
163 | asterisk to specify all fonts. For example, you would use the following line to | |
164 | define an additional bar code font that you are supplying with your printer | |
165 | driver:</P> | |
166 | ||
167 | <pre class='example'> | |
168 | <I>// name encoding version charset status</I> | |
169 | <a href='ref-ppdcfile.html#Font'>Font</a> Barcode-Foo Special "(1.0)" Special ROM | |
170 | </pre> | |
171 | ||
172 | <P>The name of the font is <TT>Barcode-Foo</TT>. Since it is not a standard | |
173 | text font, the encoding and charset name <TT>Special</TT> is used. The version | |
174 | number is <TT>1.0</TT> and the status (where the font is located) is | |
175 | <TT>ROM</TT> to indicate that the font does not need to be embedded in | |
176 | documents that use the font for this printer.</P> | |
177 | ||
178 | <P>Third comes the manufacturer, model name, and version number information | |
179 | strings:</P> | |
180 | ||
181 | <pre class='example'> | |
182 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" | |
183 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
184 | <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 | |
185 | </pre> | |
186 | ||
187 | <P>These strings are used when the user (or auto-configuration program) selects | |
188 | the printer driver for a newly connected device.</p> | |
189 | ||
190 | <P>The list of filters comes after the information strings; for the example in | |
191 | <A HREF="#LISTING1">Listing 1</A>, we have a single filter that takes CUPS | |
192 | raster data:</P> | |
193 | ||
194 | <pre class='example'> | |
195 | <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo | |
196 | </pre> | |
197 | ||
198 | <P>Each filter specified in the driver information file is the equivalent of a | |
199 | printer driver for that format; if a user submits a print job in a different | |
200 | format, CUPS figures out the sequence of commands that will produce a supported | |
201 | format for the least relative cost.</P> | |
202 | ||
203 | <P>Once we have defined the driver information we specify the supported options. | |
204 | For the example driver we support a single resolution of 600 dots per inch and | |
205 | two media sizes, A4 and Letter:</P> | |
206 | ||
207 | <pre class='example'> | |
208 | *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter | |
209 | <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 | |
210 | ||
211 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
212 | </pre> | |
213 | ||
214 | <P>The asterisk in front of the <TT>MediaSize</TT> and <TT>Resolution</TT> | |
215 | directives specify that those option choices are the default. The | |
216 | <TT>MediaSize</TT> directive is followed by a media size name which is normally | |
217 | defined in the <TT><media.defs></TT> file and corresponds to a standard | |
218 | Adobe media size name. If the default media size is <TT>Letter</TT>, the PPD | |
219 | compiler will override it to be <TT>A4</TT> for non-English localizations for | |
220 | you automatically.</P> | |
221 | ||
222 | <P>The <TT>Resolution</TT> directive accepts several values after it as | |
223 | follows:</P> | |
224 | ||
225 | <OL> | |
226 | ||
227 | <LI>Colorspace for this resolution, if any. In the example file, the | |
228 | colorspace <TT>k</TT> is used which corresponds to black. For printer | |
229 | drivers that support color printing, this field is usually specified as | |
230 | "-" for "no change".</LI> | |
231 | ||
232 | <LI>Bits per color. In the example file, we define 8 bits per color, for | |
233 | a continuous-tone grayscale output. All versions of CUPS support 1 and | |
234 | 8 bits per color. CUPS 1.2 and higher (Mac OS X 10.5 and higher) also | |
235 | supports 16 bits per color.</LI> | |
236 | ||
237 | <LI>Rows per band. In the example file, we define 0 rows per band to | |
238 | indicate that our printer driver does not process the page in | |
239 | bands.</LI> | |
240 | ||
241 | <LI>Row feed. In the example, we define the feed value to be 0 to | |
242 | indicate that our printer driver does not interleave the output.</LI> | |
243 | ||
244 | <LI>Row step. In the example, we define the step value to be 0 to | |
245 | indicate that our printer driver does not interleave the output. This | |
246 | value normally indicates the spacing between the nozzles of an inkjet | |
247 | printer - when combined with the previous two values, it informs the | |
248 | driver how to stagger the output on the page to produce interleaved | |
249 | lines on the page for higher-resolution output.</LI> | |
250 | ||
251 | <LI>Choice name and text. In the example, we define the choice name and | |
252 | text to be <TT>"600dpi/600 DPI"</TT>. The name and text are separated by | |
253 | slash (<TT>/</TT>) character; if no text is specified, then the name is | |
254 | used as the text. The PPD compiler parses the name to determine the | |
255 | actual resolution; the name can be of the form | |
256 | <TT><I>RESOLUTION</I>dpi</TT> for resolutions that are equal | |
257 | horizontally and vertically or <TT><I>HRES</I>x<I>VRES</I>dpi</TT> for | |
258 | isometric resolutions. Only integer resolution values are supported, so | |
259 | a resolution name of <TT>300dpi</TT> is valid while <TT>300.1dpi</TT> is | |
260 | not.</LI> | |
261 | ||
262 | </OL> | |
263 | ||
264 | <P>Finally, the <TT>PCFileName</TT> directive specifies that the named PPD file | |
265 | should be written for the current driver definitions:</P> | |
266 | ||
267 | <pre class='example'> | |
268 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
269 | </pre> | |
270 | ||
271 | <P>The filename follows the directive and <I>must</I> conform to the Adobe | |
272 | filename requirements in the Adobe Postscript Printer Description File Format | |
273 | Specification. Specifically, the filename may not exceed 8 characters followed | |
274 | by the extension <VAR>.ppd</VAR>. The <TT>FileName</TT> directive can be used to | |
275 | specify longer filenames:</P> | |
276 | ||
277 | <pre class='example'> | |
278 | <a href='ref-ppdcfile.html#FileName'>FileName</a> "FooJet 2000" | |
279 | </pre> | |
280 | ||
281 | ||
282 | <h3><a name='GROUPING'>Grouping and Inheritance</a></h3> | |
283 | ||
284 | <P>The previous example created a single PPD file. Driver information files can | |
285 | also define multiple printers by using the PPD compiler grouping functionality. | |
286 | Directives are grouped using the curly braces (<TT>{</TT> and <TT>}</TT>) and | |
287 | every group that uses the <TT>PCFileName</TT> or <TT>FileName</TT> directives | |
288 | produces a PPD file with that name. <A HREF="#LISTING2">Listing 2</A> shows a | |
289 | variation of the original example that uses two groups to define two printers | |
290 | that share the same printer driver filter but provide two different resolution | |
291 | options.</P> | |
292 | ||
293 | <p class='example'><a name="LISTING2">Listing 2: "examples/grouping.drv"</a></p> | |
294 | ||
295 | <pre class='example'> | |
296 | ||
297 | <I>// Include standard font and media definitions</I> | |
298 | <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> | |
299 | <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> | |
300 | ||
301 | <I>// List the fonts that are supported, in this case all standard fonts...</I> | |
302 | <a href='ref-ppdcfile.html#Font'>Font</a> * | |
303 | ||
304 | <I>// Manufacturer and version</I> | |
305 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" | |
306 | <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 | |
307 | ||
308 | <I>// Each filter provided by the driver...</I> | |
309 | <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo | |
310 | ||
311 | <I>// Supported page sizes</I> | |
312 | *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter | |
313 | <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 | |
314 | ||
315 | { | |
316 | <I>// Supported resolutions</I> | |
317 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
318 | ||
319 | <I>// Specify the model name and filename...</I> | |
320 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
321 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
322 | } | |
323 | ||
324 | { | |
325 | <I>// Supported resolutions</I> | |
326 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "1200dpi/1200 DPI" | |
327 | ||
328 | <I>// Specify the model name and filename...</I> | |
329 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001" | |
330 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojt2k1.ppd" | |
331 | } | |
332 | </pre> | |
333 | ||
334 | <P>The second example is essentially the same as the first, except that each | |
335 | printer model is defined inside of a pair of curly braces. For example, the | |
336 | first printer is defined using:</P> | |
337 | ||
338 | <pre class='example'> | |
339 | { | |
340 | // Supported resolutions | |
341 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
342 | ||
343 | // Specify the model name and filename... | |
344 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
345 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
346 | } | |
347 | </pre> | |
348 | ||
349 | <P>The printer <I>inherits</I> all of the definitions from the parent group (the | |
350 | top part of the file) and adds the additional definitions inside the curly | |
351 | braces for that printer driver. When we define the second group, it also | |
352 | inherits the same definitions from the parent group but <I>none</I> of the | |
353 | definitions from the first driver. Groups can be nested to any number of levels | |
354 | to support variations of similar models without duplication of information.</P> | |
355 | ||
356 | ||
357 | <h3><a name='COLOR'>Color Support</a></h3> | |
358 | ||
359 | <P>For printer drivers that support color printing, the | |
360 | <TT>ColorDevice</TT> and <TT>ColorModel</TT> directives should be | |
361 | used to tell the printing system that color output is desired | |
362 | and in what formats. <A HREF="#LISTING3">Listing 3</A> shows a | |
363 | variation of the previous example which includes a color printer | |
364 | that supports printing at 300 and 600 DPI.</P> | |
365 | ||
366 | <P>The key changes are the addition of the <TT>ColorDevice</TT> | |
367 | directive:</P> | |
368 | ||
369 | <pre class='example'> | |
370 | <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true | |
371 | </pre> | |
372 | ||
373 | <P>which tells the printing system that the printer supports | |
374 | color printing, and the <TT>ColorModel</TT> directives:</P> | |
375 | ||
376 | <pre class='example'> | |
377 | <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0 | |
378 | *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0 | |
379 | </pre> | |
380 | ||
381 | <P>which tell the printing system which colorspaces are supported by the printer | |
382 | driver for color printing. Each of the <TT>ColorModel</TT> directives is | |
383 | followed by the option name and text (<TT>Gray/Grayscale</TT> and | |
384 | <TT>RGB/Color</TT>), the colorspace name (<TT>w</TT> and <TT>rgb</TT>), the | |
385 | color organization (<TT>chunky</TT>), and the compression mode number | |
386 | (<TT>0</TT>) to be passed to the driver. The option name can be any of the | |
387 | standard Adobe <TT>ColorModel</TT> names:</P> | |
388 | ||
389 | <UL> | |
390 | ||
391 | <LI><TT>Gray</TT> - Grayscale output. | |
392 | ||
393 | <LI><TT>RGB</TT> - Color output, typically using the RGB | |
394 | colorspace, but without a separate black channel. | |
395 | ||
396 | <LI><TT>CMYK</TT> - Color output with a separate black | |
397 | channel. | |
398 | ||
399 | </UL> | |
400 | ||
401 | <P>Custom names can be used, however it is recommended that you use your vendor | |
402 | prefix for any custom names, for example "fooName".</P> | |
403 | ||
404 | <P>The colorspace name can be any of the following universally supported | |
405 | colorspaces:</P> | |
406 | ||
407 | <UL> | |
408 | <LI><TT>w</TT> - Luminance</LI> | |
409 | ||
410 | <LI><TT>rgb</TT> - Red, green, blue</LI> | |
411 | ||
412 | <LI><TT>k</TT> - Black</LI> | |
413 | ||
414 | <LI><TT>cmy</TT> - Cyan, magenta, yellow</LI> | |
415 | ||
416 | <LI><TT>cmyk</TT> - Cyan, magenta, yellow, black</LI> | |
417 | ||
418 | </UL> | |
419 | ||
420 | <P>The color organization can be any of the following values:</P> | |
421 | ||
422 | <UL> | |
423 | ||
424 | <LI><TT>chunky</TT> - Color values are passed together on a line | |
425 | as RGB RGB RGB RGB</LI> | |
426 | ||
427 | <LI><TT>banded</TT> - Color values are passed separately | |
428 | on a line as RRRR GGGG BBBB; not supported by the Apple | |
429 | RIP filters</LI> | |
430 | ||
431 | <LI><TT>planar</TT> - Color values are passed separately | |
432 | on a page as RRRR RRRR RRRR ... GGGG GGGG GGGG ... BBBB | |
433 | BBBB BBBB; not supported by the Apple RIP filters</LI> | |
434 | ||
435 | </UL> | |
436 | ||
437 | <P>The compression mode value is passed to the driver in the | |
438 | <TT>cupsCompression</TT> attribute. It is traditionally used to select an | |
439 | appropriate compression mode for the color model but can be used for any | |
440 | purpose, such as specifying a photo mode vs. standard mode.</P> | |
441 | ||
442 | <p class='example'><a name="LISTING3">Listing 3: "examples/color.drv"</a></p> | |
443 | ||
444 | <pre class='example'> | |
445 | ||
446 | <I>// Include standard font and media definitions</I> | |
447 | <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> | |
448 | <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> | |
449 | ||
450 | <I>// List the fonts that are supported, in this case all standard fonts...</I> | |
451 | <a href='ref-ppdcfile.html#Font'>Font</a> * | |
452 | ||
453 | <I>// Manufacturer and version</I> | |
454 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" | |
455 | <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 | |
456 | ||
457 | <I>// Each filter provided by the driver...</I> | |
458 | <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo | |
459 | ||
460 | <I>// Supported page sizes</I> | |
461 | *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter | |
462 | <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 | |
463 | ||
464 | { | |
465 | <I>// Supported resolutions</I> | |
466 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
467 | ||
468 | <I>// Specify the model name and filename...</I> | |
469 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
470 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
471 | } | |
472 | ||
473 | { | |
474 | <I>// Supports color printing</I> | |
475 | <a href='ref-ppdcfile.html#ColorDevice'>ColorDevice</a> true | |
476 | ||
477 | <I>// Supported colorspaces</I> | |
478 | <a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> Gray/Grayscale w chunky 0 | |
479 | *<a href='ref-ppdcfile.html#ColorModel'>ColorModel</a> RGB/Color rgb chunky 0 | |
480 | ||
481 | <I>// Supported resolutions</I> | |
482 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "300dpi/300 DPI" | |
483 | <a href='ref-ppdcfile.html#Resolution'>Resolution</a> - 8 0 0 0 "600dpi/600 DPI" | |
484 | ||
485 | <I>// Specify the model name and filename...</I> | |
486 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet Color" | |
487 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojetco.ppd" | |
488 | } | |
489 | </pre> | |
490 | ||
491 | ||
492 | <h3><a name='OPTIONS'>Defining Custom Options and Option Groups</a></h3> | |
493 | ||
494 | <P>The <TT>Group</TT>, <TT>Option</TT>, and <TT>Choice</TT> | |
495 | directives are used to define or select a group, option, or | |
496 | choice. <A HREF="#LISTING4">Listing 4</A> shows a variation of | |
497 | the first example that provides two custom options in a group | |
498 | named "Footasm".</P> | |
499 | ||
500 | <p class='example'><a name="LISTING4">Listing 4: "examples/custom.drv"</a></p> | |
501 | ||
502 | <pre class='example'> | |
503 | ||
504 | <I>// Include standard font and media definitions</I> | |
505 | <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> | |
506 | <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> | |
507 | ||
508 | <I>// List the fonts that are supported, in this case all standard fonts...</I> | |
509 | <a href='ref-ppdcfile.html#Font'>Font</a> * | |
510 | ||
511 | <I>// Manufacturer, model name, and version</I> | |
512 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" | |
513 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
514 | <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 | |
515 | ||
516 | <I>// Each filter provided by the driver...</I> | |
517 | <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo | |
518 | ||
519 | <I>// Supported page sizes</I> | |
520 | *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter | |
521 | <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 | |
522 | ||
523 | <I>// Supported resolutions</I> | |
524 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
525 | ||
526 | <I>// Option Group</I> | |
527 | <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm" | |
528 | ||
529 | <I>// Boolean option</I> | |
530 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10 | |
531 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "<</cupsCompression 1>>setpagedevice" | |
532 | <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "<</cupsCompression 0>>setpagedevice" | |
533 | ||
534 | <I>// Multiple choice option</I> | |
535 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooOutputType/Output Quality" PickOne AnySetup 10 | |
536 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "Auto/Automatic Selection" | |
537 | "<</OutputType(Auto)>>setpagedevice"" | |
538 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "Text/Optimize for Text" | |
539 | "<</OutputType(Text)>>setpagedevice"" | |
540 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "Graph/Optimize for Graphics" | |
541 | "<</OutputType(Graph)>>setpagedevice"" | |
542 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "Photo/Optimize for Photos" | |
543 | "<</OutputType(Photo)>>setpagedevice"" | |
544 | ||
545 | <I>// Specify the name of the PPD file we want to generate...</I> | |
546 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
547 | </pre> | |
548 | ||
549 | <P>The custom group is introduced by the <TT>Group</TT> | |
550 | directive which is followed by the name and optionally text for | |
551 | the user:</P> | |
552 | ||
553 | <pre class='example'> | |
554 | <a href='ref-ppdcfile.html#Group'>Group</a> "Footasm/Footastic Options" | |
555 | </pre> | |
556 | ||
557 | <P>The group name must conform to the PPD specification and | |
558 | cannot exceed 40 characters in length. If you specify user text, | |
559 | it cannot exceed 80 characters in length. The groups | |
560 | <TT>General</TT>, <TT>Extra</TT>, and | |
561 | <TT>InstallableOptions</TT> are predefined by CUPS; the general | |
562 | and extra groups are filled by the UI options defined by the PPD | |
563 | specification. The <TT>InstallableOptions</TT> group is reserved | |
564 | for options that define whether accessories for the printer | |
565 | (duplexer unit, finisher, stapler, etc.) are installed.</P> | |
566 | ||
567 | <P>Once the group is specified, the <TT>Option</TT> directive is | |
568 | used to introduce a new option:</P> | |
569 | ||
570 | <pre class='example'> | |
571 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooEnhance/Resolution Enhancement" Boolean AnySetup 10 | |
572 | </pre> | |
573 | ||
574 | <P>The directive is followed by the name of the option and any | |
575 | optional user text, the option type, the PostScript document group, and | |
576 | the sort order number. The option name must conform to the PPD specification | |
577 | and cannot exceed 40 characters in length. If you specify user text, it | |
578 | cannot exceed 80 characters in length.</P> | |
579 | ||
580 | <P>The option type can be <TT>Boolean</TT> for true/false | |
581 | selections, <TT>PickOne</TT> for picking one of many choices, or | |
582 | <TT>PickMany</TT> for picking zero or more choices. Boolean | |
583 | options can have at most two choices with the names | |
584 | <TT>False</TT> and <TT>True</TT>. Pick options can have any | |
585 | number of choices, although for Windows compatibility reasons | |
586 | the number of choices should not exceed 255.</P> | |
587 | ||
588 | <P>The PostScript document group is typically <TT>AnySetup</TT>, | |
589 | meaning that the option can be introduced at any point in the | |
590 | PostScript document. Other values include <TT>PageSetup</TT> to | |
591 | include the option before each page and <TT>DocumentSetup</TT> | |
592 | to include the option once at the beginning of the document.</P> | |
593 | ||
594 | <P>The sort order number is used to sort the printer commands | |
595 | associated with each option choice within the PostScript | |
596 | document. This allows you to setup certain options before others | |
597 | as required by the printer. For most CUPS raster printer | |
598 | drivers, the value <TT>10</TT> can be used for all options.</P> | |
599 | ||
600 | <P>Once the option is specified, each option choice can be | |
601 | listed using the <TT>Choice</TT> directive:</P> | |
602 | ||
603 | <pre class='example'> | |
604 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> True/Yes "<</cupsCompression 1>>setpagedevice" | |
605 | <a href='ref-ppdcfile.html#Choice'>Choice</a> False/No "<</cupsCompression 0>>setpagedevice" | |
606 | </pre> | |
607 | ||
608 | <P>The directive is followed by the choice name and optionally | |
609 | user text, and the PostScript commands that should be inserted | |
610 | when printing a file to this printer. The option name must | |
611 | conform to the PPD specification and cannot exceed 40 characters | |
612 | in length. If you specify user text, it cannot exceed 80 | |
613 | characters in length.</P> | |
614 | ||
615 | <P>The PostScript commands are also interpreted by any RIP | |
616 | filters, so these commands typically must be present for all | |
617 | option choices. Most commands take the form:</P> | |
618 | ||
619 | <pre class='example'> | |
620 | <</name value>>setpagedevice | |
621 | </pre> | |
622 | ||
623 | <P>where <TT>name</TT> is the name of the PostScript page device | |
624 | attribute and <TT>value</TT> is the numeric or string value for | |
625 | that attribute.</P> | |
626 | ||
627 | ||
628 | <h3><a name='DEFINE'>Defining Constants</a></h3> | |
629 | ||
630 | <P>Sometimes you will want to define constants for your drivers | |
631 | so that you can share values in different groups within the same | |
632 | driver information file, or to share values between different | |
633 | driver information files using the <TT>#include</TT> directive. | |
634 | The <TT>#define</TT> directive is used to define constants for | |
635 | use in your printer definitions:</P> | |
636 | ||
637 | <pre class='example'> | |
638 | <a href='ref-ppdcfile.html#_define'>#define</a> NAME value | |
639 | </pre> | |
640 | ||
641 | <P>The <TT>NAME</TT> is any sequence of letters, numbers, and | |
642 | the underscore. The <TT>value</TT> is a number or string; if the | |
643 | value contains spaces you must put double quotes around it, for | |
644 | example:</P> | |
645 | ||
646 | <pre class='example'> | |
647 | <a href='ref-ppdcfile.html#_define'>#define</a> FOO "My String Value" | |
648 | </pre> | |
649 | ||
650 | <P>Constants can also be defined on the command-line using the <tt>-D</tt> | |
651 | option:</P> | |
652 | ||
653 | <pre class='command'> | |
654 | ppdc -DNAME="value" filename.drv | |
655 | </pre> | |
656 | ||
657 | <P>Once defined, you use the notation <TT>$NAME</TT> to substitute the value of | |
658 | the constant in the file, for example:</P> | |
659 | ||
660 | <pre class='example'> | |
661 | <a href='ref-ppdcfile.html#_define'>#define</a> MANUFACTURER "Foo" | |
662 | <a href='ref-ppdcfile.html#_define'>#define</a> FOO_600 0 | |
663 | <a href='ref-ppdcfile.html#_define'>#define</a> FOO_1200 1 | |
664 | ||
665 | { | |
666 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER" | |
667 | <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_600 | |
668 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
669 | ... | |
670 | } | |
671 | ||
672 | { | |
673 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "$MANUFACTURER" | |
674 | <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> $FOO_1200 | |
675 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2001" | |
676 | ... | |
677 | } | |
678 | </pre> | |
679 | ||
680 | <P>Numeric constants can be bitwise OR'd together by placing the constants | |
681 | inside parenthesis, for example:</P> | |
682 | ||
683 | <pre class='example'> | |
684 | <I>// ModelNumber capability bits</I> | |
685 | <a href='ref-ppdcfile.html#_define'>#define</a> DUPLEX 1 | |
686 | <a href='ref-ppdcfile.html#_define'>#define</a> COLOR 2 | |
687 | ||
688 | ... | |
689 | ||
690 | { | |
691 | <I>// Define a model number specifying the capabilities of the printer...</I> | |
692 | <a href='ref-ppdcfile.html#ModelNumber'>ModelNumber</a> ($DUPLEX $COLOR) | |
693 | ... | |
694 | } | |
695 | </pre> | |
696 | ||
697 | ||
698 | <h3><a name='CONDITIONAL'>Conditional Statements</a></h3> | |
699 | ||
700 | <p>The PPD compiler supports conditional compilation using the <tt>#if</tt>, | |
701 | <tt>#elif</tt>, <tt>#else</tt>, and <tt>#endif</tt> directives. The <tt>#if</tt> | |
702 | and <tt>#elif</tt> directives are followed by a constant name or an expression. | |
703 | For example, to include a group of options when "ADVANCED" is defined:</p> | |
704 | ||
705 | <pre class='example'> | |
706 | <a href='ref-ppdcfile.html#_if'>#if</a> ADVANCED | |
707 | <a href='ref-ppdcfile.html#Group'>Group</a> "Advanced/Advanced Options" | |
708 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooCyanAdjust/Cyan Adjustment" | |
709 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" | |
710 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" | |
711 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" | |
712 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" | |
713 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" | |
714 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooMagentaAdjust/Magenta Adjustment" | |
715 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" | |
716 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" | |
717 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" | |
718 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" | |
719 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" | |
720 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooYellowAdjust/Yellow Adjustment" | |
721 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" | |
722 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" | |
723 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" | |
724 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" | |
725 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" | |
726 | <a href='ref-ppdcfile.html#Option'>Option</a> "fooBlackAdjust/Black Adjustment" | |
727 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus10/+10%" "" | |
728 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "plus5/+5%" "" | |
729 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "none/No Adjustment" "" | |
730 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus5/-5%" "" | |
731 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "minus10/-10%" "" | |
732 | <a href='ref-ppdcfile.html#_endif'>#endif</a> | |
733 | </pre> | |
734 | ||
735 | ||
736 | <h3><a name='CONSTRAINTS'>Defining Constraints</a></h3> | |
737 | ||
738 | <P>Constraints are strings that are used to specify that one or more option | |
739 | choices are incompatible, for example two-sided printing on transparency media. | |
740 | Constraints are also used to prevent the use of uninstalled features such as the | |
741 | duplexer unit, additional media trays, and so forth.</P> | |
742 | ||
743 | <P>The <TT>UIConstraints</TT> directive is used to specify a constraint that is | |
744 | placed in the PPD file. The directive is followed by a string using one of the | |
745 | following formats:</P> | |
746 | ||
747 | <pre class='example'> | |
748 | <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2" | |
749 | <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2" | |
750 | <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 *Option2 Choice2" | |
751 | <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Option1 Choice1 *Option2 Choice2" | |
752 | </pre> | |
753 | ||
754 | <P>Each option name is preceded by the asterisk (<TT>*</TT>). If no choice is | |
755 | given for an option, then all choices <I>except</I> <TT>False</TT> and | |
756 | <TT>None</TT> will conflict with the other option and choice(s). Since the PPD | |
757 | compiler automatically adds reciprocal constraints (option A conflicts with | |
758 | option B, so therefore option B conflicts with option A), you need only specify | |
759 | the constraint once.</P> | |
760 | ||
761 | <p class='example'><a name="LISTING5">Listing 5: "examples/constraint.drv"</a></p> | |
762 | ||
763 | <pre class='example'> | |
764 | ||
765 | <I>// Include standard font and media definitions</I> | |
766 | <a href='ref-ppdcfile.html#_include'>#include</a> <font.defs> | |
767 | <a href='ref-ppdcfile.html#_include'>#include</a> <media.defs> | |
768 | ||
769 | <I>// List the fonts that are supported, in this case all standard fonts...</I> | |
770 | <a href='ref-ppdcfile.html#Font'>Font</a> * | |
771 | ||
772 | <I>// Manufacturer, model name, and version</I> | |
773 | <a href='ref-ppdcfile.html#Manufacturer'>Manufacturer</a> "Foo" | |
774 | <a href='ref-ppdcfile.html#ModelName'>ModelName</a> "FooJet 2000" | |
775 | <a href='ref-ppdcfile.html#Version'>Version</a> 1.0 | |
776 | ||
777 | <I>// Each filter provided by the driver...</I> | |
778 | <a href='ref-ppdcfile.html#Filter'>Filter</a> application/vnd.cups-raster 100 rastertofoo | |
779 | ||
780 | <I>// Supported page sizes</I> | |
781 | *<a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> Letter | |
782 | <a href='ref-ppdcfile.html#MediaSize'>MediaSize</a> A4 | |
783 | ||
784 | <I>// Supported resolutions</I> | |
785 | *<a href='ref-ppdcfile.html#Resolution'>Resolution</a> k 8 0 0 0 "600dpi/600 DPI" | |
786 | ||
787 | <I>// Installable Option Group</I> | |
788 | <a href='ref-ppdcfile.html#Group'>Group</a> "InstallableOptions/Options Installed" | |
789 | ||
790 | <I>// Duplexing unit option</I> | |
791 | <a href='ref-ppdcfile.html#Option'>Option</a> "OptionDuplexer/Duplexing Unit" Boolean AnySetup 10 | |
792 | <a href='ref-ppdcfile.html#Choice'>Choice</a> True/Installed "" | |
793 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "False/Not Installed" "" | |
794 | ||
795 | <I>// General Option Group</I> | |
796 | <a href='ref-ppdcfile.html#Group'>Group</a> General | |
797 | ||
798 | <I>// Duplexing option</I> | |
799 | <a href='ref-ppdcfile.html#Option'>Option</a> "Duplex/Two-Sided Printing" PickOne AnySetup 10 | |
800 | *<a href='ref-ppdcfile.html#Choice'>Choice</a> "None/No" "<</Duplex false>>setpagedevice"" | |
801 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexNoTumble/Long Edge Binding" | |
802 | "<</Duplex true/Tumble false>>setpagedevice"" | |
803 | <a href='ref-ppdcfile.html#Choice'>Choice</a> "DuplexTumble/Short Edge Binding" | |
804 | "<</Duplex true/Tumble true>>setpagedevice"" | |
805 | ||
806 | <I>// Only allow duplexing if the duplexer is installed</I> | |
807 | <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False" | |
808 | ||
809 | <I>// Specify the name of the PPD file we want to generate...</I> | |
810 | <a href='ref-ppdcfile.html#PCFileName'>PCFileName</a> "foojet2k.ppd" | |
811 | </pre> | |
812 | ||
813 | <P><A HREF="#LISTING5">Listing 5</A> shows a variation of the first example with | |
814 | an added <TT>Duplex</TT> option and installable option for the duplexer, | |
815 | <TT>OptionDuplex</TT>. A constraint is added at the end to specify that any | |
816 | choice of the <TT>Duplex</TT> option that is not <TT>None</TT> is incompatible | |
817 | with the "Duplexer Installed" option set to "Not Installed" | |
818 | (<TT>False</TT>):</P> | |
819 | ||
820 | <pre class='example'> | |
821 | <a href='ref-ppdcfile.html#UIConstraints'>UIConstraints</a> "*Duplex *OptionDuplexer False" | |
822 | </pre> | |
823 | ||
824 | <h4>Enhanced Constraints</h4> | |
825 | ||
826 | <p>CUPS 1.4 supports constraints between 2 or more options using the | |
827 | <TT>Attribute</TT> directive. <TT>cupsUIConstraints</TT> attributes define | |
828 | the constraints, while <TT>cupsUIResolver</TT> attributes define option changes | |
829 | to resolve constraints. For example, we can specify the previous duplex | |
830 | constraint with a resolver that turns off duplexing with the following two | |
831 | lines:</p> | |
832 | ||
833 | <pre class='example'> | |
834 | <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIConstraints DuplexOff "*Duplex *OptionDuplexer False" | |
835 | <a href='ref-ppdcfile.html#Attribute'>Attribute</a> cupsUIResolver DuplexOff "*Duplex None" | |
836 | </pre> | |
837 | ||
838 | </BODY> | |
839 | </HTML> |