| <?xml version="1.0" standalone="no"?> |
| <!-- |
| Copyright 1999-2004 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 V1.1//EN" |
| "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd"> |
| |
| <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 sofware 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> |
