K.2. PPD Rules

K.2. PPD Rules
Prev	Appendix K. PPD Extensions	Next

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.

K.2.1. Generic PPD Rules

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

K.2.1.1. 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:

*SPExtra/<attrib>/<value>: <mnemonic>  \  
   <attrib>/[!]<value> ...    \  
   *<option>/<value> ...  \

	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.
	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.
	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 org.savapage-finishings-punch rules for “Canon iR-ADV 8285/8295 UFR II” are shown below.

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

*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 print-scaling) you can use this rule:

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

K.2.1.2. SPSubst

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

*SPSubst/<attrib>/<value>: <mnemonic>  \  
   <attrib>/[!]<value> ...  \  
   *<value>                 \

	The rule prefix, an IPP attribute/value pair as main independent variable, and identifying `<mnemonic>`.
	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.
	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 sheet-collate substitution rules for “Canon iR-ADV 8285/8295 UFR II” are shown below. Also see Section L.1.1.1, “org.savapage-finishings-staple”

*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

K.2.2. Custom PPD Rules

Custom PPD Rules are restricted to specific situations.

K.2.2.1. LandscapeOrientation

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" ^[54].

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:

*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 org.savapage-finishings-booklet finishing is chosen, since MFP booklet finishers are supposed to apply the correct orientation and layout.

K.2.2.1.1. 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:

*SPRule/number-up: <mnemonic>     \  
   pdf-orientation/<value>        \  
   pdf-rotation/<value>           \  
   pdf-content-rotation/<value>   \   
   user-rotate/<value>            \  
   number-up/<value>              \  
   *orientation-requested/<value> \  
   *number-up-layout/<value>      \  
   *org.savapage-landscape

	The rule prefix and identifying `<mnemonic>`.
	The orientation `<value>` of the first PDF page to be printed: `portrait`, `landscape` .
	The rotation `<value>` of the first PDF page to be printed: `0`, `90`, `180` , `270` .
	The content rotation `<value>` of the first PDF page to be printed: `0`, `90`, `180` , `270` . When not specified, value `0` is assumed.
	The user rotation `<value>` on the PDF document to be printed: `0`, `90`. See Section 3.3.3.2, “Rotation”. When not specified, value `0` is assumed.
	The selected `number-up` `<value>` : `1`, `2`, `4`, `6`, `9`.
	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.
	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.
	The third optional dependent variable is used for the Document Log 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.

*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

K.2.2.1.2. Number-up semantics and limitations

PDF input from Web Print 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.
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.

K.2.2.2. 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:

*SPLocalBooklet: True

Tip

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

^[54] 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".