fop-1_1/src/documentation/content/xdocs/trunk/anttask.xml - xmlgraphics-fop - Git at Google

 <?xml version="1.0" encoding="UTF-8" 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>Apache™ FOP: 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>
	<?xml version="1.0" encoding="UTF-8" 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>Apache™ FOP: 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>