FOray’s Heritage & History

They also serve who refactor ... (with apologies to John Milton)

Contents

• Introduction
• Timeline
• Integration of FOray with FOP

Introduction

FOray is a fork of the Apache FOP project. FOP is an XSL-FO layout engine with a good, usable core codebase. According to the FOP Status Page, development on the working branch of FOP was halted on October 22, 2001. At that point, all developers were expected to focus their efforts on the new design, which was intended to address various shortcomings in the old design, mainly in layout. While this was a laudable goal, it cut developers off from enhancing working code, and essentially violated the well-known open-source principle of “release early, release often”.

Timeline

• May 17, 2004. Project created on SourceForge.
• May 31, 2004. Extraction of font classes into a separate module completed. Incidental to this were the creation of the FOrayGraphic and FOrayPDF modules, which are now also independent of fop-maint.

Integration of FOray with FOP

Note: All references to FOP on this page refer to the so-called maintenance branch unless otherwise noted. FOray was originally designed to be integrated with FOP, and the notes in this section are intended to help with that task.

It may be helpful to review the Module Basics page for more information about the dependencies between FOray and FOP.

The files checked into the FOray fop-maint module were obtained from FOP’s maintenance branch on or about May 18, 2004. (You may want to consider tagging them ASAP to facilitate any future integration. However, since the branch is mostly inactive, this may not be important). Those files have revision 1.1.1.1 in FOray’s repository.

FOray’s logistics have been set up partly to assist in any future integration of FOray into FOP. FOray releases will be tagged, so integration can hopefully be a matter of creating a diff between FOray’s new version and its old version of fop-maint, and applying that patch to the FOP maintenance branch. Integration with FOP’s trunk, if desired, will be more difficult, but should be made easier if it is done frequently, and if reference is made to what is going on in the maintenance branch. For this reason, it may be in FOP’s interest for at least one developer to monitor FOray’s progress.

After the initial period of refactoring is over, FOray will make reasonable attempts to keep its API backward-compatible.

FOray intends to support FOP in every reasonable way. Please let us know how we can help.

Any investment made by FOP into FOray integration is protected by the fact that FOray is also open-source, and FOP can bring FOray modules in-house at its convenience.

Light or Heavy?

There are at least two approaches that can be taken with regard to integration of FOray code back into FOP, which can be thought of as “light” and “heavy”.

The light approach is to check FORay’s fop-maint module into the FOP repository, which is where it came from in the first place. The net result of this would be as if the FORay developers had been working in the FOP maintenance branch repository unsupervised. After checking in, go through an alpha test-fix-reintegrate cycle with the FOray developers, then start into a normal beta process.

The heavy approach would be to follow and analyse the changes to the FOP code. This is clearly more time consuming on the front-end, but there may be good reasons to take this approach. If this approach is taken, please note the following items, which are basically fairly good-sized changes to the repository that have no effect on the logic of the system. You may want to handle these changes separately to minimize the amount of code deltas that you evaluate:

• The fop-maint build has been streamlined and somewhat simplified, by totally eliminating the “generate” part of the build (in which source files, and many resource files were built from xml source files during the build). All source code is now compiled in place, and all previously generated classes and resources were checked into the repository in their generated state. Although it would not be very difficult to switch back to the other mode, we don’t know of a good reason to do so. One file that had JDK dependencies coded into transformation-sensitive tags was moved to the src/jdk-1.3 and src/jdk-1.4 directories to accommodate this change. To isolate this set of changes, see revisions 1.3 through 1.8 of build.xml, which occurred on May 22, 2004. (Please note that there are a lot of other changes concurrent with those in build.xml).
• In compliance with FOP coding standards, FOray uses Unix-style line endings. However, numerous files in fop-maint (and therefore in the FOP maintenance branch also) have some lines with DOS and/or Mac line endings. To try to isolate these better, FOray committed one change on May 23, 2004 at about 14:30 MDT (21:30 GMT) that should have cleaned up most of them.

Deleting files

For the first chunk of changes anyway, there are quite a few files deleted from fop-maint. These are related to 1) the changes to the build process noted above, and 2) the movement of font-related classes to FOray. While integrating the FOray fop-maint changes into FOP’s maintenance branch, it will be important to make the same deletions. There are several ways to do this. We used the Bourne shell command find . -type d -print to create lists of each directory, then did a diff on the two lists.