XEP ANT Task 2.0 User's Guide

1. Changes since version 1.*

XEP Ant Task now uses the new RenderX XEP API, introduced in XEP 3.7.

2. Overview

XEP task uses RenderX XEP XSL Processor to format XML documents to a printable format - PDF or PostScript. It requires XEP 3.7 or later 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 XEP edition. In some editions, PostScript generator is not available.

3. Configuration

The user must configure XEPTask to use it with Ant:

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

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

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

4. 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, target file name is created by appending its relative path (as specified in <fileset>) to this directory, and changing 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 is 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

XEP Ant Task can be applied:

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

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

If an XSLT stylesheet is set using 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.

5. Parameters specified as nested elements

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

classpath

Classpath used to load XEP. The user should set it to match existing XEP installation.

sysproperty

Java system property com.renderx.xep.CONFIG sets the location of XEP 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. Value of this parameter is interpreted as an Ant expression. To pass a text value to the stylesheet, enclose it into single quotes.	Yes

6. Examples

Note:

In all examples below, we assume that a classpath entry with id="xep-classpath" is available inside of build.xml, and that XEP 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 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>