diff options
Diffstat (limited to 'src/documentation/content/xdocs/0.20.5/running.xml')
| -rw-r--r-- | src/documentation/content/xdocs/0.20.5/running.xml | 190 |
1 files changed, 0 insertions, 190 deletions
diff --git a/src/documentation/content/xdocs/0.20.5/running.xml b/src/documentation/content/xdocs/0.20.5/running.xml deleted file mode 100644 index 0432735f6..000000000 --- a/src/documentation/content/xdocs/0.20.5/running.xml +++ /dev/null @@ -1,190 +0,0 @@ -<?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 V1.1//EN" - "http://svn.apache.org/viewvc/forrest/trunk/main/webapp/resources/schema/dtd/document-v12.dtd?view=co"> - -<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> |