Chapter 1 of the IREn ANT Task User's Guide

ANT Task 2.0 User's Guide

Changes since version 1.*

The ANT Task now uses the new RenderX engine API, introduced in XEP 3.7.

Overview

The task uses the RenderX IREn XSL processor to format XML documents to a printable format — PDF or PostScript. It requires XEP 3.7 or later to be installed and properly activated.

The task can operate either on a single file or on a file set. Input documents are either XSL-FO instances, or generic XML files with associated XSLT stylesheets.

Note: Availability of output formats depends on the engine edition. In some editions, the PostScript generator is not available.

Configuration

The user must configure XEPTask to use it with Ant:

Configure the task entry in build.xml, using <taskdef>. Here is a typical code snippet that is placed at the prolog of build.xml to activate the task:
```
<taskdef name="xep" classname="com.renderx.xepx.ant.XEPTask"
         classpath="XEPTask.jar/>
```
Refer to Ant documentation for details.

Create a classpath reference for the task. It must include all JARs that the engine uses, plus XEPTask.jar itself. A typical classpath entry looks like the following:

<path id="xep-classpath">
		<fileset dir="C:XEPlib">
			<include name="xep*.jar"/>
			<include name="xt.jar"/>
			<include name="saxon.jar"/>
		</fileset>
	<pathelement path="XEPTask.jar"/>
</path>

Parameters

Attribute	Description	Required
`in`	Specifies a single XML document to process.	Either `in` or a nested `<fileset>` element must be available
`out`	Used with `in`, specifies the file name for the formatted document.	No
`destDir`	Used with nested `<fileset>` element(s), specifies a destination directory for the formatted documents. For each file in the set, the target file name is created by appending its relative path (as specified in `<fileset>`) to this directory, and changing the file extension to match the selected output format. By default, the formatted documents are stored in the sources' directories.	No
`overwrite`	True or False. When "true", the task reformats all documents on each invocation. When "false", the documents are only overwritten if either the source or the stylesheet are newer than the output. If the stylesheet is not local, there is no reliable way to determine its modification date; such stylesheets are treated as if they are never modified. By default, all documents are reformatted.	No
`style`	XSLT stylesheet to apply to source XML documents, either a pathname or a URL. If it is not available, input files are assumed to be XSL-FO documents.	No
`format`	Output format. Possible values: `PDF`, `PostScript`, `XEP`. Important: format identifiers are case-sensitive!	Yes

The ANT Task can be applied:

to a single file, specified by the in attribute;
to a batch of files, selected using nested <fileset> elements.

These modes are mutually exclusive: if the in attribute is available, the task will process a single file and ignore all nested <fileset> specifiers.

If an XSLT stylesheet is set using the style attribute, the task will apply it to all input files. Without a stylesheet, the task will attempt to format the files as though they are XSL-FO documents.

Parameters specified as nested elements

The following nested elements can appear inside of the task entry.

classpath — Classpath used to load the engine. The user should set it to match the existing installation.

sysproperty — The Java system property com.renderx.xep.CONFIG sets the location of the engine configuration file.

fileset — Files to process. Multiple nested <fileset> elements are allowed.

param — XSLT parameters.

Attribute	Description	Required
`name`	XSL parameter name	Yes
`expression`	Ant expression assigned to the parameter. The value of this parameter is interpreted as an Ant expression. To pass a text value to the stylesheet, enclose it into single quotes.	Yes

Examples

Note: In all examples below, we assume that a classpath entry with id="xep-classpath" is available inside of build.xml, and that the formatter is installed in C:\XEP.

Basic case — render an XSL-FO document to produce PDF:

<xep in="mydocument.fo" out="mydocument.pdf" format="PDF">
	<classpath refid="xep-classpath"/>
	<sysproperty key="com.renderx.xep.CONFIG" value="C:/XEP/xep.xml"/>
</xep>

Transform and render a single XML document to PostScript, passing parameters to the stylesheet:

<xep in="mydocument.xml" out="mydocument.ps"
                style="stylesheets/mystyle.xsl" format="PostScript">
	<classpath refid="xep-classpath"/>
	<sysproperty key="com.renderx.xep.CONFIG" value="C:/XEP/xep.xml"/>
	<param name="date" expression="13-01-2003"/>
	<param name="time" expression="15:33"/>
</xep>

Render a set of XSL-FO documents to PDF; put formatted documents into the same directories as the source files:

<xep format="PDF">
	<classpath refid="xep-classpath"/>
	<sysproperty key="com.renderx.xep.CONFIG" value="C:/XEP/xep.xml"/>
	<fileset dir="./mydocs/src">
		<include name="*.fo"/>
	</fileset>
</xep>

Transform and render a set of XSL-FO documents to PostScript; pass one parameter to the stylesheet; put formatted documents into a separate directory:

<xep destDir="postscript" style="docbook.xsl" format="PostScript">
	<classpath refid="xep-classpath"/>
	<sysproperty key="com.renderx.xep.CONFIG" value="C:/XEP/xep.xml"/>
	<param name="title-color" expression="'red'"/>
	<fileset dir="docbook">
		<include name="*.dbx"/>
	</fileset>
</xep>