1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
<?xml version="1.0" standalone="no"?>
<!--
Copyright 1999-2005 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- $Id$ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd">
<document>
<header>
<title>Running FOP</title>
<version>$Revision$</version>
</header>
<body>
<section id="require">
<title>System Requirements</title>
<p>The following software must be installed:</p>
<ul>
<li>Java 1.2.x or later Runtime Environment.</li>
<li>FOP. The <link href="../download.html">FOP distribution</link> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:
<ul>
<li><jump href="http://xml.apache.org/xerces-j/index.html">Apache Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li>
<li><jump href="http://xml.apache.org/xalan-j/index.html">Apache Xalan-J</jump>, an XSLT processor.</li>
<li><jump href="http://xml.apache.org/batik/">Apache Batik</jump>, an SVG library.</li>
</ul>
</li>
</ul>
<p>The following software is optional, depending on your needs:</p>
<ul>
<li>Graphics libraries. Support for some graphics formats requires additional packages. See <link href="graphics.html">FOP: Graphics Formats</link> for details.</li>
<li>PDF encryption. See <link href="pdfencryption.html">FOP: PDF Encryption</link> for details.</li>
</ul>
<p>In addition, the following system requirements apply:</p>
<ul>
<li>If you will be using FOP to process SVG, you must do so in a graphical environment. See <link href="graphics.html#batik">FOP: Graphics (Batik)</link> for details.</li>
</ul>
</section>
<section id="install">
<title>Installation</title>
<section id="install-instruct">
<title>Instructions</title>
<p>Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the distribution medium, then unarchiving the resulting <code>.tar</code> file in a directory/folder that is convenient on your system. Please consult your operating system documentation or Zip application software documentation for instructions specific to your site.</p>
</section>
<section id="install-problems">
<title>Problems</title>
<p>Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip and unarchive their distribution media. This is a legacy of older Mac operating systems, which had a 31-character pathname limit. Several Mac OSX users have recommended that Mac OSX users use the shell command <code>tar -xzf</code> instead.</p>
</section>
</section>
<section id="standalone-start">
<title>Starting FOP as a Standalone Application</title>
<p>The usual and recommended practice for starting FOP from the command line is to run the batch file fop.bat (Windows) or the shell script fop.sh (Unix/Linux).
If you write your own scripts, be sure to review these standard scripts to make sure that you get your environment properly configured.</p>
<p>The standard scripts for starting FOP require that the environment variable JAVA_HOME be set to a path pointing to the appropriate Java installation on your system. Macintosh OSX includes a Java environment as part of its distribution. We are told by Mac OSX users that the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat: </strong>We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see <jump href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</jump> for information as it becomes available.</p>
<p><code>fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile></code></p>
<p>[OPTIONS]</p>
<source>
-d debug mode
-x dump configuration settings
-q quiet mode
-c cfg.xml use additional configuration file cfg.xml
-l lang the language to use for user information
-s (-at output) omit tree below block areas
-txt.encoding (-txt output encoding use the encoding for the output file.
The encoding must be a valid java encoding.
-o [password] pdf file will be encrypted with option owner password
-u [password] pdf file will be encrypted with option user password
-noprint pdf file will be encrypted without printing permission
-nocopy pdf file will be encrypted without copy content permission
-noedit pdf file will be encrypted without edit content permission
-noannotations pdf file will be encrypted without edit annotation permission</source>
<p>[INPUT]</p>
<source> infile XSLFO input file (the same as the next)
-fo infile xsl:fo input file
-xml infile xml input file, must be used together with -xsl
-xsl stylesheet xslt stylesheet</source>
<p>[OUTPUT]</p>
<source> outfile input will be rendered as pdf file into outfile
-pdf outfile input will be rendered as pdf file (outfile req'd)
-awt input will be displayed on screen
-mif outfile input will be rendered as mif file (outfile req'd)
-pcl outfile input will be rendered as pcl file (outfile req'd)
-ps outfile input will be rendered as PostScript file (outfile req'd)
-txt outfile input will be rendered as text file (outfile req'd)
-svg outfile input will be rendered as an svg slides file (outfile req'd)
-at outfile representation of area tree as XML (outfile req'd)
-print input file will be rendered and sent to the printer
see print specific options with "-print help"</source>
<p>[Examples]</p>
<source> fop foo.fo foo.pdf
fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf
fop foo.fo -mif foo.mif
fop foo.fo -print or fop -print foo.fo
fop foo.fo -awt</source>
<p>PDF encryption is only available if FOP was compiled with encryption support <strong>and</strong> if compatible encryption support is availabe at run time. Currently, only the JCE is supported. Check the <link href="pdfencryption.html">Details</link>.</p>
</section>
<section id="check-input">
<title>Using Xalan to Check XSL-FO Input</title>
<p>FOP sessions that use -xml and -xsl input instead of -fo input are actually controlling two distinct conversions: Tranforming XML to XSL-FO, then formatting the XSL-FO to PDF (or another FOP output format).
Although FOP controls both of these processes, the first is included merely as a convenience and for performance reasons.
Only the second is part of FOP's core processing.
If a user has a problem running FOP, it is important to determine which of these two processes is causing the problem.
If the problem is in the first process, the user's stylesheet is likely the cause.
The FOP development team does not have resources to help with stylesheet issues, although we have included links to some useful <link href="../resources.html#specs">Specifications</link> and <link href="../resources.html#articles">Books/Articles</link>.
If the problem is in the second process, FOP may have a bug or an unimplemented feature that does require attention from the FOP development team.</p>
<note>The user is always responsible to provide correct XSL-FO code to FOP.</note>
<p>In the case of using -xml and -xsl input, although the user is responsible for the XSL-FO code that is FOP's input, it is not visible to the user. To make the intermediate FO file visible, the FOP distribution includes xalan.bat (Windows batch file) and xalan.sh (Unix/Linux script), which run only the first (transformation) step, and write the results to a file.</p>
<note>When asking for help on the FOP mailing lists, <em>never</em> attach XML and XSL to illustrate the issue. Always run the xalan script and send the resulting XSL-FO file instead. Of course, be sure that the XSL-FO file is correct before sending it.</note>
<p>
The scripts are invoked the same way that <link href="http://xml.apache.org/xalan-j/commandline.html">Xalan</link> is:
</p>
<p>
<code>xalan -in xmlfile -xsl file -out outfile</code>
</p>
<p>
Note that there are some subtle differences between the "fop" and "xalan" command lines.
</p>
</section>
<section id="memory">
<title>Memory Usage</title>
<p>
FOP can consume quite a bit of memory, even though this has been continually improved.
This is partly inherent to the formatting process and partly caused by implementation choices.
All FO processors currently on the market have memory problems with certain layouts.
</p>
<p>
If you are running out of memory when using FOP, here are some ideas that may help:
</p>
<ul>
<li>
Increase memory available to the JVM. See <link href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the -Xmx option</link> for more information.
<!--<warning>-->
(Warning: It is usually unwise to increase the memory allocated to the JVM beyond the amount of physical RAM, as this will generally cause significantly slower performance.)
<!--</warning>-->
</li>
<li>
Avoid forward references.
Forward references are references to some later part of a document.
Examples include page number citations which refer to pages which follow the citation, tables of contents at the beginning of a document, and page numbering schemes that include the total number of pages in the document (<link href="../faq.html#pagenum">"page N of TOTAL"</link>).
Forward references cause all subsequent pages to be held in memory until the reference can be resolved, i.e. until the page with the referenced element is encountered.
Forward references may be required by the task, but if you are getting a memory overflow, at least consider the possibility of eliminating them.
A table of contents could be replaced by PDF bookmarks instead or moved to the end of the document (reshuffle the paper could after printing).
</li>
<li>
Avoid large images, especially if they are scaled down.
If they need to be scaled, scale them in another application upstream from FOP.
For many image formats, memory consumption is driven mainly by the size of the image file itself, not its dimensions (width*height), so increasing the compression rate may help.
If FOP is running embedded, clearing the image from time to time cache might prevent memory exhaustion, you can call
<code>org.apache.fop.image.FopImageFactory.resetCache()</code> to empty the
<jump href="graphics.html#caching">image cache</jump>.
</li>
<li>
Use multiple page sequences.
FOP starts rendering after the end of a page sequence is encountered.
While the actual rendering is done page-by-page, some additional memory is freed after the page sequence has been rendered.
This can be substantial if the page sequence contains lots of FO elements.
</li>
</ul>
<p>
There are currently some bugs which cause FOP to go into a nonterminating loop, which will also often result in a memory overflow.
A characteristic symptom is continuous <link href="../faq.html#boxoverflow">box overflows</link> in the log.
Most of these loops are triggered by elements that do not fit in the available space, such as big images or an improperly specified width in nested block elements.
The only workaround is to locate such problems and correct them.
</p>
<p>
One of FOP's stated design goals is to be able to process input of arbitrary size.
Addressing this goal is one of the prime motivations behind the <link href="../dev/index.html">FOP Redesign</link>.
</p>
</section>
<section id="problems">
<title>Problems</title>
<p>If you have problems running FOP, please see the <jump href="../gethelp.html">"How to get Help" page</jump>.</p>
</section>
</body>
</document>
|
