Getting Started

There are no further prerequisites as are required to run XProc. If you are not familiar with XProc 1.0, we suggest to work yourself through Roger L. Costello’s ➼ XProc tutorial first. We're planning to move transpect to XProc 3.0 soon, so you could skip version 1.0 and read our Martin Kraetke's ➼ XProc 3.0 tutorial as well.

XML Calabash

We recommend to use our pre-configured XML Calabash for running transpect’s XProc pipelines. It includes convenient frontend scripts and extensions steps which are essential to some modules.

Java

XML Calabash needs Java 1.7 and later to run. We noticed some odd behaviour while running XML Calabash with a JVMs other than Oracle. If you get memory issues, consider to install the 64-bit version.

Install XML Calabash

We recommend to use Git or SVN to checkout Calabash to take care that all dependencies are met. The calabash directory should be placed at the top-level of your project directory.

MyProject/
  |--calabash/
  |  |--calabash.sh
  |  |--calabash.bat

git clone --recursive https://github.com/transpect/calabash-frontend calabash

Optional: checkout XML Calabash with SVN

The SVN client of GitHub doesn't support SVN externals, so we have to get each module separately.

svn co https://github.com/transpect/calabash-frontend/trunk calabash
svn co https://github.com/transpect/calabash-distro/trunk calabash/distro

Some transpect modules depend on certain XML Calabash extensions, so you may want to get them, too.

svn co https://github.com/transpect/unzip-extension/trunk calabash/extensions/transpect/unzip-extension
svn co https://github.com/transpect/rng-extension/trunk calabash/extensions/transpect/rng-extension
svn co https://github.com/transpect/image-props-extension/trunk calabash/extensions/transpect/image-props-extension
svn co https://github.com/transpect/image-transform-extension/trunk calabash/extensions/transpect/image-transform-extension

Checkout the transpect modules

First, we have to checkout the modules with Git or SVN. For example, we want to get docx2hub:convert, which converts Microsoft Word to ➼ Hub XML. The docx2hub module depends on xproc-util and xslt-util.

git clone https://github.com/transpect/docx2hub
git clone https://github.com/transpect/htmlreports
git clone https://github.com/transpect/xslt-util
git clone https://github.com/transpect/xproc-util

Optional: checkout modules with SVN

svn co https://github.com/transpect/docx2hub/trunk docx2hub
svn co https://github.com/transpect/htmlreports/trunk htmlreports          
svn co https://github.com/transpect/xslt-util/trunk xslt-util
svn co https://github.com/transpect/xproc-util/trunk xproc-util

After we cloned XML Calabash and the transpect modules, our project directory should look like this.

MyProject/
  |--calabash/
  |--docx2hub/
  |--htmlreports/
  |--xproc-util/
  |--xslt-util/

Create an XML Catalog

Transpect uses canonical import URIs to import other modules. To resolve this URIs, our XML Calabash looks after an XML catalog in the project directory. Starting from the project dir, the path is usually xmlcatalog/catalog.xml. So you have to create the directory xmlcatalog and create a file named catalog.xml in this directory.

MyProject/
  |--xmlcatalog/
  |  |--catalog.xml

The XML catalog of the project is used to include the catalogs of the transpect modules. Therefore the nextCatalog element is used to connect the module catalogs. Edit the catalog.xml and add the following lines.

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <nextCatalog catalog="../docx2hub/xmlcatalog/catalog.xml"/>
  <nextCatalog catalog="../htmlreports/xmlcatalog/catalog.xml"/>
  <nextCatalog catalog="../xproc-util/xmlcatalog/catalog.xml"/>
  <nextCatalog catalog="../xslt-util/xmlcatalog/catalog.xml"/>
</catalog>

Command line

After we are included transpect in our project, we can run the docx2hub:convert pipeline to convert a Microsoft Word DOCX file to ➼ Hub XML. Users of Linux, Mac OS X or Cygwin can use a convenient Bash script:

./calabash/calabash.sh -o result=MyXMLfile.xml docx2hub/xpl/docx2hub.xpl docx=MyWordfile.docx

There exists also a Batch file for Windows users:

.\calabash\calabash.bat -o result=MyXMLfile.xml .\docx2hub\xpl\docx2hub.xpl docx=MyWordfile.docx

Include in your pipeline

You can import and use transpect modules in your own XProc pipelines. Therefore, you need to declare the namespace and add the p:import statement of the XProc step you want to use. Here is a simple XProc pipeline which implements docx2hub:convert.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" 
  xmlns:docx2hub="http://transpect.io/docx2hub"
  version="1.0">
  
  <p:output port="result"/>
  
  <p:option name="docx"/>
  
  <p:import href="http://transpect.io/docx2hub/xpl/docx2hub.xpl"/>
  
  <docx2hub:convert name="docx2hub">
    <p:with-option name="docx" select="$docx"/>
  </docx2hub:convert>
  
</p:declare-step>

If you want to get a deeper insight into the transpect framework, we would recommend to read our Tutorials.

Getting Started

Learn how to use transpect

Prerequisites