aboutsummaryrefslogtreecommitdiffstats
path: root/src/documentation/content/xdocs/0.90/running.xml
diff options
context:
space:
mode:
authorJeremias Maerki <jeremias@apache.org>2005-11-17 21:35:43 +0000
committerJeremias Maerki <jeremias@apache.org>2005-11-17 21:35:43 +0000
commit929fe2e1c858b752b60ab2e76d36846f14a757ff (patch)
tree214ea4d14438e023c63015bd9d2219a085e13362 /src/documentation/content/xdocs/0.90/running.xml
parent91003d856bb86ba14d0faa57d9b5841d4648938f (diff)
downloadxmlgraphics-fop-929fe2e1c858b752b60ab2e76d36846f14a757ff.tar.gz
xmlgraphics-fop-929fe2e1c858b752b60ab2e76d36846f14a757ff.zip
Branched 0.90 documentation from trunk docs.
Minor fixes on front page. Ignore dist directories. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@345331 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src/documentation/content/xdocs/0.90/running.xml')
-rw-r--r--src/documentation/content/xdocs/0.90/running.xml277
1 files changed, 277 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/0.90/running.xml b/src/documentation/content/xdocs/0.90/running.xml
new file mode 100644
index 000000000..3eccf6807
--- /dev/null
+++ b/src/documentation/content/xdocs/0.90/running.xml
@@ -0,0 +1,277 @@
+<?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 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>
+ <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).
+ 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
+ <a href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</a> for information as
+ it becomes available.
+ </p>
+ <p>
+ As an alternative to the start scripts you can run "java -jar build/fop.jar" in which case
+ FOP tries to build the classpath for running FOP dynamically. Please note, that this might
+ not always work as expected.
+ </p>
+ <source><![CDATA[
+USAGE
+Fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-rtf|-tiff|-png|-pcl|-ps|-txt|-at|-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 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
+
+ [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
+ -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 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)
+ -rtf outfile input will be rendered as rtf file (outfile req'd)
+ -tiff outfile input will be rendered as tiff file (outfile req'd)
+ -png outfile input will be rendered as png 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 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="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>