diff options
Diffstat (limited to 'src/documentation/content/xdocs/1.0/anttask.xml')
| -rw-r--r-- | src/documentation/content/xdocs/1.0/anttask.xml | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/1.0/anttask.xml b/src/documentation/content/xdocs/1.0/anttask.xml new file mode 100644 index 000000000..a543a5623 --- /dev/null +++ b/src/documentation/content/xdocs/1.0/anttask.xml @@ -0,0 +1,237 @@ +<?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 V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd"> +<document> + <header> + <title>Ant task</title> + <version>$Revision$</version> + </header> + <body> + <p> + Apache 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 etc. output + (see <a href="output.html">Output formats</a> 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.home" value="....path to your FOP HOME directory..."/> + +<taskdef name="fop" + classname="org.apache.fop.tools.anttasks.Fop"> + <classpath> + <fileset dir="${fop.home}/lib"> + <include name="*.jar"/> + </fileset> + <fileset dir="${fop.home}/build"> + <include name="fop.jar"/> + <include name="fop-hyph.jar" /> + </fileset> + </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>xmlfile</td> + <td>XML input file</td> + <td>Yes, if no fofile is specified</td> + </tr> + <tr> + <td>xsltfile</td> + <td>XSLT input file</td> + <td>Yes, if no fofile is specified</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/X-fop-awt-preview</code><br/> + <code>application/X-fop-print</code><br/> + <code>application/X-fop-areatree</code><br/> + <code>application/pdf</code><br/> + <code>application/postscript</code><br/> + <code>application/mif</code><br/> + <code>application/rtf</code>, + <code>text/richtext</code>, + <code>text/rtf</code><br/> + <code>application/x-pcl</code>, + <code>application/vnd.hp-PCL</code><br/> + <code>application/x-afp</code>, + <code>application/vnd.ibm.modcap</code><br/> + <code>text/plain</code><br/> + <code>image/svg+xml</code><br/> + <code>image/gif</code><br/> + <code>image/png</code><br/> + <code>image/tiff</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>. <strong>Currently doesn't work in FOP Trunk!!!</strong></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>). <strong>Currently doesn't work in FOP Trunk!!!</strong></td> + <td>No, default is <code>true</code></td> + </tr> + <tr> + <td>throwexceptions</td> + <td>Controls whether or not an exception is thrown if an error occurs during rendering.</td> + <td>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><a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSets</a> + 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> + <p> + The following example transforms and converts a single XML and XSLT file to an AFP document: + </p> + <source><![CDATA[ +<target name="generate-afp-from-transform" description="Generates a single AFP file from an XSLT stylesheet"> + <fop format="application/x-afp" + xmlfile="c:\working\foDirectory\Document.xml" + xsltfile="c:\working\foDirectory\Document.xslt" + outfile="c:\working\afpDirectory\Document.afp" /> +</target> + ]]></source> + <p> + This example transforms and converts all XML files within an entire directory to PostScript: + </p> + <source><![CDATA[ +<target name="generate-multiple-ps-from-transform" description="Generates multiple PostScript files using an XSLT stylesheet"> + <fop format="application/postscript" + xsltfile="c:\working\foDirectory\Document.xslt" + outdir="${build.dir}" messagelevel="debug"> + <fileset dir="${test.dir}"> + <include name="*.xml"/> + </fileset> + </fop> +</target> + ]]></source> + </section> + </body> +</document> + |