FOray: Running the Application

• System Requirements
• Installation
• Starting FOray as a Standalone Application
• Using Xalan to Check XSL-FO Input
• Memory Usage

System Requirements

The following software must be installed:

• Java 5.0 or later Runtime Environment.
• FOray. The FOray distribution includes all libraries that you will need to run a basic FOray installation. These can be found in the lib directory. These libraries include the following:
  • Apache Xerces-J for XML parsing. You can use other XML parsers which support SAX and DOM.
  • Apache Xalan-J, an XSLT processor.
  • Apache Batik, an SVG library.

The following sofware is optional, depending on your needs:

• PDF encryption. See FOray: PDF Encryption for details.

In addition, the following system requirements apply:

• If you will be using FOray to process SVG, you must do so in a graphical environment. See FOray: Graphics (Batik) for details.

Installation

Basic FOray installation consists of unzipping the .zip file that is the distribution medium 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.

Starting FOray as a Standalone Application

The recommended practice for starting FOray from the command line is to run the batch file foray.bat (Windows) or the shell script foray.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.

The standard scripts for starting FOray 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 /Library/Java/Home. Caveat: We suspect that, as Apple releases new Java environments and as FOray upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see Java on Mac OSX FAQ for information as it becomes available.

foray [options] [-fo|-xml] infile [-xsl file]
    [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile>

[OPTIONS]

      -c configuration-file
                        get configuration key-value pairs from configuration-file
      -so option-key option-value
                        configure a session-option key-value pair

[INPUT]

      -fo  infile       XSL-FO input file
      -xml infile       XML input file (-xsl option required)
      -xsl stylesheet   XSL input stylesheet file (use with -xml)

[OUTPUT]

      -pdf outfile      Document will be rendered as PDF
      -mif outfile      Document will be rendered as MIF
      -pcl outfile      Document will be rendered as PCL
      -ps outfile       Document will be rendered as PostScript
      -txt outfile      Document will be rendered as text
      -svg outfile      Document will be rendered as SVG slides
      -area outfile     Document will be rendered as an Area Tree (XML)
      -screen           Document will be rendered to the screen
      -print            Document will be rendered to a printer

[Examples]

      org.foray.app.FOray -fo foo.fo -pdf foo.pdf
      org.foray.app.FOray -xsl foo.xsl -xml foo.xml -pdf foo.pdf
      org.foray.app.FOray -fo foo.fo -print
      org.foray.app.FOray -fo foo.fo -screen

The -so option allows any configuration option to be set from the command-line by supplying the key and value for that option. See FOray Configuration for details.

Using Xalan to Check XSL-FO Input

FOray 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 FOray output format). Although FOray controls both of these processes, the first is included merely as a convenience and for performance reasons. Only the second is part of FOray’s core processing. If a user has a problem running FOray, 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 FOray development team does not have resources to help with stylesheet issues, although we have included links to some useful Specifications and Books/Articles. If the problem is in the second process, FOray may have a bug or an unimplemented feature that does require attention from the FOray development team.

The user is always responsible to provide correct XSL-FO code to FOray.

In the case of using -xml and -xsl input, although the user is responsible for the XSL-FO code that is FOray’s input, it is not visible to the user. To make the intermediate FO file visible, the FOray 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.

When asking for help on the FOray mailing lists, never 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.

The scripts are invoked the same way that Xalan is:

xalan -in xmlfile -xsl file -out outfile

Note that there are some subtle differences between the "foray" and "xalan" command lines.

Memory Usage

Depending on several factors, FOray can consume quite a bit of memory. If you are running out of memory when using FOray, here are some ideas that may help:

• Increase the amount of memory available to the JVM. See the -Xmx option 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.)
• 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 ("page N of TOTAL"). 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).
• Avoid large images, especially if they are scaled down. If they need to be scaled, scale them in another application upstream from FOray. 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 FOray is running embedded, clearing the image from time to time cache might prevent memory exhaustion, you can call org.foray.graphic.GraphicFactory.resetCache() to empty the image cache.
• Use multiple page sequences. FOray 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.

One of FOray’s stated design goals is to be able to process input of arbitrary size, limited by storage instead of memory, and we will address this issue in a future release.