FOP README

$Id$

Contributed by
Fotis Jannidis, James Tauber

FOP: An Open-Source XSL Formatter and Renderer

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.


A. Compiling FOP

1. Prerequisites

   a) Java 1.1.x or later

   b) 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
      <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 <http://www.jclark.com/xml/xp/index.html>

   c) 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 
      <http://sourceware.cygnus.com/cygwin/>



B. Running FOP

1) Prerequisites

   Following software must be installed:

   a) Java 1.1.x or later

   b) A sax parser like XP <http://www.jclark.com/xml/xp/index.html>.

   c) If you have to produce the formatting 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 two ways of running FOP from the command line.

   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 

   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.

   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_x_xx_x.jar;sax.jar;xp.jar;xt.jar
   org.apache.fop.apps.XTCommandLine 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.

   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 formatting-tree-file pdf-file


C) What's Implemented?

   Also see STATUS for what is being worked on.

   a) 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)

   b) 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

D) Bugs

   see STATUS file     

E) 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>

   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>