diff options
Diffstat (limited to 'src/documentation/content/xdocs/trunk/running.xml')
| -rw-r--r-- | src/documentation/content/xdocs/trunk/running.xml | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/trunk/running.xml b/src/documentation/content/xdocs/trunk/running.xml new file mode 100644 index 000000000..fdf7aacab --- /dev/null +++ b/src/documentation/content/xdocs/trunk/running.xml @@ -0,0 +1,274 @@ +<?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.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 + <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" + + -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> |