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 [RFC5234] defines the general format of lines in a PPD file:
@@ -469,11 +585,12 @@ LINE-END = CR / LF / CR LF
CUPS supports several methods of auto-configuration via PPD keywords.
-
+
+
*APAutoSetupTool: "/LibraryPrinters/vendor/filename"
-
This Mac OS X keyword defines a program that sets the default option choices. It is run when a printer is added from the Add Printer window or the Nearby Printers list in the Print dialog.
+
This macOS keyword defines a program that sets the default option choices. It is run when a printer is added from the Add Printer window or the Nearby Printers list in the Print dialog.
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.
@@ -484,7 +601,8 @@ LINE-END = CR / LF / CR LF
*APAutoSetupTool: "/Library/Printers/vendor/Tools/autosetuptool"
-
+
+
*?MainKeyword: "
PostScript query code that writes a message using the = operator...
@@ -513,7 +631,8 @@ LINE-END = CR / LF / CR LF
*CloseUI: OptionDuplex
-
+
+
*?OIDMainKeyword: ".n.n.n..."
*OIDMainKeyword OptionKeyword1: "value"
@@ -536,7 +655,7 @@ LINE-END = CR / LF / CR LF
-
CUPS supports three types of color profiles. The first type is based on sRGB and is used by the standard CUPS raster filters and GPL 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.
+
CUPS supports three types of color profiles. The first type is based on sRGB and is used by the standard CUPS raster filters and GPL Ghostscript. The second type is based on ICC profiles and is used by the Quartz-based filters on macOS. The final type is based on well-known colorspaces such as sRGB and Adobe RGB.
Note:
@@ -544,11 +663,12 @@ LINE-END = CR / LF / CR LF
-
+
+
*cupsColorProfile Resolution/MediaType: "density gamma m00 m01 m02 m10 m11 m12 m20 m21 m22"
-
This string keyword specifies an sRGB-based color profile consisting of gamma and density controls and a 3x3 CMY color transform matrix. This keyword is not supported on Mac OS X.
+
This string keyword specifies an sRGB-based color profile consisting of gamma and density controls and a 3x3 CMY color transform matrix. This keyword is not supported on macOS.
The Resolution and MediaType values may be "-" to act as a wildcard. Otherwise they must match one of the Resolution or MediaType option keywords defined in the PPD file.
@@ -581,7 +701,7 @@ f(x) = density * x
gamma
-
+
*cupsICCProfile ColorModel.MediaType.Resolution/Description: "filename"
@@ -602,11 +722,12 @@ f(x) = density * x
gamma
*cupsICCProfile ../Default: "/Library/Printers/vendor/Profiles/foo-default.icc"
-
Customizing the Profile Selection Keywords
+
Customizing the Profile Selection Keywords
-
The MediaType and Resolution main keywords can be reassigned to different main keywords, allowing drivers to do color profile selection based on different parameters. The cupsICCQualifier2 and cupsICCQualifier3 keywords define the mapping from selector to main keyword:
+
The ColorModel, MediaType, and Resolution main keywords can be reassigned to different main keywords, allowing drivers to do color profile selection based on different parameters. The cupsICCQualifier1, cupsICCQualifier2, and cupsICCQualifier3 keywords define the mapping from selector to main keyword:
+*cupsICCQualifier1: MainKeyword1
*cupsICCQualifier2: MainKeyword2
*cupsICCQualifier3: MainKeyword3
@@ -614,26 +735,28 @@ f(x) = density * x
gamma
The default mapping is as follows:
+*cupsICCQualifier1: ColorModel
*cupsICCQualifier2: MediaType
*cupsICCQualifier3: Resolution
-
+
+
*APSupportsCustomColorMatching: true
*APCustomColorMatchingName name/text: ""
*APCustomColorMatchingProfile: profile
*APDefaultCustomColorMatchingProfile: profile
-
These keywords 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 APCustomColorMatchingProfile and APDefaultColorMatchingProfile keywords specify alternate color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.
+
These keywords tell the macOS 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 APCustomColorMatchingProfile and APDefaultColorMatchingProfile keywords specify alternate color profiles (sRGB or AdobeRGB) to use for 3-color (RGB) raster data.
Note:
-Prior to Mac OS X 10.6, the default RGB color space was Apple's "GenericRGB". The new default in Mac OS X 10.6 and later is "sRGB". For more information, see "Mac OS X v10.6: About gamma 2.2" on Apple's support site.
+Prior to macOS 10.6, the default RGB color space was Apple's "GenericRGB". The new default in macOS 10.6 and later is "sRGB". For more information, see "macOS v10.6: About gamma 2.2" on Apple's support site.
-
+
*APCustomColorMatchingName name/text: ""
@@ -647,7 +770,7 @@ f(x) = density * x
gamma
*fr.APCustomColorMatchingName name/La AcmeColor(tm): ""
-
+
*APCustomColorMatchingProfile: name
@@ -669,7 +792,7 @@ f(x) = density * x
gamma
*APCustomColorMatchingProfile: AdobeRGB
-
+
*APDefaultCustomColorMatchingProfile: name
@@ -683,7 +806,7 @@ f(x) = density * x
gamma
*APDefaultCustomColorMatchingProfile: sRGB
-
+
*APSupportsCustomColorMatching: boolean
@@ -719,7 +842,8 @@ f(x) = density * x
gamma
-
+
+
*cupsUIConstraints resolver: "*Keyword1 *Keyword2 ..."
*cupsUIConstraints resolver: "*Keyword1 OptionKeyword1 *Keyword2 ..."
@@ -749,7 +873,8 @@ f(x) = density * x gamma
*cupsUIConstraints photo: "*OutputMode Photo *MediaType Transparency *Resolution 1200dpi"
-
+
+
*cupsUIResolver resolver: "*Keyword1 OptionKeyword1 *Keyword2 OptionKeyword2 ..."
@@ -851,7 +976,7 @@ f(x) = density * x
gamma
-
+
CUPS supports custom options using an extension of the CustomPageSize and ParamCustomPageSize syntax:
@@ -966,7 +1091,8 @@ option value is "1234" then CUPS will output the string "@PJL SET PASSCODE=1234"
The resulting dictionary sets the page device attributes that are sent to your raster driver in the page header.
-
Custom Page Size Code
+
+
Custom Page Size Code
There are many possible implementations of the CustomPageSize code. For CUPS raster drivers, the following code is recommended:
@@ -979,7 +1105,8 @@ option value is "1234" then CUPS will output the string "@PJL SET PASSCODE=1234"
*CustomPageSize True: "pop pop pop <</PageSize[5 -2 roll]/ImagingBBox null>>setpagedevice"
-
Supported PostScript Operators
+
+
Supported PostScript Operators
CUPS supports the following PostScript operators in addition to the usual PostScript number, string (literal and hex-encoded), boolean, null, and name values:
@@ -1038,7 +1165,8 @@ PRE B {
-
Supported Page Device Attributes
+
+
Supported Page Device Attributes
Table 2 shows the supported page device attributes along with PostScript code examples.
@@ -1309,7 +1437,8 @@ PRE B {
The CUPS media keywords allow drivers to specify alternate custom page
size limits based on up to two options.
-
+
+
*cupsMediaQualifier2: MainKeyword
@@ -1328,7 +1457,8 @@ custom page size limits.
*cupsMinSize ..Photo: "300 300"
-
+
+
*cupsMediaQualifier3: MainKeyword
@@ -1347,7 +1477,8 @@ custom page size limits.
*cupsMinSize ..Photo: "300 300"
-
+
+
*cupsMinSize .Qualifier2.Qualifier3: "width length"
*cupsMinSize .Qualifier2.: "width length"
@@ -1370,7 +1501,8 @@ are used to identify options to use for matching.
*cupsMinSize ..Photo: "300 300"
-
+
+
*cupsMaxSize .Qualifier2.Qualifier3: "width length"
*cupsMaxSize .Qualifier2.: "width length"
@@ -1394,9 +1526,24 @@ are used to identify options to use for matching.
+
+
+
*cupsPageSizeCategory name/text: "name name2 ... nameN"
+
+
This keyword lists related paper size names that should be grouped together in the Print or Page Setup dialogs. The "name" portion of the keyword specifies the root/default size for the grouping. On macOS the grouped paper sizes are shown in a submenu of the main paper size. When omitted, sizes with the same dimensions are automatically grouped together, for example "Letter" and "Letter.Borderless".
+
+
Example:
+
+
+*% Specify grouping of borderless/non-borderless sizes
+*cupsPageSizeCategory Letter/US Letter: "Letter Letter.Borderless"
+*cupsPageSizeCategory A4/A4: "A4 A4.Borderless"
+
+
+
-
+
*cupsBackSide: keyword
@@ -1472,7 +1619,7 @@ will be ignored.
-
Figure 1: Back side images
@@ -1492,7 +1639,8 @@ will be ignored.
Also see the related APDuplexRequiresFlippedMargin
keyword.
-
+
+
*cupsCommands: "name name2 ... nameN"
@@ -1508,7 +1656,7 @@ by whitespace.
-
+
*cupsEvenDuplex: boolean
@@ -1523,7 +1671,8 @@ printing is selected. The default value is false.
*cupsEvenDuplex: true
-
+
+
*cupsFax: boolean
@@ -1535,7 +1684,8 @@ printing is selected. The default value is false.
*cupsFax: true
-
+
+
*cupsFilter: "source/type cost program"
@@ -1557,12 +1707,19 @@ the special filter program "-" may be specified.
*cupsFilter: "application/vnd.cups-postscript 0 -"
-
+
+
*cupsFilter2: "source/type destination/type cost program"
This string keyword 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. The destination type is automatically created as needed and is passed to the filters and backend as the FINAL_CONTENT_TYPE value.
+Note:
+
+The presence of a single cupsFilter2 keyword in the PPD file will hide any cupsFilter keywords from the CUPS scheduler. When using cupsFilter2 to provide filters specific for CUPS 1.5 and later, provide a cupsFilter2 line for every filter and a cupsFilter line for each filter that is compatible with older versions of CUPS.
+
+
+
Examples:
@@ -1576,25 +1733,45 @@ the special filter program "-" may be specified.
*cupsFilter2: "application/vnd.cups-postscript application/postscript 0 -"
-
+
+
+
+*cupsFinishingTemplate name/text: ""
+
+This option keyword specifies a finishing template (preset) that applies zero or more finishing processes to a job. Unlike cupsIPPFinishings, only one template can be selected by the user. PPD files also generally apply a constraint between this option and other finishing options like Booklet, FoldType, PunchMedia, and StapleWhen.
+
+Examples:
+
+
+*cupsFinishingTemplate none/None: ""
+*cupsFinishingTemplate fold/Letter Fold: ""
+*cupsFinishingTemplate punch/2/3-Hole Punch: ""
+*cupsFinishingTemplate staple/Corner Staple: ""
+*cupsFinishingTemplate staple-dual/Double Staple: ""
+*cupsFinishingTemplate staple-and-fold/Corner Staple and Letter Fold: ""
+*cupsFinishingTemplate staple-and-punch/Corner Staple and 2/3-Hole Punch: ""
+
+
+
+
*cupsFlipDuplex: boolean
-Due to implementation differences between Mac OS X and Ghostscript,
+
Due to implementation differences between macOS and Ghostscript,
the cupsFlipDuplex keyword is deprecated. Instead, use
the cupsBackSide keyword to specify
the coordinate system (pixel layout) of the page data on the back side of
duplex pages.
The value true maps to a cupsBackSide value
-of Rotated on Mac OS X and Flipped with
+of Rotated on macOS and Flipped with
Ghostscript.
The default value is false.
Note:
-Mac OS X drivers that previously used
+
macOS drivers that previously used
cupsFlipDuplex may wish to provide both the old and
new keywords for maximum compatibility, for example:
@@ -1611,7 +1788,8 @@ Ghostscript can use:
*cupsFlipDuplex: true
-
+
+
*cupsIPPFinishings number/text: "*Option Choice ..."
@@ -1627,7 +1805,8 @@ values to PPD options and choices.
*cupsIPPFinishings 21/staple-bottom-left: "*StapleLocation SingleLandscape"
-
+
+
*cupsIPPReason reason/Reason Text: "optional URIs"
@@ -1641,11 +1820,7 @@ scheduler's DocumentRoot directory, a full HTTP URL
valid URI which directs the user at additional information
concerning the condition that is being reported.
-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 text URIs are
-combined (with spaces between each URI) by the ppdLocalizeIPPReason
-into a single string that can be displayed to the user.
+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 text URIs are combined by the ppdLocalizeIPPReason into a single string that can be displayed to the user.
Examples:
@@ -1671,7 +1846,8 @@ http://www.vendor.com/help"
*End
-
+
+
*cupsIPPSupplies: boolean
@@ -1684,7 +1860,63 @@ http://www.vendor.com/help"
*cupsIPPSupplies: False
-
+
+
+
+*cupsJobAccountId: boolean
+
+This keyword defines whether the printer accepts the job-account-id IPP attribute.
+
+Example:
+
+
+*% Specify the printer accepts the job-account-id IPP attribute.
+*cupsJobAccountId: True
+
+
+
+
+
+*cupsJobAccountingUserId: boolean
+
+This keyword defines whether the printer accepts the job-accounting-user-id IPP attribute.
+
+Example:
+
+
+*% Specify the printer accepts the job-accounting-user-id IPP attribute.
+*cupsJobAccountingUserId: True
+
+
+
+
+
+*cupsJobPassword: "format"
+
+This keyword defines the format of the "job-password" IPP attribute, if supported by the printer. The following format characters are supported:
+
+
+ 1: US ASCII digits.A: US ASCII letters.C: US ASCII letters, numbers, and punctuation..: Any US ASCII printable character (0x20 to 0x7e).N: Any Unicode digit character.U: Any Unicode letter character.*: Any Unicode (utf-8) character.
+
+The format characters are repeated to indicate the length of the
+password string. For example, "1111" indicated a 4-digit US ASCII PIN code.
+
+Example:
+
+
+*% Specify the printer supports 4-digit PIN codes.
+*cupsJobPassword: "1111"
+
+
+
+
*cupsLanguages: "locale list"
@@ -1695,11 +1927,26 @@ list of locale names ("en", "en_US", "fr_CA", etc.)
Example:
-*% Specify Canadian, UK, and US English, and Candian and French French
+*% Specify Canadian, UK, and US English, and Canadian and French French
*cupsLanguages: "en_CA en_UK en_US fr_CA fr_FR"
-
+
+
+
+*cupsMandatory: "attribute1 attribute2 ... attributeN"
+
+This keyword defines a list of IPP attributes that must be provided when submitting a print job creation request.
+
+Example:
+
+
+*% Specify that the user must supply a job-password
+*cupsMandatory: "job-password job-password-encryption"
+
+
+
+
*cupsManualCopies: boolean
@@ -1714,7 +1961,8 @@ hardware. The default value is false.
*cupsManualCopies: true
-
+
+
*cupsMarkerName/Name Text: ""
@@ -1728,7 +1976,8 @@ generated by the driver to human readable text.
*cupsMarkerName cyanToner/Cyan Toner: ""
-
+
+
*cupsMarkerNotice: "disclaimer text"
@@ -1742,7 +1991,22 @@ are approximate".
*cupsMarkerNotice: "Supply levels are approximate."
-
+
+
+
+*cupsMaxCopies: integer
+
+This integer keyword notifies the filters that the destination printer supports up to N copies in hardware. The default value is 9999.
+
+Example:
+
+
+*% Tell the RIP filters we can do up to 99 copies
+*cupsMaxCopies: 99
+
+
+
+
*cupsModelNumber: number
@@ -1757,7 +2021,8 @@ the output for a specific model of printer.
*cupsModelNumber: 1234
-
+
+
*cupsPJLCharset: "ISO character set name"
@@ -1772,7 +2037,8 @@ assumed.
*cupsPJLCharset: "UTF-8"
-
+
+
*cupsPJLDisplay: "what"
@@ -1791,7 +2057,8 @@ to use "@PJL RDYMSG DISPLAY". The default is "job".
*cupsPJLDisplay: "none"
-
+
+
*cupsPortMonitor urischeme/Descriptive Text: "port monitor"
@@ -1823,7 +2090,8 @@ to disable the port monitor for the given URI scheme.
*cupsPortMonitor usb/USB Status Monitor: "epson-usb"
-
+
+
*cupsPreFilter: "source/type cost program"
@@ -1842,7 +2110,7 @@ before the filter that accepts the given MIME type.
-
+
*cupsPrintQuality keyword/text: "code"
@@ -1866,7 +2134,8 @@ before the filter that accepts the given MIME type.
*CloseUI: *cupsPrintQuality
-
+
+
*cupsSingleFile: Boolean
@@ -1882,7 +2151,8 @@ before the filter that accepts the given MIME type.
*cupsSingleFile: True
-
+
+
*cupsSNMPSupplies: boolean
@@ -1897,13 +2167,14 @@ the standard SNMP Printer MIB OIDs for supply levels. The default value is
*cupsSNMPSupplies: False
-
+
+
*cupsVersion: major.minor
This required keyword 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".
+"1.0", "1.1", "1.2", "1.3", "1.4", "1.5", or "1.6".
Example:
@@ -1913,9 +2184,23 @@ PPD file extensions was used. Currently it must be the string
-
+
+
+*JCLToPDFInterpreter: "JCL"
+
+This keyword provides the JCL command to insert a PDF job file into a printer-ready data stream. The JCL command is added after the JCLBegin value and any commands for JCL options in the PPD file.
+
+Example:
+
+
+*% PJL command to start the PDF interpreter
+*JCLToPDFInterpreter: "@PJL ENTER LANGUAGE = PDF<0A>"
+
+
+
+
-
+
*APDialogExtension: "/Library/Printers/vendor/filename.plugin"
@@ -1927,9 +2212,13 @@ plug-ins.
Note:
-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.
+Since 2010, AirPrint has enabled the printing of full quality photos and
+documents from the Mac without requiring driver software. Starting with macOS
+10.12, system level security features prevent print dialog plug-ins from being
+loaded into applications that have enabled the library validation security
+feature. As of macOS 10.14 the APDialogExtension attribute used to
+create macOS print drivers is deprecated. All new printer models should support
+AirPrint moving forward.
@@ -1941,7 +2230,8 @@ in order to be usable with all applications.
*APDialogExtension: "/Library/Printers/vendor/options.plugin"
-
+
+
*APDuplexRequiresFlippedMargin: boolean
@@ -2023,7 +2313,8 @@ and the Tumble page attribute.
Also see the related cupsBackSide
keyword.
-
+
+
*APHelpBook: "bundle URL"
@@ -2038,7 +2329,8 @@ looking up IPP reason codes for this printer driver. The
*APHelpBook: "file:///Library/Printers/vendor/Help.bundle"
-
+
+
*APICADriver: boolean
@@ -2052,7 +2344,8 @@ Architecture (ICA) driver for scanning. The default is False.
*APScanAppBundleID: "com.apple.ImageCaptureApp"
-
+
+
*APPrinterIconPath: "/Library/Printers/vendor/filename.icns"
@@ -2066,7 +2359,8 @@ displaying the printer. The file must be in the Apple icon format.
*APPrinterIconPath: "/Library/Printers/vendor/Icons/filename.icns"
-
+
+
*APPrinterLowInkTool: "/Library/Printers/vendor/program"
@@ -2083,7 +2377,8 @@ Technical Note TN2144 for more information.
*APPrinterLowInkTool: "/Library/Printers/vendor/Tools/lowinktool"
-
+
+
*APPrinterPreset name/text: "*Option Choice ..."
@@ -2153,7 +2448,8 @@ choice (*MainKeyword OptionKeyword) or a preset identifier and value
*fr.APPrinterPreset Photo_on_Photo_Paper/Photo sur papier photographique: ""
-
+
+
*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/filename.app"
@@ -2168,7 +2464,8 @@ information.
*APPrinterPrinterUtilityPath: "/Library/Printers/vendor/Tools/utility.app"
-
+
+
*APScannerOnly: boolean
@@ -2182,7 +2479,8 @@ capabilities. The default is False.
*APScannerOnly: True
-
+
+
*APScanAppBundleID: "bundle ID"
@@ -2199,7 +2497,43 @@ the device.
-Changes in CUPS 1.5
+Changes in CUPS 2.3
+
+
+
+
+Changes in CUPS 1.7
+
+
+
+
+Changes in CUPS 1.6
+
+
+
+
+Changes in CUPS 1.5
@@ -2208,7 +2542,7 @@ the device.
-Changes in CUPS 1.4.5
+Changes in CUPS 1.4.5
@@ -2219,7 +2553,7 @@ the device.
-Changes in CUPS 1.4
+Changes in CUPS 1.4
@@ -2254,11 +2588,11 @@ the device.
-Changes in CUPS 1.3.1
+Changes in CUPS 1.3.1
- - Added missing Mac OS X AP keywords.
+ - Added missing macOS AP keywords.
- Added section on auto-configuration including the
OIDMainKeyword and ?MainKeyword
@@ -2269,7 +2603,7 @@ the device.
-Changes in CUPS 1.3
+Changes in CUPS 1.3
@@ -2288,7 +2622,8 @@ the device.
-Changes in CUPS 1.2.8
+
+Changes in CUPS 1.2.8
@@ -2297,7 +2632,8 @@ the device.
-Changes in CUPS 1.2
+
+Changes in CUPS 1.2
@@ -2322,7 +2658,8 @@ the device.
-Changes in CUPS 1.1
+
+Changes in CUPS 1.1
@@ -2331,6 +2668,6 @@ the device.
- Added cupsProtocol keyword
-
-
+
+