FOray: Release Notes, Release 0.2

Release 0.2 Changes of Interest to Users

FOray 0.2 is primarily for developers and module users. Although many parts of FOray work well, and are usable as modules, the application as a whole has some general problems that require attention.

Here are the more significant of the known issues:

• The FO Tree does not parse all expressions properly. Valid FO syntax is sometimes flagged as an error.
• The Area Tree does not handle tables and lists properly in most cases. Specifically, these items will likely not be placed in the proper place, and may not even be placed in a reasonable place.

General Configuration Changes

• The names of several configuration file entries have been changed for the sake of consistency and clarity:

  Old Name	New Name
  baseDir	base-directory
  debugMode	debug-mode
  dumpConfiguration	dump-configuration
  fontBaseDir	font-base-directory
  hyphenation-dir	hyphenation-base-directory
  stream-filter-list	pdf-filters
  strokeSVGText	stroke-svg-text

• A new command-line option "-so" (session option) has been added to allow the entry of any configuration option through the command-line. See FOray Configuration for more details.
• The names of several renderer options (set through command-line options or through the API) have been changed for the sake of consistency and clarity. In addition, some general command-line options have been replaced by general configuration options. Even though the old command-line options have been removed, their functional equivalent can be attained by using the new "-so" command-line option together with the new configuration option.

  Old Command-line Option	Old Renderer Option Name	New Configuration Key
  -o	ownerPassword	pdf-owner-password
  -u	userPassword	pdf-user-password
  -noprint	allowPrint	pdf-user-print
  -nocopy	allowCopyContent	pdf-user-copy
  -noedit	allowEditContent	pdf-user-modify
  -noannotations	allowEditAnnotations	pdf-user-annotate
  -txt.encoding	unknown	txt-encoding
  -s	unknown	at-sparse
  -q	n/a	verbosity
  -d	n/a	verbosity
  -x	n/a	dump-configuration (already existed)
  -l	n/a	language

• Configuration options whose value is a list are now entered as space-delimited Strings. Previously these were placed in the configuration file as value elements inside of a list element. This change was made to facilitate making these options available on the command line.
• A boolean configuration option cache-graphics was added. It defaults to "false". If set to true, graphic objects will be cached and can be reused, resulting in potential speed improvement. If set to false, graphic objects are not reused, resulting in potential memory savings.

Font Changes

• The intermediate font-metrics xml file is no longer used. Instead, font resources are read on-the-fly as needed. This has resulted in numerous changes to the font configuration file (see below).
• Fonts used by the system are no longer read entirely into memory, but are read from disk as necessary. This, along with some other improvements, should reduce the amount of memory needed for fonts.
• The embed="all" attribute for the <font> element in the font configuration file is now respected for CID fonts.
• PDF output for CID fonts now includes the ToUnicode CMap. This allows cut-and-paste, index, search, etc. to work correctly on PDF text for these fonts. This fixes FOP's Bugzilla entry #5335.
• Italic angle information is now parsed from PFM files.
• FontBBox and StemV (StdVW) information is now parsed from PFA and PFB files.
• Adobe Font Metrics (AFM) files may now be used for font metrics. To use this option, set the font configuration item metrics-file to point to an AFM file. AFM files are now the preferred way to communicate font metrics. Note that users can easily modify AFM files to correct bad font information. Also AFM files can theoretically be used for bitmapped fonts.
• Kerning has been fixed for subsetted fonts. Kerning now works correctly for all supported formats.
• The command-line class PFMReader has been removed.
• The command-line class TTFReader has been changed. It now takes either one or two arguments. If given one, and that one is a TrueType collection file, the list of fonts within that collection will be written. If given a TrueType collection file followed by the name of a font within that file, some basic metrics will be parsed and written. If given one argument, and that argument is a regular TrueType file, the basic metrics of that file will be parsed and written. This tool is useful primarily to see the list of fonts in a TTC file, and as a debugging tool if metrics do not seem to be computed properly.
• It is now possible to actively prevent the embedding of font files whose permissions restrict embedding, and FOray does prevent such embedding.
• The font-base-directory configuration option is now used as a base directory for font-file and metrics-file. It was formerly used as a base directory for the intermediate xml font metrics files.

Font Configuration Changes

The configuration of fonts has change dramatically. See Font Configuration for details on the changes listed.

• The server element has been added.
• The parameter element has been added.
• The glyph-list element has been added.
• The encoding element has been added.
• The font-family element has been added.
• The font-family-alias element has been added.
• The font-triplet element has been renamed to font-description. The font-description element must now be inside a font-family element.
• The name attribute of the element font-description (formerly font-triplet) has been removed. Instead the font-description element is placed inside a font-family element, which contains the name.

The following have been added as attributes to the font element. These were formerly command-line options in TTFReader and PFMReader (the applications that built the font metrics files):

• font-resource (was the "-er" [embed-resource] command-line option). Font files can be included in fop.jar when building fop. Both font-resource and font-file can be specified for the same font, but if font-file is specified and can be opened, it will take precedence over font-resource. Please note that the companion option -ef already exists in the font configuration file as embed-file (now called font-file).
• embed-name (was the "-fn" command-line option). If embed-name is specified, it will be used as the name of the font in the output document, if the font is embedded in that document. This is sometimes useful when trying to ensure that the embedded font is used in the document instead of a system font with the same name. (Note that if embed-name is not specified, FOray first attempts to extract and embed the name from the font itself. If that fails, it uses the configured attribute name.
• ttc-name (was the "-ttcname" command-line option. If you are reading data from a TrueType Collection (.ttc file) you must specify which font from the collection you will read metrics from.
• metrics-file. This was formerly the pfm-file that was designated positionally on the command-line. It must now be explicitly identified in the configuration file for Type 1 fonts. Please note that this is not the same meaning that metrics-file previously had. Before FOray 0.2, the metrics-file attribute pointed to the (no-longer-used) intermediate xml file that was parsed from font metrics information.
• embed. This was formerly implied by the use of embed-file and embed-resource. Since those attributes have been renamed to clarify their use, you must now explicitly state what embedding behavior is desired. Valid options are "all", "subset", and "none". The default is "none".

In addition, the following changes related to the direct parsing of font files have been made:

• The name attribute has been added for the element font in the font configuration file. This is currently not used at all, except as a fallback name to be embedded in an output file if no other name can be found. Its main purpose is for reference in writing and parsing the configuration file, but it may be used as a "key" for other configuration elements in the future.
• The former attribute embed-file for the element font in the font configuration file, has been renamed to font-file. This change was made for clarity since, for some font types, the font file contains both the embedding information and the metrics information.
• Note that the former TTFReader command-line option "-enc" has no analog in the configuration file. The artifical reencoding that this option enabled is no longer necessary now that CID fonts are properly embedded in the PDF output (see change below regarding ToUnicode CMap).

Other Changes

• Since we have now obtained rights to the internet domain "foray.org", the package structure of all FOray module classes has been moved from "com.outfitr" to "org.foray". The package structure for fop-maint remains unchanged.
• Starting with Release 0.2, FOray requires a minimum java runtime environment of 1.4.
• All properties should now be supported at the parse level, including those properties (like aural properties) that are not directly used by any FOray application. This also includes all shorthand properties. Please note that this does not mean that all properties are used or used properly by the layout or rendering systems.
• The class for running FOray from the command-line has been renamed "FOray".
• The outer-layer application API has changed significantly. This will not affect command-line users, but will affect anyone running FOray embedded within another application. Details of the new API can be found at The FOray Application, and at the run() method in the class CommandLineStarter.
• Support for the Jimi package has been removed from FOrayGraphic. We will consider adding it back if there is sufficient user demand. It was used only for supporting PNG, which is adequately supported by JAI.
• Extensions which used the fox: namespace in FOP 0.20.5 are supported in FOray under the foray: namespace with the following exceptions: 1) Support for the extension objects foray:outline and foray:label has been dropped in favor of the scheme being considered for XSL-FO 1.1, which uses bookmark-tree, bookmark, and bookmark-title objects instead. 2) The extension object foray:destination has been dropped. Named destinations are now automatically created for objects with the "id" property.
• Support for the text-transform property was added.
• A configuration option "pdf-version" was added. It defaults to "1.6", the latest version of PDF. See pdf-version configuration for more information.

Release 0.2 Changes of Interest to Developers

Modularity Changes

As of Release 0.2, all FOray modules are independent of each other, using the aXSL interfaces to achieve pluggability and interoperability. With the exception of dependencies on the utility-type modules (Common, Pretty, and PS), FOray modules now have no dependencies on other FOray modules.

• The following methods have been added to the FontConsumer interface to allow the client application to control what combinations of FreeStandingFonts and SystemFonts should be used: boolean isUsingFreeStandingFonts(), and boolean isUsingSystemFonts().
• The classes FontInfo and FontTriplet, which represented temporary data structures used during the parsing of the font configuration file, have been eliminated. Fonts and font descriptions are now registered on-the-fly as the font configuration file is parsed.
• A method FontServer.optimizeFonts(FontConsumer consumer) has been added. This method optimizes fonts in preparation for embedding. Currently, the only optimization implemented is that subset font glyph indices are sorted by their Unicode code point, which potentially saves space in PDF files. Caveat: The timing of when this process is run is very critical. It should only be run after all glyph indices that are used by the FontConsumer have been registered. It should also only be run before any glyph indices have been written to actual document output. If the client runs the registration and writing tasks concurrently, it should not use this method, as doing so will corrupt the logical connection between the glyph indices used to embed the font and those used to write the document contents. Please note that FOray's reference FO processing implementation is currently unable to use this method because of such concurrent processing.
• To assist in parsing Type1 fonts, FOray now has the modest beginnings of a PostScript interpreter emulation. It is included as part of the new "FOrayPS" module. We hope to use this for future project such as embedding EPS files in PDF output.
• The filter and encoding classes that were part of the pdf module have been moved to the new ps module. The theory here is that PDF is kind of a superset of PostScript, and that items common to both should live with PostScript.
• FontServer can (and in fact must) now be instantiated, and its variables and methods are no longer static (except for a few utility methods). It is still intended to be used as a singleton, but there is no requirement that it be so, and, with reasonable care, multiple instances should be manageable. A getFontServer() method has been added to the FontConsumer interface, as the FontConsumer must now know which FontServer it is using.
• Each of the Font, Graphic, and Text subsystems now has a Server class associated with it (e.g. GraphicServer). Instances of these servers may be passed to FOraySession's constructor. If not, default instances will be created by FOraySession. This means that you can enhance your local system by extending these Server classes. Also, because the Servers live outside of the FOray application, they can conceivably persist for multiple Sessions.
• GraphicServer has a new method registerFactory, which accepts one GraphicFactory as a parameter. Once registered, a custom factory will be consulted as each Graphic is constructed. A GraphicFactory only reads through enough of the file contents to determine whether the file is of the type that it knows how to create. If so, it can create the Graphic instance. Custom factories are consulted before standard factories, allowing developers to extend FOrayGraphic capabilities along a new dimension.
• A new Namespace class has been added in FOTree to manage the various issues associated with managing multiple namespaces within the FOTree itself. Each Namespace instance is responsible to convert elements and attributes in its namespace into FObj and Property instances that can be placed in the FOTree. Custom Namespace instances can be registered to the FOraySession instance through the registerNamespace() method, which accepts one Namespace instance as a parameter.