$Id$
Contributed by
-Fotis Jannidis
+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
+ a) Java 1.1.x or later
-b) XT from James Clark
+ 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.
+ 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.
+ 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)
+ (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>
+ 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
+ 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/>
+ 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
-[Here comes James Tauber's online doc]
-
+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>
projects / xmlgraphics-fop.git / commitdiff