<head>
<title>CUPS PPD Extensions</title>
<meta name='keywords' content='Programming, PostScript Printer Description'>
- <link rel='stylesheet' type='text/css' href='../cups.css'>
+ <link rel='stylesheet' type='text/css' href='../cups-printable.css'>
</head>
<body>
<!--
- "$Id: spec-ppd.html 6726 2007-07-25 20:50:26Z mike $"
+ "$Id: spec-ppd.html 6850 2007-08-23 18:29:04Z mike $"
CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
+ Copyright 2007 by Apple Inc.
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
- copyright law. Distribution and use rights are outlined in the file
- "LICENSE.txt" which should have been included with this file. If this
- file is missing or damaged please contact Easy Software Products
- at:
-
- Attn: CUPS Licensing Information
- Easy Software Products
- 44141 Airport View Drive, Suite 204
- Hollywood, Maryland 20636 USA
-
- Voice: (301) 373-9600
- EMail: cups-info@cups.org
- WWW: http://www.cups.org
+ property of Apple Inc. and are protected by Federal copyright
+ law. Distribution and use rights are outlined in the file "LICENSE.txt"
+ which should have been included with this file. If this file is
+ file is missing or damaged, see the license at "http://www.cups.org/".
-->
<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
</pre>
-<h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
+<h2 class='title'><a name='AUTOCONFIG'>Auto-Configuration</a></h2>
-<h3>APBookFile</h3>
+<p>CUPS supports several methods of auto-configuration via PPD attributes.
+<em>Currently these methods are only implemented on Mac OS X.</em></p>
-<p class='summary'>*APBookFile: "file URL"</p>
+<h3><span class='info'>Mac OS X 10.5</span><a name='APAutoSetupTool'>APAutoSetupTool</a></h3>
-<p>This string attribute specifies the Apple help book file to use
-for this printer driver.</p>
+<p class='summary'>*APAutoSetupTool: "/LibraryPrinters/vendor/filename"</p>
-<p>Example:</p>
+<p>This attribute defines a program that sets the default option choices. It
+is run when a printer is added from the printer browser instead of the
+normal PostScript query and SNMP OID attribute lookups.</p>
+
+<p>The program is provided with two arguments: the printer's device URI and
+the PPD file to be used for the printer. The program must write an updated
+PPD file to stdout.</p>
+
+<p>Examples:</p>
<pre class='command'>
-*APBookFile: "file:///Library/Printers/vendor/Help/filename"
+*% Use our setup tool when adding a printer
+*APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool"
</pre>
-<h3>APDuplexRequiresFlippedMargin</h3>
+<h3><span class='info'>Mac OS X 10.2</span><a name='QUERYKEYWORD'>?MainKeyword</a></h3>
-<p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
+<p class='summary'>*?<i>MainKeyword</i>: "<br>
+ PostScript query code that writes a message using the = operator...<br>
+"<br>
+*End</p>
-<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 is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt>
-and <tt>false</tt> otherwise.</p>
+<p>The <tt>?<i>MainKeyword</i><tt> attribute defines PostScript code that
+determines the currently selected/enabled option keyword (choice) for the
+main keyword (option). It is typically used when communicating with USB,
+serial, Appletalk, and AppSocket (port 9100) printers.</p>
+
+<p>The PostScript code typically sends its response back using the <tt>=</tt>
+operator.</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
+*OpenUI OptionDuplex/Duplexer Installed: Boolean
+*DuplexOptionDuplex: False
+*OptionDuplex False/Not Installed: ""
+*OptionDuplex True/Installed: ""
+
+<em>*% Query the printer for the presence of the duplexer option...</em>
+*?OptionDuplex: "
+ currentpagedevice /Duplex known
+ {(True)} {(False)} ifelse
+ = flush
+"
+*End
+*CloseUI: OptionDuplex
</pre>
-<p>Also see the related <tt>cupsBackSide</tt> attribute.</p>
+<h3><span class='info'>Mac OS X 10.4</span><a name='OID'>OIDMainKeyword</a></h3>
-<h3>APPrinterPreset</h3>
+<p class='summary'>*?OID<i>MainKeyword</i>: ".n.n.n..."<br>
+*OID<i>MainKeyword</i> <i>OptionKeyword1</i>: "value"<br>
+...<br>
+*OID<i>MainKeyword</i> <i>OptionKeywordN</i>: "value"</p>
-<p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p>
-
-<p>This attribute defines presets for multiple options that show up
-in the print dialog on Mac OS X. Each preset maps to one or more
-pairs of PPD options and choices.</p>
+<p>The <tt>OID<i>MainKeyword</i></tt> attribute is used to define
+SNMP OIDs that map to installable options. The first (query) line
+defines the OID to lookup on the network device. The second and
+subsequent attributes define a mapping from OID value to option
+keyword. Since SNMP is an IP-based network protocol, this method
+is typically only used to configure AppSocket, IPP, and LPD network
+printers.</p>
<p>Examples:</p>
<pre class='command'>
-*APPrinterPreset Text/Text Printing on Plain Paper: "
- *MediaType Plain
- *ColorModel Gray
- *Resolution 600dpi"
-*End
-
-*APPrinterPreset Photo/Photo Printing on Glossy Paper: "
- *MediaType Glossy
- *ColorModel RGB
- *Resolution 300dpi"
-*End
+*% Get the installed memory on the printer...
+*?OIDInstalledMemory: ".1.3.6.1.2.1.25.2.2.0"
+*OIDInstalledMemory 16MB: "16384 KBytes"
+*OIDInstalledMemory 32MB: "32768 KBytes"
+*OIDInstalledMemory 48MB: "49152 KBytes"
+*OIDInstalledMemory 72MB: "73728 KBytes"
</pre>
-<h3>APRemoteQueueID</h3>
-<p class='summary'>*APRemoteQueueID: "string"</p>
-
-<p>This string attribute notifies the scheduler that this PPD is for a remote CUPS printer, typically shared via Bonjour.</p>
+<h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
-<p>Example:</p>
+<p>CUPS supports three types of color profiles. The first type is
+based on sRGB and is used by the standard CUPS raster filters and
+ESP Ghostscript. The second type is based on ICC profiles and is
+used by the Quartz-based filters on MacOS X. The final type is
+based on well-known colorspaces such as sRGB and Adobe RGB.</p>
-<pre class='command'>
-*APRemoteQueueID: "myprinter"
-</pre>
+<blockquote><b>Note:</b>
-<h3><span class='info'>CUPS 1.3</span>cupsBackSide</h3>
+<p>At this time, none of the CUPS raster
+filters support ICC profiles. This will be addressed as time
+and resources permit.</p>
-<p class='summary'>*cupsBackSide: keyword</p>
+</blockquote>
-<p>This attribute requests special handling of the back side of pages
-when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a>
-shows the supported keyword values for this attribute and their affect
-on the raster data sent to your driver. The default value is
-<code>Normal</code>.</p>
+<h3><a name='cupsColorProfile'>cupsColorProfile</a></h3>
-<blockquote><b>Note:</b> <tt>cupsBackSide</tt> replaces the older
-<tt>cupsFlipDuplex</tt> attribute - if <tt>cupsBackSide</tt> is
-specified, <tt>cupsFlipDuplex</tt> will be ignored.</blockquote>
+<p class='summary'>*cupsColorProfile Resolution/MediaType: "density
+gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
-<div class='table'>
-<table width='80%' summary='Back Side Raster Coordinate System'>
-<caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption>
-<thead>
-<tr>
- <th>cupsBackSide</th>
- <th>Tumble Value</th>
- <th>Image Presentation</th>
-</tr>
-</thead>
-<tbody>
-<tr>
- <td><code>Normal</code></td>
- <td><code>false</code></td>
- <td>Left-to-right, top-to-bottom</td>
-</tr>
-<tr>
- <td><code>Normal</code></td>
- <td><code>true</code></td>
- <td>Left-to-right, top-to-bottom</td>
-</tr>
-<tr>
- <td><code>ManualTumble</code></td>
- <td><code>false</code></td>
- <td>Left-to-right, top-to-bottom</td>
-</tr>
-<tr>
- <td><code>ManualTumble</code></td>
- <td><code>true</code></td>
- <td>Right-to-left, bottom-to-top</td>
-</tr>
-<tr>
- <td><code>Rotated</code></td>
- <td><code>false</code></td>
- <td>Right-to-left, bottom-to-top</td>
-</tr>
-<tr>
- <td><code>Rotated</code></td>
- <td><code>true</code></td>
- <td>Right-to-left, top-to-bottom</td>
-</tr>
-<tr>
- <td><code>Flipped</code> *</td>
- <td><code>false</code></td>
- <td>Left-to-right, bottom-to-top</td>
-</tr>
-<tr>
- <td><code>Flipped</code> *</td>
- <td><code>true</code></td>
- <td>Right-to-left, top-to-bottom</td>
-</tr>
-</tbody>
-</table>
-</div>
+<p>This string attribute specifies an sRGB-based color profile
+consisting of gamma and density controls and a 3x3 CMY color
+transform matrix.</p>
-<p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p>
+<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
+to act as a wildcard. Otherwise they must match one of the
+<tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
+the PPD file.</p>
-<p>Examples:</p>
+<p>The <i>density</i> and <i>gamma</i> values define gamma and
+density adjustment function such that:</p>
<pre class='command'>
-<em>*% Flip the page image for the back side of duplexed output</em>
-*cupsBackSide: Flipped
-
-<em>*% Rotate the page image for the back side of duplexed output</em>
-*cupsBackSide: Rotated
+f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
</pre>
-<p>Also see the related <tt>APDuplexRequiresFlippedMargin</tt>
-attribute.</p>
+<p>The <i>m00</i> through <i>m22</i> values define a 3x3
+transformation matrix for the CMY color values. The density
+function is applied <i>after</i> the CMY transformation:</p>
-<h3>cupsEvenDuplex</h3>
+<pre class='command'>
+| m00 m01 m02 |
+| m10 m11 m12 |
+| m20 m21 m22 |
+</pre>
-<p class='summary'>*cupsEvenDuplex: boolean</p>
+<p>Examples:</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>
+<pre class='command'>
+<em>*% Specify a profile for printing at 360dpi on all media types</em>
+*cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
-<p>Example:</p>
+<em>*% Specify a profile for printing at 720dpi on Glossy media</em>
+*cupsColorProfile 720dpi/Glossy: "1.0 2.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
-<pre class='command'>
-<em>*% Always send an even number of pages when duplexing</em>
-*cupsEvenDuplex: true
+<em>*% Specify a default profile for printing at all other resolutions and media types</em>
+*cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
</pre>
-<h3>cupsFax</h3>
+<h3><span class='info'>Mac OS X 10.3/CUPS 1.2</span><a name='cupsICCProfile'>cupsICCProfile</a></h3>
-<p class='summary'>*cupsFax: boolean</p>
+<p class='summary'>*cupsICCProfile
+ColorModel.MediaType.Resolution/Description: "filename"</p>
-<p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p>
+<p>This attribute specifies an ICC color profile that is
+used to convert the document colors to the device
+colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
+<tt>Resolution</tt> keywords specify a selector for color
+profiles. If omitted, the color profile will match any option
+keyword for the corresponding main keyword.</p>
+
+<p>The <tt>Description</tt> specifies human-readable text that
+is associated with the color profile. The <tt>filename</tt>
+portion specifies the ICC color profile to use; if the filename
+is not absolute, it is loaded relative to the
+<var>/usr/share/cups/profiles</var> directory.</p>
<p>Examples:</p>
<pre class='command'>
-*cupsFax: true
-</pre>
+<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
+*cupsICCProfile CMYK..360dpi/360dpi CMYK: "/Library/Printers/vendor/Profiles/foo-360-cmyk.icc"
-<h3>cupsFilter</h3>
+<em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
+*cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "/Library/Printers/vendor/Profiles/foo-720-glossy-rgb.icc"
-<p class='summary'>*cupsFilter: "source/type cost program"</p>
+<em>*% Specify a default profile for printing at all other resolutions and media types</em>
+*cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc"
+</pre>
-<p>This string attribute provides a conversion rule from the
-given source type to the printer's native format using the
-filter "program". If a printer supports the source type directly,
-the special filter program "-" may be specified.</p>
+<h4>Customizing the Profile Selection Keywords</h4>
-<p>Examples:</p>
+<p>The <tt>MediaType</tt> and <tt>Resolution</tt> keywords can be
+reassigned to different main keywords, allowing drivers to do
+color profile selection based on different parameters. The
+<tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt>
+attributes define the mapping from selector to main keyword:</p>
<pre class='command'>
-<em>*% Standard raster printer driver filter</em>
-*cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
+*cupsICCQualifier2: MainKeyword2
+*cupsICCQualifier3: MainKeyword3
+</pre>
-<em>*% Plain text filter</em>
-*cupsFilter: "text/plain 10 texttofoo"
+<p>The default mapping is as follows:</p>
-<em>*% Pass-through filter for PostScript printers</em>
-*cupsFilter: "application/vnd.cups-postscript 0 -"
+<pre class='command'>
+*cupsICCQualifier2: MediaType
+*cupsICCQualifier3: Resolution
</pre>
-<h3><span class='info'>Deprecated</span>cupsFlipDuplex</h3>
+<h3><span class='info'>Mac OS X 10.4</span><a name='APCustom'>Custom Color Matching Support</a></h3>
-<p class='summary'>*cupsFlipDuplex: boolean</p>
+<p class='summary'>*<a href='#APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a>: true<br>
+*<a href='#APCustomColorMatchingName'>APCustomColorMatchingName</a> name/text: ""<br>
+*<a href='#APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a>: profile<br>
+*<a href='#APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a>: profile</p>
-<p>Due to implementation differences between Mac OS X and Ghostscript,
-the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use
-the <tt>cupsBackSide</tt> attribute to specify the coordinate
-system (pixel layout) of the page data on the back side of duplex
-pages.</p>
+<p>These attributes tell the Mac OS X raster filters that the printer
+driver provides its own custom color matching and that generic color
+profiles should be used when generating 1-, 3-, and 4-component raster
+data as requested by the driver. The <tt>APCustomColorMatchingProfile</tt>
+and <tt>APDefaultColorMatchingProfile</tt> attributes specify alternate
+color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.</p>
-<p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value
-of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with
-Ghostscript.</p>
+<h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingName'>APCustomColorMatchingName</a></h4>
-<p>The default value is <code>false</code>.</p>
+<p class='summary'>*APCustomColorMatchingName name/text: ""</p>
-<blockquote><b>Note:</b> Mac OS X drivers that previously used
-<tt>cupsFlipDuplex</tt> may wish to provide both the old and
-new attributes for maximum compatibility, for example:
+<p>This attribute defines an alternate name for the color matching
+provided by a driver in the <var>Color Matching</var> print panel.
+The default is to use the name "Vendor Matching" or its localized
+equivalent.</p>
+
+<p>Examples:</p>
<pre class='command'>
-*cupsBackSide: Rotated
-*cupsFlipDuplex: true
+*% Define the names for our color matching...
+*APCustomColorMatchingName name/AcmeColor(tm): ""
+*fr.APCustomColorMatchingName name/La AcmeColor(tm): ""
</pre>
-Similarly, drivers written for other operating systems using
-Ghostscript can use:
+<h4><span class='info'>Mac OS X 10.5</span><a name='APCustomColorMatchingProfile'>APCustomColorMatchingProfile</a></h4>
-<pre class='command'>
-*cupsBackSide: Flipped
-*cupsFlipDuplex: true
-</pre></blockquote>
+<p class='summary'>*APCustomColorMatchingProfile: name</p>
-<h3>cupsIPPFinishings</h3>
+<p>This attribute defines a supported RGB color profile that can be used
+when doing custom color matching. Currently only <tt>sRGB</tt> and
+<tt>AdobeRGB</tt> are supported. If not specified, RGB data will use the
+Generic RGB colorspace.</p>
-<p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p>
+<blockquote><b>Note:</b>
-<p>This attribute defines a mapping from IPP <code>finishings</code>
-values to PPD options and choices.</p>
+<p>If you provide multiple <tt>APCustomColorMatchingProfile</tt> attributes,
+you are responsible for providing the necessary user interface controls to
+select the profile in a <a href='#APDialogExtension'>print dialog pane</a>.
+Add the named profile to the print settings using the key
+<tt>kPMCustomColorMatchingProfileKey</tt>.</p>
+
+</blockquote>
<p>Examples:</p>
<pre class='command'>
-*cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait"
-*cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide"
-*cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait"
-*cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
+*% Use sRGB for RGB color by default, but support both sRGB and AdobeRGB
+*APSupportsCustomColorMatching: true
+*APDefaultCustomColorMatchingProfile: sRGB
+*APCustomColorMatchingProfile: sRGB
+*APCustomColorMatchingProfile: AdobeRGB
</pre>
-<h3>cupsIPPReason</h3>
-
-<p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
+<h4><span class='info'>Mac OS X 10.5</span><a name='APDefaultCustomColorMatchingProfile'>APDefaultCustomColorMatchingProfile</a></h4>
-<p>This optional attribute maps custom
-<code>printer-state-reasons</code> keywords that are generated by
-the driver to human readable text. The optional URIs string
-contains zero or more URIs separated by a newline. Each URI can
-be a CUPS server absolute path to a help file under the
-scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
-("http://www.domain.com/path/to/help/page.html"), or any other
-valid URI which directs the user at additional information
-concerning the condition that is being reported.</p>
+<p class='summary'>*APDefaultCustomColorMatchingProfile: name</p>
-<p>Since the reason text is limited to 80 characters by the PPD specification,
-longer text strings can be included by URI-encoding the text with the "text"
-scheme, for example "text:some%20text". Multiple <code>text</code> URIs are
-combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt>
-into a single string that can be displayed to the user.</p>
+<p>This attribute defines the default RGB color profile that will be used
+when doing custom color matching. Currently only <tt>sRGB</tt> and
+<tt>AdobeRGB</tt> are supported.</p>
<p>Examples:</p>
<pre class='command'>
-<em>*% Map com.vendor-error to text but no page</em>
-*cupsIPPReason com.vendor-error/A serious error occurred: ""
-
-<em>*% Map com.vendor-error to more than 80 characters of text but no page</em>
-*cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time
-text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country."
-
-<em>*% Map com.vendor-error to text and a local page</em>
-*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
-
-<em>*% Map com.vendor-error to text and a remote page</em>
-*cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
-
-<em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
-*APHelpBook: "file:///Library/Printers/vendor/Help/filename"
-*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
-help:anchor='com.vendor-error'%20bookID=Vendor%20Help
-http://www.vendor.com/help"
-*End
+*% Use sRGB for RGB color by default
+*APSupportsCustomColorMatching: true
+*APDefaultCustomColorMatchingProfile: sRGB
</pre>
-<h3>cupsLanguages</h3>
+<h4><span class='info'>Mac OS X 10.4</span><a name='APSupportsCustomColorMatching'>APSupportsCustomColorMatching</a></h4>
-<p class='summary'>*cupsLanguages: "locale list"</p>
+<p class='summary'>*APSupportsCustomColorMatching: boolean</p>
-<p>This attribute describes which language localizations are
-included in the PPD. The "locale list" string is a space-delimited
-list of locale names ("en", "en_US", "fr_CA", etc.)</p>
+<p>This attribute specifies that the driver provides its own custom color
+matching. When <tt>true</tt>, the default hand-off colorspace will be
+Generic Gray, Generic RGB, or Generic CMYK depending on the number of
+components the driver requests. The <a
+href='#APDefaultCustomColorMatchingProfile'><tt>APDefaultCustomColorMatchingProfile</tt></a>
+attribute can be used to override the default 3-component (RGB) colorspace.</p>
-<p>Example:</p>
+<p>The default for <tt>APSupportsCustomColorMatching</tt> is <tt>false</tt>.</p>
+
+<p>Examples:</p>
<pre class='command'>
-<em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
-*cupsLanguages: "en_CA en_UK en_US fr_CA fr_CA"
+*APSupportsCustomColorMatching: true
+*APDefaultCustomColorMatchingProfile: sRGB
</pre>
-<h3>cupsManualCopies</h3>
-<p class='summary'>*cupsManualCopies: boolean</p>
+<h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
-<p>This boolean attribute notifies the RIP filters that the
-destination printer does not support copy generation in
-hardware. The default value is <code>false</code>.</p>
-
-<p>Example:</p>
-
-<pre class='command'>
-<em>*% Tell the RIP filters to generate the copies for us</em>
-*cupsManualCopies: true
-</pre>
+<p>CUPS 1.2 and higher adds support for PPD files containing multiple
+languages by following the following additional rules:</p>
-<h3>cupsModelNumber</h3>
+<ol>
-<p class='summary'>*cupsModelNumber: number</p>
+ <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
-<p>This integer attribute specifies a printer-specific model
-number. This number can be used by a filter program to adjust
-the output for a specific model of printer.</p>
+ <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
-<p>Example:</p>
+ <li>The <tt>cupsLanguages</tt> attribute MUST be provided and
+ list each of the supported locales in the PPD file</li>
-<pre class='command'>
-<em>*% Specify an integer for a driver-specific model number</em>
-*cupsModelNumber: 1234
-</pre>
+ <li>Main and option keywords MUST NOT exceed 34 (instead of 40)
+ characters to allow room for the locale prefixes in translation
+ attributes</li>
+ <li>The main keyword "Translation" MUST NOT be used</li>
-<h3>cupsPJLCharset</h3>
+ <li>Translation strings included with the main and option
+ keywords MUST NOT contain characters outside the ASCII
+ subset of ISOLatin1 and UTF-8; developers wishing to use
+ characters outside ASCII MUST provide a separate set of
+ English localization attributes for the affected keywords.</li>
-<p class='summary'>*cupsPJLCharset: "ISO character set name"</p>
+ <li>Localizations are specified using a locale prefix of
+ the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
+ language code and "CC" is the 2-letter ISO country
+ code<ul>
+ <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li>
+ <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li>
+ </ul></li>
-<p>This string attribute specifies the character set that is used
-for strings in PJL commands. If not specified, US-ASCII is
-assumed.</p>
+ <li>Locale-specific translation strings MUST be encoded
+ using UTF-8.</li>
-<p>Example:</p>
+ <li>Main keywords MUST be localized using one of the
+ following forms:
+ <p><tt>*ll.Translation MainKeyword/translation
+ text: ""</tt><br />
+ <tt>*ll_CC.Translation MainKeyword/translation
+ text: ""</tt></p></li>
-<pre class='command'>
-<em>*% Specify UTF-8 is used in PJL strings</em>
-*cupsPJLCharset: "UTF-8"
-</pre>
+ <li>Option keywords MUST be localized using one of the
+ following forms:
+ <p><tt>*ll.MainKeyword OptionKeyword/translation
+ text: ""</tt><br />
+ <tt>*ll_CC.MainKeyword OptionKeyword/translation
+ text: ""</tt></p></li>
+ <li>Localization attributes MAY appear anywhere after the
+ first line of the PPD file</li>
-<h3>cupsPortMonitor</h3>
+</ol>
-<p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
+<blockquote><b>Note:</b>
-<p>This string attribute specifies printer-specific "port
-monitor" filters that may be used with the printer. The CUPS
-scheduler also looks for the <tt>Protocols</tt> attribute to see
-if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
-so, the corresponding port monitor ("bcp" and "tbcp",
-respectively) is listed in the printer's
-<tt>port-monitor-supported</tt> attribute.</p>
+<p>We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt>
+and limit the allowed base translation strings to ASCII to avoid
+character coding issues that would otherwise occur. In addition,
+requiring the base translation strings to be in English allows
+for easier fallback translation when no localization is provided
+in the PPD file for a given locale.</p>
-<p>The "urischeme" portion of the attribute specifies the URI scheme
-that this port monitor should be used for. Typically this is used to
-pre-select a particular port monitor for each type of connection that
-is supported by the printer. The "port monitor" string can be "none"
-to disable the port monitor for the given URI scheme.</p>
+</blockquote>
<p>Examples:</p>
<pre class='command'>
-<em>*% Specify a PostScript printer that supports the TBCP protocol</em>
-*Protocols: TBCP PJL
-
-<em>*% Specify that TBCP should be used for socket connections but not USB</em>
-*cupsPortMonitor socket/AppSocket Printing: "tbcp"
-*cupsPortMonitor usb/USB Printing: "none"
-
-<em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
-*cupsPortMonitor usb/USB Status Monitor: "epson-usb"
-</pre>
-
-<h3>cupsPreFilter</h3>
-
-<p class='summary'>*cupsPreFilter: "source/type cost program"</p>
+*LanguageVersion: English
+*LanguageEncoding: ISOLatin1
+*cupsLanguages: "de fr_CA"
+*ModelName: "Foobar Laser 9999"
-<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>
+<em>*% Localize ModelName for French and German</em>
+*fr_CA.Translation ModelName/La Foobar Laser 9999: ""
+*de.Translation ModelName/Foobar LaserDrucken 9999: ""
-<p>Examples:</p>
+*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
+<em>*% Localize printer-state-reason for French and German</em>
+*fr_CA.cupsIPPReason com.vendor-error/Une erreur sèrieuse s'est produite: "/help/com.vendor/error.html"
+*de.cupsIPPReason com.vendor-error/Eine ernste Störung trat: "/help/com.vendor/error.html"
-<pre class='command'>
-<em>*% PDF pre-filter</em>
-*cupsPreFilter: "application/pdf 100 mypdfprefilter"
+...
-<em>*% PNG pre-filter</em>
-*cupsPreFilter: "image/png 0 mypngprefilter"
+*OpenUI *InputSlot/Paper Source: PickOne
+*OrderDependency: 10 AnySetup *InputSlot
+*DefaultInputSlot: Auto
+<em>*% Localize InputSlot for French and German</em>
+*fr_CA.Translation InputSlot/Papier source: ""
+*de.Translation InputSlot/Papiereinzug: ""
+*InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice"
+<em>*% Localize InputSlot=Auto for French and German</em>
+*fr_CA.InputSlot Auto/Par Defaut: ""
+*de.InputSlot Auto/Standard: ""
+*InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice"
+<em>*% Localize InputSlot=Manual for French and German</em>
+*fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: ""
+*de.InputSlot Manual/Manueller Einzug: ""
+*CloseUI: *InputSlot
</pre>
-<h3>cupsVersion</h3>
-
-<p class='summary'>*cupsVersion: major.minor</p>
-
-<p>This required attribute describes which version of the CUPS
-PPD file extensions was used. Currently it must be the string
-"1.0", "1.1", or "1.2".</p>
-
-<p>Example:</p>
-
-<pre class='command'>
-<em>*% Specify a CUPS 1.2 driver</em>
-*cupsVersion: "1.2"
-</pre>
<h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
</ul>
+<blockquote><b>Note:</b>
+
+<p>Custom options are not directly supported by the Mac OS X Print Dialog
+nor by the CUPS web interface at this time. Vendors that use custom
+options on Mac OS X must provide their own user interface via the
+<a href='#APDialogExtension'><tt>APDialogExtension</tt></a> attribute.</p>
+
+</blockquote>
+
<p>Examples:</p>
<pre class='command'>
</pre>
-<h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
-
-<p>CUPS supports two types of color profiles. The first type is
-based on sRGB and is used by the standard CUPS raster filters and
-ESP Ghostscript. The second type is based on ICC profiles and is
-used by the Core Graphics-based filters on MacOS X.</p>
-
-<blockquote><b>Note:</b> At this time, none of the CUPS raster
-filters support ICC profiles. This will be addressed as time
-and resources permit.</blockquote>
+<h2 class='title'><a name='RASTERPS'>Writing PostScript Option Commands for Raster Drivers</a></h2>
-<h3>cupsColorProfile</h3>
+<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>
-<p class='summary'>*cupsColorProfile Resolution/MediaType: "density
-gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"</p>
+<pre class='command'>
+*PageSize A4: "<</PageSize[595 842]>>setpagedevice"
+</pre>
-<p>This string attribute specifies an sRGB-based color profile
-consisting of gamma and density controls and a 3x3 CMY color
-transform matrix.</p>
+<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>
-<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
-to act as a wildcard. Otherwise they must match one of the
-<tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
-the PPD file.</p>
+<pre class='command'>
+*CustomWatermarkText True: "<</cupsString1 3 -1 roll>>setpagedevice"
+</pre>
-<p>The <i>density</i> and <i>gamma</i> values define gamma and
-density adjustment function such that:</p>
+<p>For a custom string value of "My Watermark", CUPS will produce the following PostScript code for the option:</p>
<pre class='command'>
-f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
+(My Watermark)
+<</cupsString1 3 -1 roll>>setpagedevice
</pre>
-<p>The <i>m00</i> through <i>m22</i> values define a 3x3
-transformation matrix for the CMY color values. The density
-function is applied <i>after</i> the CMY transformation:</p>
+<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'>
-| m00 m01 m02 |
-| m10 m11 m12 |
-| m20 m21 m22 |
+<</cupsString1(My Watermark)>>setpagedevice
</pre>
-<p>Examples:</p>
+<p>The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.</p>
-<pre class='command'>
-<em>*% Specify a profile for printing at 360dpi on all media types</em>
-*cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
+<h3>Custom Page Size Code</a></h3>
-<em>*% Specify a profile for printing at 720dpi on Glossy media</em>
-*cupsColorProfile 720dpi/Glossy: "1.0 2.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
+<p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p>
-<em>*% Specify a default profile for printing at all other resolutions and media types</em>
-*cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
+<pre class='command'>
+*ParamCustomPageSize Width: 1 points <i>min-width max-width</i>
+*ParamCustomPageSize Height: 2 points <i>min-height max-height</i>
+*ParamCustomPageSize WidthOffset: 3 points 0 0
+*ParamCustomPageSize HeightOffset: 4 points 0 0
+*ParamCustomPageSize Orientation: 5 int 0 0
+*CustomPageSize True: "pop pop pop <</PageSize[5 -2 roll]/ImagingBBox null>>setpagedevice"
</pre>
-<h3>cupsICCProfile</h3>
+<h3>Supported PostScript Operators</a></h3>
-<p class='summary'>*cupsICCProfile
-ColorModel.MediaType.Resolution/Description: "filename"</p>
+<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>
-<p>This attribute specifies an ICC color profile that is
-used to convert the document colors to the device
-colorspace. The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
-<tt>Resolution</tt> keywords specify a selector for color
-profiles. If omitted, the color profile will match any option
-keyword for the corresponding main keyword.</p>
+<ul>
-<p>The <tt>Description</tt> specifies human-readable text that
-is associated with the color profile. The <tt>filename</tt>
-portion specifies the ICC color profile to use; if the filename
-is not absolute, it is loaded relative to the
-<var>/usr/share/cups/profiles</var> directory.</p>
+ <li><tt><<</tt> - Start a dictionary.</li>
-<p>Examples:</p>
+ <li><tt>>></tt> - End a dictionary.</li>
-<pre class='command'>
-<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
-*cupsICCProfile CMYK..360dpi/360dpi CMYK: "vendor/foo-360-cmyk.icc"
+ <li><tt>[</tt> - Start an array.</li>
-<em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
-*cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "vendor/foo-720-glossy-rgb.icc"
+ <li><tt>]</tt> - End an array.</li>
-<em>*% Specify a default profile for printing at all other resolutions and media types</em>
-*cupsICCProfile ../Default: "vendor/foo-default.icc"
-</pre>
+ <li><tt>copy</tt> - Copy the top N objects on the stack.</li>
-<h4>Customizing the Profile Selection Keywords</h4>
+ <li><tt>dup</tt> - Copy the top object on the stack.</li>
-<p>The <tt>MediaType</tt> and <tt>Resolution</tt> keywords can be
-reassigned to different main keywords, allowing drivers to do
-color profile selection based on different parameters. The
-<tt>cupsICCQualifier2</tt> and <tt>cupsICCQualifier3</tt>
-attributes define the mapping from selector to main keyword:</p>
+ <li><tt>index</tt> - Copy the Nth from the top object on the stack.</li>
-<pre class='command'>
-*cupsICCQualifier2: MainKeyword2
-*cupsICCQualifier3: MainKeyword3
-</pre>
+ <li><tt>pop</tt> - Pop the top object on the stack.</li>
-<p>The default mapping is as follows:</p>
+ <li><tt>roll</tt> - Shift the top N objects on the stack.</li>
-<pre class='command'>
-*cupsICCQualifier2: MediaType
-*cupsICCQualifier3: Resolution
-</pre>
+ <li><tt>setpagedevice</tt> - Set the page header values according to the key/value dictionary on the stack.</li>
+</ul>
-<h2 class='title'><a name='I18N'>Globalized PPD Support</a></h2>
+<blockquote><b>Note:</b>
-<p>CUPS 1.2 and higher adds support for PPD files containing multiple
-languages by following the following additional rules:</p>
-
-<ol>
-
- <li>The <tt>LanguageVersion</tt> MUST be <tt>English</tt></li>
-
- <li>The <tt>LanguageEncoding</tt> MUST be <tt>ISOLatin1</tt></li>
-
- <li>The <tt>cupsLanguages</tt> attribute MUST be provided and
- list each of the supported locales in the PPD file</li>
-
- <li>Main and option keywords MUST NOT exceed 34 (instead of 40)
- characters to allow room for the locale prefixes in translation
- attributes</li>
-
- <li>The main keyword "Translation" MUST NOT be used</li>
-
- <li>Translation strings included with the main and option
- keywords MUST NOT contain characters outside the ASCII
- subset of ISOLatin1 and UTF-8; developers wishing to use
- characters outside ASCII MUST provide a separate set of
- English localization attributes for the affected keywords.</li>
-
- <li>Localizations are specified using a locale prefix of
- the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
- language code and "CC" is the 2-letter ISO country
- code<ul>
- <li>A generic language translation ("ll") SHOULD be provided with country-specific differences ("ll_CC") provided only as needed</li>
- <li>For historical reasons, the "zh" and "zh_CN" locales map to Simplified Chinese while the "zh_TW" locale maps to Traditional Chinese</li>
- </ul></li>
-
- <li>Locale-specific translation strings MUST be encoded
- using UTF-8.</li>
-
- <li>Main keywords MUST be localized using one of the
- following forms:
- <p><tt>*ll.Translation MainKeyword/translation
- text: ""</tt><br />
- <tt>*ll_CC.Translation MainKeyword/translation
- text: ""</tt></p></li>
-
- <li>Option keywords MUST be localized using one of the
- following forms:
- <p><tt>*ll.MainKeyword OptionKeyword/translation
- text: ""</tt><br />
- <tt>*ll_CC.MainKeyword OptionKeyword/translation
- text: ""</tt></p></li>
-
- <li>Localization attributes MAY appear anywhere after the
- first line of the PPD file</li>
-
-</ol>
-
-<blockquote><b>Note:</b>
-We use a <tt>LanguageEncoding</tt> value of <tt>ISOLatin1</tt>
-and limit the allowed base translation strings to ASCII to avoid
-character coding issues that would otherwise occur. In addition,
-requiring the base translation strings to be in English allows
-for easier fallback translation when no localization is provided
-in the PPD file for a given locale.</blockquote>
-
-<p>Examples:</p>
-
-<pre class='command'>
-*LanguageVersion: English
-*LanguageEncoding: ISOLatin1
-*cupsLanguages: "de fr_CA"
-*ModelName: "Foobar Laser 9999"
-
-<em>*% Localize ModelName for French and German</em>
-*fr_CA.Translation ModelName/La Foobar Laser 9999: ""
-*de.Translation ModelName/Foobar LaserDrucken 9999: ""
-
-*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
-<em>*% Localize printer-state-reason for French and German</em>
-*fr_CA.cupsIPPReason com.vendor-error/Une erreur sèrieuse s'est produite: "/help/com.vendor/error.html"
-*de.cupsIPPReason com.vendor-error/Eine ernste Störung trat: "/help/com.vendor/error.html"
-
-...
-
-*OpenUI *InputSlot/Paper Source: PickOne
-*OrderDependency: 10 AnySetup *InputSlot
-*DefaultInputSlot: Auto
-<em>*% Localize InputSlot for French and German</em>
-*fr_CA.Translation InputSlot/Papier source: ""
-*de.Translation InputSlot/Papiereinzug: ""
-*InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice"
-<em>*% Localize InputSlot=Auto for French and German</em>
-*fr_CA.InputSlot Auto/Par Defaut: ""
-*de.InputSlot Auto/Standard: ""
-*InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice"
-<em>*% Localize InputSlot=Manual for French and German</em>
-*fr_CA.InputSlot Manual/Manuel mecanisme de alimentation: ""
-*de.InputSlot Manual/Manueller Einzug: ""
-*CloseUI: *InputSlot
-</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>Custom Page Size Code</h3>
-
-<p>There are many possible implementations of the <tt>CustomPageSize</tt> code. For CUPS raster drivers, the following code is recommended:</p>
-
-<pre class='command'>
-*ParamCustomPageSize Width: 1 points <i>min-width max-width</i>
-*ParamCustomPageSize Height: 2 points <i>min-height max-height</i>
-*ParamCustomPageSize WidthOffset: 3 points 0 0
-*ParamCustomPageSize HeightOffset: 4 points 0 0
-*ParamCustomPageSize Orientation: 5 int 0 0
-*CustomPageSize True: "pop pop pop <</PageSize[5 -2 roll]/ImagingBBox null>>setpagedevice"
-</pre>
-
-<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>
-
-<blockquote><b>Note:</b> <em>Never<em> use the unsupported <tt>dict</tt> or <tt>put</tt> operators in your option code. These operators are typically used in option code dating back to Level 1 PostScript printers, which did not support the simpler <tt><<</tt> or <tt>>></tt> operators. If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can rewrite it very easily to use the newer <tt><<</tt> and <tt>>></tt> operators instead. For example, the following code to set the page size:
+<p><em>Never</em> use the unsupported <tt>dict</tt> or <tt>put</tt>
+operators in your option code. These operators are typically used in
+option code dating back to Level 1 PostScript printers, which did not
+support the simpler <tt><<</tt> or <tt>>></tt> operators.
+If you have old option code using <tt>dict</tt> or <tt>put</tt>, you can
+rewrite it very easily to use the newer <tt><<</tt> and
+<tt>>></tt> operators instead. For example, the following code
+to set the page size:</p>
<style type='text/css'><!--
PRE B {
</blockquote>
-<h3>Supported Page Device Attributes</h3>
+<h3>Supported Page Device Attributes</a></h3>
<p>Table 2 shows the supported page device attributes along with PostScript code examples.</p>
</table></div>
-<h2 class='title'><a name='HISTORY'>Change History</a></h2>
+<h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
+
+<h3><span class='info'>CUPS 1.3</span><a name='cupsBackSide'>cupsBackSide</a></h3>
+
+<p class='summary'>*cupsBackSide: keyword</p>
+
+<p>This attribute requests special handling of the back side of pages
+when doing duplexed (2-sided) output. <a href='#TABLE_1'>Table 1</a>
+shows the supported keyword values for this attribute and their effect
+on the raster data sent to your driver. For example, when <tt>cupsBackSide</tt>
+is <code>Rotated</code> and <tt>Tumble</tt> is <tt>false</tt>, your driver
+will receive print data starting at the bottom right corner of the page, with
+each line going right-to-left instead of left-to-right. The default value is
+<code>Normal</code>.</p>
+
+<blockquote><b>Note:</b>
+
+<p><tt>cupsBackSide</tt> replaces the older <tt>cupsFlipDuplex</tt>
+attribute - if <tt>cupsBackSide</tt> is specified, <tt>cupsFlipDuplex</tt>
+will be ignored.</p>
+
+</blockquote>
+
+<div class='table'>
+<table width='80%' summary='Back Side Raster Coordinate System'>
+<caption>Table 1: <a name='TABLE_1'>Back Side Raster Coordinate System</a></caption>
+<thead>
+<tr>
+ <th>cupsBackSide</th>
+ <th>Tumble Value</th>
+ <th>Image Presentation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td><code>Normal</code></td>
+ <td><code>false</code></td>
+ <td>Left-to-right, top-to-bottom</td>
+</tr>
+<tr>
+ <td><code>Normal</code></td>
+ <td><code>true</code></td>
+ <td>Left-to-right, top-to-bottom</td>
+</tr>
+<tr>
+ <td><code>ManualTumble</code></td>
+ <td><code>false</code></td>
+ <td>Left-to-right, top-to-bottom</td>
+</tr>
+<tr>
+ <td><code>ManualTumble</code></td>
+ <td><code>true</code></td>
+ <td>Right-to-left, bottom-to-top</td>
+</tr>
+<tr>
+ <td><code>Rotated</code></td>
+ <td><code>false</code></td>
+ <td>Right-to-left, bottom-to-top</td>
+</tr>
+<tr>
+ <td><code>Rotated</code></td>
+ <td><code>true</code></td>
+ <td>Right-to-left, top-to-bottom</td>
+</tr>
+<tr>
+ <td><code>Flipped</code> *</td>
+ <td><code>false</code></td>
+ <td>Left-to-right, bottom-to-top</td>
+</tr>
+<tr>
+ <td><code>Flipped</code> *</td>
+ <td><code>true</code></td>
+ <td>Right-to-left, top-to-bottom</td>
+</tr>
+</tbody>
+</table>
+</div>
+
+<p><em>* - Not supported in Mac OS X 10.5.x and earlier</em></p>
+
+<div class='figure'><table summary='Back side images'>
+<caption>Figure 1: Back side images</caption>
+<tr><td><img src='../images/raster.png' width='624' height='448' alt='Back side images'></td></tr>
+</table></div>
+
+<p>Examples:</p>
+
+<pre class='command'>
+<em>*% Flip the page image for the back side of duplexed output</em>
+*cupsBackSide: Flipped
+
+<em>*% Rotate the page image for the back side of duplexed output</em>
+*cupsBackSide: Rotated
+</pre>
+
+<p>Also see the related <a href='#APDuplexRequiresFlippedMargin'><tt>APDuplexRequiresFlippedMargin</tt></a>
+attribute.</p>
+
+<h3><span class='info'>CUPS 1.3</span><a name='cupsEvenDuplex'>cupsEvenDuplex</a></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><a name='cupsFax'>cupsFax</a></h3>
+
+<p class='summary'>*cupsFax: boolean</p>
+
+<p>This boolean attribute specifies whether the PPD defines a facsimile device. The default is <tt>false</tt>.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*cupsFax: true
+</pre>
+
+<h3><a name='cupsFilter'>cupsFilter</a></h3>
+
+<p class='summary'>*cupsFilter: "source/type cost program"</p>
+
+<p>This string attribute provides a conversion rule from the
+given source type to the printer's native format using the
+filter "program". If a printer supports the source type directly,
+the special filter program "-" may be specified.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+<em>*% Standard raster printer driver filter</em>
+*cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
+
+<em>*% Plain text filter</em>
+*cupsFilter: "text/plain 10 texttofoo"
+
+<em>*% Pass-through filter for PostScript printers</em>
+*cupsFilter: "application/vnd.cups-postscript 0 -"
+</pre>
+
+<h3><span class='info'>Deprecated</span><a name='cupsFlipDuplex'>cupsFlipDuplex</a></h3>
+
+<p class='summary'>*cupsFlipDuplex: boolean</p>
+
+<p>Due to implementation differences between Mac OS X and Ghostscript,
+the <tt>cupsFlipDuplex</tt> attribute is deprecated. Instead, use
+the <a href='#cupsBackSide'><tt>cupsBackSide</tt></a> attribute to specify
+the coordinate system (pixel layout) of the page data on the back side of
+duplex pages.</p>
+
+<p>The value <code>true</code> maps to a <tt>cupsBackSide</tt> value
+of <code>Rotated</code> on Mac OS X and <code>Flipped</code> with
+Ghostscript.</p>
+
+<p>The default value is <code>false</code>.</p>
+
+<blockquote><b>Note:</b>
+
+<p>Mac OS X drivers that previously used
+<tt>cupsFlipDuplex</tt> may wish to provide both the old and
+new attributes for maximum compatibility, for example:</p>
+
+<pre class='command'>
+*cupsBackSide: Rotated
+*cupsFlipDuplex: true
+</pre>
+
+<p>Similarly, drivers written for other operating systems using
+Ghostscript can use:</p>
+
+<pre class='command'>
+*cupsBackSide: Flipped
+*cupsFlipDuplex: true
+</pre></blockquote>
+
+<h3><span class='info'>CUPS 1.3</span><a name='cupsIPPFinishings'>cupsIPPFinishings</a></h3>
+
+<p class='summary'>*cupsIPPFinishings number/text: "*Option Choice ..."</p>
+
+<p>This attribute defines a mapping from IPP <code>finishings</code>
+values to PPD options and choices.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*cupsIPPFinishings 4/staple: "*StapleLocation SinglePortrait"
+*cupsIPPFinishings 5/punch: "*PunchMedia Yes *PunchLocation LeftSide"
+*cupsIPPFinishings 20/staple-top-left: "*StapleLocation SinglePortrait"
+*cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
+</pre>
+
+<h3><span class='info'>CUPS 1.3</span><a name='cupsIPPReason'>cupsIPPReason</a></h3>
+
+<p class='summary'>*cupsIPPReason reason/Reason Text: "optional URIs"</p>
+
+<p>This optional attribute maps custom
+<code>printer-state-reasons</code> keywords that are generated by
+the driver to human readable text. The optional URIs string
+contains zero or more URIs separated by a newline. Each URI can
+be a CUPS server absolute path to a help file under the
+scheduler's <code>DocumentRoot</code> directory, a full HTTP URL
+("http://www.domain.com/path/to/help/page.html"), or any other
+valid URI which directs the user at additional information
+concerning the condition that is being reported.</p>
+
+<p>Since the reason text is limited to 80 characters by the PPD specification,
+longer text strings can be included by URI-encoding the text with the "text"
+scheme, for example "text:some%20text". Multiple <code>text</code> URIs are
+combined (with spaces between each URI) by the <tt>ppdLocalizeIPPReason</tt>
+into a single string that can be displayed to the user.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+<em>*% Map com.vendor-error to text but no page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: ""
+
+<em>*% Map com.vendor-error to more than 80 characters of text but no page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: "text:Now%20is%20the%20time
+text:for%20all%20good%20men%20to%20come%20to%20the%20aid%20of%20their%20country."
+
+<em>*% Map com.vendor-error to text and a local page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html"
+
+<em>*% Map com.vendor-error to text and a remote page</em>
+*cupsIPPReason com.vendor-error/A serious error occurred: "http://www.vendor.com/help"
+
+<em>*% Map com.vendor-error to text and a local, Apple help book, and remote page</em>
+*APHelpBook: "file:///Library/Printers/vendor/Help/filename"
+*cupsIPPReason com.vendor-error/A serious error occurred: "/help/com.vendor/error.html
+help:anchor='com.vendor-error'%20bookID=Vendor%20Help
+http://www.vendor.com/help"
+*End
+</pre>
+
+<h3><span class='info'>CUPS 1.2</span><a name='cupsLanguages'>cupsLanguages</a></h3>
+
+<p class='summary'>*cupsLanguages: "locale list"</p>
+
+<p>This attribute describes which language localizations are
+included in the PPD. The "locale list" string is a space-delimited
+list of locale names ("en", "en_US", "fr_CA", etc.)</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Specify Canadian, UK, and US English, and Candian and French French</em>
+*cupsLanguages: "en_CA en_UK en_US fr_CA fr_CA"
+</pre>
+
+<h3><a name='cupsManualCopies'>cupsManualCopies</a></h3>
+
+<p class='summary'>*cupsManualCopies: boolean</p>
+
+<p>This boolean attribute notifies the RIP filters that the
+destination printer does not support copy generation in
+hardware. The default value is <code>false</code>.</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Tell the RIP filters to generate the copies for us</em>
+*cupsManualCopies: true
+</pre>
+
+<h3><a name='cupsModelNumber'>cupsModelNumber</a></h3>
+
+<p class='summary'>*cupsModelNumber: number</p>
+
+<p>This integer attribute specifies a printer-specific model
+number. This number can be used by a filter program to adjust
+the output for a specific model of printer.</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Specify an integer for a driver-specific model number</em>
+*cupsModelNumber: 1234
+</pre>
+
+
+<h3><span class='info'>CUPS 1.3</span><a name='cupsPJLCharset'>cupsPJLCharset</a></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><span class='info'>CUPS 1.2</span><a name='cupsPortMonitor'>cupsPortMonitor</a></h3>
+
+<p class='summary'>*cupsPortMonitor urischeme/Descriptive Text: "port monitor"</p>
+
+<p>This string attribute specifies printer-specific "port
+monitor" filters that may be used with the printer. The CUPS
+scheduler also looks for the <tt>Protocols</tt> attribute to see
+if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
+so, the corresponding port monitor ("bcp" and "tbcp",
+respectively) is listed in the printer's
+<tt>port-monitor-supported</tt> attribute.</p>
+
+<p>The "urischeme" portion of the attribute specifies the URI scheme
+that this port monitor should be used for. Typically this is used to
+pre-select a particular port monitor for each type of connection that
+is supported by the printer. The "port monitor" string can be "none"
+to disable the port monitor for the given URI scheme.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+<em>*% Specify a PostScript printer that supports the TBCP protocol</em>
+*Protocols: TBCP PJL
+
+<em>*% Specify that TBCP should be used for socket connections but not USB</em>
+*cupsPortMonitor socket/AppSocket Printing: "tbcp"
+*cupsPortMonitor usb/USB Printing: "none"
+
+<em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
+*cupsPortMonitor usb/USB Status Monitor: "epson-usb"
+</pre>
+
+<h3><span class='info'>CUPS 1.3</span><a name='cupsPreFilter'>cupsPreFilter</a></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><a name='cupsVersion'>cupsVersion</a></h3>
+
+<p class='summary'>*cupsVersion: major.minor</p>
+
+<p>This required attribute describes which version of the CUPS
+PPD file extensions was used. Currently it must be the string
+"1.0", "1.1", "1.2", or "1.3".</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Specify a CUPS 1.2 driver</em>
+*cupsVersion: "1.2"
+</pre>
+
+
+<h2 class='title'><a name='MACOSX'>Mac OS X Attributes</a></h2>
+
+<h3><a name='APBookFile'>APBookFile</a></h3>
+
+<p class='summary'>*APBookFile: "file URL"</p>
+
+<p>This string attribute specifies the Apple help book file to use when
+looking up IPP reason codes for this printer driver. The
+<a href='#cupsIPPReason'><tt>cupsIPPReason</tt></a> attribute maps
+"help" URIs to this file.</p>
+
+<p>Example:</p>
+
+<pre class='command'>
+*APBookFile: "file:///Library/Printers/vendor/Help/filename"
+</pre>
+
+<h3><span class='info'>Mac OS X 10.3</span><a name='APDialogExtension'>APDialogExtension</a></h3>
+
+<p class='summary'>*APDialogExtension: "/Library/Printers/vendor/filename.plugin"</p>
+
+<p>This attribute defines additional option panes that are displayed in the
+print dialog. Each attribute adds one or more option panes. See the "OutputBinsPDE"
+example and <a href='http://developer.apple.com/qa/qa2004/qa1352.html'>Apple
+Technical Q&A QA1352</a> for information on writing your own print dialog
+plug-ins.</p>
+
+<blockquote><b>Note:</b>
+
+<p>Starting with Mac OS X 10.5, each plug-in must be compiled "4-way fat"
+(32-bit and 64-bit for both PowerPC and Intel) with garbage collection enabled
+in order to be usable with all applications.</p>
+
+</blockquote>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*% Add two panes for finishing and driver options
+*APDialogExtension: "/Library/Printers/vendor/finishing.plugin"
+*APDialogExtension: "/Library/Printers/vendor/options.plugin"
+</pre>
+
+<h3><span class='info'>Mac OS X 10.4</span><a name='APDuplexRequiresFlippedMargin'>APDuplexRequiresFlippedMargin</a></h3>
+
+<p class='summary'>*APDuplexRequiresFlippedMargin: boolean</p>
+
+<p>This boolean attribute notifies the RIP filters that the
+destination printer requires the top and bottom margins of the
+<tt>ImageableArea</tt> to be swapped for the back page. The
+default is <tt>true</tt> when <tt>cupsBackSide</tt> is <tt>Flipped</tt>
+and <tt>false</tt> otherwise. <a href='#TABLE_2'>Table 2</a> shows how
+<tt>APDuplexRequiresFlippedMargin</tt> interacts with <tt>cupsBackSide</tt>
+and the <tt>Tumble</tt> page attribute.</p>
+
+<div class='table'>
+<table width='80%' summary='Margin Flipping Modes'>
+<caption>Table 2: <a name='TABLE_2'>Margin Flipping Modes</a></caption>
+<thead>
+<tr>
+ <th>APDuplexRequiresFlippedMargin</th>
+ <th>cupsBackSide</th>
+ <th>Tumble Value</th>
+ <th>Margins</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+ <td>false</td>
+ <td>any</td>
+ <td>any</td>
+ <td>Normal</td>
+</tr>
+<tr>
+ <td>any</td>
+ <td>Normal</td>
+ <td>any</td>
+ <td>Normal</td>
+</tr>
+<tr>
+ <td>true</td>
+ <td>ManualDuplex</td>
+ <td>false</td>
+ <td>Normal</td>
+</tr>
+<tr>
+ <td>true</td>
+ <td>ManualDuplex</td>
+ <td>true</td>
+ <td>Flipped</td>
+</tr>
+<tr>
+ <td>true</td>
+ <td>Rotated</td>
+ <td>false</td>
+ <td>Flipped</td>
+</tr>
+<tr>
+ <td>true</td>
+ <td>Rotated</td>
+ <td>true</td>
+ <td>Normal</td>
+</tr>
+<tr>
+ <td>true or unspecified</td>
+ <td>Flipped</td>
+ <td>any</td>
+ <td>Flipped</td>
+</tr>
+</tbody>
+</table></div>
+
+<p>Example:</p>
+
+<pre class='command'>
+<em>*% Rotate the back side images</em>
+*cupsBackSide: Rotated
+
+<em>*% Don't swap the top and bottom margins for the back side</em>
+*APDuplexRequiresFlippedMargin: false
+</pre>
+
+<p>Also see the related <a href='#cupsBackSide'><tt>cupsBackSide</tt></a>
+attribute.</p>
+
+<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterIconPath'>APPrinterIconPath</a></h3>
+
+<p class='summary'>*APPrinterIconPath: "/Library/Printers/vendor/filename"</p>
+
+<p>This attribute defines the location of a printer icon file to use when
+displaying the printer.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*% Apple icon file
+*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
+
+*% TIFF icon file
+*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.tiff"
+
+*% PNG icon file
+*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.png"
+
+*% JPEG icon file
+*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.jpg"
+</pre>
+
+<h3><span class='info'>Mac OS X 10.4</span><a name='APPrinterLowInkTool'>APPrinterLowInkTool</a></h3>
+
+<p class='summary'>*APPrinterLowInkTool: "/Library/Printers/vendor/program"</p>
+
+<p>This attribute defines an program that checks the ink/toner/marker levels
+on a printer, returning an XML document with those levels. See the "InkTool"
+example and
+<a href='http://developer.apple.com/technotes/tn2005/tn2144.html'>Apple
+Technical Note TN2144</a> for more information.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*% Use a vendor monitoring program
+*APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool"
+</pre>
+
+<h3><span class='info'>Mac OS X 10.5</span><a name='APPrinterPreset'>APPrinterPreset</a></h3>
+
+<p class='summary'>*APPrinterPreset name/text: "*Option Choice ..."</p>
+
+<p>This attribute defines presets for multiple options that show up
+in the print dialog of applications (such as iPhoto) that set the job
+style hint to <tt>NSPrintPhotoJobStyleHint</tt>. Each preset maps to one or
+more pairs of PPD options and choices as well as providing key/value data for
+the application. The following preset names are currently defined:</p>
+
+<ul>
+
+ <li><code>Photo_with_Paper_Auto-Detect</code>; Photo printing
+ with paper auto-detect</li>
+
+ <li><code>Photo_with_Paper_Auto-Detect_-_Fine</code>; Photo printing
+ with paper auto-detect - fine</li>
+
+ <li><code>Photo_on_Plain_Paper</code>; Photo printing on plain paper</li>
+
+ <li><code>Photo_on_Plain_Paper_-_Fine</code>; Photo printing on plain
+ paper - fine</li>
+
+ <li><code>Photo_on_Photo_Paper</code>; Photo printing on photo paper</li>
+
+ <li><code>Photo_on_Photo_Paper_-_Fine</code>; Photo printing on photo
+ paper - fine</li>
+
+ <li><code>Photo_on_Matte_Paper</code>; Photo printing on matte paper</li>
+
+ <li><code>Photo_on_Matte_Paper_-_Fine</code>; Photo printing on matte
+ paper - fine</li>
+
+</ul>
+
+<p>The value string consists of pairs of keywords, either an option name and
+choice (*MainKeyword OptionKeyword) or a preset identifier and value
+(com.apple.print.preset.foo value). Preset identifiers and their supported
+values are documented in "<a
+href='http://developer.apple.com/documentation/Printing/Conceptual/PresetDraft/presets_intro/chapter_1_section_2.html'
+>Creating Printing Presets for iPhoto: Printing Presets File Format</a>".</p>
+
+<p>Presets, like options, can also be localized in multiple languages.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*APPrinterPreset Photo_on_Photo_Paper/Photo on Photo Paper: "
+ *MediaType Glossy
+ *ColorModel RGB
+ *Resolution 300dpi
+ com.apple.print.preset.graphicsType Photo
+ com.apple.print.preset.quality mid
+ com.apple.print.preset.media-front-coating glossy"
+*End
+*fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: ""
+</pre>
+
+<h3><span class='info'>Mac OS X 10.3</span><a name='APPrinterUtilityPath'>APPrinterUtilityPath</a></h3>
+
+<p class='summary'>*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"</p>
+
+<p>This attribute defines a GUI application that can be used to do printer
+maintenance functions such as cleaning the print head(s). See ... for more
+information.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*% Define the printer utility application
+*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
+</pre>
+
+<h3><span class='info'>Mac OS X 10.3</span><a name='APScanAppBundleID'>APScanAppBundleID</a></h3>
+
+<p class='summary'>*APScanAppBundleID: "bundle ID"</p>
+
+<p>This attribute defines the application to use when scanning pages from
+the device.</p>
+
+<p>Examples:</p>
+
+<pre class='command'>
+*APScanAppBundleID: "com.apple.ImageCaptureApp"
+</pre>
+
+
+<h2 class='title'><a name='HISTORY'>Change History</a></h2>
+
+<h3>Changes in CUPS 1.3.1</a></h3>
+
+<ul>
+
+ <li>Added missing Mac OS X <tt>AP</tt> attributes.</li>
+
+ <li>Added section on auto-configuration including the
+ <tt>OID<i>MainKeyword</i></tt> and <tt>?<i>MainKeyword</i></tt>
+ attributes.</li>
+
+ <li>Minor reorganization.</li>
+
+</ul>
+
-<h3>Changes in CUPS 1.3</h3>
+<h3>Changes in CUPS 1.3</a></h3>
<ul>
</ul>
-<h3>Changes in CUPS 1.2.8</h3>
+<h3>Changes in CUPS 1.2.8</a></h3>
<ul>
</ul>
-<h3>Changes in CUPS 1.2</h3>
+<h3>Changes in CUPS 1.2</a></h3>
<ul>
</ul>
-<h3>Changes in CUPS 1.1</h3>
+<h3>Changes in CUPS 1.1</a></h3>
<ul>
projects / thirdparty / cups.git / blobdiff