From: fotis Date: Fri, 18 Feb 2000 09:59:32 +0000 (+0000) Subject: readme now points to html docs X-Git-Tag: pre-columns~588 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=e83601abe7fc7528d68898fc963bad31c8e9e95d;p=xmlgraphics-fop.git readme now points to html docs status updated for 0.12.1 git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@193276 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/README b/README index aead5893a..f5406a54e 100644 --- a/README +++ b/README @@ -1,18 +1,6 @@ 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 @@ -21,490 +9,8 @@ FOP readme 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: - - - - - - - - 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 - - - - + 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 . For more information on the Apache - Software Foundation, please see http://www.apache.org/ (http://www.apache.org/). diff --git a/STATUS b/STATUS index 20b126d9a..c1a135fa8 100644 --- a/STATUS +++ b/STATUS @@ -31,6 +31,9 @@ Todo's and problems with AWT Previewer: - should "preview" be an option when calling FOP instead of having it's own main method? +0.12.1 release +to make the bug fix on XTCommandLine available to non developers + Done since 0.12.0 release: basic support for padding-{top,left,bottom,right} on blocks.