[thirdparty/cups.git] / doc / help / spec-ppd.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<!-- SECTION: Programming -->
<head>
	<title>CUPS PPD Extensions</title>
	<meta name='keywords' content='Programming, PostScript Printer Description'>
</head>
<body>
<!--
  "$Id: spec-ppd.html 4941 2006-01-18 13:16:40Z mike $"

  CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).

  Copyright 1997-2006 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
-->

<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>

<p>This specification describes the attributes and extensions
that CUPS adds to <a
href="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
Adobe TechNote #5003: PostScript Printer Description File Format
Specification Version 4.3</a>. PostScript Printer Description
("PPD") files describe the capabilities of each printer and are
used by CUPS to support printer-specific features and intelligent
filtering.</p>

<h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2>

<p>The PPD format is text-based and uses lines of up to 255
characters terminated by a carriage return, linefeed, or
combination of carriage return and line feed. The following ABNF
definition [RFC2234] defines the general format of lines in a PPD
file:</p>

<pre class='command'>
PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)

HEADER   = "*" 0x50.50.44.2D.41.64.6F.62.65 ":"   ; *PPD-Adobe:
           *WSP DQUOTE "4.3" DQUOTE LINE-END

COMMENT  = "*%" *TCHAR LINE-END

DATA     = "*" 1*KCHAR [ WSP 1*KCHAR [ "/" 1*TCHAR ] ] ":"
           1*(*WSP VALUE) LINE-END

VALUE    = 1*TCHAR / DQUOTE 1*SCHAR DQUOTE

KCHAR    = ALPHA / DIGIT / "_" / "." / "-"

SCHAR    = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF

TCHAR    = %x20-7E / %xA0-FF

LINE-END = CR / LF / CR LF
</pre>


<h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>

<h3>cupsFilter</h3>

<p>This string attribute provides a conversion rule of the
form:</p>

<pre class='command'>
source/type cost program
</pre>

<p>The destination type is assumed to the printer's type. 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>cupsFlipDuplex</h3>

<p>This boolean attribute notifies the RIP filters that the
destination printer requires an upside-down image for the back
page. The default value is false.</p>

<p>Example:</p>

<pre class='command'>
<em>*% Flip the page image for the back side of duplexed output</em> 
*cupsFlipDuplex: true
</pre>

<h3>cupsManualCopies</h3>

<p>This boolean attribute notifies the RIP filters that the
destination printer does not support copy generation in
hardware. The default value is false.</p>

<p>Example:</p>

<pre class='command'>
<em>*% Tell the RIP filters to generate the copies for us</em> 
*cupsManualCopies: true
</pre>

<h3>cupsModelNumber</h3>

<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>cupsPortMonitor</h3>

<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>Examples:</p>

<pre class='command'>
<em>*% Specify a PostScript printer that supports the TBCP protocol</em>
*Protocols: TBCP PJL

<em>*% Specify a printer-specific port monitor for an Epson USB printer</em> 
*cupsPortMonitor epson-usb/USB Status Monitor: "epson-usb"
</pre>

<h3>cupsVersion</h3>

<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>

<p>CUPS supports custom options using an extension of the
<tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt>
syntax:</p>

<pre class='command'>
*CustomFoo True: "command"
*ParamCustomFoo Name1/Text 1: order type minimum maximum
*ParamCustomFoo Name2/Text 2: order type minimum maximum
...
*ParamCustomFoo NameN/Text N: order type minimum maximum
</pre>

<p>When the base option is part of the <tt>JCLSetup</tt> section,
the "command" string contains JCL commands with "\order"
placeholders for each numbered parameter. The CUPS API handles
any necessary value quoting for HP-PJL commands.</p>

<p>For non-<tt>JCLSetup</tt> options, the "order" value is a
number from 1 to N and specifies the order of values as they are
placed on the stack before the command.</p>

<blockquote><b>Note:</b> Currently only CustomPageSize supports
more than 1 parameter. This restriction is due to value encoding
issues, since the "Custom.value" format does not allow for
specification of named parameters. We anticipate supporting the
collection value format "{Name1=foo Name2=bar}" for the final
CUPS 1.2 release. In addition, the collection value format will
allow string values to contain spaces.</blockquote>

<p>The "type" is one of the following keywords:</p>

<ul>

	<li><tt>curve</tt> - a real value from "minimum" to
	"maximum" representing a gamma correction curve using the
	function: f(x) = x <sup>value</sup></li>

	<li><tt>int</tt> - an integer value from "minimum" to
	"maximum"</li>

	<li><tt>invcurve</tt> - a real value from "minimum" to
	"maximum" representing a gamma correction curve using the
	function: f(x) = x <sup>1 / value</sup></li>

	<li><tt>passcode</tt> - a string of numbers value with a
	minimum of "minimum" numbers and a maximum of "maximum"
	numbers (passcode strings are not displayed in the user
	interface)</li>

	<li><tt>password</tt> - a string value with a minimum of
	"minimum" characters and a maximum of "maximum"
	characters (password strings are not displayed in the
	user interface)</li>

	<li><tt>points</tt> - a measurement value in points from
	"minimum" to "maximum"</li>

	<li><tt>real</tt> - a real value from "minimum" to
	"maximum"</li>

	<li><tt>string</tt> - a string value with a minimum of
	"minimum" characters and a maximum of "maximum"
	characters</li>

</ul>

<p>Examples:</p>

<pre class='command'>
<em>*% Base JCL key code option</em> 
*OpenUI JCLPasscode/Key Code: PickOne
*OrderDependency: 10 JCLSetup *JCLPasscode
*DefaultJCLPasscode: None
*JCLPasscode None/No Code: ""
*JCLPasscode 1111: "@PJL SET PASSCODE = 1111&lt;0A&gt;"
*JCLPasscode 2222: "@PJL SET PASSCODE = 2222&lt;0A&gt;"
*JCLPasscode 3333: "@PJL SET PASSCODE = 3333&lt;0A&gt;"
*JCLCloseUI: *JCLPasscode

<em>*% Custom JCL key code option</em> 
*CustomJCLPasscode True: "@PJL SET PASSCODE = \1&lt;0A&gt;"
*ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4


<em>*% Base PostScript gamma/density option</em> 
*OpenUI GammaDensity/Gamma and Density: PickOne
*OrderDependency: 10 AnySetup *GammaDensity
*DefaultGammaDensity: Normal
*GammaDensity Normal/Normal: "&lt;&lt;/cupsReal1 1.0/cupsReal2 1.0&gt;&gt;setpagedevice"
*GammaDensity Light/Lighter: "&lt;&lt;/cupsReal1 0.9/cupsReal2 0.67&gt;&gt;setpagedevice"
*GammaDensity Dark/Darker: "&lt;&lt;/cupsReal1 1.1/cupsReal2 1.5&gt;&gt;setpagedevice"
*JCLCloseUI: *GammaDensity

<em>*% Custom PostScript gamma/density option</em> 
*CustomGammaDensity True: "&lt;&lt;/cupsReal1 3 1 roll/cupsReal2 3 1&gt;&gt;setpagedevice"
*ParamCustomGammaDensity Gamma: 1 curve 0.1 10
*ParamCustomGammaDensity Density: 2 real 0 2
</pre>


<h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>

<h3>cupsColorProfile</h3>

<p>This string attribute specifies a color profile of the
form:</p>

<pre class='command'>
*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
</pre>

<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>The <i>density</i> and <i>gamma</i> values define gamma and
density adjustment function such that:</p>

<pre class='command'>
f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
</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>

<pre class='command'>
| m00 m01 m02 |
| m10 m11 m12 |
| m20 m21 m22 |
</pre>

<p>Examples:</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"

<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"

<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>cupsICCProfile</h3>

<p>This attribute specifies an ICC color profile of the
form:</p>

<pre class='command'>
*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
</pre>

<p>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'>
<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em> 
*cupsICCProfile CMYK..360dpi/360dpi CMYK: "vendor/foo-360-cmyk.icc"

<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"

<em>*% Specify a default profile for printing at all other resolutions and media types</em> 
*cupsICCProfile ../Default: "vendor/foo-default.icc"
</pre>

<h4>Customizing the Profile Selection Keywords</h4>

<p>The <tt>ColorModel</tt>, <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>cupsICCQualifier1</tt>,
<tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt>
attributes define the mapping from selector to main keyword:</p>

<pre class='command'>
*cupsICCQualifier1: MainKeyword
*cupsICCQualifier2: MainKeyword
*cupsICCQualifier3: MainKeyword
</pre>

<p>The default mapping is as follows:</p>

<pre class='command'>
*cupsICCQualifier1: ColorModel
*cupsICCQualifier2: MediaType
*cupsICCQualifier3: Resolution
</pre>


<h2 class='title'><a name='I18N'>I18N Support</a></h2>

<p>CUPS 1.2 and higher adds support for PPD files containing multiple
languages by following the following rules:</p>

<ol>

	<li>The <tt>LanguageVersion</tt> is <tt>English</tt></li>

	<li>The <tt>LanguageEncoding</tt> is <tt>ISOLatin1</tt></li>

	<li>Main and option keywords may not exceed 34
	characters, which is a subset of what the Adobe PPD spec
	allows.</li>

	<li>Translations 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</li>

	<li>Translation strings are encoded using UTF-8.</li>

	<li>Main keywords are translated using any 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 are translated using any of the
	following forms:
	<p><tt>*ll.MainKeyword OptionKeyword/translation
	text: ""</tt><br />
	<tt>*ll_CC.MainKeyword OptionKeyword/translation
	text: ""</tt></p></li>

</ol>

<p>Examples:</p>


<pre class='command'>
*LanguageVersion: English
*LanguageEncoding: ISOLatin1
*ModelName: "Foobar Laser 9999"

<em>*% Localize for French and German</em>
*fr_FR.Translation ModelName/La Foobar Laser 9999: ""
*de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""

...

*OpenUI *InputSlot/Paper Source: PickOne
*OrderDependency: 10 AnySetup *InputSlot
*DefaultInputSlot: Auto
<em>*% Localize for French and German</em>
*fr_FR.Translation InputSlot/Papier source: ""
*de_DE.Translation InputSlot/Papiereinzug: ""
*InputSlot Auto/Default: "&lt;&lt;/ManualFeed false&gt;&gt;setpagedevice"
<em>*% Localize for French and German</em>
*fr_FR.InputSlot Auto/Par Defaut: ""
*de_DE.InputSlot Auto/Standard: ""
*InputSlot Manual/Manual Feed: "&lt;&lt;/ManualFeed true&gt;&gt;setpagedevice"
<em>*% Localize for French and German</em>
*fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
*de_DE.InputSlot Manual/Manueller Einzug: ""
*CloseUI: *InputSlot
</pre>


<h2 class='title'><a name='HISTORY'>Change History</a></h2>

<h3>Changes in CUPS 1.2</h3>

<ul>

	<li>Added I18N support attributes</li>

	<li>Added custom option values support</li>

	<li>Added <tt>cupsICCProfile</tt> attribute</li>

	<li>Added <tt>cupsPortMonitor</tt> attribute</li>

	<li>Removed <tt>cupsProtocol</tt> attribute</li>

</ul>

<h3>Changes in CUPS 1.1</h3>

<ul>

	<li>Added <tt>cupsFlipDuplex</tt> attribute</li>

	<li>Added <tt>cupsProtocol</tt> attribute</li>

</ul>

</body>
</html>
Commit	Line	Data
ef416fc2	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
	2	<html>
	3	<!-- SECTION: Programming -->
	4	<head>
	5	<title>CUPS PPD Extensions</title>
	6	<meta name='keywords' content='Programming, PostScript Printer Description'>
	7	</head>
	8	<body>
	9	<!--
fa73b229	10	"$Id: spec-ppd.html 4941 2006-01-18 13:16:40Z mike $"
ef416fc2	11
	12	CUPS PPD extensions specification for the Common UNIX Printing System (CUPS).
	13
	14	Copyright 1997-2006 by Easy Software Products.
	15
	16	These coded instructions, statements, and computer programs are the
	17	property of Easy Software Products and are protected by Federal
	18	copyright law. Distribution and use rights are outlined in the file
	19	"LICENSE.txt" which should have been included with this file. If this
	20	file is missing or damaged please contact Easy Software Products
	21	at:
	22
	23	Attn: CUPS Licensing Information
	24	Easy Software Products
	25	44141 Airport View Drive, Suite 204
	26	Hollywood, Maryland 20636 USA
	27
	28	Voice: (301) 373-9600
	29	EMail: cups-info@cups.org
	30	WWW: http://www.cups.org
	31	-->
	32
	33	<h2 class='title'><a name='INTRODUCTION'>Introduction</a></h2>
	34
	35	<p>This specification describes the attributes and extensions
	36	that CUPS adds to <a
	37	href="http://partners.adobe.com/asn/developer/PDFS/TN/5003.PPD_Spec_v4.3.pdf">
	38	Adobe TechNote #5003: PostScript Printer Description File Format
	39	Specification Version 4.3</a>. PostScript Printer Description
	40	("PPD") files describe the capabilities of each printer and are
	41	used by CUPS to support printer-specific features and intelligent
	42	filtering.</p>
	43
	44	<h2 class='title'><a name='SYNTAX'>PPD File Syntax</a></h2>
	45
	46	<p>The PPD format is text-based and uses lines of up to 255
	47	characters terminated by a carriage return, linefeed, or
	48	combination of carriage return and line feed. The following ABNF
	49	definition [RFC2234] defines the general format of lines in a PPD
	50	file:</p>
	51
	52	<pre class='command'>
	53	PPD-FILE = HEADER +(DATA / COMMENT / LINE-END)
	54
	55	HEADER = "" 0x50.50.44.2D.41.64.6F.62.65 ":" ; PPD-Adobe:
	56	*WSP DQUOTE "4.3" DQUOTE LINE-END
	57
	58	COMMENT = "%" TCHAR LINE-END
	59
	60	DATA = "" 1KCHAR [ WSP 1KCHAR [ "/" 1TCHAR ] ] ":"
	61	1(WSP VALUE) LINE-END
	62
	63	VALUE = 1TCHAR / DQUOTE 1SCHAR DQUOTE
	64
	65	KCHAR = ALPHA / DIGIT / "_" / "." / "-"
	66
	67	SCHAR = LINE-END / WSP / %x21 / %x23-7E / %xA0-FF
	68
	69	TCHAR = %x20-7E / %xA0-FF
	70
	71	LINE-END = CR / LF / CR LF
	72	</pre>
	73
	74
75	<h2 class='title'><a name='ATTRIBUTES'>General Attributes</a></h2>
76
77	<h3>cupsFilter</h3>
78
79	<p>This string attribute provides a conversion rule of the
80	form:</p>
81
82	<pre class='command'>
83	source/type cost program
84	</pre>
85
86	<p>The destination type is assumed to the printer's type. If a
87	printer supports the source type directly, the special filter
88	program "-" may be specified.</p>
89
90	<p>Examples:</p>
91
92	<pre class='command'>
93	<em>*% Standard raster printer driver filter</em>
94	*cupsFilter: "application/vnd.cups-raster 100 rastertofoo"
95
96	<em>*% Plain text filter</em>
97	*cupsFilter: "text/plain 10 texttofoo"
98
99	<em>*% Pass-through filter for PostScript printers</em>
100	*cupsFilter: "application/vnd.cups-postscript 0 -"
101	</pre>
102
103	<h3>cupsFlipDuplex</h3>
104
105	<p>This boolean attribute notifies the RIP filters that the
106	destination printer requires an upside-down image for the back
107	page. The default value is false.</p>
108
109	<p>Example:</p>
110
111	<pre class='command'>
112	<em>*% Flip the page image for the back side of duplexed output</em>
113	*cupsFlipDuplex: true
114	</pre>
115
116	<h3>cupsManualCopies</h3>
117
118	<p>This boolean attribute notifies the RIP filters that the
119	destination printer does not support copy generation in
120	hardware. The default value is false.</p>
121
122	<p>Example:</p>
123
124	<pre class='command'>
125	<em>*% Tell the RIP filters to generate the copies for us</em>
126	*cupsManualCopies: true
127	</pre>
128
129	<h3>cupsModelNumber</h3>
130
131	<p>This integer attribute specifies a printer-specific model
132	number. This number can be used by a filter program to adjust
133	the output for a specific model of printer.</p>
134
135	<p>Example:</p>
136
137	<pre class='command'>
138	<em>*% Specify an integer for a driver-specific model number</em>
139	*cupsModelNumber: 1234
140	</pre>
141
142	<h3>cupsPortMonitor</h3>
143
144	<p>This string attribute specifies printer-specific "port
145	monitor" filters that may be used with the printer. The CUPS
146	scheduler also looks for the <tt>Protocols</tt> attribute to see
147	if the <tt>BCP</tt> or <tt>TBCP</tt> protocols are supported. If
148	so, the corresponding port monitor ("bcp" and "tbcp",
149	respectively) is listed in the printer's
150	<tt>port-monitor-supported</tt> attribute.</p>
151
152	<p>Examples:</p>
153
154	<pre class='command'>
155	<em>*% Specify a PostScript printer that supports the TBCP protocol</em>
156	*Protocols: TBCP PJL
157
158	<em>*% Specify a printer-specific port monitor for an Epson USB printer</em>
159	*cupsPortMonitor epson-usb/USB Status Monitor: "epson-usb"
160	</pre>
161
162	<h3>cupsVersion</h3>
163
164	<p>This required attribute describes which version of the CUPS
165	PPD file extensions was used. Currently it must be the string
166	"1.0", "1.1", or "1.2".</p>
167
168	<p>Example:</p>
169
170	<pre class='command'>
171	<em>*% Specify a CUPS 1.2 driver</em>
172	*cupsVersion: "1.2"
173	</pre>
174
175
176	<h2 class='title'><a name='OPTIONS'>Custom Options</a></h2>
177
178	<p>CUPS supports custom options using an extension of the
179	<tt>CustomPageSize</tt> and <tt>ParamCustomPageSize</tt>
180	syntax:</p>
181
182	<pre class='command'>
183	*CustomFoo True: "command"
184	*ParamCustomFoo Name1/Text 1: order type minimum maximum
185	*ParamCustomFoo Name2/Text 2: order type minimum maximum
186	...
187	*ParamCustomFoo NameN/Text N: order type minimum maximum
188	</pre>
189
190	<p>When the base option is part of the <tt>JCLSetup</tt> section,
191	the "command" string contains JCL commands with "\order"
192	placeholders for each numbered parameter. The CUPS API handles
193	any necessary value quoting for HP-PJL commands.</p>
194
195	<p>For non-<tt>JCLSetup</tt> options, the "order" value is a
196	number from 1 to N and specifies the order of values as they are
197	placed on the stack before the command.</p>
198
fa73b229	199	<blockquote><b>Note:</b> Currently only CustomPageSize supports
	200	more than 1 parameter. This restriction is due to value encoding
	201	issues, since the "Custom.value" format does not allow for
	202	specification of named parameters. We anticipate supporting the
	203	collection value format "{Name1=foo Name2=bar}" for the final
	204	CUPS 1.2 release. In addition, the collection value format will
	205	allow string values to contain spaces.</blockquote>
	206
ef416fc2	207	<p>The "type" is one of the following keywords:</p>
	208
	209	<ul>
	210
	211	<li><tt>curve</tt> - a real value from "minimum" to
	212	"maximum" representing a gamma correction curve using the
	213	function: f(x) = x <sup>value</sup></li>
	214
	215	<li><tt>int</tt> - an integer value from "minimum" to
	216	"maximum"</li>
	217
	218	<li><tt>invcurve</tt> - a real value from "minimum" to
	219	"maximum" representing a gamma correction curve using the
	220	function: f(x) = x <sup>1 / value</sup></li>
	221
	222	<li><tt>passcode</tt> - a string of numbers value with a
	223	minimum of "minimum" numbers and a maximum of "maximum"
	224	numbers (passcode strings are not displayed in the user
	225	interface)</li>
	226
	227	<li><tt>password</tt> - a string value with a minimum of
	228	"minimum" characters and a maximum of "maximum"
	229	characters (password strings are not displayed in the
	230	user interface)</li>
	231
	232	<li><tt>points</tt> - a measurement value in points from
	233	"minimum" to "maximum"</li>
	234
	235	<li><tt>real</tt> - a real value from "minimum" to
	236	"maximum"</li>
	237
	238	<li><tt>string</tt> - a string value with a minimum of
	239	"minimum" characters and a maximum of "maximum"
	240	characters</li>
	241
	242	</ul>
	243
	244	<p>Examples:</p>
	245
	246	<pre class='command'>
	247	<em>*% Base JCL key code option</em>
	248	*OpenUI JCLPasscode/Key Code: PickOne
	249	OrderDependency: 10 JCLSetup JCLPasscode
	250	*DefaultJCLPasscode: None
	251	*JCLPasscode None/No Code: ""
	252	*JCLPasscode 1111: "@PJL SET PASSCODE = 1111<0A>"
	253	*JCLPasscode 2222: "@PJL SET PASSCODE = 2222<0A>"
	254	*JCLPasscode 3333: "@PJL SET PASSCODE = 3333<0A>"
	255	JCLCloseUI: JCLPasscode
	256
	257	<em>*% Custom JCL key code option</em>
	258	*CustomJCLPasscode True: "@PJL SET PASSCODE = \1<0A>"
	259	*ParamCustomJCLPasscode Code/Key Code: 1 passcode 4 4
	260
	261
	262	<em>*% Base PostScript gamma/density option</em>
	263	*OpenUI GammaDensity/Gamma and Density: PickOne
	264	OrderDependency: 10 AnySetup GammaDensity
	265	*DefaultGammaDensity: Normal
	266	*GammaDensity Normal/Normal: "<</cupsReal1 1.0/cupsReal2 1.0>>setpagedevice"
	267	*GammaDensity Light/Lighter: "<</cupsReal1 0.9/cupsReal2 0.67>>setpagedevice"
	268	*GammaDensity Dark/Darker: "<</cupsReal1 1.1/cupsReal2 1.5>>setpagedevice"
	269	JCLCloseUI: GammaDensity
	270
271	<em>*% Custom PostScript gamma/density option</em>
272	*CustomGammaDensity True: "<</cupsReal1 3 1 roll/cupsReal2 3 1>>setpagedevice"
273	*ParamCustomGammaDensity Gamma: 1 curve 0.1 10
274	*ParamCustomGammaDensity Density: 2 real 0 2
275	</pre>
276
277
278	<h2 class='title'><a name='PROFILES'>Color Profiles</a></h2>
279
280	<h3>cupsColorProfile</h3>
281
282	<p>This string attribute specifies a color profile of the
283	form:</p>
284
285	<pre class='command'>
286	*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
287	</pre>
288
289	<p>The <i>Resolution</i> and <i>MediaType</i> values may be "-"
290	to act as a wildcard. Otherwise they must match one of the
291	<tt>Resolution</tt> or <tt>MediaType</tt> attributes defined in
292	the PPD file.</p>
293
294	<p>The <i>density</i> and <i>gamma</i> values define gamma and
295	density adjustment function such that:</p>
296
297	<pre class='command'>
298	f(x) = density * x <sup style='font-size: 100%'>gamma</sup>
299	</pre>
300
301	<p>The <i>m00</i> through <i>m22</i> values define a 3x3
302	transformation matrix for the CMY color values. The density
303	function is applied <i>after</i> the CMY transformation:</p>
304
305	<pre class='command'>
306	\| m00 m01 m02 \|
307	\| m10 m11 m12 \|
308	\| m20 m21 m22 \|
309	</pre>
310
311	<p>Examples:</p>
312
313	<pre class='command'>
314	<em>*% Specify a profile for printing at 360dpi on all media types</em>
315	*cupsColorProfile 360dpi/-: "1.0 1.5 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
316
317	<em>*% Specify a profile for printing at 720dpi on Glossy media</em>
318	*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"
319
320	<em>*% Specify a default profile for printing at all other resolutions and media types</em>
321	*cupsColorProfile -/-: "0.9 2.0 1.0 0.0 -0.2 -0.4 1.0 0.0 -0.2 0.0 1.0"
322	</pre>
323
324	<h3>cupsICCProfile</h3>
325
326	<p>This attribute specifies an ICC color profile of the
327	form:</p>
328
329	<pre class='command'>
330	*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
331	</pre>
332
333	<p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
334	<tt>Resolution</tt> keywords specify a selector for color
335	profiles. If omitted, the color profile will match any option
336	keyword for the corresponding main keyword.</p>
337
338	<p>The <tt>Description</tt> specifies human-readable text that
339	is associated with the color profile. The <tt>filename</tt>
340	portion specifies the ICC color profile to use; if the filename
341	is not absolute, it is loaded relative to the
342	<var>/usr/share/cups/profiles</var> directory.</p>
343
344	<p>Examples:</p>
345
346	<pre class='command'>
347	<em>*% Specify a profile for CMYK printing at 360dpi on all media types</em>
348	*cupsICCProfile CMYK..360dpi/360dpi CMYK: "vendor/foo-360-cmyk.icc"
349
350	<em>*% Specify a profile for RGB printing at 720dpi on Glossy media</em>
351	*cupsColorProfile RGB.Glossy.720dpi/720dpi Glossy: "vendor/foo-720-glossy-rgb.icc"
352
353	<em>*% Specify a default profile for printing at all other resolutions and media types</em>
fa73b229	354	*cupsICCProfile ../Default: "vendor/foo-default.icc"
ef416fc2	355	</pre>
	356
	357	<h4>Customizing the Profile Selection Keywords</h4>
	358
	359	<p>The <tt>ColorModel</tt>, <tt>MediaType</tt>, and
	360	<tt>Resolution</tt> keywords can be reassigned to different main
	361	keywords, allowing drivers to do color profile selection based
	362	on different parameters. The <tt>cupsICCQualifier1</tt>,
	363	<tt>cupsICCQualifier2</tt>, and <tt>cupsICCQualifier3</tt>
	364	attributes define the mapping from selector to main keyword:</p>
	365
	366	<pre class='command'>
	367	*cupsICCQualifier1: MainKeyword
	368	*cupsICCQualifier2: MainKeyword
	369	*cupsICCQualifier3: MainKeyword
	370	</pre>
	371
	372	<p>The default mapping is as follows:</p>
	373
	374	<pre class='command'>
	375	*cupsICCQualifier1: ColorModel
	376	*cupsICCQualifier2: MediaType
	377	*cupsICCQualifier3: Resolution
	378	</pre>
	379
	380
	381	<h2 class='title'><a name='I18N'>I18N Support</a></h2>
	382
	383	<p>CUPS 1.2 and higher adds support for PPD files containing multiple
	384	languages by following the following rules:</p>
	385
	386	<ol>
	387
	388	<li>The <tt>LanguageVersion</tt> is <tt>English</tt></li>
	389
	390	<li>The <tt>LanguageEncoding</tt> is <tt>ISOLatin1</tt></li>
	391
	392	<li>Main and option keywords may not exceed 34
	393	characters, which is a subset of what the Adobe PPD spec
	394	allows.</li>
	395
	396	<li>Translations are specified using a locale prefix of
	397	the form "ll" or "ll_CC." where "ll" is the 2-letter ISO
	398	language code and "CC" is the 2-letter ISO country
	399	code</li>
	400
	401	<li>Translation strings are encoded using UTF-8.</li>
	402
	403	<li>Main keywords are translated using any of the
	404	following forms:
	405	<p><tt>*ll.Translation MainKeyword/translation
	406	text: ""</tt><br />
	407	<tt>*ll_CC.Translation MainKeyword/translation
	408	text: ""</tt></p></li>
	409
	410	<li>Option keywords are translated using any of the
	411	following forms:
	412	<p><tt>*ll.MainKeyword OptionKeyword/translation
	413	text: ""</tt><br />
	414	<tt>*ll_CC.MainKeyword OptionKeyword/translation
	415	text: ""</tt></p></li>
	416
	417	</ol>
	418
419	<p>Examples:</p>
420
421
422	<pre class='command'>
423	*LanguageVersion: English
424	*LanguageEncoding: ISOLatin1
425	*ModelName: "Foobar Laser 9999"
426
427	<em>*% Localize for French and German</em>
428	*fr_FR.Translation ModelName/La Foobar Laser 9999: ""
429	*de_DE.Translation ModelName/Foobar LaserDrucken 9999: ""
430
431	...
432
433	OpenUI InputSlot/Paper Source: PickOne
434	OrderDependency: 10 AnySetup InputSlot
435	*DefaultInputSlot: Auto
436	<em>*% Localize for French and German</em>
437	*fr_FR.Translation InputSlot/Papier source: ""
438	*de_DE.Translation InputSlot/Papiereinzug: ""
439	*InputSlot Auto/Default: "<</ManualFeed false>>setpagedevice"
440	<em>*% Localize for French and German</em>
441	*fr_FR.InputSlot Auto/Par Defaut: ""
442	*de_DE.InputSlot Auto/Standard: ""
443	*InputSlot Manual/Manual Feed: "<</ManualFeed true>>setpagedevice"
444	<em>*% Localize for French and German</em>
445	*fr_FR.InputSlot Manual/Manuel mecanisme de alimentation: ""
446	*de_DE.InputSlot Manual/Manueller Einzug: ""
447	CloseUI: InputSlot
448	</pre>
449
450
451	<h2 class='title'><a name='HISTORY'>Change History</a></h2>
452
453	<h3>Changes in CUPS 1.2</h3>
454
455	<ul>
456
457	<li>Added I18N support attributes</li>
458
459	<li>Added custom option values support</li>
460
461	<li>Added <tt>cupsICCProfile</tt> attribute</li>
462
463	<li>Added <tt>cupsPortMonitor</tt> attribute</li>
464
465	<li>Removed <tt>cupsProtocol</tt> attribute</li>
466
467	</ul>
468
469	<h3>Changes in CUPS 1.1</h3>
470
471	<ul>
472
473	<li>Added <tt>cupsFlipDuplex</tt> attribute</li>
474
475	<li>Added <tt>cupsProtocol</tt> attribute</li>
476
477	</ul>
478
479	</body>
480	</html>