path: root/README

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: 
    <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 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/).