The logo is a pig framed between two angle brackets.

XProc 3.0 Tutorial

The XProc Processor

To execute an XProc pipeline, you need an XProc processor. The XProc processor reads the input data and the XProc pipeline, executes the pipeline and generates the output data.

For XProc 3.0 there exist two XProc processors:

  • The MorganaXProc-III processor implements all required features of the XProc 3.0 spec.
  • The XML Calabash processor is currently under development. The current version is only capable of running XProc 1.0.

This tutorial will focus on the use of MorganaXProc-III although all lessons could be done using any other XProc 3.0 compliant processor. Documentation about XML Calabash will be added when the processor is completed.

Download MorganaXProc-III

You can download MorganaXProc-III via Sourceforge. Download the zip file and unzip it to a directory on your hard drive. MorganaXProc requires Java to run, so please check whether Java is installed on your system:

$ java --version

Output

java 20.0.1 2023-04-18
Java(TM) SE Runtime Environment (build 20.0.1+9-29)
Java HotSpot(TM) 64-Bit Server VM (build 20.0.1+9-29, mixed mode, sharing)

Run MorganaXProc-III

The easiest way to call MorganaXProc from the command line is to use a batch file. After unzipping, you’ll find two batch files: Morgana.bat for Windows and Morgana.sh for MacOS and other UNIX-based operating systems. MorganaXProc includes an XProc pipeline (pipeline.xpl) in the same directory.

For Windows, you can call MorganaXProc-III like this:

$ cd c:\myMorganaXProcDir
$ ./Morgana.bat pipeline.xpl

For users of MacOS, Linux and other UNIX-based operating systems:

$ cd /users/myName/myMorganaXProcDir
$ sh Morgana.sh pipeline.xpl

Output

Hello world. This is an XProc 3.0 pipeline running.

Specifying Inputs and Outputs With MorganaXProc-III

Typically you want to bind inputs and outputs to files and specify options on the command line. The order of command line parameters expected by MorganaXProc is as follows:

  • pipeline path
  • port declarations (zero or more)
    -input:myportname=myfile.xml (if you want to pass multiple documents to a port, just add another -input)
    -output:myportname=myfile.xml
  • options (zero or more)
    -option:myoption=myvalue
  • switches (optional)
    -switchname -switchname2

Here are some helpful switches:
-no-run → don’t run the pipeline, just check if the syntax is correct
-debug → print more details on the executed pipeline
-graph → print the pipeline execution graph
-warning-recorder → see non-XProc warnings, e.g. from XSLT, Schematron etc.

Please see below an MorganaXProc call as example passing two input ports named source and images and one output port entitled result. The option my-option=my-value and the -debug switch are the other arguments:

$ ./Morgana.sh pipeline.xpl -input:source=my-input.xml-input:images=my-images.xml
    -output:result=my-output.xml -option:my-option=my-value -debug

If we want to pass multiple documents to one input port to MorganaXProc, we just replicate the input port parameter:

$ ./Morgana.sh pipeline.xpl -input:source=my-text.txt -input:source=my-text2.txt

If you experience any issues, MorganaXProc-III offers an extensive user manual to aid you with the various command line parameters and configuration options.

Read more…

▲