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?
+ 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
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
+ http:/xml.apache.org/fop
- 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:
- <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>
+ HTML-Documentation can be found in the subdirectory /docs.
-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 <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