The aXSL FoTree Module

Contents

• Introduction
• Contract
• Exceptions
• Missing Interfaces?
• Missing Traits?
• Known Implementations
• Reference Applications

Introduction

The FoTree module provides client access to the relevant parts of a refined FO Tree, as defined by the XSL-FO Recommendation (see Exceptions below. Because the refined tree is exposed, the methods that return property values include the term "trait" in their names. Not all objects and properties are exposed in the API, because some of them are needed only for internal FO Tree purposes (see below for details). Implementations of axslFoTree typically parse an input file or stream to create the FO Tree content.

Contract

In addition to compliance with the published API, implementations are expected to fully validate the input data. This means that an FoTreeException should be thrown for any data that does not conform to the data model specified in the standard, or that is identified as an error in the standard. For example, the standard indicates that a table-cell content model is "(%block;)+". An exception should be thrown if children are presented that do not conform to this model. The standard also specifies that "It is an error if two or more table-cells overlap ..." (XSL-FO 1.1, Section 6.7.3". An exception should be thrown if they do, or the remedial steps specified near this statement should be implemented within the FO Tree itself.

In addition to these validation steps, the FO Tree is required to normalize the following items:

• table-cells that are children of table-header, table-footer, or table-body instead of table-row should be normalized by adding a "pseudo" table-row as their parent.

The purpose of the validation and normalization specified above is to allow client applications such as AreaTrees and Layout systems to rely on certain assumptions about the validity and structure of the FO Tree.

Exceptions

There are a few places where the aXSL API deviates from the XSL-FO 1.1 Recommendation:

• The Recommendation indicates that white-space-collapse should be handled during area tree construction instead of FO Tree refinement. We currently think that it can and should be handled during FO Tree refinement instead, and therefore have not exposed this trait in the API. aXSL FoTree implementations are required to return a "refined FO Tree" that has already processed this property. We have asked the XSL-FO Working Group for clarification, and this issue may be revisited in the future, depending on their response.
• The Recommendation indicates that white-space-treatment should be handled during area tree construction instead of FO Tree refinement. aXSL FoTree implementations are required to process the "ignore" value within the FO Tree. The remaining values must be processed during area construction.
• The Recommendation indicates that text-transform should be handled during FO Tree refinement. This is not possible when this property is applied to the initial-property-set object. The aXSL API therefore exposes a method for this trait for the initial-property-set object.

Missing Interfaces?

There are several pagination-related XSL-FO objects that do not have corresponding interfaces in the aXSL FoTree. It is not that these are unimportant, but rather that their operation is entirely internal to the FO Tree. Client applications only need to know what fo:simple-page-master they should use, so the "details" of these objects are hidden from the client applications:

• fo:layout-master-set
• fo:page-sequence-master
• fo:single-page-master-reference
• fo:repeatable-page-master-reference
• fo:repeatable-page-master-alternatives
• fo:conditional-page-master-reference

Similarly, the following flow-map related objects do not have corresponding interfaces in aXSL. Instead, the substantive information contained in these objects is exposed in methods found in PageSequence (which returns a list of Flows), SimplePageMaster (which returns a list of region-body instances and can return region-body instances when given their names), and Flow (which returns a list of region-body names into which the flow should be laid out):

• fo:flow-map
• fo:flow-assignment
• fo:flow-source-list
• fo:flow-name-specifier
• fo:flow-target-list
• fo:region-name-specifier

Missing Traits?

The table below is a comprehensive list of all XSL-FO 1.1 properties, and indicating either that a method exists to obtain the value of that property, or an explanation of why such a method does not exist. Note that the application must still be able to parse all of these properties. What is documented here is which properties are exposed to client applications.

Known Implementations

The known implementations of axslFoTree are:

• [open source] FOrayFoTree

Reference Applications

Reference applications contain working code that uses axslFoTree:

• [open source] FOray