diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 546 |
1 files changed, 383 insertions, 163 deletions
@@ -1,169 +1,156 @@ - - - - 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 @@ -192,11 +179,7 @@ table-row (minimal support) table-cell (minimal support) - - - - b) Properties - + 2) Properties end-indent page-master-name page-master-first @@ -238,45 +221,282 @@ 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/). |