mirrors
/
fop
mirror of https://github.com/apache/fop.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236
							<?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>