.. /*  
    * This file is part of the SavaPage project <https://www.savapage.org>.
    * Copyright (c) 2026 Datraverse B.V.
    * Author: Rijk Ravestein.
    *
    * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. <info@datraverse.com>
    * 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-rules:

PPD Rules
---------

.. contents:: |RST_TABLE_OF_CONTENTS|
   :depth: 1
   :local:

Sometimes, simple one-to-one PPD to IPP mappings do not suffice to get
the right options to the PPD driver. In that case PPD rules can be of
help. PPD rules take independent IPP (or PDF document) options as input,
and return dependent PPD (or CUPS) options.

.. _app-ppd-ext-rules-generic:

Generic PPD Rules
~~~~~~~~~~~~~~~~~

.. contents::
   :depth: 1
   :local:

Generic PPD Rules add, assign or substitute PPD option values.

.. _app-ppd-ext-rules-generic-extra:

SPExtra
^^^^^^^

The ``SPExtra`` rule adds one or more PPD options to a print request, 
depending on one or more IPP options. The rule is formatted like this:

.. callout::

   .. code-block:: text

      *SPExtra/<attrib>/<value>: <mnemonic>  \  # <1>
         <attrib>/[!]<value> ...    \           # <2>
         *<option>/<value> ...  \               # <3>

   .. annotations::
       :1: The rule prefix, an IPP attribute/value pair as main independent 
           variable, and identifying ``<mnemonic>``. Note: the ``!`` prefix 
           before the IPP value to negates it, is **not** applicable in this
           case: you need to specify an exact IPP value to identify the rule.
       :2: Optionally one or more extra IPP attribute/value pairs as independent 
           variables. An optional ``!`` before a value negates it, and selects 
           all other attribute values.
       :3: One or more PPD option/value pairs as dependent variables. 
           These option pairs are added to the print request, when 
           all independent variables are present.


As an example, some :ref:`org.savapage-finishings-punch <app-ipp-org.savapage-finishings-punch>`
rules for “Canon iR-ADV 8285/8295 UFR II” are shown below.

.. code-block:: text

   *SPExtra/org.savapage-finishings-punch/3: punch-none \
      *CNPunch/None

   *SPExtra/org.savapage-finishings-punch/74: punch-dual-left \
      *CNPunch/Left

   *SPExtra/org.savapage-finishings-punch/82: punch-quad-left \
      *CNPunch/Left

The rule can also be used to *replace* existing options. For example:
:ref:`org.savapage-finishings-booklet <app-ipp-org.savapage-finishings-booklet>`
rules, for “Canon iR-ADV 8505 PS”. The snippet below *adds* extra
options ``BindMode`` and ``Booklet``, and *replaces* the ``media``,
``number-up``, ``sides`` and ``fit-to-page`` options.

.. code-block:: text

   *SPExtra/org.savapage-finishings-booklet/toleft-totop: booklet-toleft-totop-a3 \
      media/iso_a3_297x420mm \
      *media/iso_a4_210x297mm \
      *number-up/1 \
      *sides/one-sided \
      *BindMode/SaddleStitch \
      *Booklet/Left
    
   *SPExtra/org.savapage-finishings-booklet/toleft-totop: booklet-toleft-totop-a4 \
      media/iso_a4_210x297mm \
      *media/iso_a5_148x210mm \
      *fit-to-page/1 \
      *number-up/1 \
      *sides/one-sided \
      *BindMode/SaddleStitch \
      *Booklet/Left

You can even replace a single IPP option value. For example, if you want
to print “``NA Letter``” as ``A4`` (relying on default
:ref:`print-scaling <app-ppd-ext-mapping-ipp-iana-print-scaling>`) you can
use this rule:

.. code-block:: text

   *SPExtra/media/na_letter_8.5x11in: letter-to-a4 \
      *media/iso_a4_210x297mm

.. _app-ppd-ext-rules-generic-subst:

SPSubst
^^^^^^^

This rule is meant to assign a native PPD value to an IPP attribute, and
is formatted like this:

.. callout::

   .. code-block:: text

      *SPSubst/<attrib>/<value>: <mnemonic>  \  # <1>
         <attrib>/[!]<value> ...  \             # <2>
         *<value>                               # <3>

   .. annotations::
       :1: The rule prefix, an IPP attribute/value pair as main independent variable,
           and identifying ``<mnemonic>``.
       :2: Optionally one or more extra IPP attribute/value pairs as independent
           variables. An optional ``!`` before a value negates it, and selects
           all other attribute values.
       :3: The PPD option value as dependent variable. This value is assigned 
           as PPD option to the main IPP attribute, when all independent variables
           are present.


As an example, some
:ref:`sheet-collate <app-ppd-ext-mapping-ipp-iana-sheet-collate>`
substitution rules for “Canon iR-ADV 8285/8295 UFR II” are shown below.
Also see
:ref:`org.savapage-finishings-staple <app-ipp-org.savapage-finishings-staple>`

.. code-block:: text

   *SPSubst/sheet-collate/collated: collate \
      org.savapage-finishings-staple/3 \
      *True

   *SPSubst/sheet-collate/uncollated: group \
      org.savapage-finishings-staple/3 \
      *Group

   *SPSubst/sheet-collate/collated: staple-and-collate \
      org.savapage-finishings-staple/!3 \
      *StapleCollate

   *SPSubst/sheet-collate/uncollated: staple-and-group \
      org.savapage-finishings-staple/!3 \
      *StapleGroup


.. _app-ppd-ext-rules-custom:

Custom PPD Rules
~~~~~~~~~~~~~~~~

.. contents::
   :depth: 1
   :local:

Custom PPD Rules are restricted to specific situations.

.. _app-ppd-ext-rules-custom-landscape-orientation:

LandscapeOrientation
^^^^^^^^^^^^^^^^^^^^

.. contents::
   :depth: 1
   :local:

.. _app-ppd-ext-rules-custom-landscape-orientation-intro:

Introduction
''''''''''''

Most PPD files contain an attribute called ``LandscapeOrientation``,
with value ``Plus90`` (default) or ``Minus90``, that describes how
landscape oriented pages are rotated to fit the portrait mode "Finished
Page"  [1]_.

In ``Plus90`` mode, landscape pages are -90 rotated to fit the "Finished
Page", and the user must +90 rotate after printing, to get it into
tangible landscape view again. ``Minus90`` is vice versa. The terms
"Minus" and "Plus" are a bit confusing. They do not refer to the rotate
direction before printing, but refer to the "manual" user rotation
*after* printing, to get the "Finished Page" into landscape view again.

*SavaPage creates IPP print jobs that are effectively printed
according to Minus90*. In this way, ``staple-top-right`` makes sense for
landscape viewed pages.

As the CUPS ``number-up`` option still behaves according to the original
PPD ``LandscapeOrientation`` attribute, SavaPage corrects with
appropriate ``number-up-layout`` and ``orientation-requested`` options,
to get the overall ``Minus90`` effect for ``number-up`` printed sheets
that have landscape view.

Because SavaPage assumes that all target proxy printers behave
according to the ``Plus90`` default, any exception must be entered in a
PPDE like this:

.. code-block:: text

   *LandscapeOrientation: Minus90

When nevertheless ``number-up`` printed sheets do not turn out as
expected, corrections can be made with ``SPRule/number-up``.

.. note::

   SavaPage does **not** correct with ``number-up-layout`` and
   ``orientation-requested`` options when a
   :ref:`org.savapage-finishings-booklet <app-ipp-org.savapage-finishings-booklet>`
   finishing is chosen, since MFP booklet finishers are supposed to
   apply the correct orientation and layout.


.. [1]
   According to PWG5100.3: a Finished Page is "One side of a sheet in a
   Finished Document, i.e., one side of a sheet as perceived by a person
   after any cutting, folding, and/or booklet making".


.. _app-ppd-ext-rules-custom-number-up:

SPRule/number-up
''''''''''''''''

This is a fallback rule to make corrections, in the rare case that
``LandscapeOrientation``, as discussed in the previous section, does not
work out as expected. Each rule is prefixed with ``*SPRule/number-up:``
and formatted like this:


.. callout::

   .. code-block:: text

      *SPRule/number-up: <mnemonic>     \  # <1>
         pdf-orientation/<value>        \  # <2>
         pdf-rotation/<value>           \  # <3>
         pdf-content-rotation/<value>   \  # <4>
         user-rotate/<value>            \  # <5>
         number-up/<value>              \  # <6>
         *orientation-requested/<value> \  # <7>
         *number-up-layout/<value>      \  # <8>
         *org.savapage-landscape           # <9>


   .. annotations::
       :1: The rule prefix and identifying ``<mnemonic>``.
        
       :2: The orientation ``<value>`` of the first PDF page to be printed:
           ``portrait``, ``landscape`` .
        
       :3: The rotation ``<value>`` of the first PDF page to be printed: ``0``,
           ``90``, ``180`` , ``270`` .
        
       :4: The content rotation ``<value>`` of the first PDF page to be printed:
           ``0``, ``90``, ``180`` , ``270`` . When not specified, value ``0`` is
           assumed.
        
       :5: The user rotation ``<value>`` on the PDF document to be printed:
           ``0``, ``90``. See
           :ref:`Rotation <ch-webapp-user-main-document-rotation>`. When not
           specified, value ``0`` is assumed.
        
       :6: The selected ``number-up`` ``<value>`` : ``1``, ``2``, ``4``, ``6``,
           ``9``.
        
       :7: As the previous independent variables describe the situation “as is”,
           this is the first *dependent* variable telling CUPS the
           ``orientation-requested`` ``<value>`` : ``4`` (landscape), ``5``
           (reverse landscape) , ``6`` (reverse portrait). Note: a value of
           ``-`` indicates that this CUPS attribute is *not* used.
        
       :8: The second *dependent* variable telling CUPS the ``number-up-layout``
           ``<value>`` : ``btlr``, ``btrl``, ``lrbt``, ``lrtb``, ``rlbt``,
           ``rltb``, ``tblr``, ``tbrl``. Note: a value of ``-`` indicates that
           this CUPS attribute is *not* used.
        
       :9: The third optional *dependent* variable is used for the 
           :ref:`Document Log <ch-webapp-admin-doclog>` only, telling that the resulting
           n-up layout has logical landscape orientation. When not specified,
           portrait orientation is assumed.


As an example, some rules are shown below.

.. code-block:: text

   *SPRule/number-up: portrait-90-0-0-1 \
      pdf-orientation/portrait pdf-rotation/90 user-rotate/0 number-up/1  \
     *orientation-requested/- *number-up-layout/-

   *SPRule/number-up: portrait-90-0-0-2-270 \
       pdf-orientation/portrait pdf-rotation/90 user-rotate/0 number-up/2  \
      *orientation-requested/5 *number-up-layout/tbrl

   *SPRule/number-up: portrait-90-0-0-4 \
      pdf-orientation/portrait pdf-rotation/90 user-rotate/0 number-up/4  \
      *orientation-requested/- *number-up-layout/tbrl

   *SPRule/number-up: portrait-90-0-0-6-270 \
      pdf-orientation/portrait pdf-rotation/90 user-rotate/0 number-up/6  \
      *orientation-requested/5 *number-up-layout/lrtb

   *SPRule/number-up: portrait-90-0-0-9 \
      pdf-orientation/portrait pdf-rotation/90 user-rotate/0 number-up/9  \
      *orientation-requested/- *number-up-layout/tbrl

   *SPRule/number-up: landscape-0-0-0-2-270 \
      pdf-orientation/landscape pdf-rotation/0 user-rotate/0 number-up/2  \
     *orientation-requested/5 *number-up-layout/tbrl

   *SPRule/number-up: landscape-0-0-0-6-270 \
      pdf-orientation/landscape pdf-rotation/0 user-rotate/0 number-up/6  \
      *orientation-requested/5 *number-up-layout/lrtb

   *SPRule/number-up: landscape-270-270-0-6-270 \
      pdf-orientation/landscape pdf-rotation/270 pdf-content-rotation/270 \
      user-rotate/0 number-up/6  \
     *orientation-requested/5 *number-up-layout/tbrl

   *SPRule/number-up: landscape-270-0-90-2 \
      pdf-orientation/landscape pdf-rotation/270 pdf-content-rotation/0 \
      user-rotate/90 number-up/2  \
     *orientation-requested/- *number-up-layout/tbrl
     
   *SPRule/number-up: landscape-270-0-90-4 \
      pdf-orientation/landscape pdf-rotation/270 pdf-content-rotation/0 \
      user-rotate/90 number-up/4  \
     *orientation-requested/- *number-up-layout/tbrl *org.savapage-landscape
     
   *SPRule/number-up: landscape-270-0-90-6 \
      pdf-orientation/landscape pdf-rotation/270 pdf-content-rotation/0 \
      user-rotate/90 number-up/6  \
     *orientation-requested/- *number-up-layout/tbrl


.. _app-ppd-ext-rules-custom-number-up-semantics-limitations:

Number-up semantics and limitations
'''''''''''''''''''''''''''''''''''

-  PDF input from :ref:`Web Print <ch-webapp-user-main-upload>` can lead to
   unexpected number-up print results, when the semantic (perceived)
   orientation of a page, does not match the actual orientation/rotation
   of the PDF page. For instance, a mismatch occurs when a landscape
   oriented PDF page, has rotated portrait content. *There is no way
   SavaPage can identify this situation to make intelligent
   corrections.* |br|
   |br|

-  An ``SPRule/number-up`` is applied when its independent variables
   (orientation, rotation) match the *first* page in the PDF document.
   When these variables differ for subsequent pages, the PPD has the
   final say on how page rotation and n-up layout turns out. *A PDF
   document with different page orientations may produce an unexpected
   number-up result.*

.. _app-ppd-ext-rules-custom-booklet-imposition:

Booklet Imposition
^^^^^^^^^^^^^^^^^^

Booklet imposition is assumed to be handled by the PPD. However, while
some PPD's have an option for booklet folding, they do not handle
booklet imposition. Therefore, a special PPDE option is available to
prepare booklet page ordering, before sending PDF to CUPS. Add the
following line to a .ppde file to enable pre-processing the PDF to
booklet page ordering:

.. code-block:: text

   *SPLocalBooklet: True


.. tip::

   You can use this option in combination with IPP option
   :ref:`org.savapage-finishings-booklet <app-ipp-org.savapage-finishings-booklet>`
   to offer duplex printing in booklet page ordering, without the
   presence of a printer booklet finisher.