.. /*  
    * 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-ipp:

IPP Rules
---------

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

IPP Rules specify relations between IPP attributes.

.. _app-ppd-ext-rules-ipp-constraint:

SPConstraint
~~~~~~~~~~~~

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

An ``SPConstraint`` rule specifies values of two incompatible IPP
attributes, for example two-sided printing on transparency media. The
rule is formatted like this:

.. callout::

   .. code-block:: text

      *SPConstraint: <mnemonic>  \   # <1>
         <attrib>/[!]<value>     \   # <2>
         <attrib>/[!]<value>         # <3> 
   
   .. annotations::
       :1: The rule prefix and identifying ``<mnemonic>``.
       :2: The first IPP attribute/value pair. An optional ``!`` before
           a value negates it, and selects all other attribute values. 
       :3: The second IPP attribute/value pair, that is incompatible with the first.


Some examples:

.. code-block:: text

   *SPConstraint: transparency-two-sided \
       media-type/transparency \
       sides/!one-sided

   *SPConstraint: booklet-punch \
       org.savapage-finishings-booklet/!none \
       org.savapage-finishings-punch/!3


.. note::

   ``SPConstraint`` is the IPP counterpart of the ``UIConstraints``
   directive found in PPD files.

   *“CUPS does not enforce constraints when printing. Constraints must be
   managed and resolved by the user interface, because there is usually
   no way to specify preferences or intentions for automatic resolution
   of constraints by the driver or other filters.”* From “CUPS: Common
   Unix Printing System” by Michael R. Sweet, Sams Publishing, 2002
   (page 337).

   ``SPConstraint`` rules are used by SavaPage to validate user
   input when specifying a print job.

.. _app-ppd-ext-rules-ipp-constraint-internal:

Internal SPConstraint Rules
^^^^^^^^^^^^^^^^^^^^^^^^^^^

SavaPage has predefined rule sets. When activated, they are applied
globally, independent of any PPDE file.

.. _app-ppd-ext-rules-ipp-constraint-booklet:

Booklet SPConstraint Set
^^^^^^^^^^^^^^^^^^^^^^^^

This set is for
:ref:`org.savapage-finishings-booklet <app-ipp-org.savapage-finishings-booklet>`
and must be activated by setting configuration property
``ipp.ext.constraint.booklet.enable`` to ``Y``.

.. code-block:: text

   *SPConstraint: sp-booklet-number-up-1 \
       org.savapage-finishings-booklet/!none \
       number-up/1

   *SPConstraint: sp-booklet-number-up-4 \
       org.savapage-finishings-booklet/!none \
       number-up/4

   *SPConstraint: sp-booklet-number-up-6 \
       org.savapage-finishings-booklet/!none \
       number-up/6

   *SPConstraint: sp-booklet-number-up-9 \
       org.savapage-finishings-booklet/!none \
       number-up/9        

   *SPConstraint: sp-booklet-one-sided \
       org.savapage-finishings-booklet/!none \
       sides/one-sided

   *SPConstraint: sp-booklet-rotate-180-on \
       org.savapage-finishings-booklet/!none \
       org.savapage.int-page-rotate180/1


.. important::

   When Media Cost is specified for Proxy Printers or Job Tickets
   supporting booklet finishing, activating this set is **crucial** for
   calculating the right cost for booklet print jobs.
   See :ref:`Printer Costs <ch-webapp-admin-proxyprinter-costs-per-media-side>` and
   :ref:`Job Ticket Media Options <app-ppd-ext-job-ticket-media>`.

.. caution::

   When this set is activated, user choices will be restricted to
   ``number-up/2`` and ``side/!one-sided``. As this is correct for cost
   calculation, these options will probably **not** deliver the intended
   booklet. So, make sure to review the required IPP options for the
   booklet job, and use :ref:`SPExtra <app-ppd-ext-rules-generic-extra>`
   rules to customize proxy printer instances where needed.