aboutsummaryrefslogtreecommitdiffstats
path: root/src/documentation/content/xdocs/trunk/running.xml
blob: 4b488ef121dbea0818df982e27acabff4077fe51 (plain)
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
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
<?xml version="1.0" standalone="no"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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 V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
  <header>
    <title>Running Apache 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.3.x or later Runtime Environment.</li>
        <li>
          Apache FOP. The <a href="../download.html">FOP distribution</a> includes all libraries that you will 
          need to run a basic FOP installation. These can be found in the [fop-root]/lib directory. These 
          libraries include the following:
          <ul>
            <li>
              A JAXP-compatible XML Parser (FOP comes with <a class="fork" href="ext:xerces">Apache Xerces-J</a>).
            </li>
            <li>
              A JAXP-compatible XSLT Processor (FOP comes with <a class="fork" href="ext:xalan">Apache Xalan-J</a>).
            </li>
            <li><a class="fork" href="ext:batik">Apache Batik</a>, an SVG library.</li>
            <li><a class="fork" href="ext:jakarta/commons/logging">Apache Jakarta Commons Logging</a>, a logger abstraction kit.</li>
            <li><a class="fork" href="ext:jakarta/commons/io">Apache Jakarta Commons IO</a>, a library with I/O utilities.</li>
            <li><a class="fork" href="ext:excalibur/framework">Apache Excalibur/Avalon Framework</a>, for XML configuration handling.</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 
          <a href="graphics.html">FOP: Graphics Formats</a> for details.
        </li>
        <li>
          PDF encryption. See <a href="pdfencryption.html">FOP: PDF Encryption</a> 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 <a href="graphics.html#batik">FOP: Graphics (Batik)</a> 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>
      <section id="fop-script">
        <title>Using the fop script or batch file</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 (Unix/Linux).
        These scripts 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 
        <a href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</a> for information as 
        it becomes available.
      </p>
      <source><![CDATA[
USAGE
Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at [mime]|-print] <outfile>
 [OPTIONS]  
  -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 
  -r                relaxed/less strict validation (where available)
  -dpi xxx          target resolution in dots per inch (dpi) where xxx is a number
  -s                for area tree XML, down to block areas only
  -v                to show FOP version being used

  -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
  -pdfprofile prof  PDF file will be generated with the specified profile
                    (Examples for prof: PDF/A-1b or PDF/X-3:2003)

 [INPUT]  
  infile            xsl:fo input file (the same as the next) 
  -fo  infile       xsl:fo input file  
  -xml infile       xml input file, must be used together with -xsl 
  -atin infile      area tree input file 
  -xsl stylesheet   xslt stylesheet 
 
  -param name value <value> to use for parameter <name> in xslt stylesheet
                    (repeat '-param name value' for each parameter)
 
 [OUTPUT] 
  outfile           input will be rendered as PDF into outfile
  -pdf outfile      input will be rendered as PDF (outfile req'd)
  -pdfa1b outfile   input will be rendered as PDF/A-1b compliant PDF
                    (outfile req'd, same as "-pdf outfile -pdfprofile PDF/A-1b")
  -awt              input will be displayed on screen 
  -mif outfile      input will be rendered as MIF (FrameMaker) (outfile req'd)
  -rtf outfile      input will be rendered as RTF (outfile req'd)
  -tiff outfile     input will be rendered as TIFF (outfile req'd)
  -png outfile      input will be rendered as PNG (outfile req'd)
  -pcl outfile      input will be rendered as PCL (outfile req'd) 
  -ps outfile       input will be rendered as PostScript (outfile req'd) 
  -txt outfile      input will be rendered as plain text (outfile req'd) 
  -svg outfile      input will be rendered as an SVG slides file (outfile req'd) 
  -at [mime] out    representation of area tree as XML (outfile req'd) 
                    specify optional mime output to allow AT to be converted
                    to final format later
  -print            input file will be rendered and sent to the printer 
                    see options with "-print help" 
  -out mime outfile input will be rendered using the given MIME type
                    (outfile req'd) Example: "-out application/pdf D:\out.pdf"
                    (Tip: "-out list" prints the list of supported MIME types)

  -foout outfile    input will only be XSL transformed. The intermediate 
                    XSL-FO file is saved and no rendering is performed. 
                    (Only available if you use -xml and -xsl parameters)


 [Examples]
  Fop foo.fo foo.pdf 
  Fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)
  Fop -xml foo.xml -xsl foo.xsl -pdf foo.pdf
  Fop -xml foo.xml -xsl foo.xsl -foout foo.fo
  Fop foo.fo -mif foo.mif
  Fop foo.fo -rtf foo.rtf
  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 <a href="pdfencryption.html">Details</a>.
      </p>
      </section>
      <section id="your-own-script">
        <title>Writing your own script</title>
        <p>FOP's entry point for your own scripts is the class
<code>org.apache.fop.cli.Main</code>. The general pattern for the
        command line is: <code>java -classpath &lt;CLASSPATH>
        org.apache.fop.cli.Main  &lt;arguments></code>. The arguments
        consist of the options and infile and outfile specifications
        as shown above for the standard scripts. You may wish to review
        the standard scripts to make sure that 
        you get your environment properly configured. 
        </p>
      </section>
      <section id="jar-option">
        <title>Running with java's <code>-jar</code> option</title>
      <p>
        As an alternative to the start scripts you can run <code>java
        -jar build/fop.jar</code> from the FOP_HOME directory. In this
        case FOP tries to build the classpath for running FOP
        dynamically, see <a href="#dynamical-classpath">below</a>. If
        you use hyphenation, you must put <code>fop-hyph.jar</code> in
        the <code>lib</code> directory.
      </p>
      <p>You can also run <code>java -jar fop.jar</code> from any
      other working directory. This only works if you put
      <code>fop.jar</code> and all jar files from the <code>lib</code>
      directory in a single directory. See the <code>Class-Path</code>
      entry in the manifest file. If you use hyphenation, you
      must also put <code>fop-hyph.jar</code> in that directory.</p>
      </section>
      <section id="dynamical-classpath">
		<title>FOP's dynamical classpath construction</title>

		<p>If FOP is started without a proper classpath, it tries to
		add its dependencies dynamically. FOP expects to find
		<code>fop.jar</code> in the <code>build</code> directory,
		which is either the current working directory or one of its
		subdirectories. Then FOP adds all <code>jar</code> files in
		the <code>lib</code> directory to the classpath. The
		<code>lib</code> directory is a sibling directory of the
		<code>build</code> directory, or, if that does not exist, the
		parent directory of the <code>build</code> directory. If the
		system property <code>fop.optional.lib</code> contains the
		name of a directory, then all <code>jar</code> files in that
		directory are also added to the classpath. See the methods
		<code>getJARList</code> and <code>checkDependencies</code> in
		<code>org.apache.fop.cli.Main</code>.</p>

	  </section>
    </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 
        <a href="../resources.html#specs">Specifications</a> and 
        <a href="../resources.html#articles">Books/Articles</a>.
        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 the "-foout" option 
        which causes FOP to run only the first (transformation) step, and write the 
        results to a file. (See also the Xalan command-line below)
      </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 XSLT step (-foout) 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 -foout option works the same way as if you would call the 
        <a href="http://xml.apache.org/xalan-j/commandline.html">Xalan command-line</a>:
      </p>
      <p>
        <code>java org.apache.xalan.xslt.Process -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 
          <a href="http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/java.html">the -Xmx option</a> 
          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 
          (<a href="../faq.html#pagenum">"page N of TOTAL"</a>).
          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.
        </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>
        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 
        <a href="../dev/index.html">FOP Redesign</a>.
      </p>
    </section>
    <section id="problems">
      <title>Problems</title>
      <p>If you have problems running FOP, please see the <a href="../gethelp.html">"How to get Help" page</a>.</p>
    </section>
  </body>
</document>