-
-
-
- FOP: An Open-Source XSL Formatter and Renderer
-
-
-
-
-
-1) What is FOP?
-2) Compiling FOP
-3) Running FOP
-4) What's Implemented?
-5) Bugs
-6) FOP Relevant Specifications
-
-
- 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) Compiling FOP
-
- 1. Prerequisites
-
- a) Java 1.1.x or later
-
-
+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.
- b) An XML parser
- An XML parser which supports DOM like
- Xerces-J (http://xml.apache.org/xerces-j/index.html)
-.
-
-
- c) 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)
+ FOP is part of Apache's XML project. The homepage of FOP is
+ http:/xml.apache.org/fop (http:/xml.apache.org/fop).
-
-
-
- d) 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/)
-
-
-
+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) Running FOP
-
- 1) Prerequisites
+ 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)
-.
+ 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)
-.
-
-
-
- 2) Starting FOP as an standalone application
- There are three ways of running FOP from the command line.
- a) Batch processing formatting object files:
- java org.apache.fop.apps.CommandLine fo-file pdf-file
+ 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
+ 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
+ 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.
-
- a) Method One
+
+ 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 will need to include
- FOP, SAX and your SAX Parser in your classpath and so you might invoke
+ 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
- java -cp fop_x_xx_x.jar;sax.jar;xp.jar
- org.apache.fop.apps.CommandLine formatting-tree-file pdf-file
- 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. The following example shows
- the command line, if you use Xerces, the xml parser from xml.apache.org:
+ 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 -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser
- -cp fop_x_xx_x.jar;xerces.jar
- org.apache.fop.apps.AWTCommandLine formatting-tree-file pdf-file
-
+ 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
- b) Method Two
+ 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
+ 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_x_xx_x.jar;sax.jar;xp.jar;xt.jar
- org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file
+ 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.
+ org.xml.sax.parser to the SAX Parser class to use.
-
- c) Method Three
+ 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, SAX and your SAX Parser in your classpath
+ 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 org.apache.fop.apps.AWTCommandLine formatting-tree-file
+ 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:
+ 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
+ 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)
-
- 4) What's Implemented?
- Also see STATUS for what is being worked on.
-
- a) Formatting Objects
-
- root
+ 1) Formatting Objects
+ root
layout-master-set
simple-page-master
region-body
table-row (minimal support)
table-cell (minimal support)
-
-
-
- b) Properties
-
+ 2) Properties
end-indent
page-master-name
page-master-first
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) Bugs
- see STATUS file
-
-
-
-
-
- 6) FOP Relevant Specifications
+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:
+ <fo:list-block>
+ <fo:list-item>
+ <fo:list-item-label><fo:block></fo:block></fo:list-item-label>
+ <fo:list-item-body><fo:block></fo:block></fo:list-item-body>
+ </fo:list-item>
+ </fo:list-block>
+
+ 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:
+ <fo:table>
+ <fo:table-column column-width="150pt"/>
+ <fo:table-column column-width="150pt"/>
+ <fo:table-body font-size="10pt" font-family="sans-serif">
+ <fo:table-row>
+ <fo:table-cell>
+ <fo:block>text</fo:block>
+ </fo:table-cell>
+ <fo:table-cell>
+ <fo:block>text</fo:block>
+ </fo:table-cell>
+ </fo:table-row>
+ <fo:table-row>
+ <fo:table-cell>
+ <fo:block>text</fo:block>
+ </fo:table-cell>
+ <fo:table-cell>
+ <fo:block>text</fo:block>
+ </fo:table-cell>
+ </fo:table-row>
+ <fo:table-row>
+ <fo:table-cell>
+ <fo:block>text</fo:block>
+ </fo:table-cell>
+ <fo:table-cell>
+ <fo:block>text</fo:block>
+ </fo:table-cell>
+ </fo:table-row>
+ </fo:table-body>
+ </fo:table>
+
+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 Recommandation (http://www.w3.org/TR/xslt)
-
+ 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)
-
-
-
-
-
-
-
-Version: 1.4 1999/11/29 19:45 -
-Contact: James Tauber (jtauber@jtauber.com)
+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 <jtauber@jtauber.com>. For more information on the Apache
+ Software Foundation, please see http://www.apache.org/ (http://www.apache.org/).
projects / xmlgraphics-fop.git / commitdiff