</head>
<body>
<!--
- "$Id: spec-ppd.html 5496 2006-05-05 19:26:23Z mike $"
+ "$Id: spec-ppd.html 6252 2007-02-10 15:34:18Z mike $"
CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
- Copyright 1997-2006 by Easy Software Products.
+ Copyright 1997-2007 by Easy Software Products.
These coded instructions, statements, and computer programs are the
property of Easy Software Products and are protected by Federal
<p>This boolean attribute notifies the RIP filters that the
destination printer does not require the top and bottom margins
of the <tt>ImageableArea</tt> swapped for the back page. The
-default value is <code>true</code>.</p>
+default is <tt>true</tt> when <tt>cupsFlipDuplex</tt> is <tt>true</tt> and <tt>false</tt> otherwise.</p>
<p>Example:</p>
<pre class='command'>
+<em>*% Flip the back side images</em>
+*cupsFlipDuplex: true
+
<em>*% Don't swap the top and bottom margins for the back side</em>
*APDuplexRequiresFlippedMargin: false
</pre>
<p>Also see the related <tt>cupsFlipDuplex</tt> attribute.</p>
+<h3>cupsEvenDuplex</h3>
+
+<p class='summary'>*cupsEvenDuplex: boolean</p>
+
+<p>This boolean attribute notifies the RIP filters that the
+destination printer requires an even number of pages when 2-sided
+printing is selected. The default value is <code>false</code>.</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Always send an even number of pages when duplexing</em>
+*cupsEvenDuplex: true
+</pre>
+
<h3>cupsFilter</h3>
<p class='summary'>*cupsFilter: "source/type cost program"</p>
*cupsFlipDuplex: true
</pre>
-<p>Also see the related <tt>APDuplexRequiresFlippedMargins</tt> attribute.</p>
+<p>Also see the related <tt>APDuplexRequiresFlippedMargins</tt>
+attribute.</p>
<h3>cupsIPPReason</h3>
*cupsModelNumber: 1234
</pre>
+
+<h3>cupsPJLCharset</h3>
+
+<p class='summary'>*cupsPJLCharset: "ISO character set name"</p>
+
+<p>This string attribute specifies the character set that is used
+for strings in PJL commands. If not specified, US-ASCII is
+assumed.</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Specify UTF-8 is used in PJL strings</em>
+*cupsPJLCharset: "UTF-8"
+</pre>
+
+
<h3>cupsPortMonitor</h3>
<p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
*cupsPortMonitor usb/USB Status Monitor: "epson-usb"
</pre>
+<h3>cupsPreFilter</h3>
+
+<p class='summary'>*cupsPreFilter: "source/type cost program"</p>
+
+<p>This string attribute provides a pre-filter rule. The pre-filter
+program will be inserted in the conversion chain immediately
+before the filter that accepts the given MIME type.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+<em>*% PDF pre-filter</em>
+*cupsPreFilter: "application/pdf 100 mypdfprefilter"
+
+<em>*% PNG pre-filter</em>
+*cupsPreFilter: "image/png 0 mypngprefilter"
+</pre>
+
<h3>cupsVersion</h3>
<p class='summary'>*cupsVersion: major.minor</p>
*CloseUI: *WatermarkText
<em>*% Custom PostScript watermark option</em>
-*CustomWatermarkText True: "<</cupsString1 2 1 roll>>setpagedevice"
+*CustomWatermarkText True: "<</cupsString1 3 -1 roll>>setpagedevice"
*ParamCustomWatermarkText Text: 1 string 0 32
*CloseUI: *GammaDensity
<em>*% Custom PostScript gamma/density option</em>
-*CustomGammaDensity True: "<</cupsReal1 3 1 roll/cupsReal2 3 1>>setpagedevice"
+*CustomGammaDensity True: "<</cupsReal1 3 -1 roll/cupsReal2 5 -1>>setpagedevice"
*ParamCustomGammaDensity Gamma: 1 curve 0.1 10
*ParamCustomGammaDensity Density: 2 real 0 2
</pre>
</pre>
+<h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2>
+
+<p>PPD files are used for both PostScript and non-PostScript printers. For CUPS raster drivers, you use a subset of the PostScript language to set page device attributes such as page size, resolution, and so forth. For example, the following code sets the page size to A4 size:</p>
+
+<pre class='command'>
+*PageSize A4: "<</PageSize[595 842]>>setpagedevice"
+</pre>
+
+<p>Custom options typically use other operators to organize the values into a key/value dictionary for <tt>setpagedevice</tt>. For example, our previous <tt>CustomWatermarkText</tt> option code uses the <tt>roll</tt> operator to move the custom string value into the dictionary for <tt>setpagedevice</tt>:</p>
+
+<pre class='command'>
+*CustomWatermarkText True: "<</cupsString1 3 -1 roll>>setpagedevice"
+</pre>
+
+<p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p>
+
+<pre class='command'>
+(My Watermark)
+<</cupsString1 3 -1 roll>>setpagedevice
+</pre>
+
+<p>The code moves the string value ("My Watermark") from the bottom of the stack to the top, creating a dictionary that looks like:</p>
+
+<pre class='command'>
+<</cupsString1(My Watermark)>>setpagedevice
+</pre>
+
+<p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p>
+
+<h3>Supported PostScript Operators</h3>
+
+<p>CUPS supports the following PostScript operators in addition to the usual PostScript number, string (literal and hex-encoded), boolean, null, and name values:</p>
+
+<ul>
+
+ <li><tt><<</tt> - Start a dictionary.</li>
+
+ <li><tt>>></tt> - End a dictionary.</li>
+
+ <li><tt>[</tt> - Start an array.</li>
+
+ <li><tt>]</tt> - End an array.</li>
+
+ <li><tt>copy</tt> - Copy the top N objects on the stack.</li>
+
+ <li><tt>dup</tt> - Copy the top object on the stack.</li>
+
+ <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li>
+
+ <li><tt>pop</tt> - Pop the top object on the stack.</li>
+
+ <li><tt>roll</tt> - Shift the top N objects on the stack.</li>
+
+ <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li>
+
+</ul>
+
+<h3>Supported Page Device Attributes</h3>
+
+<p>Table 1 shows the supported page device attributes along with PostScript code examples.</p>
+
+<div class='table'>
+<table summary='Supported Page Device Attributes'>
+<caption>Table 1: <a name='TABLE_1'>Supported Page Device Attributes</a></caption>
+<thead>
+<tr>
+ <th>Name(s)</th>
+ <th>Type</th>
+ <th>Description</th>
+ <th>Example(s)</th>
+</tr>
+</thead>
+<tbody>
+<tr valign='top'>
+ <td><tt>AdvanceDistance</tt></td>
+ <td>Integer</td>
+ <td>Specifies the number of points to advance roll media after printing.</td>
+ <td><tt><</AdvanceDistance 18>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>AdvanceMedia</tt></td>
+ <td>Integer</td>
+ <td>Specifies when to advance the media: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td>
+ <td><tt><</AdvanceMedia 4>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>Collate</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether collated copies are required.</td>
+ <td><tt><</Collate true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>CutMedia</tt></td>
+ <td>Integer</td>
+ <td>Specifies when to cut the media: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td>
+ <td><tt><</CutMedia 1>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>Duplex</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether 2-sided printing is required.</td>
+ <td><tt><</Duplex true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>HWResolution</tt></td>
+ <td>Integer Array</td>
+ <td>Specifies the resolution of the page image in pixels per inch.</td>
+ <td><tt><</HWResolution[1200 1200]>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>InsertSheet</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether to insert a blank sheet before the job.</td>
+ <td><tt><</InsertSheet true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>Jog</tt></td>
+ <td>Integer</td>
+ <td>Specifies when to shift the media in the output bin: 0 = never, 1 = after the file, 2 = after the job, 3 = after the set, and 4 = after the page.</td>
+ <td><tt><</Jog 2>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>LeadingEdge</tt></td>
+ <td>Integer</td>
+ <td>Specifies the leading edge of the media: 0 = top, 1 = right, 2 = bottom, 3 = left.</td>
+ <td><tt><</LeadingEdge 0>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>ManualFeed</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether media should be drawn from the manual feed tray. Note: The <tt>MediaPosition</tt> attribute is preferred over the <tt>ManualFeed</tt> attribute.</td>
+ <td><tt><</ManualFeed true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>MediaClass</tt></td>
+ <td>String</td>
+ <td>Specifies a named media.</td>
+ <td><tt><</MediaClass (Invoices)>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>MediaColor</tt></td>
+ <td>String</td>
+ <td>Specifies the color of the media.</td>
+ <td><tt><</MediaColor >>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>MediaPosition</tt></td>
+ <td>Integer</td>
+ <td>Specifies the tray or source of the media.</td>
+ <td><tt><</MediaPosition 12>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>MediaType</tt></td>
+ <td>String</td>
+ <td>Specifies the general media type.</td>
+ <td><tt><</MediaType (Glossy)>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>MediaWeight</tt></td>
+ <td>Integer</td>
+ <td>Specifies the media weight in grams per meter<sup>2</sup>.</td>
+ <td><tt><</MediaWeight 100>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>MirrorPrint</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether to flip the output image horizontally.</td>
+ <td><tt><</MirrorPrint true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>NegativePrint</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether to invert the output image.</td>
+ <td><tt><</NegativePrint true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>NumCopies</tt></td>
+ <td>Integer</td>
+ <td>Specifies the number of copies to produce of each page.</td>
+ <td><tt><</NumCopies 100>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>Orientation</tt></td>
+ <td>Integer</td>
+ <td>Specifies the orientation of the output: 0 = portrait, 1 = landscape rotated counter-clockwise, 2 = upside-down, 3 = landscape rotated clockwise.</td>
+ <td><tt><</Orientation 3>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>OutputFaceUp</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether to place the media face-up in the output bin/tray.</td>
+ <td><tt><</OutputFaceUp true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>OutputType</tt></td>
+ <td>String</td>
+ <td>Specifies the output type name.</td>
+ <td><tt><</OutputType (Photo)>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>PageSize</tt></td>
+ <td>Integer/Real Array</td>
+ <td>Specifies the width and length/height of the page in points.</td>
+ <td><tt><</PageSize[595 842]>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>Separations</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether to produce color separations.</td>
+ <td><tt><</Separations true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>TraySwitch</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether to switch trays automatically.</td>
+ <td><tt><</TraySwitch true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>Tumble</tt></td>
+ <td>Boolean</td>
+ <td>Specifies whether the back sides of pages are rotated 180 degrees.</td>
+ <td><tt><</Tumble true>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsBorderlessScalingFactor</tt></td>
+ <td>Real</td>
+ <td>Specifies the amount to scale the page image dimensions.</td>
+ <td><tt><</cupsBorderlessScalingFactor 1.01>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsColorOrder</tt></td>
+ <td>Integer</td>
+ <td>Specifies the order of colors: 0 = chunked, 1 = banded, 2 = planar.</td>
+ <td><tt><</cupsColorOrder 0>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsColorSpace</tt></td>
+ <td>Integer</td>
+ <td>Specifies the page image colorspace: 0 = W, 1 = RGB, 2 = RGBA, 3 = K, 4 = CMY, 5 = YMC, 6 = CMYK, 7 = YMCK, 8 = KCMY, 9 = KCMYcm, 10 = GMCK, 11 = GMCS, 12 = White, 13 = Gold, 14 = Silver, 15 = CIE XYZ, 16 = CIE Lab, 17 = RGBW, 32 to 46 = CIE Lab (1 to 15 inks)</td>
+ <td><tt><</cupsColorSpace >>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsCompression</tt></td>
+ <td>Integer</td>
+ <td>Specifies a driver compression type/mode.</td>
+ <td><tt><</cupsCompression 2>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsInteger0<br>
+ ...<br>
+ cupsInteger15</tt></td>
+ <td>Integer</td>
+ <td>Specifies driver integer values.</td>
+ <td><tt><</cupsInteger11 1234>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsMarkerType</tt></td>
+ <td>String</td>
+ <td>Specifies the type of ink/toner to use.</td>
+ <td><tt><</cupsMarkerType (Black+Color)>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsMediaType</tt></td>
+ <td>Integer</td>
+ <td>Specifies a numeric media type.</td>
+ <td><tt><</cupsMediaType 999>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsPageSizeName</tt></td>
+ <td>String</td>
+ <td>Specifies the name of the page size.</td>
+ <td><tt><</cupsPageSizeName (A4.Full)>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsPreferredBitsPerColor</tt></td>
+ <td>Integer</td>
+ <td>Specifies the preferred number of bits per color, typically 8 or 16.</td>
+ <td><tt><</cupsPreferredBitsPerColor 16>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsReal0<br>
+ ...<br>
+ cupsReal15</tt></td>
+ <td>Real</td>
+ <td>Specifies driver real number values.</td>
+ <td><tt><</cupsReal15 1.234>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsRenderingIntent</tt></td>
+ <td>String</td>
+ <td>Specifies the color rendering intent.</td>
+ <td><tt><</cupsRenderingIntent (AbsoluteColorimetric)>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsRowCount</tt></td>
+ <td>Integer</td>
+ <td>Specifies the number of rows of raster data to print on each line for some drivers.</td>
+ <td><tt><</cupsRowCount 24>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsRowFeed</tt></td>
+ <td>Integer</td>
+ <td>Specifies the number of rows to feed between passes for some drivers.</td>
+ <td><tt><</cupsRowFeed 17>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsRowStep</tt></td>
+ <td>Integer</td>
+ <td>Specifies the number of lines between columns/rows on the print head for some drivers.</td>
+ <td><tt><</cupsRowStep 2>>setpagedevice</tt></td>
+</tr>
+<tr valign='top'>
+ <td><tt>cupsString0<br>
+ ...<br>
+ cupsString15</tt></td>
+ <td>String</td>
+ <td>Specifies driver string values.</td>
+ <td><tt><</cupsString0(String Value)>>setpagedevice</tt></td>
+</tr>
+</tbody>
+</table></div>
+
+
<h2 class='title'><a name='HISTORY'>Change History</a></h2>
+<h3>Changes in CUPS 1.3</h3>
+
+<ul>
+
+ <li>Added <tt>cupsPreFilter</tt> attribute.</li>
+
+</ul>
+
+<h3>Changes in CUPS 1.2.8</h3>
+
+<ul>
+
+ <li>Added section on supported PostScript commands for raster
+ drivers</li>
+
+</ul>
+
<h3>Changes in CUPS 1.2</h3>
<ul>
projects / thirdparty / cups.git / blobdiff