.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _app-ppd-ext: .. figure:: ../images/manual/savapage-logo-no-text-100px.png :width: 75px PPD Extensions ============== .. admonition:: |ADMONITION_TABLE_OF_CONTENTS| - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` Vendor specific PPD option keywords are generally not mapped to IPP attributes by CUPS. That's why we do not get IPP attributes for finishings (staple, punch, fold, booklet) or collating delivered, when we ask CUPS for an IPP printer description. To bridge this gap we built our own mapping by means of a so-called PPD Extension ``.ppde`` file. With this mapping we are able to identify printer capabilities based on IPP and feed CUPS the vendor specific PPD options as IPP attributes when sending a print job. When printing, these IPP disguised PPD options are neatly applied by CUPS in the context of the PPD driver, so the right PostScript / PCL snippets are injected in the spool file. PPD Extension files reside in the ``/opt/savapage/server/custom/cups/`` directory. An annotated ``type-model-version.ppde.template`` file is installed there for your convenience. The ``.ppde`` file can be linked to a |PROXYPRINTER|. See :ref:`Edit Proxy Printer `. When linked, the mapped PPD options will appear in the :ref:`Printer Settings Dialog `. .. important:: When the content of a PPD Extension File, assigned to any Proxy Printer, is changed, you must :ref:`Synchronize ` the Proxy Printers to take those changes into effect. .. warning:: PPD Extensions is an advanced feature. Consult your :ref:`SavaPage Service Provider ` before implementing. .. _app-ppd-ext-mapping-ipp: PPD to IPP Mappings ------------------- .. contents:: :depth: 1 :local: The PPDE file holds mappings of original PPD file options to their IPP attribute and values counterparts. Mapped IPP attributes and values can either be `IANA `__ registered, or :ref:`Internal SavaPage Extensions `. This is the syntax: .. callout:: .. code-block:: text *VENOption IppAttribute # <1> *VENOption *VENOptionValue-1 IppValue-1 # <2> ... *VENOption VENOptionValue-n IppValue-n .. annotations:: :1: ``VENOption`` must be replaced by its ``PPD`` equivalent (the ``VEN`` prefix stands for *vendor* specific). :2: - ``VENOption / VENOptionValue`` pairs, whose values must be copied from the vendor ``PPD``. ``IppValue`` is the IPP value equivalent. The optional asterix ``*`` prefix of ``VENOptionValue`` tells if the value is the default. - The ``IppValue`` *must* be unique in the ``VENOption`` set, while the ``VENOptionValue`` can be used more than once. *In this way different IPP values can be mapped to the same PPD value.* .. note:: ``VENOption / VENOptionValue`` pairs are relevant for IPP attributes that have “keyword”, “enum” or “boolean” syntax, because their values are confined to a predefined set. These pairs are not needed for IPP attributes that have unconfined values, because of their “integer”, “name”, or “text” syntax. .. _app-ppd-ext-mapping-ipp-iana: Mapping PPD to IPP ~~~~~~~~~~~~~~~~~~ .. contents:: :depth: 1 :local: `IANA IPP attributes `__ available for mapping are presented in the sections below. .. _app-ppd-ext-mapping-ipp-iana-copies: copies ^^^^^^ .. code-block:: text *VENCopies copies .. _app-ppd-ext-mapping-ipp-iana-media: media ^^^^^ .. code-block:: text *VENMedia media *VENMedia VENA3 iso_a3_297x420mm *VENMedia *VENA4 iso_a4_210x297mm *VENMedia VENA5 iso_a5_148x210mm *VENMedia VENA6 iso_a6_105x148mm # ... .. _app-ppd-ext-mapping-ipp-iana-media-source: media-source ^^^^^^^^^^^^ .. code-block:: text *VENMediaSource media-source *VENMediaSource *VENAuto auto *VENMediaSource VENMain main *VENMediaSource VENTop top *VENMediaSource VENMiddle middle *VENMediaSource VENBottom bottom *VENMediaSource VENBypassTray by-pass-tray *VENMediaSource VENManual manual *VENMediaSource VENTray1 tray-1 # tray-2 ... tray-10 .. _app-ppd-ext-mapping-ipp-iana-media-type: media-type ^^^^^^^^^^ .. code-block:: text *VENMediaType media-type *VENMediaType *VENPaper paper *VENMediaType VENTransparency transparency *VENMediaType VENLabels labels *VENMediaType VENLetterhead letterhead .. _app-ppd-ext-mapping-ipp-iana-output-bin: output-bin ^^^^^^^^^^ .. code-block:: text *VENOutputBin output-bin *VENOutputBin *VENAuto auto *VENOutputBin VENBottom bottom *VENOutputBin VENCenter center *VENOutputBin VENTop top *VENOutputBin VENFaceDown face-down *VENOutputBin VENFaceUp face-up *VENOutputBin VENLargeCap large-capacity *VENOutputBin VENLeft left *VENOutputBin VENMiddle middle *VENOutputBin VENRear rear *VENOutputBin VENSide side *VENOutputBin VENStacker1 stacker-1 # stacker-2 ... stacker-5 *VENOutputBin VENTray1 tray-1 # tray-2 ... tray-5 .. _app-ppd-ext-mapping-ipp-iana-print-color-mode: print-color-mode ^^^^^^^^^^^^^^^^ .. code-block:: text *VENPrintColorMode print-color-mode *VENPrintColorMode *VENMonochrome monochrome *VENPrintColorMode VENColor color .. _app-ppd-ext-mapping-ipp-iana-print-scaling: print-scaling ^^^^^^^^^^^^^ .. callout:: .. code-block:: text *VENPrintScaling print-scaling *VENPrintScaling *VENFit fit # <1> *VENPrintScaling VENNone none # <2> *VENPrintScaling VENAuto auto # <3> .. annotations:: :1: Scale the document to fit the printable area of the requested media size, preserving the aspect ratio of the document data without cropping the document. :2: Do not scale the document to fit the requested media size. If the document is larger than the requested media, center and clip the resulting output. If the document is smaller than the requested media, center the resulting output. :3: Value ``auto`` applies a 'fit', 'fill' or 'none' method to get an optimized imposition of the document onto the printable area of the requested media size. This is the best method to scale documents with mixed portrait/landscape pages. See :ref:`Page Scaling `. .. note:: If CUPS does not provide the IPP ``print-scaling`` option for a printer, SavaPage falls back to the CUPS `fit-to-page `__ boolean attribute to scale documents. Value ``1`` (true) scales the document up or down to fit the selected media. Value ``0`` (false) preserves the physical size of the printed document and crops any content outside the selected media. .. _app-ppd-ext-mapping-ipp-iana-printer-resolution: printer-resolution ^^^^^^^^^^^^^^^^^^ .. callout:: .. code-block:: text *VENResolution printer-resolution *VENResolution *VEN150dpi 150x150 DPI # <1> *VENResolution VEN300dpi 300x300 DPI # <2> *VENResolution VENnnndpi nnnxnnn DPI|DPC # <3> .. annotations:: :1: ``150x150`` Dots Per Inch (DPI) as default. :2: ``300x300`` Dots Per Inch (DPI). :3: General format: any combination of ``DPI`` (Dots Per Inch) or ``DPC`` (Dots Per Centimeter). .. _app-ppd-ext-mapping-ipp-iana-sheet-collate: sheet-collate ^^^^^^^^^^^^^ .. code-block:: text *VENCollate sheet-collate *VENCollate *VENCollated collated *VENCollate VENUncollated uncollated When ``sheet-collate`` is not mapped, SavaPage generates a single PDF and applies a one-copy print. The PDF is a concatenation of the requested number of copies with pages arranged in the right collate order. .. _app-ppd-ext-mapping-ipp-iana-sides: sides ^^^^^ .. code-block:: text *VENSides sides *VENSides VENOneSided one-sided *VENSides *VENTwoSidedLongEdge two-sided-long-edge *VENSides VENTwoSidedShortEdge two-sided-short-edge .. _app-ppd-ext-mapping-ipp-ext: Mapping PPD to IPP Extensions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PPD Options can be mapped to :ref:`Internal IPP Extensions `. For example: .. callout:: .. code-block:: text *VENStapleOption org.savapage-finishings-staple # <1> *VENStapleOption *VENNone 3 # <2> *VENStapleOption VENTopLeft 20 # <3> *VENStapleOption VENBottomLeft 21 # <4> .. annotations:: :1: ``VENStapleOption`` is mapped to :ref:`org.savapage-finishings-staple `. :2: ``VENNone`` value of ``VENStapleOption`` is mapped to IPP enum value ``3`` (none). The asterix ``*`` tells this options is the default. :3: ``VENTopLeft`` value of ``VENStapleOption`` is mapped to IPP enum value ``20`` (staple-top-left). :4: ``VENBottomLeft`` value of ``VENStapleOption`` is mapped to IPP enum value ``21`` (staple-bottom-left). .. _app-ppd-ext-restricting-standard-options: Restricting Standard Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. contents:: :depth: 1 :local: Standard CUPS/IPP options, like ``number-up``, are independent of PPD, and available for all printers types. The values of these options can be restricted with PPDE syntax. Below are examples for options currently supported by |PRODUCT_NAME|. .. _app-ppd-ext-restricting-standard-option-number-up: number-up ^^^^^^^^^ For example, option ``number-up`` can be restricted to values ``1`` (default), ``2`` and ``4`` like this: .. code-block:: text *number-up number-up *number-up *1 1 *number-up 2 2 *number-up 4 4 .. _app-ppd-ext-restricting-standard-option-print-scaling: print-scaling ^^^^^^^^^^^^^ For example, option ``print-scaling`` can be restricted to value ``none`` like this: .. code-block:: text *print-scaling print-scaling *print-scaling none none In this case the |RST_CHECKBOX_FIT| option is not shown in the Printer Settings dialog. See :ref:`Page Scaling `. Assuming ``tray-1`` contains ``A4`` and ``tray-2`` contains ``A3`` media, you can enforce a scaling policy with :ref:`SPSubst ` rules. .. code-block:: text # Expose attribute in full *print-scaling print-scaling *print-scaling fit fit *print-scaling none none *print-scaling *auto auto # Do NOT scale in tray-1 (A4) *SPSubst/print-scaling/fit: A4-scale-none \ media-source/tray-1 \ *none # Scale in tray-2 (A3) *SPSubst/print-scaling/none: A3-scale-fit \ media-source/tray-2 \ *fit