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

 <?xml version="1.0" standalone="no"?>
 <!--
   Copyright 1999-2004 The Apache Software Foundation

   Licensed 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>
	<?xml version="1.0" standalone="no"?>
	<!--
	Copyright 1999-2004 The Apache Software Foundation

	Licensed 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>