• 1 General
• 2 User interface text: Option, preset, choice, and tag names
• 3 Custom Options
• 4 Multi-language PPDs
• 5 Presets
• 6 Option Tagging
• 7 CUPS Options and Pre-Defined Tags
• 8 Widget Hinting
• 9 Icons for options and choices

These specifications describe extensions to PPD files as described by Adobe's PPD specifications. All extensions are compliant with Adobe's specs, so that software which does not support these extensions can still use the extended PPDs, at least providing partial functionality.

Software and facilities provided by OpenPrinting, especially the Common Printing Dialog, are intended to support these extensions wherever appropriate. They should not use other PPD extensions exclusively to achieve the same functionality.

The extensions are intended to give driver developers/printer manufacturers better possibilities to provide user interfaces for their printer drivers than Adobe's PPD specifications supply. They especially allow to have options with advanced data types, PPDs with multiple UI languages, better option categorization (tagging), quick presets, icons for options and choices, printer manufacturer logos, …

To get the best out of the Common Printing Dialog also with legacy PPDs which do not use the extensions described here, each section specifies a fallback behavior of the dialog for the case that the option definition in the PPD does not use the appropriate PPD extension. The fallbacks are clearly marked with “Fallback:” in bold. Driver developers should not create PPDs based on these fallback methods but use the proper PPD extensions. For printing dialog developers it is not required but highly recommended to implement the fallbacks.

Note: The Foomatic extensions mentioned here are planned and not implemented yet. They will be part of Foomatic 4.x. They are not directly needed for the Common Printing Dialog. They are only needed to generate PPDs with the extensions shown here with the help of Foomatic.

The space for the widgets (UI elements) in the Common Printing Dialog is rather restricted. Therefore the text labels should not get too long. Some UI elements have even fixed widths, so that too long text gets cut. And also note that for expressing something in English you usually need less characters than for expressing the same thing in any other language using Latin letters. So leave some space so that also translations would fit.

To get a feeling about possible text lengths, see the mock-ups of the dialog (dialog UI specs, Peter Sikking's blog) or try the Bazaar snapshots of the dialog under development.

As custom options we understand all kinds of user-settable printer options which cannot be represented by the option type defined in Adobe's PPD specifications. Adobe's specifications only define the option types boolean (“Boolean”) and enumerated choice (“PickOne” and “PickMany”) options. Modern printer drivers often require the user to supply data of more advanced data types like for example:

• integer numbers - for example for number of copies, watermark angle
• real numbers - interpreted linearly or exponentially, for example for color and brightness adjustments
• lengths in points - for example for margin widths
• strings - for example for user names and fax numbers
• passwords - numerical or alphanumerical

The Common Unix Printing System (CUPS) provides a set of extensions for PPD files to represent custom options. These are the extensions described in the “Custom Options” section in the CUPS specifications for PPD extensions.

• PPD files must use these extensions for all options not representable as boolean or enumerated choice.
• Options must use data types representable by standard PPD options or CUPS custom options. Other data types are not supported.

Fallback: The only alternative but now deprecated method to describe options of advanced data types in PPD files are the Foomatic keywords as described in the Foomatic documentation (See sections “Data”, “String and Password Options”, “Example for a Foomatic-generated PPD file”, and “Foomatic keywords”). It is highly recommended but not required for a printing dialog to support these keywords so that the dialog offers its full functionality with as many PPDs as possible.

Adobe's specifications only describe a method to provide user interface text in one language for PPD file (the so-called “translations”). To support several languages the printer manufacturers ship one PPD for each language they support. On CUPS-based Linux/Unix systems there is a problem. A print queue has always only one PPD file and so only one user interface language can be provided. If there are users with different user inteface languages on their client desktops, these languages are not supported for the printer options.

There is a CUPS extension for PPDs which allows several languages in one and the same PPD and so a printing dialog can select the language according to the language of the user's desktop. See section “Globalized PPD Support” in the CUPS PPD extensions.

• PPDs shall use this extension to get a completely internationalized printing dialog, including translated names for printer-specific options and choices.

Fallback: Conventional one-language PPDs should be shown in their language by the printing dialog. The dialog can provide translations for common strings in PPDs (like “PageSize”, “Resolution”, …) and this way show options or choices translated in the case of English-only PPDs or PPDs with missing translations.

The “Presets” are preselected option settings for common printing tasks (like we page, letter, photo, …). They can be used by choosing them from a drop-down menu in the printing dialog (preferably in the standard view of the main printing dialog). The presets could be named for example as “Draft”, “Normal quality document”, “High quality document”, “Photo”. Then “Draft” would for example set a low resolution and toner saving mode, “Photo” would set a high resolution, no ink/toner saving, photo paper, … So the user can quickly set several options for his printing task by one single click.

For the presets CUPS also already specifies a PPD extension:

*APPrinterPreset Document/Office Document: "*Resolution 600dpi *MediaType Plain"
*APPrinterPreset Photo/Photo: "*Resolution 1200dpi *MediaType Glossy
com.apple.print.preset.graphicsType Photo"
*End
...

The general syntax of the “*APPrinterPreset” keyword is

*APPrinterPreset <choicename>/<English UI string>: "*<option1> <value1> [*<option2> <value2> ...]
[<document type hint key> <value>"
...

with <choicename> being a unique name for the quick preset, not containing spaces, <English UI string> the text which should appear in the drop-down list if the user has an English desktop or if no translation for his desktop language is available. Between the quotes there can be any number of option settings specified by “*<option> <value>” pairs, separated by white space or line breaks (Note that Adobe's PPD specs require an “*End” line after this expression if the quoted part contains line breaks and that a single line in a PPD can never exceed 255 characters). <option> and <value> are the machine-readable option and choice names as defined in the same PPD file (or in pre-defined options like the CUPS options). In general, one puts here the same as one would use with the “-o” option of the “lp” or “lpr” command of CUPS, especially for custom options. In case of custom options the “Custom.” can be left out. Also application-specific options are allowed here, but they will be ignored if the user prints from another application (in general non-existing options should be ignored).

Note that the dialog does not only set the options listed in the definition of the presets but also sets all the other options to the current CUPS system defaults. This means that all options get a defined value when choosing a preset and a preset with empty option list does also make sense, as it is a “Set to defaults” option. But such a preset does not need to be set. If no empty preset is there, the dialog assumes one to be there, so that resetting to the defaults is always possible.

The optional “<document type hint key> <value>” pairs allow making a preset only appearing if the document to be printed is of a certain type. If it is not there, the preset will always appear in the drop-down list, if the application does not supply a document type hint, the button will also always appear. The key name cannot start with an asterisk (“*”) to not get confused with option names. The name “com.apple.print.preset.graphicsType” to specify the document type is used to be compatible with Mac OS X, for which the “*APPrinterPreset” keyword was originally introduced. This way Mac OS X clients can also show the quick presets correctly in their printing dialogs. The possible values for “com.apple.print.preset.graphicsType” are “Photo”, “Text”, and “Graphics”.

The “*APPrinterPreset” keyword has to be used once per preset, with distinct values for <choicename> and <English UI string>. The presets have to appear in the drop-down list in the same order as their “*APPrinterPreset” entries appear in the PPD file. If the dialog is called for the first time from an application (no remembered settings), the “Default Settings” preset (or the empty preset of the PPD) has to be selected.

Translations for the button texts are done as with option choices:

*de.APPrinterPreset Document/Bürodokument: ""
*de.APPrinterPreset Photo/Foto: ""
...

The general syntax is

*<language code>.APPrinterPreset <choice>/<translation>: ""
...

This follows the way translations are represented in multi-language PPDs. These translations are only allowed in CUPS-conforming multi-language PPDs. <language code> is the two-letter code of the language with an optional two-uppercase-letter country code separated by an underscore. <choice> is the same choice name as in the definition of the quick preset button with the “*APPrinterPreset” keyword. <translation> is the UTF-8-encoded translation of UI string into the given language. It should appear on the button if the user's desktop is set to the given language.

In Foomatic these keywords are generated by an option with the new “printerpreset” option type.

Clicking a button sets all options in the button's list to the given values. The options can be also set individually at any time. There will be no option appearing in dialogs not supporting this PPD extension for quick preset buttons.

The Common Printing Dialog will also have a space for a short description (around two lines) of each preset. They go into the PPD with the following keywords, one entry for each quick presety:

*APPrinterPresetDescription Document: "Office documents, like letters, business graphics, ... on
normal paper with medium resolution (600 dpi)"
*End
*de.APPrinterPresetDescription Document: "Büro-typische Dokumente, wie Briefe, Geschäftsgrafik,
... auf Normalpapier mit mittlerer Auflösung (600 dpi)"
*End

General syntax:

*APPrinterPresetDescription <choice>: "<description text>"
*<language code>.APPrinterPresetDescription <choice>: "<translated description text>"

Fallback: For legacy PPDs without special keywords for quick preset buttons the “PrintoutMode” option should be considered as the quick presets, as this one does exactly this task in Foomatic PPDs.

So a PPD file without “*APPrinterPreset” keywords and with “PrintoutMode” option should behave as it had the following lines (one line for each choice of “PrintoutMode”):

*APPrinterPreset Draft/Draft: "*PrintoutMode Draft"
*APPrinterPreset Normal/Normal Quality: "*PrintoutMode Normal"
*APPrinterPreset High/High Quality: "*PrintoutMode High"
*APPrinterPreset Photo/Photo: "*PrintoutMode Photo"

The UI strings of the choices are taken from the choices of the “PrintoutMode” option.

If there is no “PrintoutMode” option, it should be looked for a “Quality” option and then for any option having a name ending with “Quality” and after that for any option whose name contains “Quality”.

As a last mean standard options for the printout quality are set:

If there are presets but no description texts for them defined in the PPD, generate the description text from the settings. So the description text for our example of an office document setting in the beginning should be

Resolution: 600 dpi, Media Type: Plain Paper

Here the option settings are listed as

<option1>: <value1>, <option2>: <value2>

where the strings are the UI strings (or the translations if the UI is not English) from the PPD file. This fallback should also be used if there are no presets defined at all in the PPD and the presets are generated via one of the fallbacks described above.

Adobe's specifications offer as the only way to categorize options so that they can be presented in a by-task order are the groups. An option can be in one group or in none of the groups. Groups can be freely defined.

Problem of this concept is that options often fit in more than one group. For example “Duplex” can be in both “Paper handling” and “Resource saving” and some users search for it in the former, others in the latter. So a printing dialog should better show the option in both categories. To represent this in the PPDs toeach option one or more so-called tags are added telling into which category the option belongs. Each category is represented by one tag.

In the OpenUsability printing dialog there is a list of all tags for which there is at least one option available. Each tag can be activated or deactivated by the user. Options will be shown if at least one of their tags is activated. For example the “Duplex” option can have a “Paper Handling” and “Resource Saving” tag. If either of these is selected, the option will be shown.

In PPD tags have to be defined as follows:

*OPOptionTag ResourceSaving/Resource Saving: "*Duplex *Economode *number-up"
*de.OPOptionTag ResourceSaving/Resourcen sparen: ""
...

The second line shows how to provide translations for their human-readable texts.

The general syntax looks like this:

*OPOptionTag <name>/<English UI string>: "*<option1> [*<option2> ...]"
*<language code>.OPOptionTag <name>/<translation>: ""
...

<name> is here the name of the tag, a string without spaces, <English UI string> is how the tag name should be shown in the dialog on English desktops or if no translation into the user's UI language is available. <option1>, <option2>, etc. are the main keyword (option names) of the options which should appear under this tag. One option can be listed under more than one tag. In the quotes there can be listed every arbitrary number of option names, separated by white space or line breaks (Note that the Adobe's PPD specs require an “*End” line after this expression if the quoted part contains line breaks and that a single line in a PPD can never exceed 255 characters).

<name> can also be an already pre-defined tag (from the CUPS options). Then the listed options get added to the tag. In this case <English UI string> and the translations are not required, but if they are there they have priority against the original data.

The translation lines are again like in multi-language PPDs (and only allowed in such PPDs). <language code> is the two-letter language code with optional two-uppercase-letter country code, <name> must match the name in tag definition and <translation> is the UTF-8-encoded UI string for this language.

*OPCancelTags: "<tag1> [<tag2> ...]"

cancels the listed tags. This means that these tags will not appear in the tag list of the Common Printing Dialog. This way pre-defined tags can be removed to make space for the PPD's own tags, as the total number of slots in the tag list is limited to 11. Note that if options are only tagged with tags which you cancel they get unavailable. This can make sense if you replace a CUPS option by your own implementation and want to prevent users from using the original CUPS option.

To make Foomatic generate PPDs with the shown keywords for option tagging a construction like this will be added to the driver XML files (into the “<execution>…</execution>” section):

<tags>
   <tag id="PaperHandling">
      <longname>
         <en>Paper Handling</en>
         <de>Papierhandhabung</de>
      </longname>
      <options>
         <option>Duplex</option>
         <option>InputSlot</option>
      </options>
   </tag>
   <tag id="ResourceSaving">
      <longname>
         <en>Resource Saving</en>
         <de>Resourcen sparen</de>
      </longname>
      <options>
         <option>Duplex</option>
         <option>Economode</option>
         <option>number-up</option>
      </options>
   </tag>
   <tag id="ColourAdjustment">
      <canceled />
   </tag>
</tags>

General syntax:

<tags>
   <tag id="[name]">
      <longname>
         <en>[English UI string]</en>
         <[language code]>[translation]</[language code]>
         ...
      </longname>
      <options>
         <option>[option1]</option>
         ...
      </options>
   </tag>
   ...
   <tag id="[name]">
      <canceled />
   </tag>
   ...
</tags>

[name], [English UI string], [language code], [translation], and [option1] have the same meaning as the appropriate items in the PPD file as shown above. The lines with the English UI string are required for new tags, for adding options to pre-defined tags or for canceling tags the <longname> section can be left out. There can be more than one tag for one driver, but it should not result in having more than 11 tags with the pre-defined ones. Each tag cabn have any number of options and translations.

Note: The total number of tags for one PPD file must never be higher than 11, as more tags do not fit into tag list of the Common Printing Dialog. This includes also the tags already provided by default for the CUPS options (as long as the PPD file does not cancel these tags or CUPS options).

Fallback: As a fallback for legacy PPDs without tagging the option groups are used as the tags. This means that an option cannot appear under more than one tag, but this is the best approach to handle the options in such a PPD. If a PPD contains options with neither group nor tags, these options go under the “General” tag.

If there are more than 11 tags, independent whether the PPD has tag definitions or whether option groups are used as tags, then the first 10 tags appearing in the PPD are used for the dialog and the options under the remaining tags will be put under a tag named “OtherOptions”.

CUPS does not only pass a print job through a printer driver and to the printer, controlled with options defined by the developers of the printer driver (or of the printer). CUPS has also several filters which can do useful things with the print jobs. Once filters to convert most printable standard file formats to PostScript or PDF, and second, filters which can modify the job, like printing only selected pages, even/odd pages (manual duplex), 2, 4, 8, ,,, pages per sheet, gamma-corrected, … To control these features, CUPS introduces several options as part of its IPP extension.

These options are supposed to be shown by the printing dialog, too. This means that they get also tagged and therefore we have pre-defined tags as listed below. As there is only a total of 11 tags allowed for one printer, these tags have to be taken into account. Printer-specific options in the PPDs can be tagged with these tags, too. Or if a manufacturer/driver developer does not like these tags, he can cancel them in the PPD. But careful, when canceling tags options can disappear. Re-tag them to your own tags if you want to keep them.

You can also eliminate the CUPS options by canceling them directly, for example if your driver contains a more sophisticated implementation of one or another of these options. Use

*OPCancelOptions: "<option1> [<option2> ...]"

to do so.

Here is a list of all CUPS options and their pre-defined tags (options taken from the CUPS IPP specifications, Job Template Attributes):

• blackplot: HPGL2
• columns: PageLayout, Text
• cpi: Text
• fitplot: PageManagement, PageLayout
• job-billing: JobControl
• job-hold-until: JobControl
• job-sheets: JobControl
• lpi: Text
• mirror: PageManagement
• natural-scaling: PageLayout, Image
• number-up: PageManagement, PageLayout, ResourceSaving
• number-up-layout: PageManagement, PageLayout, ResourceSaving
• page-border: PageManagement, PageLayout
• page-bottom: PageLayout, Text
• page-label: PageManagement, JobControl
• page-left: PageLayout, Text
• page-ranges: PageManagement, ResourceSaving
• page-right: PageLayout, Text
• page-set: PageManagement, ResourceSaving
• page-top: PageLayout, Text
• penwidth: HPGL2
• position: PageLayout, Image
• ppi: Image
• prettyprint: Text
• scaling: PageLayout, Image
• wrap: Text

Note: The options which have the tags “Text”, “Image”, and “HPGL” do not make sense for PostScript or PDF input files. They should only be shown in the dialog if appropriate files are printed.

There are many ways for a dialog to visualize an option of a specific type. For example, a numeric option might be shown as a slider, a spinbox, or even a combination of the two. Many applications also allow the user to choose the unit in which he specifies the option value (see the gimp for example).

Therefore, it would be nice if the dialog could get some more information about an option. Since this information is purely aesthetic and not compulsory, we allow the creator of the PPD file to add any number of hints to an option.

Hints about the data type:

• “faxnumber” - for string options representing a fax number. Add a button which opens the user's/desktop's address book so that the user can fill in the field by choosing an entryu there.
• “font” - for string options representing a font, in X naming scheme (gedit has font options)
• “color” - for integer options representing RGBA color values
• “open-file” - for string options, dialog can supply file chooser (“Open” dialog)
• “save-as-file” - for string options, dialog can supply file chooser (“Save as” dialog)
• “resolution” - for real or integer values representing a resolution in dpi or ppi, the dialog might offer different units (dots/inch, dots/cm, …) and automatically convert
• “length” - a length in PostScript points, a dialog might offer different units (inch, points, cm, mm, …) and automatically convert
• “date” - string value representing a date, dialog can show a calendar
• “time” - string value representing a time
• “datetime” - string value representing date and time

Hints about widgets:

• “spinbox” - Spin box (numerical values)
• “slider” - Slider (numerical)
• “input” - Input field (string, password, numerical)
• “radiobuttons” - Radio buttons (enumerated choice, boolean)
• “dropdown” - Drop-down list (enumerated choice, boolean)
• “checkbox” - Check box (boolean)
• “history” - Drop-down history list for input field (like at the URL field of Firefox)
• “nohistory” - Suppress drop-down history list for input field
• “optionicononly”, “optionicontext”: If the option has an icon, these hints tell whether only the icon or the icon with the UI string of the option should be shown as the option label. To be ignored if the option has no icon.
• “choicesicononly”, “choicesicontext”: If ALL choices of the option have an icon, these hints tell whether the choices should be shown only as icons (then they have no radio buttons and no drop-down box, the selected choice icon is highlighted) or as text with icons (small icon at the left of the text in drop-down or at radio buttons). To be ignored if there are choices without icon.
• “hide” - Do not show this option. This is for options which only make sense in traditional PPD-based printing dialogs but are not needed in the Common Printing Dialog.
• “donthide1choice” - Do not hide the option if it has only one available choice (all but one choice excluded by options in “Installable Options” group, for enumerated and boolean, Minimum = Maximum for numerical options). Default is to not show options with only one choice.

In the PPD file any number of hints is assigned to an option via:

*OPOptionHints <option name>: "<hint1> [<hint2> ...]"

If there are more than one hints, all should be taken into account. The line

*OPOptionHints Gamma: "slider input spinbox history"

should show a slider with an input field at one end and the spin arrows at the right of the input field. In addition, the input field should have a history list.

For data type hints the dialog should show widgets most appropriate for the given data type. For example a length which the driver expects in PostScript points there should appear an input field (and an optional slider) and at the right of the input field a drop-down list for units. The dialog should convert the point value to the selected unit and it should convert it back to points when submitting the data.

A dialog implementation may choose to ignore those hints.

Fallback: The dialog implementation decides on which widgets are used for the options. It can take into account common option or choice names for that.

This extension gives the possibility to add an icon to every human-readable text item in the dialog: option names, choice names, tag names. …

Adding icons and pictures to the PPD file is optional. The dialog should simply show no icon or a standard icon in the case that the PPD does not provide an icon for a given item.

To not need to invent too many new keywords, there are simply added “translations” with the language code “OPIcon” for option choices and they have the base-64-UU-encoded icon, either a 64×64 PNG image or an SVG drawing as its code:

*OPIcon.InputSlot Auto: "begin-base64 644 InputSlot-Auto.png
iVBORw0KGgoAAAANSUhEUgAAAOAAAAC6CAMAAACA5rFCAAADAFBMVEX/////
/8z/zP//zMz/zGb/zDP/zAD/mWb/mTP/mQD/Zmb/MzPM///M/8zM/zPMzP/M
zMzMzJnMzGbMzDPMzADMmf/MmczMmZnMmWbMmTPMmQDMZjPMZgCZzP+ZzMyZ
...
4SfnV38C83lfZ0FU5/N58n1aZI2z2fxfwOTVfkPrH2h/Luv33J7bc3tuz+25
Pbfn9tye25+5/T9t163O+/ghTQAAAABJRU5ErkJggg==
===="
*End

General syntax:

*OPIcon.<option> <value>: "<Paste uuencode output here>"
*End

For main keywords the following is used:

*OPIcon InputSlot: "begin-base64 644 InputSlot.png
iVBORw0KGgoAAAANSUhEUgAAAOAAAAC6CAMAAACA5rFCAAADAFBMVEX/////
..."
*End

General syntax:

*OPIcon <main keyword>: "<Paste uuencode output here>"
*End

And this is for the option tags:

*OPIcon.OPOptionTag ResourceSaving: "begin-base64 644 ResourceSaving.svg
..."
*End

General syntax:

*OPIcon.OPOptionTag <tag name>: "<Paste uuencode output here>"
*End

For a manufacturer-specific picture (logo or so) '*OPIcon Manufacturer: “…”' is used and for a model-specific picture (image of the printer or so) '*OPIcon ModelName: “…”'. Note that here the literal main keywords “Manufacturer” and “ModelName” are meant, not the actual make and model names of the printer described by the PPD.

All icons and images should have a transparent background, so that they fit to all desktop themes. The manufacturer image goes into the upper right corner of the dialog and the model image to the upper edge of the dialog, directly to the left of the manufacturer image (or into the upper right corner if there is no manufacturer image). The images are placed at the edges of the dialog without any margins and without space between each other. If they should appear with margins and/or space between each other, the transparent background should be somewhat bigger than the picture itself.

Fallback: The dialog implementation can add its own icons to common option and choice names if the PPD does not define an icon. Icons defined by the PPD must always have priority.