upCast 8.0 Reference Manual

upCast is a module-based document processing pipeline tool, specializing in legacy, "flat" and layout-driven content. It comes with pre-defined, configurable, task oriented modules (that perform operations like importing data, XSLT processing, serialization and validation etc.) that you can put into any order you wish to create a pipeline. Pipelines can be saved and parameterized as a whole and then be run either within upCast’s UI or from the commandline or directly from Java.

Pipelines can be set up to be fully relative in their file addressing and therefore can be shared without modifcations between computers, even different platforms.

To run upCast, you must meet the following minimum requirements:

The highest-level component type in upCast usage is a document processing pipeline, or short: pipeline. Pipelines can be saved into documents (file extension .ucdoc) and recalled at any time. Complete pipelines can be exported into several formats, like a Java source file or source code for an Ant target.

To the user, upCast presents its functionality in two layers: the so-called "Simple View" and the "Edit View". Think of the Simple View as a simplifying, user-oriented layer over the Edit View, which is developer-oriented and shows the actual, fine-grained and possibly complex implementation of the conversion pipeline.

Simple View as a user-oriented layer over the detailed Edit View on a pipeline’s implementation

Pipelines are made up of modules. Modules each perform a specific and specialized task. Modules can be divided into the three categories importers, processors and exporters based on the tasks they perform.

Importers import documents into the internal document format. upCast currently includes a high-quality RTF/Word importer.

Processors come in two variants for internal and external processing. Internal processors modify the current, internal document representation. This is carried out in-place. External processors can be used to perform general tasks which are not dependent on the internal document, like running a shell command.

Exporters are used to serialize the internal document or part thereof in one of several formats.

Within a pipeline, at any time during execution there’s exactly one internal document representation the tasks are performed on. This means that modifications are in most cases performed in-place, so changes made to the internal document tree by one module are visible to subsequent ones.

While a run of an importer always replaces the internal document, you can have several exporters that serialize the same internal document in different ways. You can also serialize the document at any point in the pipeline and apply additional modifications using processors afterwards.

It is often useful to be able to save, quickly recall and share with other users different parameter settings for running a certain, parameterized pipeline. Such a parameter set can be saved into documents (file extension .ucpar) and recalled at any time.

A parameter set document only contains the pipeline parameter values as they are set in the Simple View at the time of saving. Only parameters that have their persistent property set to true are saved in that document. It also contains the Pipeline UID of the pipeline document it is based on so that it can load its implementation for execution.

For details, see the section on Parameter Sets.

Usually, a conversion is a three-phase process: You import the source data into the application, process the data, and export the result. Sometimes, a fourth, external post-processing step is added. upCast offers various modules, which can be divided into three different classes: Importers, Processors and Exporters.

Here’s a diagram of a typical upCast pipeline (with the internal document indicated over time):

upCast sample pipeline with corresponding internal document life-span; list of modules

The upCast UI is designed to be simple and effective. An upCast document is a complete pipeline setup and can be can be saved in a file with the default extension .ucdoc. Each document is shown in its own window, and you can have several pipelines open at the same time.

A document window in edit mode is divided into three parts.

The left pane shows the sequence of modules that make up the pipeline. The position of a selected module in the pipeline can be changed by using the nudge-up/nudge-down controls at the bottom of the list. A module can be deleted from the pipeline with the "–" control, a module can be added by clicking the "+" control and choosing the desired class from the popup. There can be multiple instances of the same module type in a pipeline as required, e.g. two or more XSLT processors.

A module can have the following decorators:

The right pane shows the parameters for the currently selected module. Only one module can be selected at any time. Changes to a module’s parameters are effective immediately.

At the bottom of the window, the pipeline execution controls are placed for executing a pipeline, stopping it underway and checking its progress.

An upCast document window showing a pipeline setup with the XML Exporter selected

The syntax to refer to a variable in a specific realm is similar to that of Ant, albeit with a twist:

${realm:name#modifier}

Note the special #modifier part: It is useful when wanting to modify the stored value of a variable before returning it in specific ways. This is most useful in file paths, e.g. to only retrieve the name of a file in an absolute path, the base name or just the path to some file.

The components of a variable reference are:

${SourceFile#local}

${SourceFile#url}

${SourceFile#localpath}

${SourceFile#urlpath}

${SourceFile#localname}

${SourceFile#urlname}

${SourceFile#localextension}

${SourceFile#urlextension}

${SourceFile#localbasename}

${SourceFile#urlbasename}

${SourceFile#localbasenamepath}

${SourceFile#urlbasenamepath}

Let’s have a look at the various realms in more detail:

This realm is not yet available and will be implemented in a later release of upCast.

This realm is read-only.

This realm includes upCast application-global values.

The following variables are currently defined:

By default, all file path values returned are in URL format. You can use all available modifiers on them, of course, to change format or extract parts from them.

${application:SupportFolder}

This realm is read-only.

This realm includes upCast pipeline-global environment values. Most of them are virtual in the sense of that they reflect some current state of the execution environment at the time of recalling them and are not actually stored.

The following variables are currently defined:

By default, all file path values returned are in URL format. You can use all available modifiers on them, of course, to change format or extract parts from them.

${environment:xslt-xalan-version}

For accessing these environment values from UPL, access them using the environment namespace like ordinary UPL variables. Java types as listed in the table above are coerced to the respective UPL types.

With a namespace definition of

#namespace environment "http://www.infinity-loop.de/namespace/upcast-realm/environment";

the code

println( $environment:dir-licenses );

might print the following on the console:

/Users/demo/Library/Application Support/infinity-loop/upCast RT/Licenses

and the code

println( $environment:license-features );

might print the following to the console:

{"rtfimportGUI","rtfimportAPI","rtfexportGUI","rtfexportAPI","uplGUI","uplAPI"}

It is often useful to store values that several modules will need as pipeline variables. Examples are the source document to process, the destination folder, the folder where images will be stored or the folder where temporary files should be created if needed by the pipeline.

The pipeline realm contains variables that are available to all modules in a specific pipeline. Each pipeline has its own set of pipeline variables. Modules can only access pipeline variables of the pipeline they are a member of.

This realm includes all parameters of a single module in a pipeline. This realm can only be accessed from within that module, and only the parameters of the currently executed module at the time of reference resolution can be accessed.

This realm is read-only, with the exception of the UPL execution context, where you can also set variables in that realm.

The javaproperty realm contains all currently defined Java system properties, either pre-defined ones by the Java Virtual Machine (like user.dir or user.home) or properties explicitly set on launch of the VM running the application.

${javaproperty:user.home}

${javaproperty:user.dir#url}

This realm is read-only.

The include realm returns the contents of the file specified as the name of the variable. The syntax is as follows:

${include:/absolute/filepath/to/file.ext}
${include:relative/path/to/file.ext}

A relatively specified path is always considered to be relative to the value of ${pipeline:base}, i.e. the base URL of the pipeline.

The include realm can include parameters like e.g. specifying the encoding of the file to be used for reading it. The variable reference syntax can therefore take the following, extended form:

${include( paramname: "value" [, paramname: "value" ]* ):filepath}

The following table lists the possible parameters that can be specified for an include reference:

${include( encoding: "UTF-8" ):Resources/entity.map}

${include( source: "variable" ):pipeline:DestinationFolder}

${include( fallback: "" ):doesnotexist.txt}

${include:doesnotexist.txt}

${include(fallback: "println('File does not exist!'"):doesnotexist.txt}

Parameters and variables are internally stored using standard, appropriate Java or UPL object types. Some parameters can take several different types, which, however, can only be set using native Java code using the upCast API or UPL functions. Parameters that can accept more than one of the following basic types will have this mentioned explicitly and in detail in their respective description section.

The basic parameter types are:

These can be set in the upCast Preferences dialog, available under the application menu (Mac OS X) or the File menu (other platforms).

To make the settings active, click Apply or the window’s close button.

The parameters are grouped into tabs.

${application:BundledResources}/templates

Parameters will be described using the following typography:

Name gives the internal java.lang.String name of the parameter, which is used for storing in preferences files, and can be used in the Java API as String. However, in Java, the use of the Java symbol is highly recommended instead.

Java symbol names the Java constant definition for the parameter’s Name. All constants are defined in the class de.infinityloop.common.Params.

Type specified the recommended Java type to use when programming against the API. In the GUI version, that is taken care of automatically. Also, when using alternative interfaces like an Ant task, which allows only passing arguments as character strings, upCast tries to perform an appropriate cast. So you should make sure that the data you provide in these cases will be cast-able to the specified type, as otherwise the conversion will fail or produce incorrect results at runtime.

Value describes possible value ranges, supported keywords or other specifics about that parameter’s range.

Click the Pipeline Settings… button in the pipeline window to access the window for setting pipeline-level settings.

To make the settings active, click Close or the window’s close button.

Many of these settings allow you to override the settings made in the upCast preferences.

Access the various settings by choosing the respective tab:

3.1. Pipeline Parameters

Here, you can set up a description of parameters you want your pipeline to be dependent on. The information provided here is used in three ways:

1. to create a simplified view and data entry UI objects for the user of a pipeline, where you want to hide the details of the implementation (i.e. the kind and order of modules used, calculations etc.),

2. to define the parameters a pipeline accepts and requires to be able to run from the commandline or via the Java API functions, including the ability to check those parameters for legal values, and

3. to provide documentation for the semantics of a parameter, which is shown in form of help tags in the UI, as text in the commandline, and formatted as HTML document when generating the pipeline documentation

This is a convenient feature to distribute complete, parameterized pipeline solutions to your customers in an easy-to-use, packaged way. All they need to do is open the pipeline, supply the requested parameters, and click the Run button. They are therefore completely shielded from the (possibly many) modules building up the pipeline and their complexity.

Interface element and parameter definitions

The description code you provide here serves two purposes:

1. It is the basis for determining the number and name of pipeline parameters.

2. It specifies the kind of form display element for each of these parameters.

Basically, you specify the name of the pipeline variable you wish to have set to the specified pipeline parameter’s value. This value is supplied as initial, pre-set pipeline variable to your pipeline definition.

Important

The pipeline parameters are only set when the GUI is in Simple View mode. When in full editing mode, the pipeline is executed with a completely clean set of pipeline variables (except for the base variable) – unless you check the Set specified parameter defaults when running a pipeline in edit view option (see above). In the latter case, the default values for those parameters that have a default specified are set.

Before the defining code is interpreted, upCast resolves any contained variable references for the following realms and in that order:

1. include

2. javaproperty

3. application

You cannot (for obvious resons) access variables in the pipeline or module realm.

Tip

You can use the include variable reference to your advantage in projects where you have to create similar pipelines that essentially should have the same Simple View definitions. To keep those in-sync, you can use an external file holding the parameter definition code, then include it in all pipelines that should show the same UI and have the same parameters. You then only need to update that single external file, and the UI definitions are updated automatically in all pipelines that include it.

upCast offers several types of UI elements for parameter entry: a decorating label, a text field or box, a filechooser, a popup menu and a checkbox, each one with its own set of dedicated properties.

You must assign one of these entry types to each pipeline parameter you need. The syntax for describing the properties is based on a CSS rule set: The selector part takes the form of an element selector and supplies the name of the pipeline variable to set. The declaration block part specifies the specific display and behavioural properties for that UI element.

Here are the properties which you can set for each of the following available types (option values are case-sensitive!):

3.1.1. Text label

This UI element creates static text. You can use this for headings, parameter grouping or parameter descriptions for the pipeline GUI users.

Note

We recommend creating text labels with an ID type of selector, since using an element selector would create a pipeline variable by that name (and reserve a likewise named pipeline variable).

Using an ID type of selector part prevents this from happening, and the label will just server for showing text in the UI without any further effects.

label
type	label
text	the text to display in the label
font-family	the name of the font to use; when not specified, the system’s default label font
font-weight	normal | bold
font-style	normal | italic
font-size	size of the font; when not specified, the system’s default label font size
color	the text color; must be a CSS 2.1 color value
background-color	the background color; must be a CSS 2.1 color value
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.1. 

#myLabel {
    type: label;
    text: "Simple View Sample";
    font-size: 20pt;
    font-weight: bold;
    color: olive;
}

creates a label with 20pt font size, bold text and olive text color.

3.1.2. Text field

This UI element creates a text field for arbitrary text.

It will create a parameter and pipeline variable of type String.

text
type	text
label	text to display as label at the very left
persistent	when true, current values are saved to the pipeline document and re-loaded when the document is next opened when false, the value is not stored in the document and is assigned the default value (if specified) when the document is next opened The default value is false.
default	the default value for the parameter, if newly created or persistent is false
description	the string specified here is displayed as tool-tip text in the UI when hovering over the input element and also used for descriptive messages when running in commandline mode
required	(only used in upCast commandline mode) when true, this means that specifying a value for this parameter is required to run the pipeline when false, that parameter is not required to be specified but instead, its default value should be used (if specified) or not be set at all if there is no default value The default value is true.
lines	the number of lines of the text field, the default is 1
postfix	the text to display after the text entry field; use this e.g. for displaying a value unit like "dpi" to let the user know the semantics of the number entered in the text field
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.2. 

headerText {
  type: text;
    label: "Header Text:";
    persistent: true;
    default: "My Publication";
    lines: 2;
}

creates a field to input header text used in the pipeline. The pipeline variable created will be named headerText, and values the user inputs will be stored across document openings. The input field will show two lines of text, and will be pre-occupated with the text "My Publication" on initial creation.

3.1.3. File chooser, folder chooser

This UI element creates a text field for entering a file or folder path in local or URL format. It also displays a button to pick a file or folder using the system's file chooser UI.

It will create a parameter and pipeline variable of type String.

filechooser
type	filechooser
label	text to display as label at the very left
persistent	when true, current values are saved to the pipeline document and re-loaded when the document is next opened when false, the value is not stored in the document and is assigned the default value (if specified) when the document is next opened The default value is false.
default	the default value for the parameter, if newly created or persistent is false
description	the string specified here is displayed as tool-tip text in the UI when hovering over the input element and also used for descriptive messages when running in commandline mode
required	(only used in upCast commandline mode) when true, this means that specifying a value for this parameter is required to run the pipeline when false, that parameter is not required to be specified but instead, its default value should be used (if specified) or not be set at all if there is no default value The default value is true.
mode	open displays a chooser for opening file save displays a chooser for saving a file folder displays a chooser for picking a folder file-or-folder displays a chooser for picking a file or a folder
format	local converts the chosen filepath in local file naming convention url converts the chosen filepath to a URL
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.3. 

SourceFile {
    type: filechooser;
    label: "Source file:";
    persistent: true;
    mode: open;
    format: url;
}

creates a field with a button to call a file chooser. The pipeline variable created will be named SourceFile, and values the user inputs will be stored across document openings. The file chooser will allow the user to pick files only, and the result will be stored in URL format in the editable input field.

3.1.4. List of files or folders

This UI element creates a text field for entering a list of file or folder paths (one per line) in local or URL format. It also displays a button to add a file or folder using the system's file chooser UI at the end of the current list.

It will create a parameter and pipeline variable of type List consisting of one line each of the input field as String value (in the displayed order).

filelist
type	filelist
label	text to display as label at the very left
persistent	when true, current values are saved to the pipeline document and re-loaded when the document is next opened when false, the value is not stored in the document and is assigned the default value (if specified) when the document is next opened The default value is false.
default	the default value for the parameter, if newly created or persistent is false
description	the string specified here is displayed as tool-tip text in the UI when hovering over the input element and also used for descriptive messages when running in commandline mode
required	(only used in upCast commandline mode) when true, this means that specifying a value for this parameter is required to run the pipeline when false, that parameter is not required to be specified but instead, its default value should be used (if specified) or not be set at all if there is no default value The default value is true.
mode	open displays a chooser for opening file save displays a chooser for saving a file folder displays a chooser for picking a folder file-or-folder displays a chooser for picking a file or a folder
format	local converts the chosen filepath in local file naming convention url converts the chosen filepath to a URL
lines	the number of entries (=lines) of the text field in the display, the default is 4
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.4. 

inputFiles {
    type: filelist;
    label: "Source files:";
    persistent: true;
    mode: open;
    format: url;
    lines: 5;
}

creates an entry field for a list of file specifications where each single line corresponds to one list item, i.e. here: a file path. An empty line create a list item consisting of the empty string. The pipeline variable created will be named inputFiles, and values the user inputs will be stored across document openings. The file chooser will allow the user to add files only, and the result will be stored in URL format in the editable input field.

3.1.5. Popup menu

This UI element creates a popup menu to pick a single value among a set of pre-defined ones.

It will create a parameter and pipeline variable of type String holding the internal value (see internal-values property for details) representation of the currently selected item.

popup
type	popup
label	text to display as label at the very left
persistent	when true, current values are saved to the pipeline document and re-loaded when the document is next opened when false, the value is not stored in the document and is assigned the default value (if specified) when the document is next opened The default value is false.
default	the default internal value for the parameter, if newly created or persistent is false. The value here must be exactly one of the values specified in the internal-values property.
description	the string specified here is displayed as tool-tip text in the UI when hovering over the input element and also used for descriptive messages when running in commandline mode
required	(only used in upCast commandline mode) when true, this means that specifying a value for this parameter is required to run the pipeline when false, that parameter is not required to be specified but instead, its default value should be used (if specified) or not be set at all if there is no default value The default value is true.
values	a space- or comma-separated list of values to display in the popup and to pass into the pipeline variables
internal-values	a space- or comma-separated list of internal values. The value set on the pipeline variable is the one from this list whose index matches the selected option from the values property’s list of displayed values. Use this to use descriptive values in the displayed popup, while still getting short enum-type values in your variable. It also allows for easy localization of displayed values without having to change internal processing.
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.5. 

targetType {
    type: popup;
    label: "Target type:";
    persistent: true;
    default: "db4";
    values: "DocBook 4", "DocBook 5", "DITA";
    internal-values: "db4", "db5", "dita";
}

creates a popup with three entries, "DocBook 4", "DocBook 5" and "DITA". The pipeline variable created will be named targetType, and its value will be one of the values "db4", "db5" or "dita", and the value selection will be stored across document openings. The default value of the variable will be "db4" upon field creation.

3.1.6. Checkbox

This UI element creates a labelled check box to pick enable or disable (turn on or turn off resp. set to true or to false) a specific boolean-valued option.

It will create a parameter and pipeline variable of type Bool holding the boolean representation of the current state of the checkbox (true when checked, false otherwise).

checkbox
type	checkbox
label	text to display as label at the very left
persistent	when true, current values are saved to the pipeline document and re-loaded when the document is next opened when false, the value is not stored in the document and is assigned the default value (if specified) when the document is next opened The default value is false.
default	the default value for the parameter, if newly created or persistent is false, either true or false
description	the string specified here is displayed as tool-tip text in the UI when hovering over the input element and also used for descriptive messages when running in commandline mode
required	(only used in upCast commandline mode) when true, this means that specifying a value for this parameter is required to run the pipeline when false, that parameter is not required to be specified but instead, its default value should be used (if specified) or not be set at all if there is no default value The default value is true.
text	the checkbox’s label text next to the actual checkbox graphic
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.6. 

includeStyle {
  type: checkbox;
    label: "Option:";
    persistent: false;
    default: true;
    text: "Include style information";
}

creates a checkbox with text "Include style information". The pipeline variable created will be named includeStyle and will have the Boolean value true when the box is checked, false otherwise. The popup value selection will not be remembered across document openings. The default will be the option being checked (=on).

3.1.7. List of strings

This UI element creates a text field for entering a list of arbitrary, single-line strings (one per line).

It will create a parameter and pipeline variable of type List consisting of one line each of the input field as String value (in the displayed order).

list
type	list
label	text to display as label at the very left
persistent	when true, current values are saved to the pipeline document and re-loaded when the document is next opened when false, the value is not stored in the document and is assigned the default value (if specified) when the document is next opened The default value is false.
default	the default value for the parameter, if newly created or persistent is false
description	the string specified here is displayed as tool-tip text in the UI when hovering over the input element and also used for descriptive messages when running in commandline mode
required	(only used in upCast commandline mode) when true, this means that specifying a value for this parameter is required to run the pipeline when false, that parameter is not required to be specified but instead, its default value should be used (if specified) or not be set at all if there is no default value The default value is true.
lines	the number of lines of the text field, the default is 4
initialize-when	never | unset | always | <string> Defines parameter values setting and initialization behaviour when the pipeline is run as a sub-pipeline from within an External Pipeline Processor (see there for details); the default value is unset
hidden	when true, this control is not displayed. The default value is false.
locked	when true, this control's value cannot be edited as long as the pipeline has an edit-lock password defined and the edit lock is in effect. The default value is false.

Example 6.7. 

stylenames {
    type: list;
    label: "List of stylenames:";
    description: "list of Word style names to handle";
    persistent: true;
}

creates an entry field for a list of values where each single line corresponds to one list item. An empty line create a list item consisting of the empty string.

The order in which the parameters are defined determine the display order and the order of parameters in created Java code functions.

Example 6.8. 

Concatenating all individual parameter definition examples from above into one, the following Simple View for the pipeline would be created:

Name	ParameterDefinitions
Java symbol	kParameterDefinitionsParamName
Type	String
Value

Reset persistent values

This clears any currently stored persistent values in the pipeline document.

Tip

You should clear the values when you make significant changes to the paraneter definition and prior to saving the pipeline configuration for distribution to your customers, so they do not see your last, private settings you made during development for parameters having persistence turned on.

function finalize( $childFinalizationResult as Id ) as Id {
  variable $result as Id := $childFinalizationResult; // default: CONTINUE
  /* Return the Id TERMINATE when you want to terminate the pipeline, CONTINUE otherwise. */
  return $result;
}

function message-text() as String {
  variable $result as String := "";
  /* Return a non-empty message string to display an error dialog resp. write the error text to the log. */
  return $result;
}

$${basedir}/tasks/upcast.jar

$${basedir}/MyPipelineRoot/

Parameters will be described using the following typography:

Name gives the internal java.lang.String name of the parameter, which is used for storing in preferences files, and can be used in the Java API as String. However, in Java, the use of the Java symbol is highly recommended instead.

Java symbol names the Java constant definition for the parameter’s Name. All constants are defined in the class de.infinityloop.common.Params.

Type specified the recommended Java type to use when programming against the API. In the GUI version, that is taken care of automatically. Also, when using alternative interfaces like an Ant task, which allows only passing arguments as character strings, upCast tries to perform an appropriate cast. So you should make sure that the data you provide in these cases will be cast-able to the specified type, as otherwise the conversion will fail or produce incorrect results at runtime.

Value describes possible value ranges, supported keywords or other specifics about that parameter’s range.

The following parameters are available on all modules:

Active checkbox

When the "active" checkbox in the upper left corner of the module parameter pane is checked, the module is active in the pipeline.

During pipeline development, it is often useful to have several differently configured modules to switch between, or to have modules inserted in the pipeline that generate some sort of debug output. To quickly activate and deactivate a module without having to actually delete or insert it again into a pipeline, with this parameter, modules can be quickly temporarily disabled by unchecking it.

Deactivated modules are completely skipped during a pipeline run and impose only minimal overhead – actually, it’s just writing a line to the log file.

Name

Here, you can assign a meaningful name to a module instance. By default, modules’ names are their type, like "XSLT Processor" or "RTF Importer". However, when you have e.g. several XSLT processors in your pipeline, it is desirable to use more meaningful names, like "strip namespaces XSLT" or "TEI conversion transformation".

Export

When checked, this module is handled (exported) in a File > Export… function.

You can use this to set up a single upCast pipeline document in such a way that for export to Java code or an Ant task, only certain modules will be exported. This lets you use some module instances for debugging in the UI, which then won’t be part of an exported pipeline representation.

For the Export as XML… function, module elements will have an additional attribute export with value true or false, respectively. This allows you to decide in any custom post-processing of that pipeline export format whether you want to handle that module in a special way (like discarding it completely like the built-in export options Ant and Java source).

Initialization

This parameter lets you programmatically set module parameters as well as (dynamically) prevent running the module even when its active checkbox is checked. For this, you can write a custom UPL function initialize() by clicking on the Edit initialization code… button.

If the initialize() function returns EXECUTE (which is the default), the module is further executed.

If the initialize() function returns SKIP, the module’s action is not performed and the subsequent module in the pipeline (if there is one) is run.

If the initialize() function returns TERMINATE, the module’s action is not performed and additionally, further pipeline execution is aborted.

In the initialize() function’s body, you can run arbitrary UPL code. This code is run just before actually performing the module’s functionality. This function hook’s main intent is to give you the possibility to programmatically and dynamically set module parameters’ values based on e.g. pipeline variable values (which in turn may have been set through the Simple View or by an external parameter passed to the pipeline). This way, you can set a parameter that does not allow you to have variable references expanded, like popups or check boxes. Additionally, this function serves as a dynamically evaluated condition specifying whether to run the module or not (in contrast to the module’s static Active checkbox).

#namespace module "http://www.infinity-loop.de/namespace/upcast-realm/module";
#namespace pipeline "http://www.infinity-loop.de/namespace/upcast-realm/pipeline";
function initialize() as Id {
  $module:TableModel := $pipeline:tableType;
  return EXECUTE; /* run the module */
}

Finalization

This parameter lets you specify the condition under which further pipeline execution should be cancelled after running this module.

This parameter will only be evaluated (and therefore have any effect) if the module action was actually performed, or in other words: if initialize() did not prevent the execution of the module’s action by returning TERMINATE or SKIP.

Normally, pipeline execution continues with the following defined modules even if in the current one there was a warning or error. These messages are collected and then displayed in the final pipeline execution error dialog. However, sometimes this is not a desired behaviour. Specifically, when subsequent modules rely on the proper execution of their predecessors to produce usable or correct results or – even more importantly – to not cause harm to data integrity, it may be necessary to immediately stop further execution of the pipeline when some module produces an error.

You can specify the termination behaviour by using several pre-defined, often used conditions, or you even can specify a custom condition in UPL:

To edit the UPL code for the custom finalize() function, click the Edit finalization code… button. By returning the Id TERMINATE, you can request pipeline termination, and by returning CONTINUE as result you can request pipeline continuation.

The custom function takes as Id parameter the termination status of its child component if there is any, CONTINUE otherwise.

function finalize( $childFinalizationResult as Id ) as Id {
  variable $result as Id := $childFinalizationResult; // default: CONTINUE
  /* Return the Id TERMINATE when you want to terminate the pipeline, CONTINUE otherwise. */
  return $result;
}

Log filter

Sets the logging threshold for messages that the module accepts from children and produces itself (see the logging architecture description for details).

Some default filter expressions are available from the associated popup menu, however you are free to define your own customized filter expressions. The filter expression syntax is described here.

If set to inherit, the logging filter settings are governed by the module’s execution parent’s settings (that is usually the pipeline it is contained in).

Documentation

This is a free form text field for adding notes or documentation specific to this module instance. You can use HTML tags which are copied verbatim into the generated documentation for the pipeline (via File > Generate Documentation…).

Parameters belonging to specific modules are described in that module’s detailed description.

This module allows you to set some commonly used global variables easily for re-use in subsequent modules. It is therefore most useful as the first module in a pipeline.

You can set the global variables pipeline:SourceFile, pipeline:TemporaryItemsFolder, pipeline:DestinationFolder, pipeline:ImageDestinationFolder and pipeline:DebugFolder.

The effect of using this module in API mode is the same as using UpcastEngine.setPipelineVariable().

All parameters have a type of java.lang.String.

Custom pipeline variables

Here, you can specify additional global values for use in subsequent modules. The definitions herein are processed after the fixed global parameters described above are evaluated and set, so you can refer to them using the usual ${pipeline:…} variable reference. A parameter definition must follow this syntax:

varname’:=’ ‘"’ value ‘"’;

Quotes within the variable value must themselves be quoted using the backslash character ‘\’.

This importer module handles conversion from RTF to the internal, unified upCast format, the upCast Internal DTD. With WordLink enabled, the filter also can convert Word binary files (*.doc).

Parameters are grouped logically into tabs:

General

Source file

Specify the source file in RTF or, if WordLink is available, in Word binary format that should be imported.

Hoist common inline properties to parent

If enabled, any inline formatting CSS property that extends and has the same value over all children of a paragraph-level element will be hoisted to its parent object as a style override. Effectively we’re making use of CSS inheritance and optimize the output by specifying that particular property only once on the parent instead of on each of its child elements.

Remove empty inlines

If enabled, any inline style specifications that do not contain any #PCDATA or similar, visually rendered content, are discarded from the document.

The default for this parameter is off based on the assumption that you may want to keep e.g. formatting information for empty cells so that a user may later fill in text and has the correct, originally intended formatting information available at that document location.

Allow ‘class’ and ‘style’ attributes simultaneously on <inline> elements

When on, this option allows that both a class and style attribute may be present on an element. Otherwise, the two are separated and an anonymous inline element is created for the style attribute instead.

Option checked:

This is <uci:inline uci:class="slang" uci:style="color: blue;">True Blue</uci:inline>.

Option unchecked:

This is <uci:inline uci:class="slang"><uci:inline uci:style="color: blue;">True Blue</uci:inline></uci:inline>.

You might want to use this option to have named Word styles always separated out in a dedicated element so that additional override styles can be recognized quickly by the additional inline element.

Markup revision tracking using <inserted> and <deleted>

When this is checked, document revisions are marked up in the result using the inserted and deleted elements.

If this is off, only the result of the revisions will be exported, i.e. inserted content remains in the document and deleted content is removed.

Use CSS for forced pagebreaks (where possible)

When checked, the importer tries to use CSS code for specifying forced pagebreaks wherever possible by using the pagebreak-before: always property/value combination.

If this is off, a pagebreak element will always be used.

Apply list structuring heuristics

If checked, special list structure detection algorithms are performed to create the best logically structured XML output. If unchecked, Word’s internal list IDs are used to track where a list starts and ends and where a new one begins, which may (based on the editing history of a particular list) have virtually no resemblance to what you are actually seeing in the layout.

The default value is on.

Flatten list structures

If checked, list/item element structures are not created. Instead, all elements that would constitute list item contents get the respective info attached as attributes:

Additionally, the following list-specific properties are copied onto each of the (virtual) list item's content elements:

The default value of this parameter is off.

Flatten options

Here you can control some additional aspects of list flattening:

Default font size

Some RTF documents do not specify a default font size for their text content, but rely on the default of the rendering application (like Microsoft Word). This parameter lets you set the default font size for such documents.

Microsoft Word applications up to and including Word 97 used a default value of 10pt, Word 2000 and later use a default of 12pt. When you set this parameter to * (i.e. automatic), upCast tries to guess from the RTF symbols it finds in the document whether it is a Word 2000 (or later) document and then will use 12pt as default font size, 10pt otherwise.

Note handling options: Marker mismatch handling

This option lets you specify what should happen when the reference marker to a footnote, endnote or annotation in the body text of the document does not match the marker within the footnote, endnote or annotation definition itself:

The RTF Importer uses pre-defined Word character styles ("footnote reference", "endnote reference", "annotation reference") to find the marker information in a footnote, endnote or annotation definition, respectively. In normal usage patterns of the Word application, the setting of these styles is automatic and correct. However, when markers are edited manually in a footnote definition (and not paying attention), the marker-identifying style may be inadvertently applied also to some or all of the footnote contents. Since upCast tries to automatically remove the marker portion from the footnote definition (since that info is usually (re-) created at the final output/rendering stage), a wrong setting of the respective character styles may lead to actual footnote content getting lost. Such authoring mistakes are usually detected by checking if the reference marker text in the document body is the same as the marker in the definition that the RTF Importer detects based on the special character style settings. Issuing an error when that text is different alerts the user that there's probably something wrong with the document that needs checking and/or fixing in order to not lose any content.

Note handling options: Marker in note definition

This option lets you specify what should happen with any (repeated) marker text in the actual footnote definition:

Literal pass-through styles

If checked, you can specify a set of (Word-) styles, separately for the paragraph style and the character style category, by specifying their exact names which should be treated as literals. This means that all text in the document set using these styles will be written to the output without any interpretation by upCast. This lets you write e.g. XHTML or XML code directly within your document the way it should appear at that location in the output.

Paragraph style names

When Literal pass-through styles is on, specify here the list of paragraph styles that should be treated as literal content indicators. Enclose the names of the styles in double-quotes, separate styles by a space character.

Character style names

When Literal pass-through styles is on, specify here the list of character styles that should be treated as literal content indicators. Enclose the names of the styles in double-quotes, separate styles by a space character.

Images

Include images

When checked, images contained in the document are processed as configured by the image processing parameters. If unchecked, all images of the source document will be completely discarded from the document.

Temporary images folder

This is the location where images in a read document will be temporarily stored while the pipeline is processed. It is e.g. the responsibility of an exporter to copy images intended to be permanently saved across a pipeline run to a different location.

Use inline copies instead of referenced original images (if available)

When this option is checked, for images that have been included in the RTF document using both methods, by reference and by embedding, the module will try to use the embedded substitute representation. This option essentially breaks the link to the original image file, if a substitute representation has been embedded in the RTF file, and instead links to the embedded representation of the original file.

When an image has only been linked and no substitute representation is available in the RTF, however, the original link to the image is preserved and used.

Incoming images default resolution

This parameter determines the image resolution in dpi (dots per inch) to use for embedded images that do not specify their resolution explicitly. This is true for all (originally) GIF images and some variants of JPEG and PNG images.

Without any dpi information, the RTF importer (and, as a matter of fact, even Word) cannot determine the absolute size of images, which is necessary to create a fully specified export file. This parameter is then used to establish a default dpi value and corresponds roughly to Word’s Web Options > Image resolution setting.

When setting this to the default ‘*’ value, the RTF importer determines the absolute size of the image from the image properties in the RTF document (if available) and modifies the embedded image data by adding the resolution determined from the (absolute size/number of pixels)-pair to the externalized image. This ensures that subsequent processors can correctly determine absolute sizes and scale any images accordingly.

Outgoing images rendering resolution

This value affects the WMF to pixmap renderer built into the RTF Importer. This means that WMF (or EMF) images will be rendered into a pixmap with pixel dimensions for width and height that correspond to this value.

The default value is 96 dpi (used e.g. by Microsoft’s Internet Explorer™). You may want to change this when outputting for Netscape Navigator 4.7 on the Mac, which by default displays at 72 dpi and therefore would downscale images written using 96 dpi resolution.

Suppose you have a WMF image in your document that is 2 by 1 inches in size. With 96 dpi output resolution, this will yield a pixmap of size 192 by 96 pixels.

However, if you set the output resolution to only 72 dpi, the resulting pixmap will be 144 by 72 pixels in size.

Export embedded images of type…

While exporting embedded images, you have the option to convert them to a different format.

The RTF Importer includes a custom WMF to pixmap renderer fully programmed in Java. It is neither intended nor recommended for production quality image conversion! To perform high-quality image conversion, we strongly encourage you to consider specialized third-party products. Nevertheless, the built-in renderer is useful and intended for producing draft image renderings for viewing in a web browser or creating documents for editorial review and should perform well enough for most purposes except final publishing.

Embedded images in an RTF document can be of several image format types: WMF, EMF, JPEG, PNG and Macintosh PICT. The RTF importer lets you specify a handling method for each of these formats, so you can e.g. use already pixel based images like JPEG or PNG unchanged while rendering vector formats like WMF into a pixel-based representation.

The following handling methods are available (some of which are not applicable to all source formats):

When using the option external cmd, two additional parameters can be set:

This works as follows: The file to be converted is available at the location in imgsrc#local. The RTF importer then constructs a target file name, using the source file name as basis, but setting the extension to the one specified. Since the RTF importer needs to know the final resulting filename for referring to the externally converted image in the internal document tree, but there is no way to return a string from a shell command easily (just an integer return code), it prescribes the target file name itself. This is what the variable imgdest#local is for. You must make sure that the final, processed image file is available at the location contained in that specific variable.

Objects

These parameters specify how embedded objects (OLE) should be handled. The RTF importer generates an uci:object element for each embedded object it finds in the RTF. The child elements of this container object are alternative representations of the object’s data. This can can be an uci:image (if available in the source document: represents the current display of that object at the time of saving the document), or an uci:ole element (if available: it contains a base64 representation of the binary data of the OLE object, which makes it possible to reconstruct it to an editable instance using the RTF exporter).

Include image representation

When checked, an image representation alternative will be added to the object element (if available in the source document).

Embed binary OLE object data as base64-encoded text

When checked, an uci:ole binary data representation alternative will be added to the object element. The uci:ole element contains the base64-encoded binary data as character data.

Extract object from OLE object and serialize to file

When checked, an uci:extobject element within the uci:object element is written with the following attributes:

Currently, the following OLE CLSIDs are supported for externalization:

If the OLE object is of some type that is not explicitly supported, a warning is issued to the logging system and the object (unwrapped from the embedded OLE object in the Word document) is written to the file. Note that in most cases, you will not be able to use that file with the application that originally created the OLE, as the data structure of such objects is proprietary to that application and extracting the correct portion of the data from the OLE object requires knowledge of that particular application's OLE file format.

Include MathML representation

When MathLink is available, i.e. you have Design Science‘s MathType software (version 5.2) installed on your Windows system and are running upCast on that same machine, for MathType OLEs, you can also embed a MathML representation of your formula in the object element as m:math element.

WordLink

Set WordLink features.

Mode

When Process .doc files only is selected, WordLink and all options specified will only be applied to Word binary (*.doc) files.

When Process all files is selected, WordLink and all options specified will be applied to any input document, i.e. even files that are in RTF format already. This lets you automatically update fields or add pagestart and linestart elements.

Run macro named „il_premacro"

When checked, WordLink will first run a Word macro named il_premacro on the source document. This macro must either be defined in the respective document (when it is a Word binary .doc file) or in the global document template file (*.dot).

When this macro is not available, an error will be issued after conversion, though the further conversion process is not affected.

Update fields

When checked, WordLink will update any fields in the source document with current values: date, time, pages, …

Update from linked images

When including an image only by reference (i.e., using Word’s INCLUDEPICTURE field), the RTF importer is not able to determine the actual image size as that information is not part of RTF. By checking this option, the linked image is temporarily included into the document with the effect that image size and possibly applied scaling in the .doc Word binary file can be evaluated by the importer.

This feature is not beneficial for RTF source files, as in these the necessary information is already lost (also for Word).

Mark up layout page breaks using <pagestart />

This inserts a <pagestart /> empty inline element at those places where in current layout flow, there would be a dynamic page break when rendering the document.

Mark up layout line breaks using <linestart />

This inserts a <linestart /> empty inline element at those places where in current layout flow, there would be a dynamic line break when rendering the document.

Kill timeout

When hitting a corrupt document, WordLink may have problems and/or hang the application. Therefore, you can set a kill timeout value after which the WordLink functions will be aborted. The default value is 300 seconds.

Copy temporary .rtf file to debug folder as "basename-tmp.rtf"

This is mainly for debugging purposes. It copies the intermediate RTF file to the specified debug folder with a name of basename-tmp.rtf after having applied all WordLink functions. This is the file that the RTF importer itself takes as source for its actual conversion process.

This module lets you run a program written in the Upcast Processing Language (UPL).

The single context node for all UPL code in this module is the document root node (XPath: / ). Note that this is different from the document root element!

UPL code

This contains the UPL code you want to execute. The code must define a function main() as follows:

function main() as Value {
   ... your code goes here ...
}

The UPL Processor calls this function main() once when it runs and executes the code defined therein (or in any dependent, user-defined functions). For a detailed description of UPL, see the separate documentation, Upcast Processing Language.

The returned result of the function is stored into the pipeline variable ModuleResult.

UPL parameters

This contains the assignments for variables to be passed to the UPL program. For a detailed description of how UPL receives parameter values, see the separate documentation, Upcast Processing Language.

A parameter definition must follow this syntax:

paramname ':=' '"' value '";'

Quotes within the parameter value must themselves be quoted using the backslash character ‘\’.

This module differs from the UPL Processor in that it does not call a single function once, but you can define code to be run upon visiting each node of the current internal document in a depth-first traversal, depending on certain conditions you specify.

UPL code

This contains the UPL code you want to execute. For a detailed description of the UPL, see the separate documentation, Upcast Processing Language.

UPL parameters

This contains the assignments for variables to be passed to the UPL program. For a detailed description of how UPL receives parameter values, see the separate documentation, Upcast Processing Language.

A parameter definition must follow this syntax:

paramname ‘:=’ ‘"’ value ‘"’;

Quotes within the parameter value must themselves be quoted using the backslash character ‘\’.

Grouper

When turned on, the grouping algorithm will be run on the internal tree. This will be before the finalize() or finalize-error() UPL method is called.

Grouping processing order

This parameter lets you set the order of the colors in which the grouping should be performed.

With all colors in alphabetical order, all colors that have been used for setting painters or tags are grouped in alphabetical order of the color name. The ordering is the same as the Java class java.lang.TreeSet uses by default on the platform you are running upCast on.

With colors in specified order, then all remaining:, you can specify a list of colors you want to be grouped in a given order before all others in the text field below, with any remaining ones being grouped in alphabetical order (see all colors in alphabetical order) afterwards.

With only these colors in specified order, you can specify the colors and their order of grouping in the text field below. No other colors will be grouped, even if respective painters or tags have been placed on nodes in the internal document tree.

After a run of the grouper, all painters, tags and paintings of nodes are removed from the internal tree. This means that any further grouper instances running after a grouper has already run will have no effect unless new painters and tags have been placed on nodes of the internal document tree, usually using the UPL processor.

Color order is specified by listing the colors in sequence, separated by whitespace. If a color name includes whitespace (which is deprecated), the full color name must be enclosed in double quotes.

Element Splitter

When turned on, any split actions attched to nodes using mark-split() in the internal tree will be executed. This will be after running the grouper (if enabled), but before the finalize() or finalize-error() UPL method will be called.

The Sectioner module is used for creating a nested, deeper structure based specifically on elements that have a heading level set (via set-heading-level() in UPL), and uci:part elements that have the grouping property set (via set-grouping() in UPL).

Sectioning works only on the direct children of the uci:body element in the upCast Internal DTD.

…
<part is-grouping="true"/>
<par>…</par>
<par>…</par>
<part is-grouping="false"/>
<par>…</par>
<part is-grouping="true"/>
<par>…<par>
…

…
<part is-grouping="true">
    <par>…</par>
    <par>…</par>
    <part is-grouping="false"/>
    <par>…</par>
</part>
<part is-grouping="true">
    <par>…<par>
…

<par>…</par> 
<par heading-level="1">…</par>
<par>…</par>
<par heading-level="2">…</par>
<par>…</par> 
<par heading-level="4">…</par>
<par>…</par> 
<par heading-level="3">…</par>
<par>…</par> 
<par heading-level="1">…</par>
<par>…</par>

<par>…</par>
<section level="1">
  <par heading-level="1">…</par>
  <par>…</par>
  <section level="2">
    <par heading-level="2">…</par>
    <par>…</par>
    <section level="3">
      <section level="4">
        <par heading-level="4">…</par>
        <par>…</par> 
      </section>
    </section>
    <section level="3">
      <par heading-level="3">…</par>
      <par>…</par> 
    </section>
  </section>
</section>
<section level="1">
  <par heading-level="1">…</par>
  <par>…</par>
</section>

<par heading-level="1">…</par>
<par>…</par>
<table>…</table>
<par>…</par>
<par heading-level="2">…</par>
<par>…</par>

<section level="1">
  <sectionintro>
    <par heading-level="1">…</par>
    <par>…</par>
    <table>…</table>
    <par>…</par>
  </sectionintro>
  <section level="2">
    <sectionintro>
      <par heading-level="2">…</par>
      <par>…</par>
    </sectionintro>
  </section>
</section>

<section level="1">
  <sectionintro>
    <par heading-level="1">…</par>
    <par>…</par>
    <table>…</table>
    <par>…</par>
  </sectionintro>
  <section level="2">
    <par heading-level="2">…</par>
    <par>…</par>
  </section>
</section>

The Grouper module actually performs a grouping that has been earlier specified during a run of an UPL Tree Processor.

Grouping processing order

This parameter lets you set the order of the colors in which the grouping should be performed.

With all colors in alphabetical order, all colors that have been used for setting painters or tags are grouped in alphabetical order of the color name. The ordering is the same as the Java class java.lang.TreeSet uses.

With colors in specified order, then all remaining:, you can specify a list of colors you want to be grouped in a given order before all others in the text field below, with any remaining ones being grouped in alphabetical order (see all colors in alphabetical order) afterwards.

With only these colors in specified order, you can specify the colors and their order of grouping in the text field below. No other colors will be grouped, even if respective painters or tags have been placed on nodes in the internal document tree.

After a run of the grouper, all painters, tags and paintings of nodes are removed from the internal tree. This means that any further grouper instances running after a grouper has already run will have no effect unless new painters and tags have been placed on nodes of the internal document tree, usually using the UPL processor.

Color order is specified by listing the colors in sequence, separated by whitespace. If a color name includes whitespace (which is deprecated), it must be enclosed in double quotes.

This module imports any XML document into the internal tree variable, replacing any existing document. This is useful when you want to apply some of the specific UPL functions on it and need not rely on styling info (which is currently not imported/recognized and cannot be created within upCast).

Source File

This parameter lets you choose the source XML file to import.

Discard ignorable whitespace

If the document to be imported has a DOCTYPE declaration associating a DTD with the document, the parser can identify ignorable whitespace. When this parameter is checked, ignorable whitespace will be discarded from the internal tree.

External DTD subset fallback

This parameter lets you choose a fallback for the external DTD subset for the imported document. This is useful if you want to import an XML document that does not have a DOCTYPE declaration, but you have an XML DTD that you know the imported document must satisfy. Specifying the external DTD subset here (DTD file) allows you to supply that info to the parser, which in turn may use that info to determine which whitespace is ignorable in the imported document.

Essentially, specifying a file here has the same effect as if the imported XML document had a

<!DOCTYPE root SYSTEM "specified-file">

declaration, unless it explicitly specifies a DOCTYPE declaration of its own.

Attach locator info

When checked, each element node of the imported document will get attached the following set of attributes:

All values are 1-based.

This module serves for serializing the internal tree to XML. It offers a choice for the table model to write (internal, HTML or CALS), debugging and pretty-printing options. It also offers choices for handling images in the document (separate for referenced/linked images and embedded images) and you can use a Unicode Translation Map.

General

Destination File

Choose the full filename into which the result should be written. You can use upCast’s variables for building the path.

Output resolution

Specify the output resolution in dpi. This value is used for calculating device pixel values, e.g. in HTML tables’ cell widths or images’ sizes.

Output file encoding

Lets you specify the encoding in which the XML file will be written. If your further tool chain allows it, we strongly recommend to use the default, UTF-8.

Table model

This parameter lets you choose which table model to use for tables. You can either choose the native (upCast) table model, which is a very simple table > row > cell model, the HTML 4 table model, or the OASIS-EM (CALS) (OASIS XML Exchange Table Model, a subset of CALS) table model.

The HTML 4 table model uses the HTML namespace http://www.w3.org/HTML/1998/html4, the CALS table model uses the special, proprietary namespace http://www.infinity-loop.de/namespace/2006/upcast-cals.

Style information

Lets you specify how general CSS styles for known elements and named styles for paragraphs and inline elements should be exported. Options are:

Include generator info as comment

When checked, adds info about when and by which version of upCast the XML file was produced to that file as an XML comment. This may be useful both for infinity-loop support during trouble shooting and for you, when you need to relate some produced XML files to a certain version (in time) of your pipelines.

Wrap individual Text nodes with element <uci:text>

When checked, each single Text node in the internal DOM tree will be surrounded by an <uci:text> element on serialization. That element is also the carrier for the uci:node-id attribute for the original Text node's id as obtained from the generate-id() XPath function when called on that node.

Serialize node id as attribute @uci:node-id

When checked, each serialized element automatically receives an additional attribute uci:node-id, holding the value obtained by calling generate-id() on that element.

Pretty-print output

Turns on pretty-printing the output for elements whose whitespace handling mode is known explicitly to the serializer.

Images

During import, e.g. using the RTF importer, all references to images are made absolute and stored this way in the internal tree as follows:

Embedded images are written to disk into a temporary location and possibly a format conversion is applied. The internal tree at this point holds the absolute path to these temporary image files.

Linked (or referenced) images are stored with their absolute path to the original image; no matching files for linked images are created in the temporary image files location.

At export time, you can decide how the image location information (and possibly the actual image files) should be handled. The handling mode can be set individually for images that were embedded in the original document and (external) images that were only linked to.

Embedded Images

This parameter governs the handling of images that originally had been embedded in the source document.

Referenced images

This parameter governs the handling of linked (referenced) images in the original source file.

Image Destination Folder

You can specify a separate folder dedicated for images. By default, this is set to ${module:DestinationFile#urlpath}, which evaluates to the same folder where the XML file is saved. However, if you want to put images into a separate folder, you can do this here. This is the folder where any of the above options that physically copy the image file will place the file. Any relative references to the image from within the XML file will be adjusted accordingly.

Filter

The nodes in the internal tree may have a very rich set of attributes attached, many of which have only been useful while processing the tree within upCast, e.g. with UPL. Serializing all those attributes may create huge files, where only a fraction of the info contained will be used down the further processing chain of the document. To reduce unnecessary memory consumption and processing time, the XML Exporter offers a way to set up a filter on the attributes serialized for each internal tree node. This is achieved by using a specially formed UPL program in conjunction with the dedicated filtering function filter-attrs().

Attribute Filter

This field holds the UPL program to perform the filtering.

As in the UPL Tree-Processor, you can define several UPL rules. The selector part determines for which kind of node (and possibly more complex conditions) the attribute filter applies. This lets you filter attributes differently on different elements.

The action part is applied, when the selector matches. Although theoretically, you can use the complete range of UPL functionality on such a node, many changes to the node will not be picked up by the serialiazer (except for changes in the node’s attributes), so we recommend against using this UPL program for other things than filtering attributes.

It is important to understand how the context node supplied to the UPL program looks like:

The filtering UPL code is not called for nodes of other DOM node types than Element.

Clicking the Insert defaults button inserts the current upCast default filter setup for new XML Exporter instances before any existing code in the Attribute Filter text field.

Maps

Unicode translation map

This field lets you enter a Unicode Translation Map. You can enter any mappings directly or include an externally created Unicode Translation Map file using the include realm: ${include(encoding="…"):file}.