Running FOP


	Prerequisites

Following software must be installed:

a) Java 1.1.x or later (If you want to use AWTCommandLine, you need Swing)

b) An XML parser which supports SAX and DOM like Xerces-J. (Xerces is the default xml parser)

c) If you have to produce the flow objects files, which are the input for FOP, you need a transformation utility to create this files from your xml files. Normally this is an XSLT stylesheet processor like XT or XALAN.


	Starting FOP as an standalone application

There are three ways to run FOP from the command line.

a) Batch processing formatting objects (fo) files:

java org.apache.fop.apps.CommandLine fo-file pdf-file

b) Batch processing xml files (includes production of the fo-files):

java org.apache.fop.apps.XTCommandLine xml-file xsl-file pdf-file

c) Previewing the fo-file:

java org.apache.fop.apps.AWTCommandLine fo-file

Each method uses next to the fop classes other packages. The following describes each method in detail.


	Method One

One is to first use an XSLT engine to produce the formatting object tree as an XML document and then running the class org.apache.fop.apps.CommandLine with the formatting object file name and PDF filename as arguments. You need to set classpath and set the used sax parser according to your enviroment

Classpath settings: You will need to include FOP and your XML Parser in your classpath and so you might invoke FOP, if Xerces-J is your xml parser:

java -cp fop.jar;xerces.jar

org.apache.fop.apps.CommandLine fo-file pdf-file

If you want to use another sax parser, you will need to set the property org.xml.sax.parser to any other SAX Parser class to use. The following example shows the command line, if you use XP from James Clark:

java -Dorg.xml.sax.parser=com.jclark.xml.sax.Driver

-cp fop.jar;xerces.jar;xp.jar

org.apache.fop.apps.CommandLine fo-file pdf-file

Note: The xerces jar file must be included, because xp has no dom support.


	Method Two

Rather than performing transformation with an XSLT before invoking FOP, it is possible, if you use XT as your XSLT engine, to just call FOP and have it call XT for you. To do this, run the class org.apache.fop.apps.CommandLine with the source XML file name, XSL file name and PDF file name as arguments. You will need to include XT in your classpath and so you might invoke

java -cp fop.jar;xt.jar;xerces.jar

org.apache.fop.apps.XTCommandLine xml-file xsl-file pdf-file

Again, if your SAX Parser is other than Xerces, you will need to set the property org.xml.sax.parser to the SAX Parser class to use.


	Method Three

If you already produced the FO file, you can preview the results of your transformation without using any pdf viewer by invoking FOP with the viewer application. You will need to include FOP and your XML Parser in your classpath

java -cp fop.jar;xerces.jar

org.apache.fop.apps.AWTCommandLine fo-file

The viewer uses the swing classes.

Note: If you are using java 2 or later (i.e. jdk 1.2. or later) you can put all needed jar files into the subdirectory jdk1.2.x\jre\lib\ext (windows example). Then FOP can be started without classpath:

java org.apache.fop.apps.CommandLine fo-file pdf-file


	Running FOP on MacOS

Ensure that you have a recent MRJ, and that you have downloaded and unpacked the XP and SAX distributions. The xp.jar and sax.jar files work as is on MacOS.

Drag the FOP jarfile onto the JBindery icon. When the first dialog appears, type "org.apache.fop.apps.CommandLine" in the "Class name" field. Using UNIX syntax, type the names of the input formatting-object file and the output PDF in the "Optional parameters" field.

Click on the Classpath icon. To add the xp.jar and sax.jar files, click the "Add .zip file" button, navigate to the file in question, and click Open.

Once both are added (the FOP jarfile will already be in the list), click Run. A "stdout" window will appear and display FOP runtime messages.


	Problems

If you have problems running FOP, please have a look at the FOP FAQ. If you don't find a solution there, you can ask for help on the list fop-dev@xml.apache.org. Maybe it is a bug and maybe somebody is already working on it.