|
|
@@ -3,40 +3,211 @@ FOP README |
|
|
|
$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> |