Runlist

The Runlist is based on a very simple scripting language that uses a few statements and variables to create sheets based on templates, place pages on those sheets, and manipulate the values of the variables used.

  • Note: The Runlist contains information and instructions for the imposition process in a simple script language.

Name of the runlist

The configuration files file extension has to be ".runlist" and the content has to start with the reserved word "NAME" followed by a <Tab> and a Name. This file is just assigned the name Runlist in UTF-8 code. As long as only standard letters from A to Z and a to z without umlauts or accents, and numbers and simple signs such as period, comma, hyphen or under-­score are used in names, ASCII corresponds to UTF-8 code.
If you wish to use names with umlauts or signs from non-Western languages – such as Russian or Japanese – these will have to be saved in UTF-8. Some text editors – e.g. BBEdit 7 in Mac – offer special save options for this. Under this name the sheet definition can be activated in the Desktop version of pdfToolbox in the "Impose" action dialog.

.runlist configuration

The .runlist file contains the Runlist with the actual imposition script that arranges the pages on sheets that have been taken from the sheet supply. With the help of commands and special counters the actual imposition process can be controlled within such an imposition script. The commands and counters available are explained below. The file hat to start with the reserved word "NAME" followed by a <Tab> and a Name. This is the name of the configuration as it will show up using the runlist pulldown menu of the imposition action in pdfToolbox.

Counters available in the run list

Page counters are needed when placing pages of the original PDF file onto the imposition sheet.

FirstPage

At the beginning of the imposition process this is set to 1 (as the first page in the source document is always specified as 1).

LastPage

At the start of the imposition process this is set to the number of pages in the source document. However, at the same time the parameter TotalPagesMultipleOf in the settings file SheetConfig.dat is taken into consideration and the value for the number of pages in the source document is rounded up to the next value that can be evenly divided by TotalPagesMultipleOf.
Without considering TotalPagesMultipleOf, in a 29-page document LastPage would have a value of 29. If the entry TotalPagesMultipleOf is set to 4, 29 will be rounded up to the next value dividable by 4 so that LastPage would have the value 32.

MidPage

At the beginning of the imposition process this is set to (LastPage / 2) +1 

In the case of a 16-page document MidPage would have a value of 9 at the outset of the imposition process (LastPage would then be 16, as long as TotalPagesMultipleOf were not applied; 16 divided by 2 equals 8, plus one equals 9). 

LastPhysicalPage

Return the number of the last physical page in the PDF. Might be useful as the value of "LastPage" usually changes during imposition.

Runlist commands

With the following commands you can insert a new sheet, place a page on a sheet or manipulate one of the counter variables.

There is a TAB (and not SPACE) between the command and the argument.

New Sheet 
NewSheet	<Sheet number>

The parameter NewSheet inserts the next template page from the tem-­plate file as a new sheet. If a template consists of multiple sheets, the sheets will be used in sequence. If there are no more sheets, the first sheet will be used again. The optional parameter <Sheet number> allows to use a specific sheet from the template.

Position Page 
PositionPage	<COUNTER>	Slot_##: 
PositionPage	FirstPage	Slot_1 

This places the <COUNTER> page from the source document in the slot with the ID Slot_## and the current template.

<COUNTER>

must be one of the variables FirstPage, MidPage or LastPage

Slot_##

## is the number of the Slot, as defined in the template configura­tion
  • Note: Before calling up PositionPage for the first time, the command NewSheet must have been called up at least once.
Position Page 
PositionPage	<PAGE_COUNTER>	<SLOT>	<SLOT_COUNTER>
Click to copy

PositionPage with three arguments.
Places page <PAGE_COUNTER> in Slot <SLOT_COUNTER>, the <SLOT> param is ignored.
This allows to address the slot using a counter instead of a slot identifier. <SLOT_COUNTER> is optional.

Increment 
Increment	<COUNTER> 
Increment	FirstPage 

The counter <COUNTER> counts upwards by one; the counter then points to the next page in the source document.

<COUNTER>

must be  one of the values FirstPage, MidPage or LastPage 
Decrement 
Decrement	<COUNTER>
Decrement	LastPage

The counter <COUNTER> counts downwards by one; the counter then points to the previous page in the source document.

<COUNTER>

muss eine der Variablen FirstPage, MidPage oder LastPage sein
Append Pages 
AppendPages

The command AppendPages does not take any parameters. Instead it appends empty pages according to the current value of variable <LastPage>.  This fills the file to be imposed with pages up to the page count defined by LastPage.

  • Note: This command should be executed early, best before calling the position­ing of pages.
Destination Sheets 
Set    DestSheetsMultipleOf    <Number (default: 1)>
Set    DestFillupSheet    <Number (default: 1)>

The imposed file will be filled up with empty pages from the sheet tem­plate (page DestFillupSheet) to the next page count divisible by the number defined in DestSheetsMultipleOf.

Place text

TextFont 
Set	TextFont	<FONT>
Set	TextFont	"AmericanTypewriter"

Sets the font to be used for PlaceText. The default value is "Arial".

You can use each value from the list of known fonts, which will be created automatically when going to the action "Impose" in the Desktop version of callas pdfToolbox (section "Arrange"). You will then find the file "FontNames.txt" in the folder "Actions/Impose/Run­lists" inside your pdfToolbox user preferences.

Using the CLI, the command --listfonts will list all font names available for impositioning.

TextSize 
Set	TextSize	<SIZE>
Set	TextSize	"12pt"

Sets the text size to be used for PlaceText. The default value is "10pt".

TextColorSpace 
Set	TextColorSpace	<Color space>
  • Note: Color space can be any of: DeviceGray, DeviceRGB, DeviceCMYK or a Spot color name.

By default the text is using Separation color "All", also known as Regis-­tration color. This parameter allows to define a specific color space to be used for the text element to be placed. Defining this parameters requires to also define the parameter TextColorValues.

TextColorValues 
Set	TextColorValues	<Color value>
Set	TextColorValues	"100/100/0/0"

This parameter defines the color values to be used based on the color space defined by TextColorSpace. The values have to be formatted in such a way that they represent the color tints of the color channels avail-­able in the defined color space. The values have to be defined in a range from 0 to 100.


  • For DeviceGray the values has to be the <Gray> tint in %
  • For DeviceRGB the values have to be <Red>/<Green>/<Blue> in %
  • For DeviceCMYK the values have to be <Cyan>/<Magenta>/<Yellow>/<Black> in %
  • For <Spot Color> the values have to be either <Red>/<Green>/<Blue> or      <Cyan>/<Magenta>/<Yellow>/<Black> in % and represent the alternate color space definition
TextTintValue 
Set	TextTintValue	<Spot color tint value>
Set	TextTintValue	"50"

If using a spot color, this parameters allow to define the used tint value of the spot color.

PlaceText 
PlaceText	<SLOT>	<TEXT>
PlaceText	Slot_3	"callas"

PlaceText uses the currently set values for TextFont and TextSize – if these are not defined, "Arial" and "10pt" will be used by default.
    

  • Note: Only characters contained in WinAnsi or MacRoman encoding (by usage of the system's fonts) are supported at the moment. Therefore the text may only consist of characters that are present in the by font set by TextFont.
PageBox 
BoxOrder	<BOX NAME>
BoxOrder	CropBox<Tab>TrimBox

This parameter defines which PageBox is used for positioning pages during imposition. A list of box names, tabulator-key separated is possible.

Allowed values are: ArtBox, BleedBox, TrimBox, CropBox, MediaBox

Shingling

Below are all the possible runlist commands related to shingling. A more detailed explanation of each parameter can be found in this article.

ShinglingMethod 
Set	ShinglingMethod	<method>
Click to copy 
Set	ShinglingMethod	"Scale"
Click to copy

This parameter is optional. If no ShinglingMethod is set, shifting is applied by default.

Supported shingling methods: 

  • "Legacy" (Default): Shingling by shifting the page contents inwards (ShinglingOffset < 0) or outwards (ShinglingOffset > 0)
  • "Shift"
  • "Scale"
  • "ScaleP"

Note: The "Legacy" method uses the legacy ShinglingOffset. All other methods use the ShinglingIncrement instead.

ShinglingStapleSize

Note: This parameter has no effect for the "Legacy" shingling method.

Set	ShinglingStapleSize	<value>
Click to copy 
Set	ShinglingStapleSize	"16"
Click to copy

Defines the number of signatures in a staple.

ShinglingDirection

Note: This parameter has no effect for the "Legacy" shingling method.

Set	ShinglingDirection	<direction>
Click to copy 
Set	ShinglingDirection	"both"
Click to copy

Defines the direction of the shingling:

Supported singling directions:

  • "inwards"
  • "outwards"
  • "both"
ShinglingIncrement

Note: This parameter has no effect for the "Legacy" shingling method.

Set	ShinglingIncrement	<unit value>
Click to copy 
Set	ShinglingIncrement	"0,563mm"
Click to copy

The shingling value is incremented by this value for each signature in a staple. 

This parameter is a unit value, e.g. "1mm" or "10pt".

ShinglingOffset

Note: Only if the "Legacy" shingling method is used the ShinglingOffset parameter can be used.

Set	ShinglingOffset	<offset>
Set	ShinglingOffset	"0,02mm"

ShinglingOffset or increment  is applied automatically based on the page currently placed in relation to the middle page in the document. The default value is 0,00 mm for no binding moves.
A positive value moves placed pages away from the binding margin and negative value moves placed pages towards the binding margin. Normally negative values are more useful since inner pages of a booklet normally require moving page contents inside. 

Starting from the first and last page the shingling value is incremented every two pages by ShinglingOffset starting with the value 0.
Example:

For a 16 page document:

Pages 1,2,15,16: Shingling = 0 * ShinglingOffset
Pages 3,4,13,14: Shingling = 1 * ShinglingOffset
Pages 5,6,11,12: Shingling = 2 * ShinglingOffset
Pages 7,8,9,10: Shingling = 3 * ShinglingOffset

ShinglingValue 
Set	ShinglingValue	<value>
Set	ShinglingValue	"-0,05mm"

When a value is defined, "ShinglingValue" overwrites the current shingling value calculated on the basis of "ShinglingOffset". The default value is 'empty'.

Shingling

Shingling is read only that denotes the "ShinglingValue" that was effective during the last placement action.

If-else condition

This allows to process runlist functions and commands depending on spe­cific conditions.

If	<boolean condition>
<processing steps>
Else
<processing steps>
EndIf

Additional available functions are:

ElseIf
ErrorIf
Example: 
If	var("FirstPage")>1
PlaceText    Slot_102    var("FirstPage")
Else
PlaceText    Slot_102    "Not first page"
EndIf

Working through the script to be imposed

The Runlist is gone through from start to finish, step by step, repeating as often as necessary, until the condition 

FirstPage > LastPage

is met. This means that the Runlist must be set up in such a way that this condition is only met once all the pages have been imposed. 

If the Runlist has been worked through to the end but the break condition has not yet been met, the process will start all over again. 

If the break condition is met before the Runlist reaches the end, the way the Runlist process terminates is defined by the RunListTerminationMode parameter. 

RunListTerminationMode defines the behaviour when FirstPage gets larger than LastPage. Allowed values are 1 and 2, the default is 1. 

  1. The loop stops. If the sheet is not completely imposed, it is discarded. 
  2. If the loop stops (FirstPage > LastPage), the currently imposed sheet is stored even if not all slots are filled.