FOray: Configuration

• Introduction
  • Configuration File
  • Command-Line Entry
• General Options
• Options Specific to the AT Renderer
• Options Specific to the PDF Renderer
• Options Specific to the TXT Renderer

Introduction

Many aspects of FOray’s behavior are configurable, and the purpose of this document is to explain what aspects can be configured, and how to configure them. FOray options are supplied to the system through a consistent set of key-value pairs. There are several ways to set the values, with well-defined rules of precedence between them. For example, a value set from the command-line will override a value set in the configuration file. Configuration options can be set in the following ways, listed from lowest precedence to highest precedence:

• Default.
• Configuration file.
• Command-line entry.
• Programmatically through FOray’s Java API (precedence is up to the application setting the value).

Configuration File

The FOray configuration file is an XML file containing the various configuration options that you wish to set. The general structure of the configuration file is a series of <entry> tags, each containing a <key> and a <value>. Here is an example:

<entry>
  <key>stroke-svg-text</key>
  <value>false</value>
</entry>

The easiest way to get started using a FOray configuration file is to copy the sample found at {foray-dir}/conf/userconfig.xml to a location of your choice, and then to edit it according to your needs. It contains templates for some configuration options, most of which are commented out. Remove the comments and change the settings for entries that you wish to use. Be sure to follow any instructions, including comments which specify the value range. Also, since the configuration file is XML, be sure to keep it well-formed.

After creating your configuration file, you must tell FOray how to find it:

• If running FOray from the command-line, see the "-c" command-line option in Running FOray.
• If running FOray as an embedded application, see Parsing a Configuration File.
• Configuration options can also be set programmatically. See Configuring One Option for instructions on how to do so in an embedded environment.

Command-Line Entry

To set a configuration option from the command-line, use the "-so" (session option) flag. For example, the following will change the value for the font-base-directory:
-so font-base-directory /u/resources/fonts.

Option keys are always one word, but some option values are lists, and may contain zero or more words. In any case where the option value is not exactly one word, enclose the value in quotation marks so that the system can interpret it as one item. In cases where the option value is intended to be null, enclose a single space in quotation marks: " ".

General Options

This section provides detailed information for configuration options at the session level, i.e. those options that are global in nature.

base-directory

Accepts a URL. Default is the current directory. Use this entry to indicate a base directory for files used by FOray.

cache-graphics

Accepts a boolean (true or false). Default is false. Set to true if you want graphics to be kept in memory after they have been used, so that they can be reused later. If the same image is used repeatedly in a document, this will result in somewhat faster performance, at the price of using additional memory. If memory is tight, set this value to false.

dump-configuration

Accepts a boolean (true or false). Default is false. Set this to true to have FOray send a list of configuration options to the log.

font-base-directory

Accepts a URL. Default is the value of base-directory. Use this entry to indicate a base directory for the location of fonts that are described in the separate font configuration file. This allows the same font configuration file to be used for multiple systems.

font-configuration

Accepts a URL. Default is null. Use this entry to set the path to the font configuration file.

hyphenation-base-directory

Accepts a URL. Default is the value of base-directory. Use this entry to indicate a directory containing custom hyphenation files (if any). See FOray: Hyphenation for more information on creating and modifying hyphenation within FOray.

language

Accepts a string describing the natural language in which messages should be logged. This is currently ignored. All messages are logged in English.

stroke-svg-text

Accepts a boolean (true or false). Default is true. In some cases, some text in SVG documents is converted to graphical shapes instead of retaining its character as text. To force all text to be rendered as text, set stroke-svg-text = false.

verbosity

Accepts one of "quiet", "normal", or "debug", each being more verbose than its predecessor. Default is "normal".

xml-catalog

Accepts a string containing a URI pointing to an Oasis XML catalog. These catalogs are useful for documenting the location of DTDs on a local machine when the DTD cannot be accessed from the Internet. The URI entry must be in standard URI form. Here is an example: ///D:/xml-catalogs/standard-catalog.xml

Options Specific to the AT Renderer

at-sparse

Accepts a boolean (true or false). Default is false. Applies to the AT renderer only. If set to true, area-tree nodes below the block level are not rendered.

Options Specific to the PDF Renderer

pdf-owner-password

Accepts a string. Default is null. If set, the file will be encrypted with the owner password set to value. The password is currently used as the encryption key. Generally, if a user can supply this password, PDF applications will disregard any restriction on the PDF document.

If user access is restricted through another option, and no owner password has been supplied, a random password is used.

pdf-user-password

Accepts a string. Default is null. If set, the file will be encrypted with the user password set to value. If set, PDF applications should ask the user for this password before giving access to the document.

pdf-user-print

Accepts a boolean (true or false). Default is false (but is only effective if the document is encryped).

pdf-user-modify

Accepts a boolean (true or false). Default is false (but is only effective if the document is encryped).

pdf-user-copy

Accepts a boolean (true or false). Default is false (but is only effective if the document is encryped).

pdf-user-annotate

Accepts a boolean (true or false). Default is false (but is only effective if the document is encryped).

pdf-filters

Accepts a space-delimited ordered list of filters that should be applied to the PDF file when it is written. Valid values are flate, ascii-85, and ascii-hex. Default is "flate ascii-85". Filters are applied in the order listed. This option is primarily useful for debugging, because setting the value to null or an empty String will turn off all filtering.

pdf-version

Accepts a String. Valid values are "1.3", "1.4", "1.5", and "1.6". Default is "1.6", which can normally be safely used. Setting pdf-version to a lower value will only eliminate features if they are known to cause problems on PDF applications supporting only the lower version. PDF is designed so that applications that don't recognize features from a more advanced PDF version should simply ignore those features.

Options Specific to the TXT Renderer

txt-encoding

Accepts a string. Applies to the TXT renderer only. Default is "UTF-8". See Java Charset documentation for more information.