1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<?xml version="1.0" standalone="no"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- $Id$ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd">
<document>
<header>
<title>Ant task</title>
<version>$Revision$</version>
</header>
<body>
<p>
FOP provides an Ant task for automating the document build process.</p>
<section id="basics"><title>Description</title>
<p>
The FOP Ant task will convert XSL-FO documents to PDF/PS/PCL/MIF/RTF output
(see <link href="output.html">Output formats</link> for available formats).</p>
<p>
To call FOP tasks within Ant, first add a FOP task definition to your Ant build file.
One method of defining the task is as follows:
</p>
<source><![CDATA[
<property name="fop.dir" value="....path to your FOP jar files..."/>
<taskdef name="fop"
classname="org.apache.fop.tools.anttasks.Fop">
<classpath>
<pathelement location="${fop.dir}\fop.jar"/>
<pathelement location="${fop.dir}\avalon.jar"/>
<pathelement location="${fop.dir}\batik.jar"/>
</classpath>
</taskdef>
]]></source>
<p>
Then create FOP tasks within your Ant build file, using the FOP task parameters listed below.</p>
</section>
<!-- TODO: Installation/Configuration -->
<section id="parameters"><title>Parameters for FOP Ant task</title>
<table><caption>Parameters specified as attributes</caption>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>fofile</td>
<td>XSL-FO file to be rendered</td>
<td>Yes, if no fileset nested element is used</td>
</tr>
<tr>
<td>outfile</td>
<td>Output filename</td>
<td>Yes, when fofile is used. (This attribute is not valid for filesets.)</td>
</tr>
<tr>
<td>format</td>
<td>Possible output formats:<br/>
<code>application/pdf</code><br/>
<code>application/postscript</code><br/>
<code>application/vnd.mif</code><br/>
<code>application/rtf</code><br/>
<code>application/vnd.hp-PCL</code><br/>
<code>text/plain</code><br/>
<code>text/xml</code><br/>
</td>
<td>No, defaults to <code>application/pdf</code></td>
</tr>
<tr>
<td>outdir</td>
<td>Output directory</td>
<td>Required if a fileset is used to specify the files to render; optional for fofile. (Can alternatively specify the full path in the fofile value.)</td>
</tr>
<tr>
<td>force</td>
<td>Recreate target files, even if they are newer than their corresponding
source files. Note: This attribute is available in post-0.20.5
versions (0.20.x nightly build and 1.0dev) only; target files are
always generated (i.e., force=true) in 0.20.5 release.
</td>
<td>No, default is <code>false</code></td>
</tr>
<tr>
<td>basedir</td>
<td>Base directory to resolve relative references (e.g., graphics files) within the
FO document.
</td>
<td>No, for single FO File entry, default is to use the location
of that FO file.
</td>
</tr>
<tr>
<td>relativebase</td>
<td>For fileset usage only. A value of <code>true</code> specifies using the location
of each .fo file as the base directory for resolving relative file references located
within that .fo file. A value of <code>false</code> specifies using the value of
basedir for all files within the fileset, or just the current working directory
if basedir is not specified.
</td>
<td>No, default is <code>false</code>.
</td>
</tr>
<tr>
<td>userconfig</td>
<td>User configuration file (same as the FOP "-c" command line option)</td>
<td>No</td>
</tr>
<tr>
<td>messagelevel</td>
<td>Logging level<br/>
Possible values: <code>error</code>, <code>warn</code>, <code>info</code>, <code>verbose</code>, <code>debug</code></td>
<td>No, defaults to <code>verbose</code></td>
</tr>
<tr>
<td>logFiles</td>
<td>Controls whether the names of the files that are processed are logged
(<code>true</code>) or not (<code>false</code>)</td>
<td>No, default is <code>true</code></td>
</tr>
</table>
<p/>
<table><caption>Parameters specified as nested elements</caption>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Required</th>
</tr>
<tr>
<td>fileset</td>
<td><link href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSets</link>
are used to specify multiple XSL-FO files to be rendered.</td>
<td>Yes, if no fofile attribute is supplied</td>
</tr>
</table>
</section>
<section id="examples">
<title>Examples</title>
<p>
The following example converts a single XSL-FO file to a PDF document:
</p>
<source><![CDATA[
<target name="generate-pdf" description="Generates a single PDF file">
<fop format="application/pdf"
fofile="c:\working\foDirectory\foDocument.fo"
outfile="c:\working\pdfDirectory\pdfDocument.pdf" />
</target>
]]></source>
<p>
This example converts all XSL-FO files within an entire directory to PostScript:
</p>
<source><![CDATA[
<target name="generate-multiple-ps"
description="Generates multiple PostScript files">
<fop format="application/postscript"
outdir="${build.dir}" messagelevel="debug">
<fileset dir="${fo.examples.dir}">
<include name="*.fo"/>
</fileset>
</fop>
</target>
]]></source>
</section>
</body>
</document>
|