FOP readme
Content
1. What is FOP?
2. Downloading FOP
3. Running FOP
4. Features
5. Limitations
6. Compiling FOP
7. Embedding FOP
8. Getting involved
9. FOP Relevant Specifications
10. License
1. What is FOP?
FOP is the world's first print formatter driven by XSL formatting
objects. It is a Java 1.1 application that reads a formatting object
tree and then turns it into a PDF document. The formatting object
tree, can be in the form of an XML document (output by an XSLT engine
like XT or Xalan) or can be passed in memory as a DOM Document or (in
the case of XT) SAX events.
FOP is part of Apache's XML project. The homepage of FOP is
http:/xml.apache.org/fop (http:/xml.apache.org/fop).
2. Downloading FOP
2.1. Downloading binaries
You can download the latest release version FOP 0.12.0
(http://xml.apache.org/dist/fop_bin_0_12_0.jar).
NOTE: you do not have to unjar or unzip this jar file.
To run FOP from the command line, see Running FOP. If you are
interested in embedding FOP in a Java application of your own, see
Embedding FOP.
2.2. Downloading source code
You can also download the source code v. 0.12.0
(http://xml.apache.org/dist/fop_src_0_12_0.jar) as a jar file
3. Running FOP
3.1. Prerequisites
Following software must be installed:
a) Java 1.1.x or later
b) An XML parser which supports SAX and DOM like
Xerces-J (http://xml.apache.org/xerces-j/index.html).
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 (http://www.jclark.com/xml/xt.html)
or XALAN (http://xml.apache.org/xalan/index.html).
3.2. 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.CommandLine 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.
3.2.1. 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 XP is your sax parser
and Xerces-J your DOM parser:
java -cp fop_bin_0_12_0.jar;xp.jar;xerces.jar
org.apache.fop.apps.CommandLine fo-file pdf-file
For historical reasons the standard sax parser for FOP is XP from James Clark.
This will change in the future to Xerces-J, but at the moment 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 Xerces-J:
java -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser
-cp fop_bin_0_12_0.jar;xerces.jar
org.apache.fop.apps.CommandLine fo-file pdf-file
PLEASE NOTE: Starting with v 0.12.1 [dev] the standard parser for FOP is xerces-J.
Therefore if you use xerces, you don't need to
set -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser
3.2.2. 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 FOP, SAX, your SAX Parser and XT in your classpath and so you might
invoke
java -cp fop_bin_0_12_0.jar;xt.jar;xp.jar;xerces.jar
org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file
Again, if your SAX Parser is other than XP, you will need to set the property
org.xml.sax.parser to the SAX Parser class to use.
PLEASE NOTE: Starting with v 0.12.1 [dev] the standard parser for FOP is xerces-J.
Therefore the example will only work, if you use xerces. Otherwise
you have to set the sax parser
3.2.3. 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_bin_0_12_0.jar;xp.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
3.3. 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.
3.4. Problems
If you have problems running FOP, please have a look at the
FOP FAQ (faq-running.html). 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.
4. Features
4.1. What's Implemented?
The following formatting objects and properties of the xsl-fo
working draft are implemented. Please have also a look at the
section on limitations (limitations.html)
1) Formatting Objects
root
layout-master-set
simple-page-master
region-body
region-before
region-after
page-sequence
sequence-specification
sequence-specifier-single
sequence-specifier-repeating
sequence-specifier-alternating
flow
static-content
block
list-block
list-item
list-item-label
list-item-body
page-number
display-sequence
inline-sequence
display-rule
display-graphic
table (minimal support)
table-column (minimal support)
table-body (minimal support)
table-row (minimal support)
table-cell (minimal support)
2) Properties
end-indent
page-master-name
page-master-first
page-master-repeating
page-master-odd
page-master-even
margin-top (only on pages and regions)
margin-bottom (only on pages and regions)
margin-left (only on pages and regions)
margin-right (only on pages and regions)
extent
page-width
page-height
flow-name
font-family
font-style
font-weight
font-size
line-height
text-align
text-align-last
space-before.optimum
space-after.optimum
start-indent
end-indent
provisional-distance-between-starts
provisional-label-separation
rule-thickness
color
wrap-option
white-space-treatment
break-before
break-after
text-indent
href
column-width
background-color
padding-top (only in conjunction with background color)
padding-left (only in conjunction with background color)
padding-bottom (only in conjunction with background color)
padding-right (only in conjunction with background color)
5. Limitations
Although FOP implements the above listed fo objects and properties, sometimes it does so
only in a limited way.
5.1. list-block
The fo working draft allows describes two ways to markup lists.The list-block must
have as children either: 1) pairs of fo:list-item-label and fo:list-item-body
formatting objects, or 2) fo:list-item formatting objects.
At the moment FOP only implements the second way. Therefore a list has a basic
structure like this:
5.2. Padding
Padding works in conjunction with indents and spaces. It is only implemented
for blocks. At the moment padding can't be used to make extra space (indents+spaces
must be used), but only to control how much the background-color extends beyond
the content rectangle.
5.3. Tables
There two limitations for tables: 1) FOP needs you to explicitly specify column widths
2) Cells have to contain block-level FOs. They can't contain straight character data.
A working basic example of a table looks like this:
text
text
text
text
text
text
6. Compiling FOP
6.1. Prerequisites
6.1.1. Java 1.1.x or later
If you use Java 1.1.x you must also seperately include the swing classes, which can
be found at the Sun website (http://java.sun.com/products/jfc/#download-swing). From
Java 1.2 on (aka Java 2) they are part of the standard distribution.
6.1.2. An XML parser
An XML parser which supports DOM like Xerces-J
(http://xml.apache.org/xerces-j/index.html).
6.1.3. XT from James Clark
Some of the Java source code in FOP is generated from XML using
XSLT. XT must be used to generate this code.
XT is an XSL stylesheet processor written in java. At the moment you
can't use any other processor, because the make file makes use of some
proprietary features of Clark's xt which allow to write output in more
then one document. You can find XT at James Clark's website
(http://www.jclark.com/xml/xt.html). You have to use XT version 19991105
or later. (Under windows you shouldn't use the prepackaged xt.exe but also the
generic jar file, otherwise make won't work)
XT relies on an sax parser like XP (also J. Clark), which can be
downloaded at James Clark's Website (http://www.jclark.com/xml/xp/index.html)
6.1.4. make
Under windows it has been reported that the use of the cygnus solutions port
of the GNU utilities works. You can find it at
Cygnus Solutions (http://sourceware.cygnus.com/cygwin/)
6.2. Compiling FOP on MacOS
We strongly recommend the use of Codewarrior Java. You will find
a link to more information in the near future.
7. Embedding FOP
Instantiate org.apache.fop.apps.Driver. Once this class is
instantiated, methods are called to set the
Renderer to use, the (possibly multiple) ElementMapping(s) to
use and the PrintWriter to use to output the results of the
rendering (where applicable). In the case of the Renderer and
ElementMapping(s), the Driver may be supplied either with the
object itself, or the name of the class, in which case Driver will
instantiate the class itself. The advantage of the latter is it
enables runtime determination of Renderer and ElementMapping(s).
Once the Driver is set up, the buildFOTree method
is called. Depending on whether DOM or SAX is being used, the
invocation of the method is either buildFOTree(Document) or
buildFOTree(Parser, InputSource) respectively.
A third possibility may be used to build the FO Tree, namely
calling getDocumentHandler() and firing the SAX events yourself.
Once the FO Tree is built, the format() and render() methods may be
called in that order.
Here is an example use of Driver from CommandLine.java:
Driver driver = new Driver();
driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version);
driver.addElementMapping("org.apache.fop.fo.StandardElementMapping");
driver.addElementMapping("org.apache.fop.svg.SVGElementMapping");
driver.setWriter(new PrintWriter(new FileWriter(args[1])));
driver.buildFOTree(parser, fileInputSource(args[0]));
driver.format();
driver.render();
8. Getting involved
8.1. First steps
1. Subscribe to fop-dev@xml.apache.org by sending an email
to fop-dev-subscribe@xml.apache.org
2. Read the archives to fop-dev to get an idea of the issues being
discussed.
3. Subscribe to fop-cvs@xml.apache.org by sending an email to
fop-cvs-subscribe@xml.apache.org (it is important
that you follow changes being made).
4. Try :-) to wrap your head around the XSL working draft.
5. Get CVS working on your system.
6. Ask, on fop-dev, any questions you have at all about the code, design, etc.
7. When you feel comfortable modifying the code, send diffs to
fop-dev with your contributions.
8. Have fun!
8.2. The Ways of FOP
The following shows an example use of FOP from org.apache.fop.apps.CommandLine.java:
1) Driver driver = new Driver();
2) driver.setRenderer ("org.apache.fop.render.pdf.PDFRenderer", version);
3) driver.addElementMapping ("org.apache.fop.fo.StandardElementMapping");
3) driver.addElementMapping ("org.apache.fop.svg.SVGElementMapping");
4) driver.setWriter (new PrintWriter(new FileWriter(args[1])));
5) driver.buildFOTree(parser, fileInputSource(args[0]));
6) driver.format();
7) driver.render();
1. step: Initiate class Driver
Driver is the primary class that drives overall FOP process.
2. step: Set Renderer
You set the renderer for the output format of your choice. At the moment 3 formats are
supported: a) pdf (org.apache.fop.render.pdf.PDFRenderer)
b) awt (org.apache.fop.render.awt.AWTRenderer)
c) xml (org.apache.fop.render.xml.XMLRenderer)
All renderers implement the interface Renderer which defines the methods an area
needs to be laid out.
The xml renderer is meant for debugging purposes.
The interface Renderer takes a string as a version argument indicating the application
that is producing the output. Many output formats like PDF allow the inclusion
of a "Producer" string.
3. step: Set Element Mapping
By setting the element mapping you choose the dictionaries of elements which
FOP can handle. At the moment two dictionaries are available:
a) Standard xsl elements (org.apache.fop.fo.StandardElementMapping)
b) Graphic elements described by SVG (org.apache.fop.svg.SVGElementMapping)
All element mappings implement the interface ElementMapping.
4. step: Set output destination
Normally this will be a Printwriter of some sort. If you are just displaying the
output on screen you can skip this step.
5. step: Build FO Tree
Builds the tree of formatting objects contained in the input source. Either walks
the tree of the input document (DOM) or uses SAX events to build up the tree
by looking up the definitions of the fo in the element mappings. Depending on
whether DOM or SAX is being used, the invocation of the method is either
buildFOTree(Document) or buildFOTree(Parser, InputSource) respectively.
6. step: Build Area Tree from FO Tree
By calling format() of the driver class the fo tree is written/formatted into
a area tree. Every formatting object knows how to layout itself, that is every
formatting object has a an layout method which is now called to produce an area.
The setup of the font info for the renderer is also done in this step.
7. step: Renderer renders Areas
The renderer, which has been set in step 2, is given the area tree. It uses the
layout information to output it in its specific format. Example: For the PDF
renderer there is a set of methods to create a pdf file containing the FOP
supported kind of layout features.
--------------------------------------------------------------------------
If you want to extend the functionality of FOP by adding new formatting objects,
you should do the following:
1. FO Object: Write a class which contains the description of your formatting
object and put it into the package fop.fo.flow, fop.fo.pagination (if it
is a property it goes to fop.fo.properties. The classes in this package are
generated via an xslt stylesheet located in codegen/properties.xml)
2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it
is a property you need to add it to fop.fo.PropertyListBuilder)
3. Area: Either your need can be fulfilled within one of the existing classes
in fop.layout, then just add the code to handle the new fo/property or you
must write a new one.
4. Renderer: Choose the renderer you are interested in. If you worked on an
existing layout class you must add code to handle the new features to the
already existing area specific method in the renderer class. Otherwise you
have to add a new method.
9. FOP Relevant Specifications
XML Recommendation (http://www.w3.org/TR/REC-xml)
XSL-FO Working Draft (http://www.w3.org/TR/WD-xsl/)
XSLT Recommendation (http://www.w3.org/TR/xslt)
PDF Documentation (http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf)
Simple API for XML (SAX) (http://www.megginson.com/SAX/)
Document Object Model (DOM) (http://www.w3.org/TR/REC-DOM-Level-1)
Namespaces in XML Recommendation (http://www.w3.org/TR/REC-xml-names/)
Java JDK 1.1 Documentation (http://java.sun.com/products/jdk/1.1/docs/index.html)
10. License
The Apache Software License, Version 1.1
Copyright (C) 1999 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must
include the following acknowledgment: "This product includes software
developed by the Apache Software Foundation (http://www.apache.org/)."
Alternately, this acknowledgment may appear in the software itself, if
and wherever such third-party acknowledgments normally appear.
4. The names "FOP" and "Apache Software Foundation" must not be used to
endorse or promote products derived from this software without prior
written permission. For written permission, please contact
apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may
"Apache" appear in their name, without prior written permission of the
Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU-
DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals
on behalf of the Apache Software Foundation and was originally created by
James Tauber . For more information on the Apache
Software Foundation, please see http://www.apache.org/ (http://www.apache.org/).