User agent = a rendererer, a viewer, or a SWIG wrapper calling the FO formatter
The formatter will deliver a sequence of areas grouped by pages.
The user agent shall ask to the formatter the pages in an order that meets its needs. It may also ask the formatter to keep them on disk for later use.
Rationale: Consider for exemple the effect of forward references; these will normally only delay the completion of a single page, which will appear in the output out of sequence. Some user agents cannot work with pages out of sequence. and it is simpler to implement a mechanism to reorder the pages once for all in the formatter, instead of implementing it in many user agents.
The ability to keep pages on disk is needed for the viewers, because they might request pages in random order when the user is browsing them, even after rendering has been completed.
The output API will allow for user agents to register as listeners on page completion events. The actual output will be passed as a parameter of the callback function. The user agent should consider this output as read-only. The formatter will be responsible of deleting these data in memory on return of the callback function. But it might keep a copy of these data on disk for later use.
There are two other events : start of document and end of document. An user agent can ask for a page even after the end of document event has been received.
The formatter will follow the model outlined in Section 4.9 of the XSL specification. Before it delivers it to the user agent, it simplifies this conceptual model, for example by making all coordinates absolute with respect to current page. The data delivered to the user agent will be in a simplified subset of SVG (Scalable Vector Graphics).
The formatter might chooses a better font accordingly to character's alphabet (Arabic, Hebrew, Japanese...). The formatter will also recode the characters to the font's encoding. Internally, the formatter will handle UTF-8.
The page description used internally by the formatter will consist in a sequence of areas. The areas describing each page are _exactly_ those described in the conceptual area tree in the XSL specification.
Rationale: This is based on experience with the prototype. It is easiest if the spec is not deviated from except for a very good reason, because otherwise confusion will result.
NOTE (AS): Do we want the areas to be organised as a sequence (i.e. a list), or as a tree? Bear in mind that if a sequence is used that the references (child-parent) will still be available, as they must in order to follow the XSL rendering model.
A sequence, if we use that, would be exactly the pre-order traversal of the area tree.
The major factor that may favour one approach over the other is z-index. We will have to think about this.
NOTE (EB): Do as you want. I tend to think that trees are usually something easy to manipulate, but you're the one that knows better what an area description is.
The internal description will manipulate areas as objects which are instances of subclasses of an Area class. This class will probably NOT be identical to any area classes used in formatting.
Here follows a list of potential traits that MAY be set on an Area.
NOTE (AS): We will have to further edit the lists. It does no harm to include any of these traits because they will certainly be available in the formatter. Basically it is a safe assumption that if a user agents needs one of these traits then it can be very easily made available by the formatter.