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
|
<?xml version="1.0" standalone="no"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
<document>
<header>
<title>Running FOP</title>
</header>
<body>
<section>
<title>Installation</title>
<section>
<title>Overview</title>
<p>The following software must be installed:</p>
<ul>
<li>Java 1.2.x or later.</li>
<li>FOP. The <jump href="http://xml.apache.org/fop/download.html">FOP distribution</jump> 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:</li>
<ul>
<li>Apache <jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li>
<li>Apache Xalan, an XSLT processor.</li>
<li>Apache <jump href="http://xml.apache.org/batik/">Batik</jump>, an SVG library.</li>
</ul>
<li>Optional Libraries</li>
</ul>
</section>
<section>
<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>
<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>
<title>Starting FOP as a standalone application</title>
<p>Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.</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="running_xalan">
<title>Running Xalan</title>
<p>
The FOP distribution provicdes a Xalan.bat and a Xalan.sh
script for conveniently running an XSL transformation without
formatting. This can be useful for tracking down problems
introduced during transformation and for preparing FO files
for all kinds of purposes, including for inquiring help on the
mailing lists.
</p>
<p>
The scripts are invoked the same way <link href="http://xml.apache.org/xalan-j/commandline.html">Xalan</link> is, in short:
</p>
<p>
<code>xalan -in xmlfile -xsl file -out outfile</code>
</p>
<p>
Note that there are subtle differences to the FOP command line.
</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>
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 might be eliminated, relying on PDF bookmarks instead.
Or it might be moved to the end of the document without dimishing its value very much.
Or, in some circumstances, the paper could even be reshuffled 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.
</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 allocated for other purposes could be freed after the page sequence has been rendered.
</li>
<li>
Break down large tables.
If you don't use table headers and footers, just start a new table every N rows.
With headers and footers, consider integrating them as normal table rows, or, if they are used at page breaks, try to put the information into static content.
You can then use markers to change them.
</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>
<title>Problems</title>
<p>If you have problems running FOP, please have a look at the <jump href="gethelp.html">"How to get Help" page</jump>.</p>
</section>
</body>
</document>
|
