FOray
|
FOray: Configuration
IntroductionMany 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:
Configuration FileThe 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:
Command-Line EntryTo 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: 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 OptionsThis section provides detailed information for configuration options at the session level, i.e. those options that are global in nature. base-directoryAccepts a URL. Default is the current directory. Use this entry to indicate a base directory for files used by FOray. cache-graphicsAccepts 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-configurationAccepts 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-directoryAccepts 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-configurationAccepts a URL. Default is null. Use this entry to set the path to the font configuration file. hyphenation-base-directoryAccepts 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. languageAccepts a string describing the natural language in which messages should be logged. This is currently ignored. All messages are logged in English. stroke-svg-textAccepts 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. verbosityAccepts one of "quiet", "normal", or "debug", each being more verbose than its predecessor. Default is "normal". xml-catalogAccepts 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:
Options Specific to the AT Rendererat-sparseAccepts 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 Rendererpdf-owner-passwordAccepts 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-passwordAccepts 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-printAccepts a boolean (true or false). Default is false (but is only effective if the document is encryped). pdf-user-modifyAccepts a boolean (true or false). Default is false (but is only effective if the document is encryped). pdf-user-copyAccepts a boolean (true or false). Default is false (but is only effective if the document is encryped). pdf-user-annotateAccepts a boolean (true or false). Default is false (but is only effective if the document is encryped). pdf-filtersAccepts 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-versionAccepts 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 Renderertxt-encodingAccepts a string. Applies to the TXT renderer only. Default is "UTF-8". See Java Charset documentation for more information. |