Extensible Stylesheet Language (XSL)
Version 1.0

W3C Working Draft 12 January 2000

This version:

http://www.w3.org/TR/2000/WD-xsl-20000112

Latest version:

http://www.w3.org/TR/xsl

Previous version:

http://www.w3.org/TR/1999/WD-xsl-19990421

Authors and Contributors:

Sharon Adler (IBM) <sca@us.ibm.com>
Anders Berglund (IBM) <alrb@us.ibm.com>
Jeff Caruso (Bitstream) <jcaruso@bitstream.com>
Stephen Deach (Adobe) <sdeach@adobe.com>
Alex Milowski (Lexica) <alex@milowski.com>
Scott Parnell (Xerox) <Scott.Parnell@usa.xerox.com>
Jeremy Richman (Interleaf) <jrichman@hq.ileaf.com>
Steve Zilles (Adobe) <szilles@adobe.com>

Copyright ©2000 W3C^® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

---

Abstract

XSL is a language for expressing stylesheets. It consists of two parts:

1. a language for transforming XML documents, and

2. an XML vocabulary for specifying formatting semantics.

An XSL stylesheet specifies the presentation of a class of XML documents by describing how an instance of the class is transformed into an XML document that uses the formatting vocabulary.

Status of this document

This is a W3C Working Draft for review by W3C members and other interested parties. This adds additional functionality to what was described in the previous draft. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. The XSL Working Group will not allow early implementation to constrain its ability to make changes to this specification prior to final release. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of current W3C working drafts can be found at http://www.w3.org/TR/.

This document has been produced as part of the W3C Style Activity by the XSL Working Group (members only).

Comments may be sent to xsl-editors@w3.org. Public discussion of XSL takes place on the XSL-List mailing list.

Table of contents

Appendices

1 Introduction to XSL

1.1 Processing a stylesheet

The following section is still to be developed. It will contain pictures and an explanation of the XSL "Processing Model".

1.1.1 Transformation

TBD

1.1.2 Formatting

TBD

1.1.3 Rendering

Issue (imaging-model-font-indices):

The plan is to reference SVG Section 4: Rendering Model. Does SVG permit glyph indices into a particular font?

1.2 An example

TBD

1.3 Why XSL => Benefits of XSL

TBD

1.4 How to Read this Document

TBD

2 Introduction to XSL Transformation

What this section will contain:

XSLT fits in how

This is the normative reference to XSLT

2.1 Tree Construction

Issue (xslt-reference):

This serves temporary place-holder

The Tree Construction is described in "XSL Transformations (XSLT)".

The provisions in "XSL Transformations" form an integral part of this recommendation and are considered normative.

2.2 XSL Namespace

The XSL namespace has the URI http://www.w3.org/1999/XSL/Format.

NOTE:

The 1999 in the URI indicates the year in which the URI was allocated by the W3C. It does not indicate the version of XSL being used.

XSL processors must use the XML namespaces mechanism [W3C XML Names] to recognize elements and attributes from this namespace. Elements from the XSL namespace are recognized only in the stylesheet, not in the source document. Implementors must not extend the XSL namespace with additional elements or attributes. Instead, any extension must be in a separate namespace.

This specification uses the prefix fo: for referring to elements in the XSL namespace. However, XSL stylesheets are free to use any prefix, provided that there is a namespace declaration that binds the prefix to the URI of the XSL namespace.

An element from the XSL namespace may have any attribute not from the XSL namespace, provided that the expanded-name of the attribute has a non-null namespace URI. The presence of such attributes must not change the behavior of XSL elements and functions defined in this document. Thus, an XSL processor is always free to ignore such attributes, and must ignore such attributes without giving an error if it does not recognize the namespace URI. Such attributes can provide, for example, unique identifiers, optimization hints, or documentation.

It is an error for an element from the XSL namespace to have attributes with expanded-names that have null namespace URIs (i.e., attributes with unprefixed names) other than attributes defined for the element in this document.

NOTE:

The conventions used for the names of XSL elements, attributes, and functions are as follows: names are all lower-case, hyphens are used to separate words, dots are used to separate names for the components of complex datatypes, and abbreviations are used only if they already appear in the syntax of a related language such as XML or HTML.

3 Introduction to Formatting

The aim of this section is to describe the general process of formatting, enough to read the area model and the formatting-object descriptions and properties and to understand the process of refinement.

Formatting is the process of turning the result of an XSL transformation into a tangible form for the reader or listener. This process comprises several steps, some of which depend on others in a non-sequential way. Our model for formatting will be the construction of an area tree, which is an ordered tree containing geometric information for the placement of every glyph, shape, and image in the document, together with information embodying spacing constraints and other rendering information; this information is referred to under the rubric of traits, which are to areas what properties are to formatting objects and attributes are to XML nodes. Section 4 (see [4 Area Model]) will describe the area tree and define the default placement-constraints on stacked areas. However, this is an abstract model which need not be actually implemented in this way in a formatter, so long as the resulting tangible form obeys the implied constraints.

Formatting objects are elements in the formatting-object tree, whose names are from the XSL namespace; a formatting object belongs to a class of formatting objects identified by its element name. The formatting behavior of each class of formatting objects is described in terms of what areas are created by a formatting object of that class, how the traits of the areas are established based, and how the areas are structured hierarchically with respect to areas created by other formatting objects. Sections 6 (see [6 Formatting Objects]) and Section 7 (see [7 Formatting Properties] describe formatting objects and their properties.

Some formatting objects are block-level and others are inline-level. This refers to the types of areas which they generate, which in turn refer to their default placement method. Inline-areas (for example, glyph-areas) are collected into lines and the direction in which they are stacked is the inline-progression-direction. Lines are a type of block-area and these are stacked in a direction perpendicular to the inline-progression-direction, called the block-progression-direction. See Section 4 for detailed decriptions of these area types and directions.

In Western writing systems, the block-progression-direction is "top-to-bottom" and the inline-progression-direction is "left-to-right". This specification treats other writing systems as well and introduces the terms "block" and "inline" instead of using absolute indicators like "vertical" and "horizontal". Similarly this specification tries to give relatively-specified directions ("before" and "after" in the block-progression-direction, "start" and "end" in the inline-progression-direction) where appropriate, either in addition to or in place of absolutely-specified directions such as "top", "bottom", "left", and "right". These are interpreted according to the value of the writing-mode property.

Central to this model of formatting is refinement. This is a computational process which finalizes the specification of properties based on the attribute values in the XML result tree. Though the XML result tree and the formatting-object tree have very similar structure, it is helpful to think of them as separate conceptual entities. Refinement involves

• propagating the various inherited values of properties (both implicitly and those with an attribute value of "inherit"),

• evaluating expressions in property value specifications into actual values, which are then used to determine the value of the properties

• converting relative numerics to absolute numerics,

• constructing some composite properties from more than one attribute,

• converting text nodes to sequences of fo:character formatting objects,

• creating implied fo:bidi-override formatting objects to support mixed writing directions.

Some of these operations (particularly evaluating expressions) depend on knowledge of the area tree. Thus refinement is not necessarily a straightforward, sequential procedure, but may involve look-ahead, back-tracking, or control-splicing with other processes in the formatter. Refinement is described more fully in Section 5. See (see [5 Property Refinement / Resolution]).

To summarize, formatting proceeds by constructing an area tree (containing areas and their traits) which satisfies constraints based on information contained in the XML result tree (containing element nodes and their attributes). Conceptually, there is an intermediate step of refinement, constructing a formatting-object tree (containing formatting objects and their properties); this step may proceed in an interleaved fashion during the construction of the area tree.

3.1 Conceptual Procedure

This subsection contains a conceptual description of how formatting could work. This conceptual procedure does not mandate any particular algorithms or data structures as long as the result obeys the implied constraints.

The procedure works by processing formatting objects. Each object, while being processed, may initiate processing in other objects. While the objects are hierarchically structured, the processing is not; processing of a given object is rather like a co-routine which may pass control to other processes, but pick up again later where it left off. The procedure starts by initiating the processing of the fo:root formatting object.

Unless otherwise specified, processing a formatting object creates areas and returns them to its parent to be placed in the area tree. Like a co-routine, it resumes control later and initiates formatting of its own children (if any), or some subset of them. The formatting object supplies parameters to its children based on the traits of areas already in the area tree, possibly including areas generated by the formatting object or its ancestors. It then disposes of the areas returned by its formatting-object children. It might simply return such an area to its parent (and will always do this if it does not generate areas itself), or alternatively it might arrange the area in the area tree according to the semantics of the formatting object; this may involve changing its geometric position. It terminates processing when all its children have terminated processing (if initiated) and it is finished generating areas.

Some formatting objects do not themselves generate areas, instead these formatting objects simply return the areas returned to them by their children. Alternatively, a formatting object may continue to generate (and return) areas based on information discovered while formatting its own children; for example, the fo:page-sequence formatting object will continue generating pages as long as it contains a flow with unprocessed descendants.

Areas received by an fo:root formatting object are pages, and are simply placed as children of the area tree root in the order in which they are returned, with no geometrical implications.

As a general rule, the order of the area tree parallels the order of the formatting-object tree. That is, if one formatting object precedes another in the depth-first traversal of the formatting-object tree, with neither containing the other, then all the areas generated by the first will precede all the areas generated by the second in the depth-first traversal of the area tree, unless otherwise specified. Typical exceptions to this rule would be things like inline floats, block floats, and footnotes.

At the end of the procedure, the areas and their traits have been constructed, and they are required to satisfy constraints described in the definitions of their associated formatting objects, and in the area model section. In particular, size and position of the areas will be subject to the placement and spacing constraints described in the area model, unless the formatting-object definition indicates otherwise.

The formatting-object definitions, property descriptions, and area model are not algorithms. Thus, the formatting-object semantics do not specify how the line-breaking algorithm must work in collecting characters into words, positioning words within lines, shifting lines within a container, etc. Rather this specification assumes that the formatter has done these things and describes the constraints which the result is supposed to satisfy.

4 Area Model

In XSL, one creates a tree of formatting objects that serve as inputs or specifications to a formatter. The formatter generates a hierarchical arrangement of areas which comprise the formatted result. This section defines the general model of areas and how they interact. The purpose is to present an abstract framework which is used in describing the semantics of formatting objects. It should be seen as describing a series of constraints for conforming implementations, and not as prescribing particular algorithms.

4.1 Introduction

The formatter generates an ordered tree, the area tree, which describes a geometric structuring of the output medium. The terms child, sibling, parent, descendant, and ancestor refer to this tree structure. The tree has a root node.

Each area tree node other than the root is called an area and is associated to a rectangular portion of the output medium. Areas are not formatting objects; rather, a formatting object generates zero or more rectangular areas, and normally each area is generated by a unique object in the formatting object tree.

NOTE:

The only exceptions are when several leaf nodes of the formatting object tree are combined to generate a single area, for example when several characters in sequence generate a single ligature glyph. In all such cases, relevant properties such as font-family and font-size are the same for all the generating formatting objects.

An area has a content-rectangle, the portion in which its child areas are assigned, and optional padding and border. The diagram shows how these portions are related to one another. The outer bound of the border is called the border-rectangle, and the outer bound of the padding is called the padding-rectangle.

Each area has a set of traits, a mapping of names to values, in the way elements have attributes and formatting objects have properties. Individual traits are used either for rendering the area or for defining constraints on the result of formatting, or both. Traits used strictly for formatting purposes or for defining constraints may be called formatting traits, and traits used for rendering may be called rendering traits. For the complete list of the type of traits see [C Property Index].

The semantics of each type of formatting object that generates areas are given in terms of which areas it generates and their place in the area-tree hierarchy. This may be further modified by interactions between the various types of formatting objects. The properties of the formatting object determine what areas are generated and how the formatting object's content is distributed among them. (For example, a word that is not to be hyphenated may not have its glyphs distributed into areas on two separate line-areas.)

The traits of an area are either:

1. "directly-derived" -- The values of directly-derived traits are the computed value of a property of the same name on the generating formatting object, or

2. "indirectly-derived" -- The values of indirectly-derived traits are the result of a computation involving the computed values of one or more properties on the generating formatting object, other traits on this area or other interacting areas (ancestors, parent, siblings, and/or children) and/or one or more values constructed by the formatter. The calculation formula may depend on the type of the formatting object.

This description assumes that refined values have been computed for all properties of formatting objects in the result tree, i.e., all relative and corresponding values have been computed and the inheritable values have been propagated as described in [5 Property Refinement / Resolution]. This allows the process of inheritance to be described once and avoids a need to repeat information on computing values in this description.

4.2 Rectangular Areas

4.2.1 Area Types

There are two types of areas: block-areas and inline-areas. These differ according to how they are typically stacked by the formatter. An area can have child areas of one type or the other as determined by the generating formatting object, but an area's children must all be of one type. One should note that although block-areas and inline-areas are typically stacked, some areas can be explicitly positioned.

A line-area is a special kind of block-area whose children are all inline-areas. A glyph-area is a special kind of inline-area which has no child areas, and has a single glyph image as content.

Typical examples would be: a paragraph rendered by using an fo:block formatting object, which generates block-areas, and a character rendered by using an fo:character formatting object, which generates an inline-area (in fact, a glyph-area).

4.2.2 Common Traits

Associated with any area are two directions, which are derived from the generating formatting object's "writing-mode" and "reference-orientation" properties: the block-progression-direction is the direction for stacking block-area descendants of the area, and the inline-progression-direction is the direction for stacking inline-area descendants of the area. Another trait, the shift-direction, is present on inline-areas and refers to the direction in which the baseline shifts are applied. Also the glyph-orientation defines the orientation of glyph-images in the rendered result.

An area has a Boolean trait is-indent-reference, which determines whether or not it establishes a coordinate system for specifying indents. An area for which this trait is true is called a reference-area. A reference-area may be either a block-area or an inline-area.

A set of traits describes the position, height, and width of the area. Other traits specify:

• the amount of space outside the border-rectangle: space-before, space-after, space-start, and space-end (though some of these may be required to be zero on certain classes of area);

• the thickness of each of the four sides of the padding: padding-before, padding-after, padding-start, and padding-end;

• the style, thickness, and color of each of the four sides of the border: border-before, etc.; and

• the background rendering of the area: background-color, etc.

4.2.3 Geometric Definitions

As described above, the content-rectangle is the rectangle bounding the inside of the padding and is used to describe the constraints on the positions of descendant areas. It is possible that marks from glyph contents or descendant areas may appear outside the content-rectangle.

Related to this is the allocation-rectangle of an area, which is used to describe the constraints on the position of the area within its parent area. For an inline-area this extends to the content-rectangle in the block-progression-direction and to the border-rectangle in the inline-progression-direction.

Allocation- and content-rectangles of an inline-area

For a block-area, it extends to the border-rectangle in the block-progression-direction and outside the border-rectangle in the inline-progression-direction by an amount equal to the space-end, and in the opposite direction by an amount equal to the space-start. The traits actual-height and actual-width of an area apply to the content-rectangle.

NOTE:

The inclusion of space outside the border-rectangle of a block-area in the inline-progression-direction does not affect placement constraints, and is intended to promote compatibility with the CSS box model.

Allocation- and content-rectangles of a block-area

The edges of a rectangle are designated as follows:

• the before-edge is the edge occurring first in the block-progression-direction and perpendicular to it;

• the after-edge is the edge opposite the before-edge;

• the start-edge is the edge occurring first in the inline-progression-direction and perpendicular to it,

• the end-edge is the edge opposite the start-edge.

The following diagram shows the correspondence between the various edge names for a mixed writing-mode example:

For purposes of this definition, the content-rectangle of an area uses the inline-progression-direction and block-progression-direction of that area; but the border-rectangle, padding-rectangle, and allocation-rectangle use the directions of its parent area. Thus the edges designated for the content-rectangle may not correspond with the same-named edges on the padding-, border-, and allocation-rectangles. This is important in the case of nested block-areas with different writing-modes.

Each inline-area has a designated position-point on the start-edge of its allocation-rectangle; for a glyph-area, this is a point on the leading edge of the glyph on its nominal baseline. The descent of an inline-area is defined to be how far its allocation-rectangle extends in the block-progression-direction from the position-point, and the ascent is defined to be how far the allocation-rectangle extends in the opposite direction. Together these add up to the actual-height of the inline-area.

4.2.4 Ordering

In the area tree, the set of areas with a given parent is ordered. The terms initial, final, preceding, and following refer to this ordering.

This extends to a strict partial ordering among all descendant areas of a given area by saying (recursively) that A precedes B (and B follows A) when

• A precedes B under the same parent, or

• A precedes the parent of B, or

• A's parent precedes B.

(This is a only a partial ordering, since it does not define an area as following or preceding its descendant areas.)

If C follows A and precedes B, C is said to be between A and B.

Typically areas follow one another in sequence when stacked, but some areas may be marked as not following the main sequence (e.g., floats and absolutely positioned areas). The out-of-sequence trait is a Boolean value which is true if the area is to be treated in this way; a sequenced-area is an area for which this trait is false.

Issue (out-of-line-or-sequence):

Inadvertent inconsistency between Area Model that uses term "out-of-sequence" and Introduction to Formatting Objects that uses the term "out-of-line" to be consistent with the categorization of formatting objects in the April Draft. Another discrepancy is between "sequenced-area" and "normal area". These need to be harmonized.

If A and B are sequenced block-areas, A consecutively precedes B (or B consecutively follows A) if A precedes B and there is no sequenced-area between A and B, and further: (1) all ancestors of A which precede B have zero border-after and padding-after, and (2) all ancestors of B which follow A have zero border-before and padding-before.

Similarly, if A and B are inline-areas, A consecutively precedes B (or B consecutively follows A) if A precedes B and there is no area between A and B, and further: (1) all ancestors of A which precede B have zero border-end and padding-end, and (2) all ancestors of B which follow A have zero border-start and padding-start.

NOTE:

The intention of the definition is to identify areas at any level of the tree which have only space between them.

Example. In this diagram each node represents a block-area. Assume that all padding and border widths are zero. Then A consecutively precedes B, A consecutively precedes C, C consecutively precedes D, B consecutively precedes E, and D consecutively precedes E; these are the only pairs of consecutively preceding elements in the diagram. If B had non-zero padding-after, then D would not consecutively precede E (though B would still consecutively precede E).

Recursively define an area A to be leading in another area B if

1. A is the initial child of B, or

2. A is the initial child of an area C, where C is leading in B and C has zero border-before and padding-before.

Define an area A to begin an area B if A is leading in B and all of A's ancestors which are descendants of B have zero space-before.

Recursively define an area A to be trailing in another area B if

1. A is the final child of B, or

2. A is the final child of an area C, where C is trailing in B and C has zero border-after and padding-after.

Define an area A to end an area B if A is trailing in B and all of A's ancestors which are descendants of B have zero space-after.

NOTE:

It is possible for several areas to be leading or trailing, e.g., if the first child area is a block-area that has nested block-areas.

Example. In this diagram each node represents a block-area. Assume that all areas have zero border and padding. Then A, B, and C are all leading areas in P. If B had non-zero before-border, then only A and B would be leading in P.

4.3 Spaces and Conditionality

A space-specifier is a compound datatype consisting of a minimum, optimum, and maximum, conditionality, and precedence.

Minimum, optimum, and maximum are lengths and can be used to define a constraint on a distance, namely that the distance should preferably be the optimum, and in any case no less than the minimum nor more than the maximum. Any of these values may be negative, which can (for example) cause areas to overlap, but in any case the minimum should be less than or equal to the optimum value, and the optimum less than or equal to the maximum value.

Conditionality is a Boolean value which controls whether a space-specifier has effect at the beginning or end of a reference-area; a conditional space-specifier is one for which this value is true.

Precedence has a value which is either an integer or the special token force. A forcing space-specifier is one for which this value is force.

Space-specifiers occurring in sequence may interact with each other. The constraint imposed by a sequence of space-specifiers is computed by calculating for each space-specifier its associated resolved space-specifier in accordance with their conditionality and precedence, as shown below in the space-resolution rules.

The constraint imposed on a distance by a sequence of resolved space-specifiers is additive; that is, the distance is constrained to be no less than the sum of the resolved minimum values and no larger than the sum of the resolved maximum values.

Recursively define that a space-specifier S' consecutively follows another space-specifier S (and S consecutively precedes S') if

1. S' is the space-before of a block-area, and S is the space-after of the area's preceding sibling, or

2. S' is the space-after of a block-area B, where B has zero padding-after and border-after and is not a reference-area, and S is the space-after of a block-area A which is a not a line-area, and A is the final child of B, or

3. S' is the space-before of a block-area B, where B has zero padding-before and border-before and is not a reference-area, and S is the space-before of a block-area A which is not a line-area, and A is the initial child of B, or

4. S' is the space-start of an inline-area, and S is the space-end of the area's preceding sibling, or

5. S' is the space-end of an inline-area I, where I has zero padding-end and border-end values, and is not a reference-area, and S is the space-end of the final child of I, or

6. S' is the space-start of an inline-area I, where I has zero padding-start and border-start values and is not a reference-area, and S is the space-start of the initial child of I, or

7. S' consecutively follows a space-specifier S'', S'' consecutively follows S, and S'' has zero values for minimum, optimum, and maximum.

Space-resolution rules. To compute the resolved space-specifier of a given space-specifier S, consider the maximal sequence of space-specifiers containing S in which each is consecutively followed by the next. The resolved space-specifier of each of these space-specifiers is a non-conditional space-specifier computed in terms of this sequence.

1. If any of the space-specifiers is conditional, and is the space-before of an area which begins a reference-area, then it is suppressed, which means that its resolved space-specifier is zero. Further, conditional space-specifiers which consecutively follow a space-specifier suppressed in this way are also suppressed.

If a conditional space-specifier is the space-after of an area which ends a reference-area, then it is suppressed together with any other conditional space-specifiers which consecutively precede it.

2. If any of the remaining space-specifiers is forcing, all non-forcing space-specifiers are suppressed, and the value of each of the forcing space-specifiers is taken as its resolved value.

3. Alternatively if all of the remaining space-specifiers are non-forcing, then the resolved space-specifier is defined in terms of those space-specifiers whose precedence is highest, and among these those whose optimum value is the greatest. All other space-specifiers are suppressed. If there is only one of these then its value is taken as its resolved value.

Otherwise the resolved space-specifier of the last space-specifier in the sequence is derived from these spaces by taking their common optimum value as its optimum, the greatest of their minimum values as its minimum, and the least of their maximum values as its maximum, and all other space-specifiers are suppressed.

Example. Suppose the sequence of space values occurring at the beginning of a reference-areas is: first, a space with value 10 points (that is minimum, optimum, and maximum all equal to 10 points) and conditionality true; second, a space with value 4 points and conditionality false; and third, a space with value 5 points and conditionality true; all three spaces having precedence zero. Then the first (10 point) space is suppressed under rule 1, and the second (4 point) space is suppressed under rule 3. The resolved value of the third space is a non-conditional 5 points, even though it originally came from a conditional space.

Note that the padding of a block-area does not affect the resolved value of any space-specifier (except that by definition, the presence of padding at the before- or after-edge causes space-specifiers around it to be non-consecutive.)

The border or padding at the before-edge of a block-area may be specified as conditional. If so, then it is set to zero if its space-before is zero or conditional, and either its space-before consecutively follows a conditional space suppressed under rule 1 or the area begins a reference-area. In this case, the border or padding is taken to be zero for purposes of the definition of when a space-specifier consecutively follows another. Similarly the border or padding at the after-edge of a block-area may be specified as conditional. If so, then it is set to zero if its space-after is zero or conditional, and either its space-after consecutively precedes a conditional space suppressed under rule 1 or the area ends a reference-area.

4.4 Block-areas

Block-areas have several traits which typically affect the placement of their children. The line-height is used in line placement calculations. So is its nominal-glyph-height, which is the size (in the block-progression-direction) of a glyph-area in the default font of the generating formatting object; this is the sum of its nominal-ascent and nominal-descent. These three "nominal" traits depend only on the default font and not on which glyphs (or fonts) actually occur among descendants of the block-area. The line-stacking-strategy trait controls what kind of allocation is used for descendant line-areas and has an enumerated value (either font-height, max-height, or line-height). This is all rigorously described below. All block-areas have these traits, but they only have meaning for areas which have stacked block-area children.

The space-before and space-after determine the distance between the block-area and surrounding block-areas.

A block-area which is not a line-area typically has its size in the inline-progression-direction determined by its start-indent and end-indent and by the size of its nearest ancestor reference-area. A block-area which is not a line-area typically varies in the block-progression-direction to accommodate its descendants. Alternatively the generating formatting object may specify a height for the block-area.

4.5 Stacked Block-areas

Block-area children of an area are typically stacked in the block-progression-direction within their parent area, and this is the default method of positioning such block-areas. However, formatting objects are free to specify other methods of positioning child areas of areas which they generate.

If P is an area with block-area children, a block-area descendant B of P is stackable in P if the out-of-sequence trait of B is false and either

1. B is a child area of P, or

2. B is a child area of a block-area A, where A is a stackable descendant of P, A is not a reference-area, and A has the same block-progression-direction and inline-progression-direction as P.

Example. In the diagram,P is a block area, B₁ is an embedded block-area, L₁,...,L₅ are line-areas, H is a block-area which is an inline float (with out-of-sequence trait equal to true) and B₂ is a block-area child of H, T is a reference-area which is a block-area generated by an fo:table formatting object, and C₁₁,...,C₂₂ are block-areas which represent cells of the table. In this case L₁, B₁, L₂, L₃, L₄, L₅, and T are all stackable in P. However, H, B₂, and C₁₁, ..., C₂₂ are not stackable in P, and thus the constraints described below do not involve them.

For a parent area P whose children are block-areas, P is defined to be properly stacked if all of the following conditions hold:

1. Either P is a reference-area R, or P has an ancestor reference-area and P's closest ancestor reference-area R has the same block-progression-direction and inline-progression-direction as P.

2. For each stackable block-area which is a descendant of P, the following hold:

   • the before-edge and after-edge of its allocation-rectangle are parallel to the before-edge and after-edges of the content-rectangle of P,

   • the start-edge of its allocation-rectangle is parallel to the start-edge of the content-rectangle of R, and offset from it by a distance equal to the block-area's start-indent plus its start-intrusion-adjustment, minus its border-start, padding-start, and space-start values, and

   • the end-edge of its allocation-rectangle is parallel to the end-edge of the content-rectangle of R, and offset from it by a distance equal to the block-area's end-indent plus its end-intrusion-adjustment, minus its border-end, padding-end, and space-end values.

   

   NOTE:

   The start-intrusion-adjustment and end-intrusion-adjustment are traits used to deal with intrusions from floats. The notion of indent is intended to apply to the content-rectangle, but the constraint is written in terms of the allocation-rectangle, because as noted earlier the edges of the content-rectangle may not correspond to like-named edges of the allocation-rectangle.

3. For each pair of stackable block-area descendants B and B' of P, if B precedes B' consecutively, then the distance from the after-edge of the allocation-rectangle of B to the before-edge of the allocation-rectangle of B' is consistent with the constraint imposed by the resolved values of the space-after traits of B and of any of its ancestors which precede B', and of the space-before traits of B' and of any of its ancestors which follow B.

   NOTE:

   In both this clause and the next, several block-areas may have placement constraints relative to another area or to the content-rectangle of P, and together these determine the size of all block-areas, which may affect things like which background color has effect at a given point.

   

   Example. In the diagram, if area A has a space-after value of 3 points, B a space-before of 1 point, and C a space-before of 2 points, all with precedence of force, and with zero border and padding, then the constraints will place B's allocation-rectangle 4 points below that of A, and C's allocation-rectangle 6 points below that of A. Thus the 4-point gap receives the background color from P, and the 2-point gap before C receives the background color from B.

4. The distance from the before-edge of the content-rectangle of P to the before-edge of the allocation-rectangle of any leading block-area descendant B of P is consistent with the constraint imposed by the resolved values of the space-before traits of B of all the ancestors of B which are descendants of P.

   Similarly, the distance from the after-edge of the allocation-rectangle of any trailing block-area descendant B' of P to the after-edge of the content-rectangle of P is consistent with the constraint imposed by the resolved values of the space-after traits of B' and of all the ancestors of B' which are descendants of P.

4.6 Line-areas

A line-area is a special type of block-area, and is generated by the same formatting object which generated its parent. Line-areas do not have borders and padding, i.e., border-before-width, padding-before-width, etc. are all zero.

The allocation-rectangle of a line is determined by the value of the line-stacking-strategy trait: if the value is font-height, the allocation-rectangle is the nominal-requested-line-rectangle, defined below; if the value is max-height, the allocation-rectangle is the maximum-line-rectangle, defined below; and if the value is line-height, the allocation-rectangle is the per-inline-height-rectangle, defined below.

The nominal-requested-line-rectangle for a line-area is the rectangle bounded in the inline-progression-direction by the content-rectangle of the parent block-area, as modified by typographic properties such as indents, and in the block-progression-direction by the nominal-glyph-height of the parent block-area. It has the same height for each line-area child of a block-area.

The maximum-line-rectangle for a line-area has the same length as the nominal-requested-line-rectangle in the inline-progression-direction. In the block-progression-direction, it is bounded by the maximum ascent and the maximum descent for the inline-areas descendants stacked within the line-area, as raised and lowered by the shift-amount trait perpendicular to the inline-progression-direction, but may not be less than the nominal-glyph-height. Its height may vary depending on the descendants of the line-area.

Nominal and Maximum Line Rectangles

The per-inline-height-rectangle has the same length as the nominal-requested-line-rectangle in the inline-progression-direction. For each inline-area the half-leading is defined to be half the difference of its line-height minus its actual-height. The expanded-ascent of an inline-area is its ascent plus half-leading, and the expanded-descent is its descent plus half-leading. As in the definition of the maximum-line-rectangle, this is raised or lowered according to mandated adjustments perpendicular to the baseline. The per-inline-height-rectangle extends in the line-progression-direction from the maximum expanded-ascent to the maximum expanded-descent over all the inline-area descendants stacked within the line-area. Its height may vary depending on the descendants of the line-area.

NOTE:

Using the nominal-requested-line-rectangle allows equal baseline-to-baseline spacing. Using the maximum-line-rectangle allows constant space between line-areas. Using the per-inline-height-rectangle and zero space-before and space-after allows CSS-style line box stacking.

Inline-areas are stacked within a line-area relative to a baseline-start-point which is a point on the start-edge of its content-rectangle, separated from the before-edge of the nominal-requested-line-rectangle by a distance equal to the nominal-ascent.

4.7 Inline-areas

An inline-area has its own line-height trait, which may be different from the line-height of its containing block-area. This may affect the placement of its ancestor line-area when the line-stacking-strategy is line-height. An inline area has a font-ascent and font-descent trait for the font associated with the generating formatting object.

An inline-area may or may not have child areas, and if so it may or may not be a reference-area. The content-rectangle for an inline-area without children has a specified size in both dimensions. An inline-area with children has a content-rectangle which is the minimum rectangle (with sides parallel to those of the content-rectangle of its parent area) which includes the allocation-rectangles of all of its children, and which extends in the block-progression-direction by at least the font-descent from its position-point, and in the opposite direction by at least the font-ascent from its position-point.

Examples of inline-areas with children might include portions of inline mathematical expressions or areas arising from mixed writing systems (left-to-right within right-to-left, for example).

4.8 Stacked Inline-areas

Inline-area children of an area are typically stacked in the inline-progression-direction within their parent area, and this is the default method of positioning such inline-areas.

If P is an area with inline-area children, an inline-area descendant I of P is stackable in P if the out-of-sequence trait of I is false and either

1. I is a child area of P, or

2. I is a child area of an inline-area J, where J is a stackable descendant of P, J is not a reference-area, and J has the same block-progression-direction and inline-progression-direction as P.

A stackable inline-area is leading if there is no inline-area descendant of P which precedes it, and is trailing if there is no inline-area descendant of P which follows it.

Inline-areas are stacked relative to a baseline, defined as follows:

1. If P is a line-area, the baseline of P is defined to be the line through the baseline-start-point which is parallel to the inline-progression-direction;

2. If P is an inline-area, the baseline of P is defined to be the line through the position-point of P which is parallel to the inline-progression-direction.

For a parent area P whose children are inline-areas, P is defined to be properly stacked if all of the following conditions hold:

1. For each stackable inline-area descendant I of P, the before-edge and after-edge of the allocation-rectangle of I are parallel to the before-edge and after-edge of the content-rectangle of P, and the start-edge and end-edge of the content-rectangle of I are parallel to those of P.

2. For each pair of stackable inline-area descendants I and I' of P, if I precedes I' consecutively, then the distance from the end-edge of the allocation-rectangle of I to the start-edge of the allocation-rectangle of I' is consistent with the constraint imposed by the resolved values of the space-after traits of I and of any of its ancestors which precede I', and of the space-before traits of I' and of any of its ancestors which follow I.

Issue (mixed-writing-direction-line-area-2):

This item (2.) has not yet been updated to account for mixed writing directions within a single line-area.

3. The distance from the start-edge of the content-rectangle of P to the start-edge of the allocation-rectangle of any leading inline-area descendant I of P is consistent with the constraint imposed by the resolved values of the space-start traits of I of all the ancestors of I which are descendants of P.

Similarly, the distance from the end-edge of the allocation-rectangle of any trailing inline-area descendant I' of P to the end-edge of the content-rectangle of P is consistent with the constraint imposed by the resolved values of the space-end traits of I' and of all the ancestors of I' which are descendants of P.

4. For any stackable inline-area descendant I of P, the distance in the shift-direction from the baseline of P to the position-point of I equals the value of the baseline-shift trait of I. The baseline-shift trait is calculated from the baseline-shift property plus an amount computed to compensate for mixed writing systems with different nominal glyph baselines.

Issue (mixed-writing-direction-line-area-4):

This item (4.) has not yet been updated to reflect the notion of different baselines for mixed writing systems within a single line-area.

4.9 Glyph-areas

The most common inline-area is a glyph-area, which contains the representation for a character in a particular font.

A glyph-area has font-family, font-size, and font-weight traits, which apply to its character data.

The position-point and escapement-point of a glyph-area are assigned according to the writing-system in use (e.g., the glyph baseline in European languages), and are used to control placement of inline-areas descendants of a line-area. The formatter may generate inline-areas with different inline-progression-directions from their parent to accommodate correct inline-area stacking in the case of mixed-language formatting.

A glyph-area has no children, and its ascent and descent should depend only on the font-name, font-size, and font-weight properties of its generating formatting object, and is not based on the individual glyph rendered.

5 Property Refinement / Resolution

Issue (Mapping-CSS-Box):

Include mapping to CSS box so that CSS properties can be read and interpreted for XSL.

5.1 Specified, Computed, and Actual Values and Inheritance

Issue (refinement1):

This section is incomplete and may be inconsistent with other parts of this working draft.

The semantics of formatting is divided into a set of simple steps to simplify the explanation and to highlight what interactions (or, perhaps more importantly, lack of interactions) exist between formatting objects and the properties on them. Although they are described as steps, this is solely for the convenience of exposition and does not imply they must be implemented as separate steps in any conforming implementation. A conforming implementation must only achieve the same effect. Some of the relevant steps are, for each formatting object in the result tree, determining (computed) values for all the properties applicable to that formatting object and then using the formatting model to describe how the values of these properties constrain the distribution of the content of these formatting objects into areas and the resolution of the spacing adjustments among the various areas.

The step of determining the computed values of the relevant properties is described below. The process of distribution and space resolution is described and/or constrained by the descriptions of the formatting properties and the formatting objects which use them.

For every property that is applicable to the a given formatting object, it is necessary to determine the value of the property. Three variants of the property value are distinguished: the specified value, the computed value, and the actual value. The "specified value" is one that is placed on the formatting object during the tree-constuction process. A specified value may not be in a form that is directly usable; for example, it may be a percentage that must be converted into an absolute value. A value resulting from such a conversion is called the "computed value". Finally, the computed value may not be realizable on the output media and may need to be adjusted prior to use in rendering. For example, a line width may be adjusted to become an integral number of output medium pixels. This adjusted value is the "actual value."

5.1.1 Specified Values

The specified value of a property is determined using the following mechanisms (in order of precedence):

1. If the tree-construction process placed the property on the formatting object, use the value of that property as the specified value. This is called "explicit specification".

2. Otherwise, if the property is inheritable, use the value of that property from the parent formatting object, generally the computed value (see below).

3. Otherwise use the property's initial value, if it has one. The initial value of each property is indicated in the property's definition. If there is no initial value, that property is not specifed on the formatting object. (A property will only be "not specified" if there are corresponding properties that can provide equivalent information.

Since it has no parent, the root of the result tree cannot use values from its parent formatting object; in this case, the initial value is used if necessary.

5.1.2 Computed Values

Specified values may be absolute (i.e., they are not specified relative to another value, as in "red" or "2mm") or relative (i.e., they are specified relative to another value, as in "auto", "2em", and "12%"). For most absolute values, no computation is needed to find the computed value. Relative values, on the other hand, must be transformed into computed values: percentages must be multiplied by a reference value (each property defines which value that is), values with relative units (em, ex, px) must be made absolute by multiplying with the appropriate font or pixel size, "auto" values must be computed by the formulas given with each property, certain property values ("smaller", "bolder") must be replaced according to their definitions.

Some properties have more than one way in which the property value can be specified. The simplest example of such properties are those which can be specified either in terms of a direction relative to the writing-mode (e.g., padding-before) or a direction in terms of the absolute geometric orientation of the viewport (e.g., padding-top). These two properties are called the relative property and the absolute property, respectively. Collectively, they are called "corresponding properties."

Specifying a value for one property determines both a computed value for the specified property and a computed value for the corresponding property. Which relative property corresponds to which absolute property depends on the writing-mode. For example, if the "writing-mode" at the top level of a document is "lr-tb", then "padding-start" corresponds to 'padding-left", but if the "writing-mode" is "rl-tb", then "padding-start" corresponds to "padding-right". The exact specification of how to compute the values of corresponding properties is given in the section on Computing the values of Corresponding Properties, below.

In most cases, elements inherit computed values. However, there are some properties whose specified value may be inherited (e.g., the number value for the "line-height" property). In the cases where child elements do not inherit the computed value, this is described in the property definition.

5.1.3 Actual Values

A computed value is in principle ready to be used, but a user agent may not be able to make use of the value in a given environment. For example, a user agent may only be able to render borders with integer pixel widths and may, therefore, have to adjust the computed width to an integral number of media pixels. The actual value is the computed value after any such adjustments have been applied.

5.2 Inheritance

Issue (refinement2):

This section is incomplete and may be inconsistent with other parts of this working draft.

Some of the properties applicable to formatting objects are "inheritable." Such properties are so identified in the property description. The inheritable properties can be placed on any formatting object. The inheritable properties are propagated down the result tree from a parent to each child. (These properites are given their initial value at the root of the result tree.) For a given inheritable property, if that property is present on a child, then that value of the property is used for that child (and its descendents until explicitly re-set in a lower descendent); otherwise, the specified value of that property on the child is the computed value of that property on the parent formatting object. Hence there is always a specified value defined for every inheritable property for every formatting object.

5.3 Computing the Values of Corresponding Properties

Issue (refinement3):

This section is incomplete and may be inconsistent with other parts of this working draft.

Where there are corresponding properties, such as "padding-left" and "padding-start", a computed value is determined for all the corresponding properties. How the computed values are determined for a given formatting object is dependent on which of the corresponding properties are specified.

5.3.1 Properties with a Simple Correspondance

The simplest class of corresponding properties are those for which there are only two variants in the correspondance, an absolute property and a relative property, and the property names differ only in the choice of absolute or relative designation; for example, "border-left-color" and "border-start-color".

Issue (correspondance):

Need to add description of the correspondance because it involves both writing-mode and reference-orientation of all enclosing reference-areas.

For this class, the computed values of the corresponding properties are determined as follows. If the corresponding absolute variant of the property is specified on the formatting object, its computed value is used to set the computed value of the corresponding relative property. If the corresponding absolute property is not explicitly specified, then the computed value of the absolute property is set to the computed value of the relative property of the same name.

Note that if both the absolute and the relative properties are not explicitly specified, then the rules for determining the specifed value will use either inheritance if that is defined for the property or the initial value. The initial value must be the same for all possible corresponding properties. If both an absolute and a corresponding relative property are explicitly specified, then the above rule gives precedence to the absolute property, and the specified value of the corresponding relative property is ignored in determining the computed value of the corresponding properties.

The (corresponding) properties that use the above rule to determine their computed value are:

• Border-after-color

• Border-before-color

• Border-end-color

• Border-start-color

• Border-after-style

• Border-before-style

• Border-end-style

• Border-start-style

• Border-after-width

• Border-before-width

• Border-end-width

• Border-start-width

• Padding-after

• Padding-before

• Padding-end

• Padding-start

5.3.2 Space and Margin Properties

The "space-before", "space-after", "space-start", and "space-end" properties are handled very similarly to the properties immediately above, but the corresponding absolute properties are in the set: "margin-top", "margin-bottom", "margin-left", and "margin-right". Again the correspondance between the relative property and the corresponding absolute property is determined by the "writing-mode" property of the formatting object. For example, at the top level of a document, if the "writing-mode" is "lr-tb", then "space-before" corresponds to "margin-top", but if the "writing-mode" is "tb-rl", the "space-before" corresponds to "margin-right".

5.3.3 Start-indent and End-indent

There are two more properties, "end-indent" and "start-indent", for which the computed value may be determined by the computed value of the absolute margin properties. For these traits, the calculation of the value of the trait when the corresponding absolute property is present depends on three computed values: the computed value of the corresponding absolute property, the computed value of the corresponding "padding" property, and the computed value of the corresponding "border-width" property.

Here the term "corresponding" has been broadened to mean that if "margin-left" is the corresponding absolute property to "start-indent", then "padding-left" (and "padding-start") and 'border-left-width" (and "border-start-width") are the "corresponding" "padding" and "border-width" properties.

The formulae for calculating the computed value of the x-indent properties are as follows (where "margin-corresponding" is a place-holder for the corresponding absolute "margin" property):

End-indent = margin-corresponding + padding-end + border-end-width

Start-indent = margin-corresponding + padding-start + border-start-width

If an absolute "margin" property is not explicity specified, these equations determine a computed value for the corresponding "margin" property given values for the three traits corresponding-indent, padding-corresponding and border-corresponding width.

5.4 Expressions

All property value specifications in attributes within an XSL stylesheet can be expressions. These expressions represent the value of the property specified. The expression is first evaluated and then the resultant value is used to determine the value of the property.

5.4.1 Property Context

Properties are evaluated against a property-specific context. This context provides:

• A list of allowed resultant types for a property value.

• Conversions from resultant expression value types to an allowed type for the property.

• The current font-size value.

• Conversions from relative numerics by type to absolute numerics within additive expressions.

NOTE:

It is not necessary that a conversion is provided for all types. If no conversion is specified, it is an error.

When a type instance (e.g., a string, a keyword, a numeric, etc.) is recognized in the expression it is evaluated against the property context. This provides the ability for specific values to be converted with the property context's specific algorithms or conversions for use in the evaluation of the expression as a whole.

For example, the "auto" enumeration token for certain properties is a calculated value. Such a token would be converted into a specific type instance via an algorithm specified in the property definition. In such a case the resulting value might be an absolute length specifying the width of some aspect of the formatting object.

In addition, this allows certain types like relative numerics to be resolved into absolute numerics prior to mathematical operations.

All property contexts allow conversions as specified in [5.4.12 Expression Value Conversions].

5.4.2 Evaluation Order

When a set of properties is being evaluated for a specific formatting object element in the formatting object element tree there is a specific order in which properties must be evaluated. Essentially, the font-size property must be evaluated first before all other properties. Once the font-size property has been evaluated, all other properties may be evaluated in any order.

When the "font-size" property is evaluated, the current font-size for use in evaluation is the font-size of the formatting object element's parent. Once the "font-size" property has been evaluated, that value is used as the current font-size for all property contexts of all properties value expressions being further evaluated.

5.4.3 Basics

5.4.4 Function Calls

5.4.5 Numerics

A numeric represents all the types of numbers in an XSL expression. Some of these numbers are absolute values. Others are relative to some other set of values. All of these values use a floating-point number to represent the number-part of their definition.

A floating-point number can have any double-precision 64-bit format IEEE 754 value [IEEE 754]. These include a special "Not-a-Number" (NaN) value, positive and negative infinity, and positive and negative zero. See Section 4.2.3 of [JLS] for a summary of the key rules of the IEEE 754 standard.

The following operators may be used with numerics:

+

Performs addition.

-

Performs subtraction or negation.

*

Performs multiplication.

div

Performs floating-point division according to IEEE 754.

mod

Returns the remainder from a truncating division.

NOTE:

Since XML allows - in names, the - operator (when not used as a UnaryExpr negation) typically needs to be preceded by whitespace. For example the expression 10pt - 2pt means subtract 2 points from 10 points. The expression 10pt-2pt means a length value of 10 with a unit of "pt-2pt".

NOTE:

The following are examples of the mod operator:

• 5 mod 2 returns 1

• 5 mod -2 returns 1

• -5 mod 2 returns -1

• -5 mod -2 returns -1

NOTE:

The mod operator is the same as the % operator in Java and ECMAScript and is not the same as the IEEE remainder operation, which returns the remainder from a rounding division.

Numeric Expressions

NOTE:

The effect of this grammar is that the order of precedence is (lowest precedence first):

• +, -

• *, div, mod

and the operators are all left associative. For example, 2*3 + 4 div 5 is equivalent to (2*3) + (4 div 5).

If a non-numeric value is used in an AdditiveExpr and there is no property context conversion from that type into an absolute numeric value, the expression is invalid and considered an error.

5.4.6 Absolute Numerics

An absolute numeric is an absolute length which is a pair consisting of a Number and a UnitName raised to a power. When an absolute length is written without a unit, the unit power is assumed to be zero. Hence, all floating point numbers are a length with a power of zero.

Each unit name has associated with it an internal ratio to some common internal unit of measure (e.g., a meter). When a value is written in a property expression, it is first converted to the internal unit of measure and then mathematical operations are performed.

In addition, only the mod, addition, and subtraction operators require that the numerics on either side of operation be absoluted numerics of the same unit power. For other operations, the unit powers may be different and the result should be mathematically consistent as with the handling of powers in algebra.

A property definition may constrain an absolute length to a particular power. For example, when specifying font-size, the value is expected to be of power "one". That is, it is expect to have a single powered unit specified (e.g., 10pt).

When the final value of property is calculated, the resulting power of the absolute numeric must be either zero or one. If any other power is specified, the value is an error.

5.4.7 Relative Numerics

Relative lengths are values that are calculated relative to some other set of values. When written as part of an expression, they are either converted via the property context into an absolute numeric or passed verbatim as the property value.

It is an error if the property context has no available conversion for the relative numeric and a conversion is required for expression evaluation (e.g., within an add operation).

5.4.7.1 Percents

Percentages are values that are counted in 1/100 units. That is, 10% as a percentage value is 0.10 as a floating point number. When converting to an absolute numeric, the percentage is defined in the property definition as being a percentage of some known property value.

For example, a value of "110%" on a "font-size" property would be evaluated to mean 1.1 times the current font size. Such a definition of the allowed conversion for percentages is specified on the property definition. If no conversion is specified, the resulting value is a percentage.

5.4.7.2 Relative Lengths

A relative length is a unit-based value that is measured against the current value of the font-size property.

There is only one relative unit of measure, the "em". The definition of "1em" is equal to the current font size. For example, a value of "1.25em" is 1.25 times the current font size.

When an em measurement is used in an expression, it is converted according to the font-size value of the current property's context. The result of the expression is an absolute length. See [7.6.3 "font-size"]

5.4.8 Strings

Strings are represented either as literals or as an enumeration token. All properties contexts allow conversion from enumeration tokens to strings. See [5.4.12 Expression Value Conversions].

5.4.9 Colors

A color is a set of values used to identify a particular color from a color space. Currently, only RGB colors are supported by this draft.

Issue (color-space):

Change this section when/if "color-profile" and "rendering-intent" properties are incorporated into XSL.

RGB colors are directly represented in the expression language using a hexadecimal notation. They can also be accessed through the system-color function or through conversion from a EnumerationToken via the property context.

5.4.10 Keywords

Keywords are special tokens in the grammar that provide access to calculated values or other property values. The allowed keywords are defined in the following subsections.

5.4.10.1 inherit

The property takes the same computed value as the property for the formatting object's parent object.

5.4.11 Lexical Structure

When processing an expression, whitespace (ExprWhitespace) may be allowed before or after any expression token even though it is not explicitly defined as such in the grammar. In some cases, whitespace is necessary to make tokens in the grammar lexically distinct. Essentially, whitespace should be treated as if it does not exist after tokenization of the expression has occurred.

The following special tokenization rules must be applied in the order specified to disambiguate the grammar:

• If the character following an NCName (possibly after intervening ExprWhitespace) is "(", then the token must be recognized as FunctionName.

• A number terminates at the first occurrence of a non-digit character other than ".". This allows the unit token for length quantities to parse properly.

• When an NCName immediately follows a Number, it should be recognized as a UnitName or it is an error.

• The Keyword values take precedence over EnumerationToken.

• If a NCName follows a numeric, it should be recognized as an OperatorName or it is an error.

Expression Lexical Structure

5.4.12 Expression Value Conversions

Values that are the result of an expression evaluation may be converted into property value types. In some instances this is a simple verification of set membership (e.g., is the value a legal country code). In other cases, the value is expected to be a simple type like an integer and must be converted.

It is not necessary that all types be allowed to be converted. If the expression value cannot be converted to the necessary type for the property value, it is an error.

The following table indicates what conversions are allowed.

The specific conversion to be applied is property specific and can be found in the definition of each property.

5.5 Core Function Library

5.5.1 Number Functions

Function: numeric floor( numeric)

The floor function returns the largest (closest to positive infinity) integer that is not greater than the argument. The numeric argument to this function must be of unit power zero.

NOTE:

If it is necessary to use the floor function for a property where a unit power of one is expected, then an expressions such as: "floor(1.4in/1.0in)*1.0in" must be used. This applies to the ceiling, round, and other such functions where a unit power of zero is required.

Function: numeric ceiling(numeric)

The ceiling function returns the smallest (closest to negative infinity) integer that is not less than the argument. The numeric argument to this function must be of unit power zero.

Function: numeric round(numeric)

The round function returns the integer that is closest to the argument. If there are two such numbers, then the one that is closest to positive infinity is returned. The numeric argument to this function must be of unit power zero.

Function: numeric min( numeric , numeric)

The min function returns the minimum of the two numeric arguments. These arguments must have the same unit power.

Function: numeric max(numeric , numeric)

The min function returns the maximum of the two numeric arguments. These arguments must have the same unit power.

Function: numeric abs( numeric)

The abs functions returns the absolute value of the numeric argument. That is, if the numeric argument is negative, it returns the negation of the argument.

5.5.2 Color Functions

Function: color rgb(numeric , numeric , numeric)

The rgb function returns a specific color from the RGB color space. The parameters to this function must be numerics (real numbers) with a length power of zero.

Function: color system-color( NCName)

The system-color function returns a system defined color with a given name.

5.5.3 Font Functions

Function: object system-font( NCName , NCName)

The system-font funtions returns a characteristic of a system font. The first argument is the name of the system font and the second argument, which is optional, names the property that specifies the characteristic. If the second argument is omitted, then the characteristic returned is the same as the name of the property to which the expression is being assigned.

For example, the expression "system-font(heading,font-size)" returns the font-size characteristic for the system font named "heading". This is equivalent to the property assignment 'font-size="system-font(heading)"'.

5.5.4 Property Value Functions

Function: object inherited-property-value(NCName)

The inherited-property-value function returns the inherited value of the property whose name matches the argument specified. It is an error if this property is not an inherited property.

Function: numeric label-end()

The label-end function returns the calculated label-end value for lists. See the definition of the provisional-label-separation property.

Function: numeric body-start()

The body-start function returns the calculated body-start value for lists. See the definition of the provisional-distance-between-starts property.

NOTE:

When this function is used outside of a list, it still returns a calculated value as specified.

Function: object from-parent( NCName)

The from-parent function returns a computed value of the property whose name matches the argument specified. The value returned is that for the parent of the formatting object for which the expression is evaluated. If there is no parent, the value returned is the initial value. If the argument specifies a shorthand property and if the expression only consists of the from-parent function with an argument matching the property being computed, it is interpreted as an expansion of the shorthand with each property into which the shorthand expands; each having a value of from-parent with an argument matching the property. It is an error if arguments matching a shorthand property are used in any other way.

Function: object from-nearest-specified-value( NCName)

The from-nearest-specified-value function returns a computed value of the property whose name matches the argument specified. The value returned is that for the closest ancestor of the formatting object for which the expression is evaluated on which there is an assignment of the property in the formatting object element tree. If there is no such ancestor, the value returned is the initial value. If the argument specifies a shorthand property and if the expression only consists of the from-nearest-specified-value function with an argument matching the property being computed, it is interpreted as an expansion of the shorthand with each property into which the shorthand expands; each having a value of from-nearest-specified-value with an argument matching the property. It is an error if arguments matching a shorthand property are used in any other way.

Function: object from-table-column( NCName)

The from-table-column function returns the inherited value of the property, whose name matches the argument specified, from the fo:table-column whose column-number matches the column for which this expression is evaluated and whose number-columns-spanned also matches any span. If there is no match for the number-columns-spanned, it is matched against a span of 1. If there is still no match, the initial value is returned. It is an error to use this function on formatting objects that are not an fo:table-cell or its descendants.

5.6 Property Datatypes

Certain property values are described in terms of compound datatypes, in terms of restrictions on permitted number values, or strings with particular semantics.

The compound datatypes, such as space, are represented in the result tree as multiple attributes. The names of these attributes consist of the property name, followed by a period, followed by the component name. For example a the "space-before" property may be specified as:

space-before.minimum="2.0pt"
space-before.maximum="4.0pt"
space-before.optimum="3.0pt"
space-before.precedence="0"
space-before.conditionality="discard"

The following datatypes are defined:

Issue (datatypes-review):

Some datatypes may be missing. To be checked against those used in the property section.

<integer>

A signed integer value which consists of an optional '+' or '-' character followed by a sequence of digits. A property may define additional constraints on the value.

<number>

A signed real number which consists of an optional '+' or '-' character followed by a sequence of digits followed by an optional '.' character and sequence of digits. A property may define additional constraints on the value.

<length>

A signed length value where a 'length' is a real number plus a unit qualification. A property may define additional constraints on the value.

<length-range>

A compound datatype, with components: minumum, optimum, maximum. Each component is a <length>. A property may define additional constraints on the values.

<space>

A compound datatype, with components: minumum, optimum, maximum, precedence, and conditionality. The minumum, optimum, and maximum components are <length>s. The precedence component is either "force" or an <integer>. The conditionality component is either "discard" or "retain".

<angle>

An <integer> representing an angle.

<character>

A single Unicode character.

<string>

A sequence of characters.

<name>

A string of characters representing a name. It must not contain any whitespace, or space characters.

<family-name>

A string of characters identifying a font.

<color>

TBD

<country>

A string of characters conforming to an ISO 3166 country code.

<language>

A string of characters conforming to the ISO 639 3 letter code.

<script>

A string of characters conforming to an ISO 15924 script code.

<id>

A string of characters conforming to the XML NMTOKEN definition that is unique within the stylesheet.

<idref>

A string of characters conforming to the XML NMTOKEN definition that matches an ID property value used within the stylesheet.

<uri>

A sequence of characters conforming to a URI value as specified in the URI specification.

6 Formatting Objects

6.1 Introduction to Formatting Objects

The refined formatting-object tree describes one or more intended presentations of the information within this tree. Formatting is the process which converts the description into a presentation. See [3 Introduction to Formatting].The presentation is represented, abstractly, by an area tree, as defined in the area model. See [4 Area Model]. Each possible presentation is represented by one or more area trees in which the information in the refined formatting object tree is positioned on a two and one-half dimensional surface.

There are three kinds of formatting objects: (1) those that generate areas, (2) those that return areas, but do not generate them, and (3) those that are used in the generation of areas. The first and second kinds are typically called flow objects. The third kind is either a layout object or an auxilliary object. The kind of formatting object is indicated by the terminology used with the object. Formatting objects of the first kind are said to "generate one or more areas". Formatting objects of the second kind are said to "return one or more areas". Formatting objects of the first kind may both generate and return areas. Formatting objects of the third kind are "used in the generation of areas"; that is, they act like parameters to the generation process.

6.1.1 Definitions Common to Many Formatting Objects

This categorization leads to defining two traits which characterize the relationship between an area and the formatting objects which generate and return that area. These traits are generated-by and returned-by.

The value of the generated-by trait is a single formatting object. A formatting object F is defined to generate an area A if the semantics of F specify the generation of one or more areas and A is one of the areas thus generated.

Issue (single-area-from-multiple-FOs):

How is generation specified when more than one refined formatting object, for example, a sequence of fo:character formatting objects in an Indic syllable, are used to generate a single area; namely, the glyph composition for the Indic syllable with appropriate pre-, post-, above-, and below-vowels and marks.

There are two other kinds of generation anomalies: (1) where a character, such as a final hyphen, is generated by a "process", such as line-breaking; and (2) when an fo:character, such as a space at the end or at the beginning of a line, does not generate anything because the space is "removed". The modification of a German "double s" at a hyphenation point is another example of spontaneous generation of areas. Should the German "double s" and cases (1) and (2) above be described as transformations on the sequence of fo:character objects rather than transformations on areas?

The value of the returned-by trait is a set of pairs, where each pair consists of a formatting object and a positive integer. The integer represents the position of the area in the ordering of all areas returned by the formatting object.

A formatting object F is defined to return the sequence of areas A, B, C, ... if the pair (F,1) is a member of the returned-by trait of A, the pair (F,2) is a member of the returned-by trait of B, the pair (F,3) is a member of the returned-by trait of C, ...

If an area is a member of the sequence of areas returned by a formatting object, then either it was generated by the formatting object or it was a member of the sequence of areas returned by a child of that formatting object. Not all areas returned by a child of a formatting object need be returned by that formatting object. A formatting object may generate an area that has, as some of its children areas, areas returned by the children of that formatting object. These children (in the area tree) of the generated area are not returned by the formatting object to which they were returned.

A set of nodes in a tree is a lineage if:

• there is a node N in the set such that all the nodes in the set are ancestors of N, and

• for every node N in the set, if the set contains an ancestor of N, it also contains the parent of N.

The set of formatting objects that an area is returned by is a lineage.

Areas returned by a formatting object may be either normal or out-of-line. Normal areas represent areas in the "normal flow of text"; that is, they become area children of the areas generated by the formatting object to which they are returned. Normal areas have a returned-by lineage of size one. There is only one kind of normal area.

Out-of-line areas are areas used outside the normal flow of text either because the are absolutely positioned or they are part of a float or footnote. Out-of-line areas may have a returned-by lineage of size greater than one.

The area-class trait indicates which class, normal or out-of-line, an area belongs to. For out-of-line areas, it also indicates the subclass of out-of-line area. The values for this trait are: "normal", "absolute", "xsl-footnote", "xsl-start-float", "xsl-end-float" or "xsl-top-float". An area is normal if and only if the value of the area-class trait is "normal"; otherwise, the area is an out-of-line area.

The areas returned-by a given formatting object are ordered as noted above. This ordering defines an ordering on the sub-sequence of areas that are of a given area-class, such as the sub-sequence of normal areas. An area A precedes an area B in the sub-sequence if and only if area A precedes area B in the areas returned-by the formatting objects.

6.2 Formatting Object Content

The content of a formatting object is described using xml content model syntax. In some cases additional constraints, not expressable in xml content models, are given in prose.

The parameter entity, "%block;" in the content models below, contains the following formatting objects:

     block
     block-container
     table-and-caption
     table
     list-block

The parameter entity, "%inline;" in the content models below, contains the following formatting objects:

     bidi-override
     character
     external-graphic
     instream-graphic
     inline
     inline-container
     leader
     page-number
     page-number-citation
     simple-link
     multi-toggle

The following formatting objects are "neutral" containers and may be used anywhere where #PCDATA, %block;, or %inline; are allowed:

     multi-switch
     multi-properties
     wrapper

The following "out-of-line" formatting objects may be used anywhere where #PCDATA, %block;, or %inline; are allowed:

     float
     footnote

6.3 Formatting Objects Summary

bidi-override

The fo:bidi-override inline formatting object is used where it is necessary to override the default Unicode-bidirectionality algorithm writing-direction for different (or nested) inline scripts in mixed-language documents.

block

The fo:block formatting object is commonly used for formatting paragraphs, titles, headlines, figure and table captions, etc.

block-container

The fo:block-container flow object is used to generate a block-level reference-area.

character

The fo:character flow object represents a character that is mapped to a glyph for presentation.

conditional-page-master-reference

The fo:conditional-page-master-reference is used to identify a page-master that is to be used when the conditions on its use are satisfied.

external-graphic

The fo:external-graphic flow object is used for an inline graphic where the graphics data resides outside of the fo:element tree.

float

The fo:float flow object is used to gather content of a floating figure, table, or sidebar.

flow

The content of the fo:flow formatting object is a sequence of flow objects that forms one unit of content distribution, such as an article, a chapter, or a section.

footnote

The fo:footnote formatting object is used to gather the components of a floating note.

footnote-citation

The fo:footnote-citation formatting object is used to specify the properties that affect the formatting of a footnote citation.

initial-property-set

The fo:initial-property-set specifies formatting properties for the first line of an fo:block.

inline

The fo:inline formatting object is commonly used for formatting a portion of text with a background or enclosing it in a border.

inline-container

The fo:inline-container flow object is used to generate an inline reference-area.

instream-graphic

The fo:instream-graphic flow object is used for an inline graphic where the graphics data resides as descendants of the fo:instream-graphic.

layout-master-set

The fo:layout-master-set is a wrapper around all masters used in the document.

leader

The fo:leader formatting object is used to generate leaders consisting either of a rule or of a row of a repeating character or cyclically repeating pattern of characters that are used for connecting two text formatting objects and split-quads (space-leaders).

list-block

The fo:list-block flow object is used to format a list item or a list.

list-item

The fo:list-item formatting object contains the label and the body of an item in a list.

list-item-body

The fo:list-item-body formatting object contains the content of the body of a list-item.

list-item-label

The fo:list-item-label formatting object contains the content of the label of a list-item; typically used to either enumerate, identify or adorn the list-item's body.

multi-case

The fo:multi-case is used to embed flow objects, that the parent fo:multi-switch can choose to either show or hide.

multi-properties

The fo:multi-properties is used to switch between two or more property sets that are associated with a given portion of content.

multi-property-set

The fo:multi-property-set is used to specify an alternative set of formatting properties that, dependent on a DOM state, are applied to the content.

multi-switch

The fo:multi-switch is used to switch between two or more sub-trees of formatting objects.

multi-toggle

The fo:multi-toggle is used within an fo:multi-case to switch to another fo:multi-case.

page-number

The fo:page-number formatting object is used to represent the current page-number.

page-number-citation

The fo:page-number-citation is used to reference the page-number for the page containing the first area generated by the cited formatting object.

page-sequence

The fo:page-sequence formatting object is used to specify how to create a (sub-)sequence of pages within a document; for example, a chapter of a report. The content of these pages comes from flow children of the fo:page-sequence.

page-sequence-master

The fo:page-sequence-master specifies sequences of page-masters that are used when generating a sequence of pages.

region-after

This region defines a viewport that is located on the "after" side of fo:region-body region.

region-before

This region defines a viewport that is located on the "before" side of fo:region-body region.

region-body

This region specifies a viewport that is located in the "center" of the fo:simple-page-master.

region-end

This region defines a viewport that is located on the "end" side of fo:region-body region.

region-start

This region defines a viewport that is located on the "start" side of fo:region-body region.

repeatable-page-master-alternatives

An fo:repeatable-page-master-alternatives specifies a sub-sequence consisting of repeated instances of a set of alternative page-masters. The number of repetitions may be bounded or potentially unbounded.

repeatable-page-master-reference

An fo:repeatable-page-master-reference specifies a sub-sequence consisting of repeated instances of a single page-master. The number of repetitions may be bounded or potentially unbounded.

root

The fo:root node is the top node of an XSL result tree. This tree is composed of formatting objects.

simple-link

The fo:simple-link is used for representing the start resource of a simple link.

simple-page-master

The fo:simple-page-master is used in the generation of pages and specifies the geometry of the page. The page may be subdivided into up to five regions

single-page-master-reference

An fo:single-page-master-reference specifies a sub-sequence consisting of a single instance of a single page-master.

static-content

The fo:static-content formatting object holds a sequence or a tree of formatting objects that is to be presented in a single region or repeated in like-named regions on one or more pages in the page-sequence. Its common use is for repeating or running headers and footers.

table

The fo:table flow object is used for formatting the tabular material of a table.

table-and-caption

The fo:table-and-caption flow object is used for formatting a table together with its caption.

table-body

The fo:table-body formatting object is used to contain the content of the table body.

table-caption

The fo:table-caption formatting object is used to contain block-level formatting objects containing the caption for the table.

table-cell

The fo:table-cell formatting object is used to group content to be placed in a table-cell.

table-column

The fo:table-column formatting object specifies characteristics applicable to table cells that have the same column and span.

table-footer

The fo:table-footer formatting object is used to contain the content of the table footer.

table-header

The fo:table-header formatting object is used to contain the content of the table header.

table-row

The fo:table-row formatting object is used to group table-cells into rows.

wrapper

The fo:wrapper formatting object is used to specify inherited properties for a group of formatting objects. It has no additional formatting semantics.

6.4 Pagination and Layout Formatting Objects

6.4.1 Introduction

The root node of the formatting-object tree must be an fo:root formatting object. The children of the fo:root formatting object are a single fo:layout-master-set and a sequence of one or more fo:page-sequences. The fo:layout-master-set defines the geometry and sequencing of the pages; the children of the fo:page-sequences, which are called flows, provide the content that is distributed into the pages. The process of generating the pages is done automatically by the XSL processor formatting the result tree.

The children of the fo:layout-master-set are the pagination and layout specifications. The names of these specifications end in "-master". There are two types of pagination and layout specifications: page-masters and page-sequence-masters. Page-masters have the role of describing the intended subdivisions of a page and the geometry of these subdivisions. Page-sequence-masters have the role of describing the sequence of page-masters that will be used to generate pages during the formatting of an fo:page-sequence.

6.4.1.1 Page-sequence-masters

Each fo:page-sequence-master characterizes a set of possible sequences of page-masters. For any given fo:page-sequence, only one of the possible set of sequences will be used. The sequence that is used is the smallest sequence that satisfies the constraints determined by the individual page-masters, the flows which generate pages from the page-masters and the fo:page-sequence-master itself.

The fo:page-sequence-master is used to determine which page-masters are used and in which order. The children of the fo:page-sequence-master are a sequence of sub-sequence specifications. The page-masters in a sub-sequence may be specified by a reference to a single page-master or as a repetition of one or more page-masters. For example, a sequence might begin with several explicit page-masters and continue with a repetition of some other page-master (or masters).

The fo:single-page-master-reference is used to specify a sub-sequence consisting of a single page-master.

There are two ways to specify a sub-sequence that is a repetition. The fo:repeatable-page-master-reference specifies a repetition of a single page-master. The fo:repeatable-page-master-alternatives specifies the repetition of a set of page-masters. Which of the alternative page-masters is used at a given point in the sub-sequence is conditional and may depend on whether the page number is odd or even, is the first page, is the last page or is blank. The "maximum" property on the repetition specification controls the number of repetitions. If this property is not specified, there is no limit on the number of repetitions.

6.4.1.2 Page-masters

A page-master is a master that is used to generate a page. A page is a combination of two (nested) reference-areas: the media reference-area and the page-level reference-area. The media reference-area is defined by the output medium; the page-level reference-area defined by the content-rectangle of the media reference-area and is a child (in the area tree) of the media reference-area. This has the affect of positioning the page-level reference-area on the output media.

The term page is used ambiguously to refer to both the media reference-area, the page-level reference-area, or both together. The intended referent is clear from context. Most references to page will be referring either to both reference-areas or to the page-level reference-area. The media reference-area is used only when defining the position of the page-level reference-area on the output medium. Children of the page are always children of the page-level reference-area and the parent of the page is always the parent of the media reference-area. Where confusion would arise, such the values of traits on the reference-areas, the term "page" will not be used, and, instead, the appropriate reference-area will be explicity identified.

A single page-master may be used multiple times, each time it is used it generates a single page; for example, a page-master that is referenced from an fo:repeatable-page-master-reference will generate one page for each occurrence of the reference in the specified sub-sequence.

NOTE:

When pages are used with a user agent such as a Web Browser, it is common that the each document has only one page. The viewport used to view the page determines the size of the page. When pages are placed on non-interactive media, such as sheets of paper, pages correspond to one or more of the surfaces of the paper. The size of the paper determines the size of the page.

In this specification, there is only one kind of page-master, the fo:simple-page-master. Future versions of this specification may add additional kinds of page-masters.

An fo:simple-page-master has, as children, specifications for one or more regions.

A region specification is used as a master, the region-master, when generating both a viewport reference-area and a region reference-area. The region reference-area is the only area child of the viewport reference-area. The viewport reference-area represents an opening in the page-level reference-area through which the region reference-area can be viewed. Scrolling and clipping is controlled in terms of the viewport reference-area. We will say a viewport/region area corresponds to a region if the viewport/region area was generated using the region-master specified by that region.

NOTE:

The regions on the page are analogous to "frames" in an HTML document. Typically, at least one of these regions is of indefinite length in one of its dimensions. For languages with a lr-tb (or rl-tb) writing-mode, this region is typically of indefinite length in the top-to-bottom direction. The viewport represents the visible part of the frame. The flow assigned to the region is viewed by scrolling the region reference-area through the viewport.

Each region is defined by a region formatting object. Each region formatting object has a name and a definite position. In addition, the region's height or width is fixed and the other dimension may be either fixed or indefinite. For example, a region that is the body of a Web page may have indefinite height.

The specification of the region determines the size and position of the viewport associated with the region. The positioning of the viewport is relative to the page-level reference-area that is generated using the page-master that is the parent of the region. The region reference-area takes its position from the viewport and size from the size specification of the region.

For version 1.0 of this recommendation, a page-master will consist of up to five regions: "region-body" and four other regions, one on each side of the body. To allow the side regions to correspond to the current writing-mode, these regions are named "region-before" (which corresponds to "header" in the "lr-tb" writing-mode), "region-after" (which corresponds to "footer" in the "lr-tb" writing-mode), "region-start" (which corresponds to a "left-sidebar" in the "lr-tb" writing-mode) and "region-end" (which corresponds to a "right-sidebar" in the "lr-tb" writing-mode). It is expected, that a future version of the recommendation will introduce a mechanism that allows a page-master to contain an arbitrary number of arbitrarily sized and positioned regions.

6.4.1.3 Page Generation

Pages are generated automatically by the formatting of fo:page-sequences. As noted above, pages are page-level reference-areas. The parent of each page is the area tree root. Each page is generated by using a page-master to define the viewport areas and region reference-areas that correspond to the regions specified by that page-master.

Each fo:page-sequence references either an fo:page-sequence-master or an fo:page-master. If the reference is to an fo:page-master, this is interpreted as if it were a reference to an fo:page-sequence-master that repeats the referenced fo:page-master an unbounded number of times. We will say an fo:page-sequence references a page-master if either the fo:page-sequence directly references the page-master via the "master-name" property or that property references an fo:page-sequence-master that references the page-master.

6.4.1.4 Flows and Flow Mapping

There are two kinds of flows: fo:static-content and fo:flow. An fo:static-content flow holds content, such as the text that goes into headers and footers, that is repeated on many of the pages. The fo:flow flow holds content that is distributed across a sequence of pages. The processing of the fo:flow flow is what determines how many pages are generated to hold the fo:page-sequence. The fo:page-sequence-master is used as the generator of the sequence of page-masters into which the flow children content is distributed.

The children of a flow are a sequence of block-level flow objects. Each flow has a name, and no two fo:flow or fo:static-content formatting objects in the same page-sequence may have the same name.

The assignment of flows to regions on a page-master is determined by an implicit flow-map. The flow-map specifies an association between the flow children of the fo:page-sequence and regions defined within the page-masters referenced by that fo:page-sequence.

In version 1.0 of XSL, the flow-map is implicit. The "flow-name" property of a flow specifies to which region that flow is assigned. Each region has a "region-name" property. The implicit flow-map assigns a flow to the region that has the same name. In future versions of XSL, the flow map is expected to become an explicit formatting object.

To avoid requiring users to generate region-names, the regions all have default values for the "region-name" property. The region-names all begin with the prefix, "xsl-" and the suffix is the element name of the region formatting object. For example, the region that has the element name, "region-body" would have "xsl-region-body" as its default region-name.

6.4.1.5 Constraints on Page Generation

The areas that are descendant from a page are constrained by the page-master used to generate the page and the flows that are assigned to the regions specified on the page-master. For fo:static-content flows, the processing of the flow is repeated for each page generated using a page-master having the region to which the flow is assigned. For fo:flow flows, the areas generated by the descendants of the flow are distributed across the pages in the sequence that were generated using page-masters having the region to which the flow is assigned.

Issue (pagination-intro-traits):

Need to say how the traits of reference-areas generated "using" the region-master for a region reference-area are determined. The region-master provides the geometry, background, boarder, padding, etc. trait values. The traits determined by "writing-mode" are taken from the "writing-mode" of the flow that is assigned to the region.

Issue (pagination-intro-constraints):

There may be other constraints that should be satisfied in determining the "preferred" page trees. For example, one might want that all footnotes appear on the page from which they are referenced, even if that might require more pages than a page-tree that does not meet this constraint.

There may be many area trees that would satisfy the constraints determined by the formatting objects in the result tree. Among these, the area trees with the least number of pages are preferred. Among the area trees with the same number of pages, the ones with the least number of lines are preferred.

6.4.1.6 Area Generated by Descendants of a Given Flow

The areas generated by the descendants of a flow are called flow-descendant-areas.

Every flow-descendant-area is in two relationships: an area-descendant relationship and a generation-descendant relationship.

As an area, a flow-descendant-area is an immediate area descendant of its parent area in the area tree. In addition, a flow-descendant-area is, necessarily, a descendant of some page in the area tree. That is, there is some page for which the flow-descendant-area is an area descendant.

The flow-descendant-area is also a generation descendant of the flow that is an ancestor of the flow descendant that generated that area. That is, the flow objects that are the descendants of a given flow generate areas which are generation descendants of that flow.

In the sequel, the qualifiers "area" and "generation" will normally be omitted before the term "descendant" because the qualifier (and, therefore, the relationship) is implied by whether the area is described as descendant from an area or from a flow.

The area model defines a partial ordering of areas in the area tree. This area tree ordering becomes a total area tree ordering by adding the rule that A precedes B if A is a descendant of B. Using this total ordering, the flow-descendant-areas of a given flow are totally ordered. This is called the total ordering of flow-descendant-areas. This is the depth first traversal of the area tree ordering.

The same rules that define a total ordering on the area tree can can, by analogy, be used define a total ordering on the refined formatting-object tree. This order is called the total ordering of formatting objects. This is the depth first traversal of the refined formatting object tree ordering.

Combining this ordering and the generated-by trait defines a second ordering on the flow-descendant-areas. A flow-descendant-area A precedes a flow-descendant-area B (in the total generation ordering of flow-descendant-areas) if and only if the formatting object that generated A precedes the formatting object that generated B in the total ordering of formatting objects.

These orderings are used to express constraints on the order of appearance of objects in the refined formatting object tree and in the area tree.

6.4.1.7 Pagination Tree Structure

The result tree structure is shown below.

6.4.1.8 Examples

TBD

6.4.2 fo:root

• Common Usage:

  This is the top node of the formatting object tree. It holds an fo:layout-master-set formatting object (which holds all masters used in the document) and one or more fo:page-sequence objects. Each fo:page-sequence represents a sequence of pages that result from formatting the content children of the fo:page-sequence.

  NOTE:

  A document can contain multiple fo:page-sequences. For example, each chapter of a document could be a separate fo:page-sequence; this would allow chapter-specific content, such as the chapter title, to be placed within a header or footer.

• Areas:

  Page-level areas are returned by the fo:page-sequence children of the fo:root formatting object. The fo:root does not generate any areas.

• Constraints:

  The children of the root of the area tree consist solely of, and totally of, the page-level areas returned by the fo:page-sequence children of the fo:root. The ordering of area children (a) preserves the ordering of areas returned by each fo:page-sequence child and (b) orders all page-level areas returned by a given fo:page-sequence child before all of the page-level areas returned by all of its following sibling fo:page-sequences.

• Contents:

  (layout-master-set,page-sequence+)
  

• Properties:

  • [7.19.19 "id"]

6.4.3 fo:page-sequence

• Common Usage:

  The fo:page-sequence formatting object is used to specify how to create a (sub-)sequence of pages within a document; for example, a chapter of a report. The content of these pages comes from flow children of the fo:page-sequence. The layout of these pages comes from the fo:page-sequence-master referenced by the "master" property on the fo:page-sequence. The sequence of areas returned by each of the flow-object children of the fo:page-sequence are made descendants of the generated pages as described below.

• Areas:

  The fo:page-sequence formatting object generates and returns a sequence of pages. For each page, and each region specified in the page-master used to generate that page, the fo:page-sequence object also generates the viewport reference-area and region reference-area for the occurrence of that region on that page. If the region allows conditional regions within it, then the regions that are children of the region reference-area are also generated. The generation of the viewport reference-areas, the region reference-areas and their children reference-areas, if any, are described under the fo:simple-page-master and the region-masters.

• Constraints:

  The sequence of pages has as its descendants, in the area tree, the areas returned by the flows that are the children of the fo:page-sequence.

  Each page in the page-sequence is constrained to be generated using a page-master that satisfies the constraints of the page-sequence-master identified by the "master" property of the fo:page-sequence.

  For a given page, the viewport reference-areas and region reference-areas generated for that page are constrained to correspond to the regions that are descendants of the fo:simple-page-master that was used to generate the page. In addition, for flow-descendant-areas of a given flow, the areas must be descendants of a region reference-area that corresponds to the region to which the flow was assigned. The assignment of flows to regions is discussed in Section [6.4.1.4 Flows and Flow Mapping].

  There are a set of ordering constraints on the flow-descendant-areas of the pages:

  We will say that a flow is assigned to a page if the flow is assigned to a region specified in the page-master that is used to generate that page.

  For each page returned-by the fo:page-sequence and each fo:static-content formatting object that is a child of the fo:page-sequence, either the fo:static-content is assigned to the page or the fo:static-content is not used with that page. If the fo:static-content is not assigned to the page then none of the areas returned by the fo:static-content formatting object are flow-descendant areas of the page. If the fo:static-content is assigned to the page, then the treatment of, and constraints on, the returned areas are covered in the descriptions of the fo:simple-page-master and the associated region-masters.

  Issue (returned-order):

  Returned order equals generation order. Is it valid to assume that the ordering of areas returned-by child FO's is the same as the generation order defined in the FO Intro.

  For areas descendant from an fo:flow formatting object,

  1. For this version of the specification, for any two pages P and Q in the page-sequence returned by fo:page-sequence, if an fo:flow is assigned to page P, then the fo:flow must either be assigned to the same region in the page-master used to generate Q or it must not be assigned to any region in the page-master used to generate Q.

  2. If a fo:flow is assigned to pages P and Q, and page P precedes page Q in the ordering of pages,

     1. then all normal flow-descendant-areas of that fo:flow that are area descendants of page P must be generation ordered before all normal flow-descendant-areas of that fo:flow that are area descendants of page Q.

        Issue (generation-ordered-term):

        Is "generation ordered" the desired terminology and concept?

     2. and, for out-of-line flow-descendant-areas of that fo:flow that are area descendants of page P and for which the value of the area-class trait is "xsl-footnote", "xsl-start-float", "xsl-end-float" and "xsl-top-float", then within each class, all flow-descendant-areas of that fo:flow that are area descendants of page P must be generation ordered before all flow-descendant-areas of that fo:flow that are area descendants of page Q.

  For the ordered sequence of areas returned-by an fo:flow formatting object, consider the sub-sequences of areas belonging to each area-class. For each such sub-sequence, we say a sub-sub-sequence is contiguous if areas A and B are members of the sub-sub-sequence and A precedes B in the sub-sequence ordering, then every area C that follows A and precedes B is also in the sub-sub-sequence.

  The flow-descendant-areas descendant from a given page returned by the fo:page-sequence must, for each area-class, be a contiguous sub-sub-sequence of the areas returned by each fo:flow that is a child of the fo:page-sequence. In addition, if B is an area which precedes area A in the sub-sub-sequence for a given area-class and is not a flow-descendant-area of the page from which A is a descendant, then area B must be a flow-descendant area of some page that precedes that page from which A is a descendant.

  NOTE:

  These constraints insure that all of the areas returned-by a given fo:flow are placed on some page and that the order of the areas is preserved. The normal areas are placed sequentially on sequential pages (on which the region to which that flow is assigned appears). Footnotes and floats in the block-progression-direction are also placed sequentailly, but, it is not necessary that the sequence be place in sequential pages. For example, some pages may have not footnotes or floats and a sequence of floats that is too big to fit on one page may be distributed across a sequence of pages.

• Contents:

  (static-content*,flow)
  

• Properties:

  • [7.17.1 "format"]
  • [7.17.2 "letter-value"]
  • [7.17.3 "grouping-separator"]
  • [7.17.4 "grouping-size"]
  • [7.19.19 "id"]
  • [7.11.7 "initial-page-number"]
  • [7.11.8 "force-page-count"]
  • [7.11.5 "master-name"]

6.4.4 fo:layout-master-set

• Common Usage:

  The fo:layout-master-set is a wrapper around all masters used in the document. This includes page-sequence masters, page-masters and region-masters.

• Areas:

  The masters that are the children of the fo:layout-master-set are used by the fo:page-sequence to generate pages.

• Constraints:

  The value of the "master-name" property on each child of the fo:layout-master-set must be unique within the set.

• Contents:

  (simple-page-master|page-sequence-master)+
  

• Properties:

  • [7.19.19 "id"]

6.4.5 fo:page-sequence-master

• Common Usage:

  The fo:page-sequence-master is used to specify the constraints on and the order in which a given set of page-masters will be used in generating a sequence of pages. Pages are automatically generated when the fo:page-sequence-master is used in formatting an fo:page-sequence.

  NOTE:

  There are several ways of specifying a potential sequence of pages. One can specify a sequence of references to particular page-masters. This yields a bounded sequence of potential pages. Alternatively, one can specify a repeating sub-sequence of one or more page-masters. This sub-sequence can be bounded or unbounded. Finally one can intermix the two kinds of sub-sequence specifiers.

• Areas:

  This formatting object is used by the fo:page-sequence formatting object to generate pages.

• Constraints:

  The children of the fo:page-sequence-master are a sequence of sub-sequence-specifiers. A page-sequence satisfies the constraint determined by an fo:page-sequence-master if (a) it can be partitioned into sub-sequences of pages that map one-to-one, in order, to the sub-sequence of sub-sequence-specifiers that are the children of the fo:page-sequence specification and, (b) for each sub-sequence of pages, that sub-sequence satisfies the constraints of the corresponding sub-sequence specifier. Note that the mapping of sub-sequences of the sequence of pages to sub-sequence-specifiers need not be onto; that is, the sequence of sub-sequences of pages can be shorter than the sequence of sub-sequence-specifiers.

• Contents:

  (single-page-master-reference|repeatable-page-master-reference|repeatable-page-master-alternatives)+
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.5 "master-name"]

6.4.6 fo:single-page-master-reference

• Common Usage:

  An fo:single-page-master-reference is the simplest sub-sequence-specifier. It specifies a sub-sequence consisting of a single instance of a single page-master. It is used to specify the use of a particular page-master at a given point in the sequence of pages that would be generated using the fo:page-sequence-master that is the parent of the fo:single-page-master-reference.

• Areas:

  This formatting object is used by the fo:page-sequence formatting object to generate pages.

• Constraints:

  The fo:single-page-master-reference has a reference to the fo:simple-page-master which has the same master-name as the "master-name" property on the fo:single-page-master-reference.

  The sub-sequence of pages mapped to this sub-sequence-specifier satisfies the constraints of this sub-sequence-specifier if (a) the sub-sequence of pages consists of a single page and (b) that page is constrained to have been generated using the fo:simple-page-master referenced by the fo:single-page-master-reference.

• Contents:

  EMPTY
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.5 "master-name"]

6.4.7 fo:repeatable-page-master-reference

• Common Usage:

  An fo:repeatable-page-master-reference is the next simplest sub-sequence-specifier. It specifies a sub-sequence consisting of repeated instances of a single page-master. The number of repetitions may be bounded or potentially unbounded.

• Areas:

  The fo:repeatable-page-master-reference formatting object is used by the fo:page-sequence formatting object to generate pages.

• Constraints:

  The fo:repeatable-page-master-reference has a reference to the fo:simple-page-master which has the same master-name as the "master-name" property on the fo:repeatable-page-master-reference.

  The "maximum-repeats" property determines how many repeats of the referenced page-master are allowed. A sub-sequence of pages that has a length that is less than or equal to the value of the "maximum-repeats" property satisfies this property; a sub-sequence of pages that has a length that is greater does not.

  The sub-sequence of pages mapped to this sub-sequence-specifier satisfies the constraints of this sub-sequence-specifier if (a) the sub-sequence of pages consist of zero or more pages, (b) each page is constrained to have been generated using the fo:simple-page-master referenced by the fo:repeatable-page-master-reference, and (c) the constraint determined by the "maximum-repeats" property is satisfied.

  Issue (repeatable-page-master-reference-constraint):

  Should the constraint be for "zero or more pages" or for "one or more pages"? Zero seems right if there is no fo:flow that would cause the referenced page-master to be used. This could lead to ambiguous partitions of the page-sequence when satisfying the constraint of the parent fo:page-sequence-master, however.

• Contents:

  EMPTY
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.5 "master-name"]
  • [7.11.9 "maximum-repeats"]

6.4.8 fo:repeatable-page-master-alternatives

• Common Usage:

  The fo:repeatable-page-master-alternatives formatting object is the most complex sub-sequence-specifier. It specifies a sub-sequence consisting of repeated instances of a set of alternative page-masters. The number of repetitions may be bounded or potentially unbounded. Which of the alternative page-masters is used at any point in the sequence depends on the evaluation of a condition on the use of the alternative. Typical conditions include, testing whether the page which is generated using the alternative is the first or last page in a page-sequence or is the page blank. The full set of conditions allows different page-masters to be used for the first page, for odd and even pages, for blank pages.

  NOTE:

  Because the conditions are tested in order from the beginning of the sequence of children, the last alternative in the sequence usually has a condition that is always true and this alternative references the page-master that is used for all pages that do not receive some specialized layout.

• Areas:

  The fo:repeatable-page-master-alternatives formatting object generates no area directly. This formatting object is used by the fo:page-sequence formatting object to generate pages.

• Constraints:

  The children of the fo:repeatable-page-master-alternatives are fo:conditional-page-master-references. These children will be called alternatives.

  The "maximum-repeats" property determines how many repeats of the referenced page-master are allowed. A sub-sequence of pages that has a length that is less than or equal to the value of the "maximum-repeats" property satisfies this property; a sub-sequence of pages that has a length that is greater does not.

  The sub-sequence of pages mapped to this sub-sequence-specifier satisfies the constraints of this sub-sequence-specifier if (a) the sub-sequence of pages consist of zero or more pages, (b) each page is constrained to have been generated using the fo:simple-page-master referenced by the one of the alternatives that are the children of the fo:repeatable-page-master-alternatives, (c) the conditions on that alternative are "true", (d) that alternative is the first alternative in the sequence of children for which all the conditions are "true", and (e) the constraint determined by the "maximum-repeats" property is satisfied.

• Contents:

  (conditional-page-master-reference+)
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.9 "maximum-repeats"]

6.4.9 fo:conditional-page-master-reference

• Common Usage:

  The fo:conditional-page-master-reference is used to identify a page-master that is to be used when the conditions on its use are satisfied. This allows different page-masters to be used, for example, for even and odd pages, for the first page in a page-sequence, or for blank pages. This usage is typical in chapters of a book or report where the first page has a different layout than the rest of the chapter and the headings and footings on even and odd pages may different as well.

• Areas:

  The fo:conditional-page-master-reference formatting object is used by the fo:page-sequence formatting object to generate pages.

• Constraints:

  The fo:conditional-page-master-reference has a reference to the fo:simple-page-master which has the same master-name as the "master-name" property on the fo:conditional-page-master-reference.

  There are three properties, "page-position", "odd-or-even", and "blank-page" that specify the sub-conditions on the use of the referenced page-master. All three sub-conditions must be "true" for the condition on the fo:conditional-page-master-reference to be "true". Since, these properties are not inherited and the initial value of all the properties makes the corresponding sub-condition "true", this really means that the specified properties must make the corresponding sub-condition "true".

  The sub-condition corresponding to the "page-position" property is "true", if the page generated using the fo:conditional-page-master-reference has the specifed position in sequence of pages generated by the referencing page-sequence; namely, "first", "last", "rest" (not first) or "any" (all of the previous). The referencing page-sequence is the fo:page-sequence that referenced the fo:page-sequence-master from which this fo:conditional-page-master-referenece is a descendant.

  The sub-condition corresponding to the "odd-or-even" property is "true", if the page generated using the fo:conditional-page-master-reference is an "even", "odd", or "any" page in the ordinal ordering of all pages descendent from the area tree root.

  The sub-condition corresponding to the "blank" property is "true", (a) if value of the property is "not-blank" and the page generated using the fo:conditional-page-master-reference has flow-desecendant areas from the fo:flow formatting object; (b) if value of the property is "blank" and the page generated using the fo:conditional-page-master-reference was automatically generated either because the constraints on the flow-descendant areas of the fo:flow formatting object would not be satisfied if they were descendant from this page or because the page was generated at the end of a page-sequence to force an even or odd page count; or (c) if value of the property is "any".

• Contents:

  EMPTY
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.5 "master-name"]
  • [7.11.10 "page-position"]
  • [7.11.11 "odd-or-even"]
  • [7.11.12 "blank-page"]

6.4.10 fo:simple-page-master

• Common Usage:

  The fo:simple-page-master is used in the generation of pages and specifies the geometry of the page. The page may be subdivided into up to five regions: region-body, region-before, region-after, region-start, and region-end.

  NOTE:

  For example, if the "writing-mode" of the fo:simple-page-master is "lr-tb", then these regions correspond to to the body of a document, the header, the footer, the left sidebar and the right sidebar.

  NOTE:

  The simple-page-master is intended for systems that wish to provide a simple page layout facility. Future versions of this specification will support more complex page layouts constructed using the fo:page-master formatting object.

• Areas:

  The fo:simple-page-master is used in the generation of pages by an fo:page-sequence.

  When the fo:simple-page-master is used to generate a page, two reference-areas area generated: the media reference area and the page-level reference-area. The page-level reference-area is a child of the media reference-area. The media reference-area represents the physical bounds of the output medium. The page-level reference-area represents the portion of the page on which content is intended to appear; that is, the area inside the page margins.

  In addition, when the fo:simple-page-master is used to generate a page, reference-areas that correspond to the regions that are the children of the fo:simple-page-master are also generated. For each such region, the region-master is used to generate a viewport-area and a region reference-area. (See the formatting object specifications for the five regions for the details on the generation of these areas.)

  

• Trait Derivation:

  In this version of this specification, borders and padding are not allowed with a page-area. The remaining traits on the page-area are set according to normal rules for determining the values of traits.

• Constraints:

  When a page-master is used in the generation of a page, the "height" and "width" of the content-rectangle of the media reference-area are determined using the "page-height" and "page-width" properties. Note these properties may be set using the shorthand property, "size". If the "page-height" and "page-width" properties have explicit values, they are used to set the corresponding height and width trait on the media reference-area. If the "page-height" and/or "page-width" are set to "auto", the size of the media reference-area will be determined from the size of the media. If the media has a fixed size, then the size of the media is used. In the case of continuous media, the size of the user agent window is used.

  NOTE:

  The above size calculations are intended to match the handling of a frameset in a browser window when the media is continuous and to match pages when the media is paged.

  Issue (simple-page-master-frames):

  This may need further review.

  The values of the margin properties determine the size of the content-rectangle, that is, the page, within the media reference-area. "margin-top", "margin-bottom", "margin-left" and "margin-right" are used to indent the page-level reference-area content-rectangle from the corresponding edge of the media page. Here "top", "bottom", "left" and "right" are determined by the value of the "reference-orientation" property on the fo:simple-page-master.

  

  Issue (simple-page-master-media-reference-area):

  The notion of a "media reference-area" was introduced to have a reference from which the margin properties could determine the page-level reference-area (a.k.a "page"). This needs further discussion.

  The fo:simple-page-master may have an fo:title formatting object as a child. The user agent may use this information to help identify the page, for example, present the information in its "title bar".

  The value of the page-number trait on the first page returned by the fo:page-sequence is constrained to equal the value of the "initial-page-numer" property. The value of the page-number trait on subsequent pages is constrained to be one greater than the value on the immediately preceding page.

  The "format", "letter-value", "grouping-separator", "grouping-size" and "lang" properties are used to format the number into a string form, as specified in XSLT, section 7.7.1. This formatted number is used as the value of the fo:page-number flow object.

• Constraints applicable to regions:

  There are a number of constraints that apply to all the regions that are specified within a given fo:simple-page-master.

  Flow-descendant-areas descendant from the region reference-area must also be generation descendant from the flow assigned to the region-master used to generate the region reference-area. In addition, the sub-sequence of normal areas returned by the flow object assigned to the corresponding region and descendant from the region reference area (or in the case of the fo:region-body from the remaining region-body reference-area) must be properly stacked in that reference-area.

  The inline-progression-dimension of the region reference-area that corresponds to a given region-master is determined by the "inline-progression-dimension" property on the flow object that is assigned to the corresponing region. If the value of the "inline-progression-dimension" property is "auto", then the inline-progression-dimension of the region reference-area is determined from the inline-progression-dimension of the corresponding viewport reference-area. (See each region-master for further information on how the inline-progression-dimension of the corresponding viewport reference-area is determined.) Otherwise, the inline-progression-dimension of the region reference-area is taken from the inline-progression-dimension of the flow object.

  Issue (orientation):

  Orientation can change viewport dimensions. The above paragraph needs to be re-written to use "effective block-progression-dimension" which is the viewport dimension that corresponds to block-progression-dimension in the region reference-area. The "orientation" property may have the region be rotated with respect to the viewport. See also below for same problem.

  If the block-progression-dimension of the properly stacked region reference-area is less than or equal to the block-progression-dimension of the viewport reference-area that is its parent, then the padding-after trait of the region reference-area shall be such that the block-progression-dimension of the region reference-area plus the padding-after of that area equal the block-progression-dimension of the viewport reference-area.

  NOTE:

  Adding padding after the content-rectangle of the region reference-area insures that the background of the region reference-area will fill the entire viewport.

  If the block-progression-dimension of the properly stacked region reference-area is greater than the block-progression-dimension of the viewport reference-area that is its parent, then the constraints on the relationship between the viewport reference-area and the region reference area depend on values of the "overflow" property on the region formatting object and the kind of flow assigned to the region.

  If the flow assigned to the corresponding region is an fo:static-content flow object, then

  • If the value of the "overflow" property is "scroll" or "visible", then there is no constraint on the block-progression-dimension of the region reference-area.

  • If the value of the "overflow" property is "hidden", then the block-progression-dimension of the region reference-area is constrained to be no greater than the block-progression-dimension of the viewport reference-area.

  Issue (overflow-static-content):

  Overflow on static-content. When an fo:static-content flow object is assigned to a region and the value of the "overflow" property on that region is "hidden", should the block-progression-dimension of the corresponding region reference-area by constrained or not?

  If the flow assigned to the corresponding region is an fo:flow formatting object, then

  • If the value of the "overflow" property is "scroll", then there is no constraint on the block-progression-dimension of the region reference-area.

  • If the value of the "overflow" property is "hidden"or "visible", then the block-progression-dimension of the region reference-area is constrained to be no greater than the block-progression-dimension of the viewport reference-area.

  The block-progression-dimension of a region-area that corresponds to a given region-master depends on the value of the "overflow" property on that region-master.

• Contents:

  (title?,region-body,region-before?,region-after?,region-start?,region-end?)
  

• Properties:

  • [7.19.19 "id"]
  • [7.9 Common Margin Properties-Block]
  • [7.11.5 "master-name"]
  • [7.11.13 "page-height"]
  • [7.11.14 "page-width"]
  • [7.19.29 "reference-orientation"]
  • [7.19.32 "size"]
  • [7.19.51 "writing-mode"]

6.4.11 fo:region-body

• Common Usage:

  Used in constructing a simple-page-master. This region specifies a viewport that is located in the "center" of the fo:simple-page-master. The "overflow" property controls how much of the underlying region reference-area is visible; that is, is the reference-area clipped by the viewport-area that corresponds to the region-master or not.

  NOTE:

  Typically, for paged media, the flow-descendant-areas returned by the fo:flow formatting object in a fo:page-sequence are made to be descendants of a sequence of region reference-areas that correspond to the region-body. These region reference-areas are all area descendants of pages for which the page-master included an fo:region-body. For continuous media, the flow-descendant areas all descend from a single region reference-area that usually corresponds to the region-body. If the fo:flow flow is assigned to some other region, then its flow-descendant-areas are constrained to be descendants of region reference-areas that correspond to the assigned region.

  NOTE:

  The body region should be sized and positioned within the content-rectangle of the fo:simple-page-master so that there is room for the flow-descendant-areas from the flow that is assigned to the fo:region-body and for any desired side regions, that is, fo:region-before, fo:region-after, fo:region-start and fo:region-end's that are to be placed on the same page. These side regions are positioned within the content-rectangle of the page. The margins on the fo:region-body are used to position the viewport-area for the fo:region-body and to leave space for the other regions that surround the fo:region-body.

  

  The spacing between the last four regions and the fo:region-body is determined by subtracting the relevant "extent" property on the side regions from the corresponding "margin-x" property on the fo:region-body.

  The fo:region-body may be also be used to provide multiple columns. When the "column-count" property is greater than one, then the region-body will be subdivided into multiple columns.

• Areas:

  The fo:region-body formatting object is used to generate one viewport reference-area and one region reference-area whenever an fo:simple-page-master that has an fo:region-body as a child is used to generate a page. Horizontal and/or vertical scroll bars areas are generated children of the viewport reference-area if the value of the "overflow" property is "scroll".

  Issue (scroll-bar-areas):

  Scroll-bar areas?

  The position and size of the viewport-area is specified relative to the content-rectangle of the page-level reference-area generated by fo:simple-page-master. The content-rectangle of the viewport-area is indented from the content-rectangle of the page-level reference-area by the values of the "margin-top", "margin-bottom", "margin-left" and "margin-right" properties. In this version of this specification, the values of the "padding" and "border-width" properties must be "0".

  The region reference-area generated using an fo:region-body is a child of the viewport-area. The "reference-orientation" property of the fo:region-body is used to orient the coordinate system of the region reference-area generated by the fo:region-body relative to the coordinate system of the reference-area generated by fo:simple-page-master (and, therefore, relative to the viewport positioned in that latter coordinate system).

  In addition to the the viewport reference-area and its descendant region reference-area, when the region-body is used to generate areas, at least one and up to three additional reference-areas are generated. These reference-areas correspond to the conditional reference-area for "xsl-top-float"s, the conditional reference-area for "xsl-footnote"s and the remaining region-body reference-area. The latter reference-area comprises the space left after space is borrowed for the two conditional reference-areas. The remaining region-body reference-area has no padding, border, or space associated with it.

  NOTE:

  If there are no conditional regions that are children of the region-body reference area, then the content rectangle of the remaining region-body reference-area is co-terminus with the content rectangle of the region-body region reference area. If there are conditional reference areas that are children of the region-body region reference-area, then the content rectangle of the remaining region-body reference-area is reduced by the space consumed by the conditional reference-areas.

  Types of areas when "column-count" is greater than 1:

  If the "column-count" property has a value other than 1, for example, N, then N additional reference-areas are generated as children of the remaining region-body reference-area generated using the fo:region-body. These N reference-areas are the column reference-areas.

  The inline-progression-dimension of each of these column reference-areas is determined by subtracting (N-1) times the computed value of the "column-gap" property from the inline-progression-dimension of the remaining region-body reference-area generated using the fo:region-body and dividing that result by N. Using "body-in-size" for the name of the inline-progression-dimension of the remaining region-body reference-area and "column-in-size" for the name of the size of the column reference-areas in the inline-progression-direction, the formula is:

  column-in-size = (body-in-size - (N - 1)*column-gap)/N

  The size of the column reference-areas in the block-progression-direction is the same as the size of the containing reference-area in the block-progression-direction.

  NOTE:

  As noted above, the size of the containing reference-area in the block-progression direction may be less than the size of the region reference-area if conditional reference-areas are children of the region reference-area.

  The column reference-areas are positioned within the reference-area generated by the fo:region-body as follows: The first column is positioned with its before-edge and start-edge coincident with the before-edge and start-edge of the remaining region-body reference-area. The Jth column reference-area is positioned with its before-edge coincident with the before-edge of the remaining region-body reference-area and with is start-edge at ((J-1)*(column-in-size + column-gap)) in the inline-direction. This results in the end-edge of the Nth column reference-area being coincident with the end-edge of the remaining region-body reference-area.

  NOTE:

  If the "writing-mode" is "rl-tb", the above description means that the columns are ordered from right-to-left as would be expected. This follows because the start-edge is on the right in an "rl-tb"writing-mode.

  Issue (region-body-scroll-and-column-count):

  Interaction between scroll and column-count > 1. This was deemed to be an error.

• Constraints:

  The constraints applicable to all regions (see fo:simple-page-master) all apply.

  The inline-progression-dimension of the viewport reference-area is determined by the inline-progression-dimension of the content-rectangle for the page-level reference area minus the values of the space properties on the start-edge and end-edge of the region-master. The start-edge and end-edge of the region-master are determined by the "reference-orientation" property on the page-master.

  The block-progression-dimension of the viewport reference-area is determined by the block-progression-dimension of the content-rectangle for the page-level reference area minus the values of the space properties on the before-edge and after-edge of the region-master. The before-edge and after-edge of the region-master are determined by the "reference-orientation" property on the page-master.

  The values of the "space-before" and "start-indent" properties are used to position the viewport reference-area relative to the page-level reference-areas before-edge and start-edge.

  The constraints on the size and position of the region reference-area generated using the fo:region-body are covered in the "Constraints applicable to regions" section of the description of fo:simple-page-master.

  The reference-orientation of the region reference-area is taken from the value the "reference-orientation" property on the region-master which specifies the region.

  Issue (constraints):

  what constraints are necessary on the body itself. Where is the appropriate place to describe conditional areas? Do we need page-sequence like constraints on the column order?

  If the remaining region-body reference-area is subdivided into more than one column, then for any two coluns C and D:

  If column C precedes column D in the ordering of columns,

  1. then all normal flow-descendant-areas of that fo:flow that are area descendants of page P must be generation ordered before all normal flow-descendant-areas of that fo:flow that are area descendants of page Q.

  2. and, for out-of-line flow-descendant-areas of that fo:flow that are area descendants of page P and for which the value of the area-class trait is "xsl-footnote", "xsl-start-float", "xsl-end-float" and "xsl-top-float", then within each class, all flow-descendant-areas of that fo:flow that are area descendants of page P must be generation ordered before all flow-descendant-areas of that fo:flow that are area descendants of page Q.

  NOTE:

  This is sometimes called, "snaking columns".

• Contents:

  EMPTY
  

• Properties:

  • [7.19.1 "clip"]
  • [7.11.1 "column-count"]
  • [7.11.2 "column-gap"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.19 "id"]
  • [7.19.25 "overflow"]
  • [7.11.6 "region-name"]
  • [7.19.37 "vertical-align"]
  • [7.19.29 "reference-orientation"]
  • [7.19.51 "writing-mode"]

6.4.12 fo:region-before

• Common Usage:

  Used in constructing a simple-page-master. This region defines a viewport that is located on the "before" side of fo:region-body region. In lr-tb writing-mode, this region corresponds to the header region. The visibility of the content that is bound to the region by an fo:page-sequence is controlled by the "overflow" property on the region.

  Issue (region-before-side-in-terms-of):

  the "before" side is in terms of the writing mode of the fo:simple-page-master and not fo:region-body.

• Areas:

  The fo:region-before formatting object is used to generate one viewport reference-area and one region reference-area.

  This viewport is positioned with its before edge coincident with the before-edge of the content-rectangle of the page-level reference-area generated using the parent fo:simple-page-master. In the direction perpendicular to the before-edge, the size of the viewport is determined by the "extent" property on the fo:region-before formatting object.

  In the direction parallel to the before-edge, the size of the viewport is determined by the "precedence" properties on the fo:region-before. If the value of the "precedence" property is "true", then the region-before viewport extends up to the start-edge and after-edges of the content rectangle of the page-level reference-area. In this case, the area generated by the region-before acts like a float into areas generated by the region-start (respectively, the region-end). If the value of the "precedence" property on the fo:region-before is "false", then these adjacent regions float into the area generated by the fo:region-before and the extent of the fo:region-before is (effectively) reduced by the incursions of the adjacent regions.

  The reference-area generated by fo:region-before lies on a canvas underneath the above viewport. The "reference-orientation" property is used to orient the coordinate system of the reference-area generated by the fo:region-before relative to the coordinate system of the reference-area generated by fo:simple-page-master (and, therefore, the viewport positioned in that latter coordinate system).

  The size of the reference-area depends on the setting of the "overflow" property on the region. If the value of that property is "auto", "hidden" or "visible" then the size of the area container is the same as the size of the viewport. If the value of the "overflow" property is "scroll", the size of the reference-area is equal to the size of the viewport in the inline-progression-direction in the "writing-mode" for the region and is long enough in the block-progression-direction to hold the distribution of all the content bound to the region.

• Constraints:

  The constraints on the size and position of the region reference-area generated using the fo:region-body are covered in the "Constraints applicable to regions" section of the description of fo:simple-page-master.

• Contents:

  EMPTY
  

• Properties:

  • [7.19.1 "clip"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.11.3 "extent"]
  • [7.19.19 "id"]
  • [7.19.25 "overflow"]
  • [7.11.15 "precedence"]
  • [7.11.6 "region-name"]
  • [7.19.37 "vertical-align"]
  • [7.19.29 "reference-orientation"]
  • [7.19.51 "writing-mode"]

6.4.13 fo:region-after

• Common Usage:

  Used in constructing a simple-page-master. This region defines a viewport that is located on the "after" side of fo:region-body region. In lr-tb writing-mode, this region corresponds to the footer region. The visibility of the content that is bound to the region by an fo:page-sequence is controlled by the "overflow" property on the region.

  Issue (region-after-side-in-terms-of):

  the "after" side is in terms of the writing-mode of the fo:simple-page-master and not fo:region-body.

• Areas:

  The fo:region-after formatting object is used to generate one viewport reference-area and one region reference-area.

  This viewport is positioned with its after-edge coincident with the after-edge of the content-rectangle of the page-level reference-area generated using the parent fo:simple-page-master. In the direction perpendicular to the after-edge, the size of the viewport is determined by the "extent" property on the fo:region-after formatting object.

  In the direction parallel to the after-edge, the size of the viewport is determined by the "precedence" properties on the fo:region-after. If the value of the "precedence" property is "true", then the region-after viewport extends up to the start-edge and after-edge edges of the content rectangle of the page-level reference-area. In this case, the area generated by the region-after acts like a float into areas generated by the region-start (respectively, the region-end). If the value of the "precedence" property on the fo:region-after is "false", then these adjacent regions float into the area generated by the fo:region-after and the extent of the fo:region-after is (effectively) reduced by the incursions of the adjacent regions.

  The reference-area generated by fo:region-after lies on a canvas underneath the above viewport. The "reference-orientation" property is used to orient the coordinate system of the reference-area generated by the fo:region-after relative to the coordinate system of the reference-area generated by fo:simple-page-master (and, therefore, the viewport positioned in that latter coordinate system).

  The size of the reference-area depends on the setting of the "overflow" property on the region. If the value of that property is "auto", "hidden" or "visible" then the size of the reference-area is the same as the size of the viewport. If the value of the "overflow" property is "scroll", the size of the reference-area is equal to the size of the viewport in the inline-progression-direction in the "writing-mode" for the region and is long enough in the block-progression-direction to hold the distribution of all the content bound to the region.

• Constraints:

  The constraints on the size and position of the region reference-area generated using the fo:region-body are covered in the "Constraints applicable to regions" section of the description of fo:simple-page-master.

• Contents:

  EMPTY
  

• Properties:

  • [7.19.1 "clip"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.11.3 "extent"]
  • [7.19.19 "id"]
  • [7.19.25 "overflow"]
  • [7.11.15 "precedence"]
  • [7.11.6 "region-name"]
  • [7.19.37 "vertical-align"]
  • [7.19.29 "reference-orientation"]
  • [7.19.51 "writing-mode"]

6.4.14 fo:region-start

• Common Usage:

  Used in constructing a simple-page-master. This region defines a viewport that is located on the "start" side of fo:region-body region. In lr-tb writing-mode, this region corresponds to a left sidebar. The visibility of the content that is bound to the region by an fo:page-sequence is controlled by the "overflow" property on the region.

  Issue (region-start-side-in-terms-of):

  the "start" side is in terms of the writing mode of the fo:simple-page-master and not fo:region-body.

• Areas:

  The fo:region-start formatting object is used to generate one viewport reference-area and one region reference-area.

  This viewport is positioned with its start edge coincident with the start edge of the content-rectangle of the page-level reference-area generated using the parent fo:simple-page-master. In the direction perpendicular to the start edge, the size of the viewport is determined by the "extent" property on the fo:region-start formatting object.

  In the direction parallel to the start edge, the size of the viewport is determined by the "precedence" properties on the adjacent fo:region-before and the fo:region-after. If the value of the "precedence" property is "false", then the region-start viewport extends up to the before (or, respectively, after) edge of the content-rectangle of the page-level reference-area. In this case, the area generated by the region-start acts like a float into areas generated by the region-before (respectively, the region-after). If the value of the "precedence" property on the adjacent regions is "true", then these adjacent regions float into the area generated by the fo:region-start and the "extent" of the fo:region-start is (effectively) reduced by the incursions of the adjacent regions with the value of the "precedence" property equal to "true".

  The reference-area generated by fo:region-start lies on a canvas underneath the above viewport. The "reference-orientation" property is used to orient the coordinate system of the reference-area generated by the fo:region-start relative to the coordinate system of the reference-area generated by fo:simple-page-master (and, therefore, the viewport positioned in that latter coordinate system).

  The size of the reference-area depends on the setting of the "overflow" property on the region. If the value of that property is "auto", "hidden" or "visible" then the size of the area container is the same as the size of the viewport. If the value of the "overflow" property is "scroll", the size of the reference-area is equal to the size of the viewport in the inline-progression-direction in the "writing-mode" for the region and is long enough in the block-progression-direction to hold the distribution of all the content bound to the region.

• Constraints:

  The constraints on the size and position of the region reference-area generated using the fo:region-body are covered in the "Constraints applicable to regions" section of the description of fo:simple-page-master.

• Contents:

  EMPTY
  

• Properties:

  • [7.19.1 "clip"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.11.3 "extent"]
  • [7.19.19 "id"]
  • [7.19.25 "overflow"]
  • [7.11.6 "region-name"]
  • [7.19.37 "vertical-align"]
  • [7.19.29 "reference-orientation"]
  • [7.19.51 "writing-mode"]

6.4.15 fo:region-end

• Common Usage:

  Used in constructing a simple-page-master. This region defines a viewport that is located on the "end" side of fo:region-body region. In lr-tb writing-mode, this region corresponds to a right sidebar. The visibility of the content that is bound to the region by an fo:page-sequence is controlled by the "overflow" property on the region.

  Issue (region-end-side-in-terms-of):

  the "end" side is in terms of the writing mode of the fo:simple-page-master and not fo:region-body.

• Areas:

  The fo:region-end formatting object is used to generate one viewport reference-area and one region reference-area.

  This viewport is positioned with its end edge coincident with the end edge of the content-rectangle of the page-level reference-area generated using the parent fo:simple-page-master. In the direction perpendicular to the end edge, the size of the viewport is determined by the "extent" property on the fo:region-end formatting object.

  In the direction parallel to the end edge, the size of the viewport is determined by the "precedence" properties on the adjacent fo:region-before and the fo:region-after. If the value of the "precedence" property is "false", then the region-end viewport extends up to the before (or, respectively, after) edge of the content-rectangle of the page-level reference-area. In this case, the area generated by the region-end acts like a float into areas generated by the region-before (respectively, the region-after). If the value of the "precedence" property on the adjacent regions is "true", then these adjacent regions float into the area generated by the region-end and the extent of the region end is (effectively) reduced by the incursions of the adjacent regions with the value of the "precedence" property equal to "true".

• Constraints:

  The constraints on the size and position of the region reference-area generated using the fo:region-body are covered in the "Constraints applicable to regions" section of the description of fo:simple-page-master.

• Contents:

  EMPTY
  

• Properties:

  • [7.19.1 "clip"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.11.3 "extent"]
  • [7.19.19 "id"]
  • [7.19.25 "overflow"]
  • [7.11.6 "region-name"]
  • [7.19.37 "vertical-align"]
  • [7.19.29 "reference-orientation"]
  • [7.19.51 "writing-mode"]

6.4.16 fo:flow

• Common Usage:

  The content of the fo:flow formatting object is a sequence of flow objects that forms one "unit of content", such as an article, a chapter, or a section. The result of formatting this "unit of content" is distributed across the pages generated by the fo:page-sequence which is the parent of the fo:flow.

• Areas:

  The fo:flow formatting object does not generate any areas. The fo:flow formatting object returns sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:flow. The order of concatenation is the same order as the children are ordered under the fo:flow.

• Constraints:

  The (implicit) flow-map determines the assignment of the content of the fo:flow to a region.

  Issue (height-and-width-on-fo-flow):

  CSS takes the height and width of the region reference-area from the height and width on the (equivalent of) the fo:flow object. If the those values are "auto", then the viewport size is used.

• Contents:

  (%block;)+
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.4 "flow-name"]

6.4.17 fo:static-content

• Common Usage:

  The fo:static-content formatting object is used to group a "unit of content" that may be used on more than one page, such as the content of a header or footer. This "unit of content" is repeated, in its entirety, on every page to which it is assigned.

• Areas:

  The fo:static-content formatting object does not generate any areas. The fo:static-content formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:flow. The order of concatenation is the same order as the children are ordered under the fo:static-content.

• Constraints:

  The (implicit) flow-map determines the assignment of the content of the fo:static-content to a region.

• Contents:

  (%block;)+
  

• Properties:

  • [7.19.19 "id"]
  • [7.11.4 "flow-name"]

6.5 Block-level Formatting Objects

Issue (subroutines):

Identify required "subroutines" for descriptions that pertain to multiple FO classes.

Determine appropriate placement in the Draft to hold subroutines.

6.5.1 Introduction

The fo:block formatting object is used for formatting paragraphs, titles, figure captions, table titles, etc. The following example illustrates the usage of the fo:block in a style sheet.

6.5.1.1 Example

6.5.1.1.1 Chapter and Section Titles, Paragraphs

Input sample:

<doc>
  <chapter><title>Chapter</title>
    <p>Text</p>
    <section><title>Section</title>
    <p>Text</p>
    </section>
    <section><title>Section</title>
    <p>Text</p>
    </section>
  </chapter>
  <chapter><title>Chapter</title>
    <p>Text</p>
    <section><title>Section</title>
    <p>Text</p>
    </section>
    <section><title>Section</title>
    <p>Text</p>
    </section>
  </chapter>
</doc>

In this example the Chapter title appears at the top of the page (its "space-before" is discarded).

Space between Chapter title and first section title is (8pt,8pt,8pt): the chapter title's "space-after" has a higher precedence than the section title's "space-before" (which takes on the initial value of zero), so the latter is discarded

Space between the first section title and Section one's first paragraph is (6pt,6pt,6pt): the section title's "space-after" has higher precedence than the paragraph's "space-before", so the latter is discarded.

Space between the two paragraphs is (6pt,8pt,10pt): the "space-after" the first paragraph is discarded because its precedence is equal to that of the "space-before" the next paragraph, and the optimum of the "space-after" of the first paragraph is greater than the optimum of the "space-before" of the second paragraph.

Space between the second paragraph of the first section and the title of the second section is (12pt,12pt,12pt): the "space-after" the paragraph is discarded because its precedence is equal to that of the "space-before" of the section title, and the optimum of the "space-after" of the paragraph is less than the optimum of the "space-before" of the section title.

The indent on the first line of the first paragraph in section one and the only paragraph in section two is 2pc; the indent on the first line of the second paragraph in section one is zero.

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="chapter">
  <fo:block break-before="page">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="chapter/title">
  <fo:block text-align="center" space-after="8pt"
            space-before="16pt" space-after.precedence="3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="section/title">
  <fo:block text-align="center" space-after="6pt"
            space-before="12pt" space-before.precedence="0"
            space-after.precedence="3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="p[1]" priority="1">
  <fo:block text-indent="0pc" space-after="7pt"
            space-before.minimum="6pt" space-before.optimum="8pt"
            space-before.maximum="10pt">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="p">
  <fo:block text-indent="2pc" space-after="7pt"
            space-before.minimum="6pt" space-before.optimum="8pt"
            space-before.maximum="10pt">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

</xsl:stylesheet>

Result Instance: elements and attributes in the fo: namespace

<fo:block break-before="page">
  <fo:block text-align="center" space-after="8pt"
  space-before="16pt" space-after.precedence="3">Chapter
  </fo:block>

  <fo:block text-indent="0pc" space-after="7pt"
  space-before.minimum="6pt" space-before.optimum="8pt"
  space-before.maximum="10pt">Text
  </fo:block>

  <fo:block text-align="center" space-after="6pt"
  space-before="12pt" space-before.precedence="0"
  space-after.precedence="3">Section
  </fo:block>

  <fo:block text-indent="0pc" space-after="7pt"
  space-before.minimum="6pt" space-before.optimum="8pt"
  space-before.maximum="10pt">Text
  </fo:block>

  <fo:block text-align="center" space-after="6pt"
  space-before="12pt" space-before.precedence="0"
  space-after.precedence="3">Section
  </fo:block>

  <fo:block text-indent="0pc" space-after="7pt"
  space-before.minimum="6pt" space-before.optimum="8pt"
  space-before.maximum="10pt">Text
  </fo:block>
</fo:block>

<fo:block break-before="page">
  <fo:block text-align="center" space-after="8pt"
  space-before="16pt" space-after.precedence="3">Chapter
  </fo:block>

  <fo:block text-indent="0pc" space-after="7pt"
  space-before.minimum="6pt" space-before.optimum="8pt"
  space-before.maximum="10pt">Text
  </fo:block>

  <fo:block text-align="center" space-after="6pt"
  space-before="12pt" space-before.precedence="0"
  space-after.precedence="3">Section
  </fo:block>

  <fo:block text-indent="0pc" space-after="7pt"
  space-before.minimum="6pt" space-before.optimum="8pt"
  space-before.maximum="10pt">Text
  </fo:block>

  <fo:block text-align="center" space-after="6pt"
  space-before="12pt" space-before.precedence="0"
  space-after.precedence="3">Section
  </fo:block>

  <fo:block text-indent="0pc" space-after="7pt"
  space-before.minimum="6pt" space-before.optimum="8pt"
  space-before.maximum="10pt">Text
  </fo:block>
</fo:block>

6.5.2 fo:block

• Common Usage:

  The fo:block formatting object is commonly used for formatting paragraphs, titles, headlines, figure and table captions, etc.

• Areas:

  Each fo:block formatting object returns a sequence of one or more areas, including at least one normal area. Each of the normal areas returned by an fo:block formatting object F is a block area and is generated by F.

• Trait Derivation:

  The nominal-glyph-height trait is set from the computed value of the "font-size" property. The half-leading trait is set to 1/2 the computed value of the "line-height" property minus the "font-size" property.

• Constraints:

  The children of each normal area returned by an fo:block formatting object must be properly stacked.

  No area may have more than one normal child area returned by the same fo:block formatting object.

  For each child of a normal area returned by an fo:block formatting object F, either

  • the area is a normal area returned by a child of F, or

  • the area is a line area that was generated by F

  For each area generated by an fo:block formatting object F, either

  • the area is returned by F, or

  • the area is a line area that is a child of a normal area returned by F, or

  • the area is child of a line area generated by F, and has a non-null composed-by trait

  Issue (line-building):

  The constraints on area sequence in line areas needs to be completed. The description will also be moved as it is common to several formatting objects.

  The original area sequence of a line area ia a sequence of areas produced from the sequence of child areas by replacing each child area that has a non-null composed-from trait by the sequence of areas that is the value of the composed-from trait.

  The original area sequences of the line areas generated by a fo:block formatting object F must correspond to the normal inline areas returned by children of F. More precisely, the original area sequence of a fo:block formatting object F is defined as follows. The original area sequence of F must be the same as the concatenation of the normal areas in the sequences returned by the children of F.

  An area with a non-null composed-by trait can be generated in the following circumstances:

  • inserting hyphens at the end of a line

  • dropping spaces at the end of a line

  • substituting and reordering glyphs based on font information

• Contents:

  (#PCDATA|%inline;|%block;)*
  

  In addition an optional fo:initial-property-set may be the first child of the fo:block.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.7 Common Hyphenation Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.3 "color"]
  • [7.19.17 "hyphenation-keep"]
  • [7.19.18 "hyphenation-ladder-count"]
  • [7.15.2 "keep"]
  • [7.19.21 "last-line-end-indent"]
  • [7.19.47 "linefeed-treatment"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.24 "line-stacking-strategy"]
  • [7.15.3 "orphans"]
  • [7.15.1 "page-break-inside"]
  • [7.19.48 "space-treatment"]
  • [7.19.33 "span"]
  • [7.19.34 "text-align"]
  • [7.19.35 "text-align-last"]
  • [7.19.36 "text-indent"]
  • [7.19.38 "visibility"]
  • [7.19.45 "white-space"]
  • [7.19.46 "white-space-treatment"]
  • [7.19.49 "white-space-collapse"]
  • [7.15.4 "widows"]
  • [7.19.50 "wrap-option"]
  • [7.19.51 "writing-mode"]
  • [7.19.52 "z-index"]

6.5.3 fo:block-container

• Common use:

  The fo:block-container flow object is used to generate a block-level reference-area; typically containing text blocks with a different writing-mode. In addition, it can also be used with a different reference-orientation to rotate its content.

  NOTE:

  The use of this flow object is not required for changing the inline-progression-direction only; in that case the Unicode bidi algorithm and the fo:bidi-override are sufficient.

• Area type:

  The fo:block-container flow object results in a block-area. If the block-area will not fit in the remaining space in the containing area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the properties of the content of this flow object. The area is a reference-area.

• Content distribution:

  The size of the reference-area has to be fixed in the inline-progression-direction. It must be specified unless the inline-progression-direction is parallel to the inline-progression-direction of the reference-area into which the areas resulting from this flow object are placed.

  The size in the block-progression-direction is determined by the content of this flow object.

• Content:

  (%block;)+
  

• Properties:

  • [7.19.13 "block-progression-dimension"]
  • [7.19.1 "clip"]
  • [7.3 Common Absolute Position Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.8 Common Keeps and Breaks Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.10 "height"]
  • [7.19.19 "id"]
  • [7.19.42 "inline-progression-dimension"]
  • [7.15.2 "keep"]
  • [7.19.25 "overflow"]
  • [7.19.29 "reference-orientation"]
  • [7.19.33 "span"]
  • [7.19.39 "width"]
  • [7.19.51 "writing-mode"]

6.6 Inline-level Formatting Objects

6.6.1 Introduction

Inline formatting objects are most commonly used to format a portion of text or for generating rules and leaders. There are many other uses. The following examples illustrate some of these uses of inline-level formatting objects.

• putting the first line of a paragraph into small-caps,

• turning a normally inline formatting object, fo:external-graphic, into a block by "wrapping" with an fo:block formatting object,

• formatting a running footer containing the word "Page" followed by a page number.

6.6.1.1 Examples

6.6.1.1.1 First Line of Paragraph in Small-caps

Input sample:

<doc>
<p>This is the text of a paragraph that is going to be
presented with the first line in small-caps.</p>
</doc>

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="p">
  <fo:block>
    <fo:initial-property-set font-variant="small-caps"/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

</xsl:stylesheet>

Result instance: elements and attributes in the fo: namespace

<fo:block>
  <fo:initial-property-set font-variant="small-caps">
  </fo:initial-property-set>This is the text of a paragraph that is going to be
presented with the first line in small-caps.
</fo:block>

6.6.1.1.2 Figure with a Photograph

Input sample:

<doc>
  <figure>
    <photo image="TH0317A.jpg"/>
    <caption>C'ieng Tamlung of C'ieng Mai</caption>
  </figure>
</doc>

In this example the image (an fo:external-graphic) is placed as a centered block-level object. The caption is centered with 10mm indents.

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="figure">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="photo">
  <fo:block text-align="center">
    <fo:external-graphic href="{@image}"/>
  </fo:block>
</xsl:template>

<xsl:template match="caption">
  <fo:block space-before="3pt" text-align="center"
    start-indent="10mm" end-indent="10mm">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

</xsl:stylesheet>

fo: element and attribute tree:

<fo:block>
  <fo:block text-align="center">
    <fo:external-graphic href="TH0317A.jpg"/>
  </fo:block>

  <fo:block space-before="3pt" text-align="center" start-indent="10mm"
    end-indent="10mm">C'ieng Tamlung of C'ieng Mai</fo:block>
</fo:block>

6.6.1.1.3 Page numbering and page number reference

Input sample:

<!DOCTYPE doc SYSTEM "pgref.dtd">
<doc>
  <chapter id="x"><title>Chapter</title>
    <p>Text</p>
  </chapter>
  <chapter><title>Chapter</title>
    <p>For a description of X see <ref refid="x"/>.</p>
  </chapter>
</doc>

In this example each page has a running footer containing the word "Page" followed by the page number. The "ref" element generates the word "see" followed by the page number of the page on which the referenced by the "refid" attribute was placed.

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="doc">
  <fo:root>
    <fo:layout-master-set>
      <fo:simple-page-master master-name="page"
        page-height="297mm" page-width="210mm"
        margin-top="20mm" margin-bottom="10mm"
        margin-left="25mm" margin-right="25mm">
        <fo:region-body
          margin-top="0mm" margin-bottom="15mm"
          margin-left="0mm" margin-right="0mm"/>
        <fo:region-after extent="10mm"/>
      </fo:simple-page-master>
    </fo:layout-master-set>
    <fo:page-sequence master-name="page">
      <fo:static-content flow-name="xsl-region-after">
        <fo:block>
          <xsl:text>Page </xsl:text>
          <fo:page-number/>
        </fo:block>
      </fo:static-content>
      <fo:flow flow-name="xsl-region-body">
        <xsl:apply-templates/>
      </fo:flow>
    </fo:page-sequence>
  </fo:root>
</xsl:template>

<xsl:template match="chapter/title">
  <fo:block id="{generate-id(.)}">
    <xsl:number level="multiple" count="chapter" format="1. "/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="p">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="ref">
  <xsl:text>page </xsl:text>
  <fo:page-number-citation refid="{generate-id(id(@refid)/title)}"/>
</xsl:template>

</xsl:stylesheet>

Result Instance: elements and attributes in the fo: namespace

<fo:root>
  <fo:layout-master-set>
    <fo:simple-page-master master-name="page"
      page-height="297mm" page-width="210mm"
      margin-top="20mm" margin-bottom="10mm"
      margin-left="25mm" margin-right="25mm">
      <fo:region-body margin-top="0mm" margin-bottom="15mm"
        margin-left="0mm" margin-right="0mm"/>
      <fo:region-after extent="10mm"/>
    </fo:simple-page-master>
  </fo:layout-master-set>
  <fo:page-sequence master-name="page">
    <fo:static-content flow-name="xsl-region-after">
      <fo:block>Page <fo:page-number/>
      </fo:block>
    </fo:static-content>
    <fo:flow flow-name="xsl-region-body">
      <fo:block id="N5">1. Chapter</fo:block>
      <fo:block>Text</fo:block>
      <fo:block id="N13">2. Chapter</fo:block>
      <fo:block>For a description of X see page <fo:page-number-citation refid="N5"/>
      </fo:block>
    </fo:flow>
  </fo:page-sequence>
</fo:root>

6.6.2 fo:bidi-override

• Common use:

  The fo:bidi-override formatting object is used when the Unicode-bidi algorithm fails. It forces a string of text to be written in a specific direction.

• Area type:

  The fo:bidi-override formatting object produces an inline-area.

• Area size:

  The size of the area is determined in the same manner as all other inline-areas.

• Determination of trait values:

  The "direction" property is combined with the "writing-mode" to determine the new writing-direction.

• Content:

  (#PCDATA|%inline;)*
  

• Properties:

  • [7.19.3 "color"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.19.4 "direction"]
  • [7.19.5 "unicode-bidi"]
  • [7.19.19 "id"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.31 "score-spaces"]
  • [7.13.6 "text-decoration"]
  • [7.13.7 "text-shadow"]
  • [7.13.8 "text-transform"]
  • [7.19.5 "unicode-bidi"]
  • [7.13.3 "word-spacing"]

6.6.3 fo:character

• Common use:

  The fo:character flow object represents a character that is mapped to a glyph for presentation. It is an atomic unit to the formatter.

  When the result tree is interpreted as a tree of formatting objects, a character in the result tree is treated as if it were an empty element of type fo:character with a character attribute equal to the Unicode representation of the character. The semantic of an "auto" value for character properties, which is typically their initial value, are based on the Unicode codepoint. Overrides may be specified in an implementation-specific manner.

  NOTE:

  In a stylesheet the explicit creation of an fo:character may be used to explicitly override the default mapping.

• Area type:

  The fo:character flow object results in a single inline area.

• Content distribution:

  The width and height of the area is determined by the font metrics for the glyph.

• Content:

  EMPTY
  

• Properties:

  • [7.13.4 "apply-word-spacing"]
  • [7.13.1 "character"]
  • [7.19.3 "color"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.8 "font-height-override-after"]
  • [7.19.9 "font-height-override-before"]
  • [7.19.6 "glyph-orientation-horizontal"]
  • [7.19.7 "glyph-orientation-vertical"]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.31 "score-spaces"]
  • [7.13.5 "suppress-at-eol"]
  • [7.13.6 "text-decoration"]
  • [7.13.7 "text-shadow"]
  • [7.13.8 "text-transform"]
  • [7.19.37 "vertical-align"]
  • [7.13.3 "word-spacing"]

6.6.4 fo:initial-property-set

• Common use:

  The fo:initial-property-set specifies formatting properties for the first line of an fo:block.

  NOTE:

  It is analogous to the CSS first-line pseudo-element.

  In future verions of this recommendation a property controlling the number of lines, or the "depth" that these initial properties apply to may be added.

• Area type:

  The fo:initial-property-set object does not directly produce any area.

• Determination of trait values:

  The properties specified on the fo:initial-property-set are taken into account as if the inline formatting objects, or parts of them in the case of a line break, that were used in formatting the first line were enclosed by and fo:inline-sequence, as a direct child of the fo:block, with those properties specified.

• Content:

  EMPTY
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.3 "color"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.19.19 "id"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.31 "score-spaces"]
  • [7.13.6 "text-decoration"]
  • [7.13.7 "text-shadow"]
  • [7.13.8 "text-transform"]
  • [7.13.3 "word-spacing"]

6.6.5 fo:external-graphic

Issue (scaling-properties-for-graphics):

For scaling we want:

- scale factor for x and y

- individual for x and y

- max-width and height

- min-width and height

- height and width

Use cases:

- intrinsic size of graphic: just get it as is

- scale by a specified factor

- scale to a specified size

- put constraints on the scaling to be between

- Note fallback for graphics formats that do not have an intrinsic size.

- For the case of fixing the height of a graphic and caption and aligning the in x and y: use the fo:block-container.

CSS questions: is the graphic rescaled when its intrinsic height differs from the height property (and the height property is not "auto")

• Common use:

  The fo:external-graphic flow object is used for an inline graphic where the graphics data resides outside of the fo:element tree.

• Area type:

  The fo:external-graphic flow object results in a single inline-area.

• Content distribution:

  In the simple case, the "height" and "width" properties are used to set this object's size. If they are not specified, the "min-height" or "max-height" and "min-width" or "max-width" properties and the "scale-graphic" property (combined with any size specified by the content) are used to derive a size between the limits specified.

• Content and its placement:

  The fo:external-graphic flow object has no children.

• Content:

  EMPTY
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.13 "block-progression-dimension"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.10 "height"]
  • [7.19.16 "href"]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.19.42 "inline-progression-dimension"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.15 "maximum-block-progression-dimension"]
  • [7.19.44 "maximum-inline-progression-dimension"]
  • [7.19.12 "max-height"]
  • [7.19.41 "max-width"]
  • [7.19.14 "minimum-block-progression-dimension"]
  • [7.19.43 "minimum-inline-progression-dimension"]
  • [7.19.11 "min-height"]
  • [7.19.40 "min-width"]
  • [7.19.30 "scale"]
  • [7.19.37 "vertical-align"]
  • [7.19.39 "width"]

6.6.6 fo:instream-graphic

Issue (render-processor):

How to "call" or indicate appropriate processor for rendering? Should it be: a special property or making use of mime-type machinery?

• Common use:

  The fo:instream-graphic flow object is used for an inline graphic where the graphics data resides as descendants of the fo:instream-graphic; typically as an XML element subtree in a non-XSL namespace.

  NOTE:

  A common format is SVG.

• Area type:

  The fo:instream-graphic flow object results in a single inline-area.

• Content distribution:

  In the simple case, the "height" and "width" properties are used to set this object's size. If they are not specified, the "min-height" or "max-height" and "min-width" or "max-width" properties and the "scale-graphic" property (combined with any size specified by the content) are used to derive a size between the limits specified.

• Content:

  The fo:instream-graphic flow object has children from a non-XSL namespace. The permitted structure of these children is that defined for that namespace.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.13 "block-progression-dimension"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.10 "height"]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.19.42 "inline-progression-dimension"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.15 "maximum-block-progression-dimension"]
  • [7.19.44 "maximum-inline-progression-dimension"]
  • [7.19.12 "max-height"]
  • [7.19.41 "max-width"]
  • [7.19.14 "minimum-block-progression-dimension"]
  • [7.19.43 "minimum-inline-progression-dimension"]
  • [7.19.11 "min-height"]
  • [7.19.40 "min-width"]
  • [7.19.30 "scale"]
  • [7.19.37 "vertical-align"]
  • [7.19.39 "width"]

6.6.7 fo:inline

• Common Usage:

  The fo:inline formatting object is commonly used for formatting a portion of text with a background or enclosing it in a border.

• Areas:

  Each fo:inline formatting object returns a sequence of one or more areas, including at least one normal area. Each of the normal areas returned by an fo:inline formatting object F is an inline area and is generated by F.

• Constraints:

  The children of each normal area returned by an fo:block formatting object must be properly stacked.

  No area may have more than one normal child area returned by the same fo:inline formatting object.

  Issue (line-fragment-text):

  The common text, to be written, on constraints on line fragments needs to be referenced here. This also includes adding hyphens at the end of a line, removing areas at the line break etc.

• Contents:

  (#PCDATA|%inline;)*
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.2 "baseline-shift"]
  • [7.19.3 "color"]
  • [7.19.19 "id"]
  • [7.15.2 "keep"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.38 "visibility"]
  • [7.19.52 "z-index"]

6.6.8 fo:inline-container

• Common use:

  The fo:inline-container flow object is used to generate an inline reference-area; typically containing text blocks with a different writing-mode.

  NOTE:

  The use of this flow object is not required for bidirectional text; in this case the Unicode bidi algorithm and the fo:bidi-override are sufficient.

• Area type:

  The fo:inline-container flow object results in an inline-area. If the inline-area will not fit in the remaining space in the containing area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the properties of the content of this flow object. The area is a reference-area.

• Content distribution:

  The size of the reference-area has to be fixed in the inline-progression-direction; it must be specified.

  The size in the block-progression-direction is determined by the content of this flow object.

• Content:

  (%block;)+
  

• Properties:

  • [7.19.13 "block-progression-dimension"]
  • [7.19.1 "clip"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.10 "height"]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.19.42 "inline-progression-dimension"]
  • [7.15.2 "keep"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.25 "overflow"]
  • [7.19.29 "reference-orientation"]
  • [7.19.37 "vertical-align"]
  • [7.19.39 "width"]
  • [7.19.51 "writing-mode"]

6.6.9 fo:leader

• Common use:

  The fo:leader formatting object is often used:

  • in TOCs to generate sequences of "." glyphs that separate titles from page numbers

  • to create entry fields in fill-in-the-blank forms

  • to create horizontal rules for use as separators

• Area type:

  The fo:leader formatting object results in a single inline-area.

• Content distribution:

  A leader is atomic and may not break/wrap across multiple lines.

  The height of the content-rectangle is the "line-height", determined in the usual manner for inline-areas.

  The width of the leader is determined as described in the "leader-length" property.

  If the leader's minimum length is too long to place in the current line, the leader will begin a new line. If it is too long to be placed in a line by itself, it will overflow the line and potentially overflow the reference-area in accordance with that container's "overflow" property.

• Content and its placement:

  The fo:leader formatting object can have any inline formatting objects or PCDATA as its children, except that fo:leaders may not be nested. Its children are ignored unless the value of the "leader-pattern" property is "use-content".

  NOTE:

  If the "leader-pattern" property is "use-content" and the fo:leader has no children, the leader shall be filled with blank space.

  The inline-area generated by the fo:leader has a dimension in the inline-progression-direction which shall be at least the "leader-length.minimum" and at most the "leader-length.maximum".

  For lines-areas that have been specified to be justified, the justified line-area must honor the "leader-alignment" property of any inline-areas generated by fo:leaders.

  If the value of the "leader-pattern" property is "dots" or "use-content", the following constraints apply:

  • The inline-area generated by the fo:leader has as its children the areas returned by children of the fo:leader, or obtained by formatting the pattern specified in the "leader-pattern" property, repeated an integral number of times. If the width of even a single repetition is larger than the dimension of the inline-area in the inline-progression-direction, the inline-area shall be filled with blank space. The space-start and space-end of the child areas is set to account for the constraints specified in the "leader-pattern-width" and "leader-alignment" properties.

  • The "leader-pattern-width" property is ignored if its value is less than the width obtained by formatting the specified leader pattern.

• Content:

  (#PCDATA|%inline;)*
  

  The content must not contain an fo:leader, or fo:inline-container, either as a direct child or as a descendant.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.2 "baseline-shift"]
  • [7.19.3 "color"]
  • [7.19.8 "font-height-override-after"]
  • [7.19.9 "font-height-override-before"]
  • [7.19.19 "id"]
  • [7.14.1 "leader-alignment"]
  • [7.14.4 "leader-length"]
  • [7.14.2 "leader-pattern"]
  • [7.14.3 "leader-pattern-width"]
  • [7.14.5 "rule-style"]
  • [7.14.6 "rule-thickness"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.13.7 "text-shadow"]
  • [7.19.38 "visibility"]
  • [7.13.3 "word-spacing"]
  • [7.19.52 "z-index"]

NOTE:

If it is desired that the leader should stretch to fill all available space on a line, the maximum length of the leader should be specified to be at least as large as the column width.

NOTE:

The alignment of the leader may be script specific and may require indicating what aligment point is required, because it is different from the default alignment for the script. For example, in some usage of Indic scripts the leader is aligned at the baseline.

NOTE:

An fo:leader can be wrapped in an fo:block to create a rule for separating or decorating block-areas.

6.6.10 fo:page-number

• Common use:

  The fo:page-number flow object is used to obtain an inline-area whose content is the page number for the page on which the inline-area is placed.

• Area type:

  The fo:page-number flow object results in a single inline-area.

  The content of this inline-area is the same as the result of formatting a result-tree fragment consisting of fo:character flow objects; one for each character in the page number string.

  The page number string is obtained by converting the page number on which the inline-area is placed in accordance with the number to string conversion properties specified on the page master used for instantiating the page.

• Content distribution:

  Height and width are determined in the usual manner for inline-areas.

• Content:

  EMPTY
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.31 "score-spaces"]
  • [7.13.6 "text-decoration"]
  • [7.13.7 "text-shadow"]
  • [7.13.8 "text-transform"]
  • [7.19.37 "vertical-align"]
  • [7.13.3 "word-spacing"]

6.6.11 fo:page-number-citation

• Common use:

  The fo:page-number-citation is used to reference the page-number for the page containing the cited formatting object.

  NOTE:

  It may be used to provide the page numbers in the table of contents, cross-references, and index entries.

• Area type:

  The fo:page-number-citation flow object results in an inline-area in a manner analogous to that of the fo:page-number flow object.

• Content distribution:

  Height and width are determined in the usual manner for inline-areas.

• Determination of trait values:

  The "ref-id" property is used to locate the item being referenced. The page-number of the page containing the first area resulting from this item is then acquired as an unstyled text string and the character-level properties are applied to that string in the same manner as for fo:inline.

• Content:

  EMPTY
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.28 "ref-id"]
  • [7.19.31 "score-spaces"]
  • [7.13.6 "text-decoration"]
  • [7.13.7 "text-shadow"]
  • [7.13.8 "text-transform"]
  • [7.19.37 "vertical-align"]
  • [7.13.3 "word-spacing"]

6.7 Formatting Objects for Tables

6.7.1 Introduction

There are nine formatting objects used to construct tables: fo:table-and-caption, fo:table, fo:table-column, fo:table-caption, fo:table-header, fo:table-footer, fo:table-body, fo:table-row, and fo:table-cell. The result tree structure is shown below.

6.7.1.1 Examples

TBD

6.7.2 fo:table-and-caption

NOTE:

This formatting object corresponds to the CSS anonymous box that encloses the table caption and the table.

• Common use:

  The fo:table-and-caption flow object is used for formatting a table together with its caption.

  NOTE:

  A fo:table-and-caption may be placed inline by enclosing it in an fo:inline-container.

• Area type:

  The fo:table-and-caption flow object results in a block-area. If the block-area will not fit in the remaining space in the containing area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the properties of the content, to accommodate the content.

• Content distribution:

  The width of the content-rectangle of the resulting block-area is the width of the content-rectangle of the containing reference-area less than the "start-indent" and "end-indent".

  The height is determined by the height of the content.

• Content and its placement:

  The content of the table-and-caption flow object is one or two areas, acting as reference-areas; one for the table caption and one for the table itself. These are positioned relative to each other as specified by the "caption-side" property. They are placed relative to the content-rectangle as specified by the "text-align" property.

• Content:

  (table-caption?,table)
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.12.3 "caption-side"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.19 "id"]
  • [7.15.2 "keep"]

6.7.3 fo:table

• Common use:

  The fo:table flow object is used for formatting the tabular material of a table.

  The fo:table flow object and its child flow objects model the visual layout of a table in a "row primary" manner. A complete table may be seen as consisting of a grid of rows and columns where each cell occupies one or more grid units in the row-progression-direction and column-progression-direction.

  The table content is divided into a header (optional), footer (optional), and one or more bodies. Properties specify if the headers and footers should be repeated at a break in the table. Each of these parts occupies of one or more rows in the table grid.

• Area type:

  The fo:table flow object results in a block-area. If the block-area will not fit in the remaining space in the containing area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the properties of the rows, cells, and their content.

• Content distribution:

  The width of the content-rectangle of the table is the sum of the widths of the columns in the table grid. The method used to determine these widths is specified by the "table-layout" property.

  Issue (auto-in-tables):

  The CSS2 specification states that a table-width of "auto" should be interpreted as table-layout="auto". It does not say how the width="auto" on a table-column or table-cell should be treated. Some outstanding issues still being investigated.

  The method for determining the height of the table is governed by the "height" property.

  NOTE:

  The CSS2 specification explicitly does not specify what the behavior should be if there is a mismatch between an explicitly specified table height and the height of the content.

• Determination of trait values:

  The column-progression-direction and row-progression-direction are governed by the "writing-mode" property.

  The method for deriving the border trait for a table is specified by the "border-collapse" property.

  If the value of the "border-collapse" property is "separate" the border is composed of two components. The first, which is placed with the inside edge coincident with the outermost table grid boundary line, has the width of half the value for the "border-spacing" property. It is filled in accordance with the "background" property of the fo:table. Outside the outermost table grid boundary line is placed, for each side of the table, a border based on a border specified on the table.

  If the value of the "border-collapse" property is "collapse" the border is determined, for each segment, at the cell level.

  NOTE:

  By specifying an appropriately high priority on the border specification for the fo:table one may ensure that this specification is the one used on all border segments.

  The background color of a cell is determined in accordance with 17.5.1 of the CSS2 specification.

• Content:

  (table-column*,table-header?,table-footer?,table-body+)
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.13 "block-progression-dimension"]
  • [7.12.1 "border-collapse"]
  • [7.12.2 "border-spacing"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.8 Common Keeps and Breaks Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.19 "id"]
  • [7.19.42 "inline-progression-dimension"]
  • [7.19.10 "height"]
  • [7.15.2 "keep"]
  • [7.12.7 "table-layout"]
  • [7.12.9 "table-omit-footer-at-break"]
  • [7.12.8 "table-omit-header-at-break"]
  • [7.19.39 "width"]

6.7.4 fo:table-column

• Common use:

  The fo:table-column formatting object specifies characteristics applicable to table cells that have the same column and span. The most important property is the "column-width" property.

• Type of Area:

  This formatting object does not directly generate any area.

• Content:

  EMPTY
  

• Properties:

  • [7.12.4 "column-number"]
  • [7.12.5 "column-width"]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.19.19 "id"]
  • [7.12.12 "number-columns-repeated"]
  • [7.12.10 "number-columns-spanned"]
  • [7.19.38 "visibility"]

6.7.5 fo:table-caption

• Common use:

  The fo:table-caption formatting object is used to contain block-level formatting objects containing the caption for the table.

• Type of Area:

  The fo:table-caption generates a reference-area.

• Content Distribution and Size:

  For the case when the value of the "caption-side" property is "before" or "after" the width of the reference-area is equal to the width of the content-rectangle of the reference-area that encloses it.

  When the value is "start" or "end" the width of the reference-area is given by the "caption-width" property.

• Content:

  (%block;)+
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.13 "block-progression-dimension"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.19.10 "height"]
  • [7.19.19 "id"]
  • [7.19.42 "inline-progression-dimension"]
  • [7.15.2 "keep"]
  • [7.19.39 "width"]

6.7.6 fo:table-header

• Common use:

  The fo:table-header formatting object is used to contain the content of the table header.

• Type of Area:

  This formatting object does not directly create any area.

• Content:

  (table-row+|table-cell+)
  

  The fo:table-header has fo:table-row (one or more) as its children, or alternatively fo:table-cell (one or more). In the latter case cells are grouped into rows using the starts-row and ends-row properties.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.19.19 "id"]

6.7.7 fo:table-footer

• Common use:

  The fo:table-footer formatting object is used to contain the content of the table footer.

• Type of Area:

  This formatting object does not directly create any area.

• Content:

  (table-row+|table-cell+)
  

  The fo:table-footer has fo:table-row (one or more) as its children, or alternatively fo:table-cell (one or more). In the latter case cells are grouped into rows using the starts-row and ends-row properties.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.19.19 "id"]

6.7.8 fo:table-body

• Common use:

  The fo:table-body formatting object is used to contain the content of the table body.

• Type of Area:

  This formatting object does not directly create any area.

• Content:

  (table-row+|table-cell+)
  

  The fo:table-body has fo:table-row (one or more) as its children, or alternatively fo:table-cell (one or more). In the latter case cells are grouped into rows using the starts-row and ends-row properties.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.19.19 "id"]

6.7.9 fo:table-row

• Common use:

  The fo:table-row formatting object is used to group table-cells into rows; all table-cells in a table-row start in the same geometric row on the table grid.

• Type of Area:

  This formatting object does not directly create any area.

• Content Distribution and Size:

  The method for determining the height of the row in the grid is governed by the "row-height" property.

• Content:

  (table-cell+)
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.13 "block-progression-dimension"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.19.19 "id"]
  • [7.12.13 "may-break-after-row"]
  • [7.12.14 "may-break-before-row"]
  • [7.19.10 "height"]
  • [7.15.2 "keep"]

6.7.10 fo:table-cell

• Common use:

  The fo:table-cell formatting object is used to group content to be placed in a table-cell.

• Type of Area:

  A table-cell occupies one or more grid units in the row-progression-direction and column-progression-direction and acts as a reference-area. The content-rectangle of the cell is the size of the portion of the grid the cell occupies minus, for each of the four sides:

  • If the value of the "border-collapse" property is "separate": half the value of the "border-spacing" property; otherwise 0.

  • If the value of the "border-collapse" property is "separate": the thickness of the cell-border; otherwise half the thickness of the effective border.

  • The cell padding.

• Content Distribution and Size:

  The method for determining the height of the cell in the grid is governed by the "row-height" property.

• Determination of Trait Values:

  • background: in accordance with the CSS2 inheritance rules specified in 17.5.1.

    NOTE:

    A cell that is spanned may have a different background in each of the grid units it occupies.

  • border: the method for deriving the border for a cell is specified by the "border-collapse" property.

    If the value of the "border-collapse" property is "separate" the border is composed of two components. The first, which is placed with the outside edge coincident with the table grid boundary line, has the width of half the value for the "border-spacing" property. It is filled in accordance with the "background" property of the fo:table. Inside this border is placed, for each side of the cell, a border based on a border specified on the cell or inherited.

    If the value of the "border-collapse" property is "collapse" the border for each side of the cell is determined by, for each segment of a border, selecting, from all border specifications for that segment, the border that has the highest priority. It is an error if there are two such borders that have the same priority but are not identical. Each border segment is placed centered on the table grid boundary line.

  • padding: the value for the table-cell; either specified or inherited.

• Content:

  (%block;)+
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.13 "block-progression-dimension"]
  • [7.12.4 "column-number"]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.12.6 "empty-cells"]
  • [7.12.15 "ends-row"]
  • [7.19.10 "height"]
  • [7.19.19 "id"]
  • [7.12.10 "number-columns-spanned"]
  • [7.12.11 "number-rows-spanned"]
  • [7.12.16 "starts-row"]

6.8 Formatting Objects for Lists

6.8.1 Introduction

There are four formatting objects used to construct lists: fo:list-block, fo:list-item, fo:list-item-label, and fo:list-item-body.

The fo:list-block has the role of containing the complete list and to specify values used for the list geometry in the inline-progression-direction (see details below).

The children of the fo:list-block are one or more fo:list-item, each containing a pair of fo:list-item-label and fo:list-item-body.

The fo:list-item has the role of containing each item in a list.

The fo:list-item-label has the role of containing the content, block-level formatting objects, of the label for the list-item; typically an fo:block containing a number, a ding-bat character, or a term.

The fo:list-item-body has the role of containing the content, block-level formatting objects, of the body of the list-item; typically one or more fo:block.

The placement, in the block-progression-direction, of the label with respect to the body is made in accordance with the "vertical-align" property of the fo:list-item.

The specification of the list geometry in the inline-progression-direction is achieved by:

• Specifying appropiate values of the "provisional-distance-between-starts" and "provisional-label-separation" properties. The "provisional-distance-between-starts" specifies the desired distance between the start-indents of the label and the body of the list item. The "provisional-label-separation" specifies the desired separation between the end-indent of the label and the start-indent of the body of the list item.

• Specifying end-indent="label-end()" on the fo:list-item-label.

  Specifying start-indent="body-start()" on the fo:list-item-body.

  NOTE:

  These list specific functions are defined below.

The start-indent of the list item label and end-indent of the list item body, if desired, are typically specified as a length.

6.8.1.1 Examples

6.8.1.1.1 Numbered List

The list-items are contained in an "ol" element. The items are contained in "item" elements and contain text (as opposed to paragraphs).

The style is to number the items alphabetically with a dot at the end of the number.

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="ol">
  <fo:list-block provisional-distance-between-starts="15mm"
   provisional-label-separation="5mm" space-between-list-rows="3mm">
    <xsl:apply-templates/>
  </fo:list-block>
</xsl:template>

<xsl:template match="ol/item">
  <fo:list-item>
    <fo:list-item-label start-indent="5mm" end-indent="label-end()">
      <fo:block>
        <xsl:number format="a."/>
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>
        <xsl:apply-templates/>
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
</xsl:template>

</xsl:stylesheet>

Input sample:

<ol>
<item>List item 1.</item>
<item>List item 2.</item>
<item>List item 3.</item>
</ol>

Result Instance: elements and attributes in the fo: namespace

<fo:list-block provisional-distance-between-starts="15mm"
  provisional-label-separation="5mm" space-between-list-rows="3mm">

  <fo:list-item>
    <fo:list-item-label start-indent="5mm" end-indent="label-end()">
      <fo:block>a.
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>List item 1.
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>

  <fo:list-item>
    <fo:list-item-label start-indent="5mm" end-indent="label-end()">
      <fo:block>b.
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>List item 2.
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>

  <fo:list-item>
    <fo:list-item-label start-indent="5mm" end-indent="label-end()">
      <fo:block>c.
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>List item 3.
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>

</fo:list-block>

6.8.1.1.2 HTML-style "dl" lists

In this example the stylesheet processes HTML-style "dl" lists, which contain unwrapped pairs of "dt" and "dd" elements, transforming them into fo:list-blocks.

Balanced pairs of "dt"/"dd"s are converted into fo:list-items. For unbalanced "dt"/"dd"s, the stylesheet makes the following assumptions:

• Multiple "dt"s are grouped together into a single fo:list-item-label in a single list-item.

• Multiple DDs are:

  • Output as individual FO list-items with an empty list-item-label if the stylesheet variable $allow-naked-dd is true.

  • Are grouped together into a single FO list-item-body if $allow-naked-dd is false.

In other words, given a structure like this:

<doc>
<dl>
  <dt>term</dt>
  <dd>definition</dd>
  <dt>term</dt>
  <dt>term</dt>
  <dd>definition</dd>
  <dt>term</dt>
  <dd>definition</dd>
  <dd>definition</dd>
</dl>
</doc>

If $allow-naked-dd is true, the result instance: elements and attributes in the fo: namespace is:

<fo:list-block provisional-distance-between-starts="35mm"
  provisional-label-separation="5mm" space-between-list-rows="3mm">
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
      <fo:block>term
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
      <fo:block>term
      </fo:block>
      <fo:block>term
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
      <fo:block>term
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
</fo:list-block>

If $allow-naked-dd is false, the result instance: elements and attributes in the fo: namespace is:

<fo:list-block provisional-distance-between-starts="35mm"
  provisional-label-separation="5mm" space-between-list-rows="3mm">
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
      <fo:block>term
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
      <fo:block>term
      </fo:block>
      <fo:block>term
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
  <fo:list-item>
    <fo:list-item-label end-indent="label-end()">
      <fo:block>term
      </fo:block>
    </fo:list-item-label>
    <fo:list-item-body start-indent="body-start()">
      <fo:block>definition
      </fo:block>
      <fo:block>definition
      </fo:block>
    </fo:list-item-body>
  </fo:list-item>
</fo:list-block>

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:include href="dtdd.xsl"/>

<xsl:template match="doc">
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="dl">
  <xsl:call-template name="process.dl"/>
</xsl:template>

<xsl:template match="dt|dd">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

</xsl:stylesheet>

Included stylesheet "dtdd.xsl"

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:variable name="allow-naked-dd" select="true()"/>

<xsl:template name="process.dl">
  <fo:list-block provisional-distance-between-starts="35mm"
   provisional-label-separation="5mm" space-between-list-rows="3mm">
    <xsl:choose>
      <xsl:when test="$allow-naked-dd">
        <xsl:call-template name="process.dl.content.with.naked.dd"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:call-template name="process.dl.content"/>
      </xsl:otherwise>
    </xsl:choose>
  </fo:list-block>
</xsl:template>

<xsl:template name="process.dl.content.with.naked.dd">
  <xsl:param name="dts" select="./force-list-to-be-empty"/>
  <xsl:param name="nodes" select="*"/>

  <xsl:choose>
    <xsl:when test="count($nodes)=0">
      <!-- Out of nodes, output any pending DTs -->
      <xsl:if test="count($dts)>0">
        <fo:list-item>
          <fo:list-item-label end-indent="label-end()">
            <xsl:apply-templates select="$dts"/>
          </fo:list-item-label>
          <fo:list-item-body start-indent="body-start()"/>
        </fo:list-item>
      </xsl:if>
    </xsl:when>

    <xsl:when test="name($nodes[1])='dd'">
      <!-- We found a DD, output the DTs and the DD -->
      <fo:list-item>
        <fo:list-item-label end-indent="label-end()">
          <xsl:apply-templates select="$dts"/>
        </fo:list-item-label>
        <fo:list-item-body start-indent="body-start()">
          <xsl:apply-templates select="$nodes[1]"/>
        </fo:list-item-body>
      </fo:list-item>
      <xsl:call-template name="process.dl.content.with.naked.dd">
        <xsl:with-param name="nodes" select="$nodes[position()>1]"/>
      </xsl:call-template>
    </xsl:when>

    <xsl:when test="name($nodes[1])='dt'">
      <!-- We found a DT, add it to the list of DTs and loop -->
      <xsl:call-template name="process.dl.content.with.naked.dd">
        <xsl:with-param name="dts" select="$dts|$nodes[1]"/>
        <xsl:with-param name="nodes" select="$nodes[position()>1]"/>
      </xsl:call-template>
    </xsl:when>

    <xsl:otherwise>
      <!-- This shouldn't happen -->
      <xsl:message>
        <xsl:text>DT/DD list contained something bogus (</xsl:text>
        <xsl:value-of select="name($nodes[1])"/>
        <xsl:text>).</xsl:text>
      </xsl:message>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

<xsl:template name="process.dl.content">
  <xsl:param name="dts" select="./force-list-to-be-empty"/>
  <xsl:param name="dds" select="./force-list-to-be-empty"/>
  <xsl:param name="output-on"></xsl:param>
  <xsl:param name="nodes" select="*"/>

  <!-- The algorithm here is to build up a list of DTs and DDs, -->
  <!-- outputing them only on the transition from DD back to DT -->

  <xsl:choose>
    <xsl:when test="count($nodes)=0">
      <!-- Out of nodes, output any pending elements -->
      <xsl:if test="count($dts)>0 or count($dds)>0">
        <fo:list-item>
          <fo:list-item-label end-indent="label-end()">
            <xsl:apply-templates select="$dts"/>
          </fo:list-item-label>
          <fo:list-item-body start-indent="body-start()">
            <xsl:apply-templates select="$dds"/>
          </fo:list-item-body>
        </fo:list-item>
      </xsl:if>
    </xsl:when>

    <xsl:when test="name($nodes[1])=$output-on">
      <!-- We're making the transition from DD back to DT -->
      <fo:list-item>
        <fo:list-item-label end-indent="label-end()">
          <xsl:apply-templates select="$dts"/>
        </fo:list-item-label>
        <fo:list-item-body start-indent="body-start()">
          <xsl:apply-templates select="$dds"/>
        </fo:list-item-body>
      </fo:list-item>

      <!-- Reprocess this node (and the rest of the node list) -->
      <!-- resetting the output-on state to nil -->
      <xsl:call-template name="process.dl.content">
        <xsl:with-param name="nodes" select="$nodes"/>
      </xsl:call-template>
    </xsl:when>

    <xsl:when test="name($nodes[1])='dt'">
      <!-- We found a DT, add it to the list and loop -->
      <xsl:call-template name="process.dl.content">
        <xsl:with-param name="dts" select="$dts|$nodes[1]"/>
        <xsl:with-param name="dds" select="$dds"/>
        <xsl:with-param name="nodes" select="$nodes[position()>1]"/>
      </xsl:call-template>
    </xsl:when>

    <xsl:when test="name($nodes[1])='dd'">
      <!-- We found a DD, add it to the list and loop, noting that -->
      <!-- the next time we cross back to DT's, we need to output the -->
      <!-- current DT/DDs. -->
      <xsl:call-template name="process.dl.content">
        <xsl:with-param name="dts" select="$dts"/>
        <xsl:with-param name="dds" select="$dds|$nodes[1]"/>
        <xsl:with-param name="output-on">dt</xsl:with-param>
        <xsl:with-param name="nodes" select="$nodes[position()>1]"/>
      </xsl:call-template>
    </xsl:when>

    <xsl:otherwise>
      <!-- This shouldn't happen -->
      <xsl:message>
        <xsl:text>DT/DD list contained something bogus (</xsl:text>
        <xsl:value-of select="name($nodes[1])"/>
        <xsl:text>).</xsl:text>
      </xsl:message>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

</xsl:stylesheet>

The "dtdd.xsl" stylesheet may be customized in the following ways:

• Set the value of $allow-naked-dd to control the processing of unbalanced "dd"s.

• Change "dt" to the name of the element which is a term in the list.

• Change "dd" to the name of the element which is a definition in the list.

• In the, perhaps unlikely, event that the documents may contain an element named "force-list-to-be-empty", that element name should be changed to a name that is not used in the documents.

In the stylesheet using the "dtdd.xsl" stylesheet change the "dl" to the name of the element which is the wrapper for the list.

6.8.2 fo:list-block

• Common use:

  The fo:list-block flow object is used to format a list item or a list.

• Type of Area:

  The fo:list-block flow object results in a block-area. If the block-area will not fit in the remaining space in the containing area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the content of the list-block.

• Content and its Placement:

  The list-block must have one or more fo:list-item formatting objects as children.

  The areas produced by these are placed one after the other in the block-progression-direction.

• Content:

  (list-item+)
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.8 Common Keeps and Breaks Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.19 "id"]
  • [7.15.2 "keep"]
  • [7.19.27 "provisional-distance-between-starts"]
  • [7.19.26 "provisional-label-separation"]

6.8.3 fo:list-item

• Common use:

  The fo:list-item formatting object contains the label and the body of an item in a list.

• Type of Area:

  The fo:list-item flow object results in a block-area. If the block-area will not fit in the remaining space in the containing area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the content of the list-item.

• Content Distribution and Size:

  The width of the content-rectangle of the block-area is the width of the reference-area into which it is placed minus the start-indent and end-indent.

  The height is determined by the content of the fo:list-item.

• Content and its Placement:

  The placement of the areas produced by formatting the fo:list-item-label and fo:list-item-body objects are positioned with respect to each other in the following manner:

  • In the block-progression-direction these areas are positioned according to the "vertical-align" property.

  • In the inline-progression-direction these areas are positioned according to the start-indent and end-indent properties of the content of the fo:list-item-label and fo:list-item-body formatting objects. It is an error if the areas overlap.

    NOTE:

    These areas are not reference-areas, hence the indents on all objects within them are measured relative to the reference-area that holds the content of the fo:list-block.

• Content:

  (list-item-label,list-item-body)
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.8 Common Keeps and Breaks Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.19 "id"]
  • [7.15.2 "keep"]

6.8.4 fo:list-item-body

• Common use:

  The fo:list-item-body formatting object contains the content of the body of a list-item.

• Type of Area:

  The fo:list-item-body formatting object does not directly create any area.

• Content:

  (%block;)+
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.19 "id"]

6.8.5 fo:list-item-label

• Common use:

  The fo:list-item-label formatting object contains the content of the label of a list-item; typically used to either enumerate, identify or adorn the list-item's body.

• Type of Area:

  The fo:list-item-label formatting object does not directly create any area.

• Content:

  (%block;)+
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.19 "id"]

6.9 Link and Multi Formatting Objects

6.9.1 Introduction

The following classes of "dynamic" effects are covered by the formatting objects included in this section:

• One-directional single-target links.

• The ability to switch between the display of two or more formatting object subtrees. This can be used for, e.g., expandable/collapsible table of contents, display of an icon or a full table or graphic.

• The ability to switch between different property values, such as color or font-weight, depending on DOM state, such as "mouse-over".

The switching between subtrees is achieved by using the following three formatting objects: fo:multi-switch, fo:multi-case, and fo:multi-toggle. The result tree structure is shown below.

The role of the fo:multi-switch is to wrap fo:multi-case formatting objects, each containing a subtree. Each subtree is given a name on the fo:multi-case formatting object. Activating, for example implemented as clicking on, an fo:multi-toggle causes a named subtree, the previous, the next, or "any" subtree to be displayed; controlled by the "switch-to" property. For "any", an implementation would typically present a list of choices each labeled using the "case-title" property of the fo:multi-case. The initial subtree displayed is controlled by the "starting-state" property on the fo:multi-case.

6.9.1.1 Examples

6.9.1.1.1 Expandable/Collapsible Table of Contents

Input sample:

<doc>
  <chapter><title>Chapter</title>
    <p>Text</p>
    <section><title>Section</title>
    <p>Text</p>
    </section>
    <section><title>Section</title>
    <p>Text</p>
    </section>
  </chapter>
  <chapter><title>Chapter</title>
    <p>Text</p>
    <section><title>Section</title>
    <p>Text</p>
    </section>
    <section><title>Section</title>
    <p>Text</p>
    </section>
  </chapter>
</doc>

In this example the chapter and section titles are extracted into a table of contents placed at the front of the result. The chapter titles are preceeded by an icon indicating either collapsed or expanded state. The section titles are only shown in the expanded state. Furthermore,there are links from the titles in the table of contents to the corresponding titles in the body of the document.

The two states are achieved by, for each chapter title, using an fo:multi-switch with a fo:multi-case for each state. The icon is contained in an fo:multi-toggle with the appropriate fo:multi-case "switch-to" property to select the other state.

The links in the table of contents are achieved by adding a unique id on the title text in the body of the document and wrapping the title text in the table of contents in an fo:simple-link referring to that id.

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="doc">
  <!-- create the table of contents -->
  <xsl:apply-templates select="chapter/title" mode="toc"/>
  <!-- do the document -->
  <xsl:apply-templates/>
</xsl:template>

<xsl:template match="chapter/title" mode="toc">
  <fo:multi-switch>
    <fo:multi-case case-name="collapsed" case-title="collapsed"
    starting-state="show">
      <fo:block>
        <fo:multi-toggle switch-to="expanded">
          <fo:external-graphic href="plus-icon.gif"/>
        </fo:multi-toggle>
        <fo:simple-link internal-destination="{generate-id(.)}">
          <xsl:number level="multiple" count="chapter" format="1. "/>
          <xsl:apply-templates mode="toc"/>
        </fo:simple-link>
      </fo:block>
    </fo:multi-case>
    <fo:multi-case case-name="expanded" case-title="expanded"
    starting-state="hide">
      <fo:block>
        <fo:multi-toggle switch-to="collapsed">
          <fo:external-graphic href="minus-icon.gif"/>
        </fo:multi-toggle>
        <fo:simple-link internal-destination="{generate-id(.)}">
          <xsl:number level="multiple" count="chapter" format="1. "/>
          <xsl:apply-templates mode="toc"/>
        </fo:simple-link>
      </fo:block>
      <xsl:apply-templates select="../section/title" mode="toc"/>
    </fo:multi-case>
  </fo:multi-switch>
</xsl:template>

<xsl:template match="section/title" mode="toc">
  <fo:block start-indent="10mm">
    <fo:simple-link internal-destination="{generate-id(.)}">
      <xsl:number level="multiple" count="chapter|section" format="1.1 "/>
      <xsl:apply-templates/>
    </fo:simple-link>
  </fo:block>
</xsl:template>

<xsl:template match="chapter/title">
  <fo:block id="{generate-id(.)}">
    <xsl:number level="multiple" count="chapter" format="1. "/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="section/title">
  <fo:block id="{generate-id(.)}">
    <xsl:number level="multiple" count="chapter|section" format="1.1 "/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="p">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

</xsl:stylesheet>

Result Instance: elements and attributes in the fo: namespace

<fo:multi-switch>
  <fo:multi-case case-name="collapsed" case-title="collapsed" starting-state="show">
    <fo:block>
      <fo:multi-toggle switch-to="expanded">
        <fo:external-graphic href="plus-icon.gif">
        </fo:external-graphic>
      </fo:multi-toggle>
      <fo:simple-link internal-destination="N4">1. Chapter
      </fo:simple-link>
    </fo:block>
  </fo:multi-case>
  <fo:multi-case case-name="expanded" case-title="expanded" starting-state="hide">
    <fo:block>
      <fo:multi-toggle switch-to="collapsed">
        <fo:external-graphic href="minus-icon.gif">
        </fo:external-graphic>
      </fo:multi-toggle>
      <fo:simple-link internal-destination="N4">1. Chapter
      </fo:simple-link>
    </fo:block>
    <fo:block start-indent="10mm">
      <fo:simple-link internal-destination="N11">1.1 Section
      </fo:simple-link>
    </fo:block>
    <fo:block start-indent="10mm">
      <fo:simple-link internal-destination="N19">1.2 Section
      </fo:simple-link>
    </fo:block>
  </fo:multi-case>
</fo:multi-switch>
<fo:multi-switch>
  <fo:multi-case case-name="collapsed" case-title="collapsed" starting-state="show">
    <fo:block>
      <fo:multi-toggle switch-to="expanded">
        <fo:external-graphic href="plus-icon.gif">
        </fo:external-graphic>
      </fo:multi-toggle>
      <fo:simple-link internal-destination="N28">2. Chapter
      </fo:simple-link>
    </fo:block>
  </fo:multi-case>
  <fo:multi-case case-name="expanded" case-title="expanded" starting-state="hide">
    <fo:block>
      <fo:multi-toggle switch-to="collapsed">
        <fo:external-graphic href="minus-icon.gif">
        </fo:external-graphic>
      </fo:multi-toggle>
      <fo:simple-link internal-destination="N28">2. Chapter
      </fo:simple-link>
    </fo:block>
    <fo:block start-indent="10mm">
      <fo:simple-link internal-destination="N35">2.1 Section
      </fo:simple-link>
    </fo:block>
    <fo:block start-indent="10mm">
      <fo:simple-link internal-destination="N43">2.2 Section
      </fo:simple-link>
    </fo:block>
  </fo:multi-case>
</fo:multi-switch>

<fo:block id="N4">1. Chapter
</fo:block>
<fo:block>Text
</fo:block>
<fo:block id="N11">1.1 Section
</fo:block>
<fo:block>Text
</fo:block>
<fo:block id="N19">1.2 Section
</fo:block>
<fo:block>Text
</fo:block>
<fo:block id="N28">2. Chapter
</fo:block>
<fo:block>Text
</fo:block>
<fo:block id="N35">2.1 Section
</fo:block>
<fo:block>Text
</fo:block>
<fo:block id="N43">2.2 Section
</fo:block>
<fo:block>Text
</fo:block>

6.9.2 fo:simple-link

• Common use:

  The fo:simple-link is used for representing the start resource of a simple one-directional single-target link. The object allows for traversal to the destination resource, typically by clicking on any of the containing areas.

• Type of Area:

  The fo:simple-link flow object results in an inline-area. If the inline-area will not fit in the remaining space in the containing line-area, one (or more) additional areas may be generated by the formatter, consistent with the constraints given by the properties of the content, to accommodate the content.

  NOTE:

  An fo:simple-link may be displayed by enclosing it in an fo:block.

• Content Distribution and Size:

  The width is determined by the content. The height is determined by the height of the content.

  The content is formatted in the general manner of inlines.

• Content:

  (#PCDATA|%inline;|%block;)*
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.18.1 "external-destination"]
  • [7.19.19 "id"]
  • [7.18.4 "indicate-destination"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.18.2 "internal-destination"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.18.3 "show-destination"]
  • [7.18.5 "destination-placement-offset"]
  • [7.19.37 "vertical-align"]

6.9.3 fo:multi-switch

• Common use:

  The fo:multi-switch is used to switch between two or more sub-trees of formatting objects.

  The direct children of an fo:multi-switch object are fo:multi-case objects. Only a single fo:multi-case may be visible at a single time. The user may switch between the available multi-cases.

  Each fo:multi-case may contain one or more fo:multi-toggle objects, which controls the fo:multi-case switching of the fo:multi-switch.

  NOTE:

  An fo:multi-switch can be used for many interactive tasks, such as table-of-content views, embedding link targets, or generalized (even multi-layered hierarchical), next/previous views. The latter are today normally handled in HTML by next/previous links to other documents, forcing the whole document to be replaced whenever the users decides to move on.

  The fo:multi-switch shall initially display the first fo:multi-case child that has the property "starting-state" assigned to "show".

• Type of Area:

  The fo:multi-switch does not directly create any areas, but acts as an transparent container, and is (conceptually) replaced by the currently visible flow objects.

• Content:

  (multi-case+)
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.18.6 "auto-restore"]
  • [7.19.19 "id"]

6.9.4 fo:multi-case

• Common use:

  The fo:multi-case is used to embed flow objects, that the parent fo:multi-switch can choose to either show or hide.

• Type of Area:

  The fo:multi-case does not directly create any areas, but acts as a transparent container, and is (conceptually) replaced by the flow objects it contains.

• Content:

  (#PCDATA|%inline;|%block;)*
  

  The fo:multi-case may contain any formatting objects that are permitted as a replacement of the fo:multi-switch formatting object. In particular, it can contain fo:multi-toggle objects (at any depth), which controls the fo:multi-case switching.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.19 "id"]
  • [7.18.7 "starting-state"]
  • [7.18.8 "case-name"]
  • [7.18.9 "case-title"]

6.9.5 fo:multi-toggle

• Common use:

  The fo:multi-toggle is typically used to create an area that when "clicked," has the effect of switching from one fo:multi-case to another. The "switch-to" property value of the fo:multi-toggle typically matches the "case-name" property value of the fo:multi-case to switch to.

• Type of Area:

  The fo:multi-toggle results in the sequence of areas obtained by formatting the content of the fo:multi-toggle formatting object.

• Content:

  (#PCDATA|%inline;|%block;)*
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.19 "id"]
  • [7.18.10 "switch-to"]

6.9.6 fo:multi-properties

• Common use:

  The fo:multi-properties is used to switch between two or more property sets that are associated with a given portion of content. The direct children of an fo:multi-properties formatting object is an ordered set of fo:multi-property-set formatting objects followed by any character, inline, and block-level formatting objects. The specified properties of all fo:multi-property-set formatting objects for states that apply are merged. In this merger, properties specified in later fo:multi-property-set objects replace any values set in earlier fo:multi-property-set objects. This assembled set of property specifications are added to the inheritable properties for all the child formatting objects of the fo:multi-properties formatting object that are not of the class fo:multi-property-set. This has the same effect as if an fo:wrapper formatting object with the assembled set of property specifications had enclosed them. If no states apply, there is no change to the inheritable properties. The states on the fo:multi-property-set are the states (and events) that are identified by the DOM.

  NOTE:

  An fo:multi-properties formatting object can be used to give different appearances to a given portion of content. For example, when a link changes from the not-yet-visited state to the visited-state, this could change the set of properties that would be used to format the content. Designers should be careful in choosing which properties they change, because many property changes could cause reflowing of the text which may not be desired in many circumstances. Changing properties such as "color" or "text-decoration" should not require re-flowing the text.

• Type of Area:

  The fo:multi-properties does not directly result in any areas. Areas may be generated by formatting the content of the fo:multi-properties formatting object.

• Content:

  (multi-property-set+,wrapper)
  

  The properties that should take a merged value shall be specified with a value of "from-parent()". This function, when applied on an fo:wrapper that is a direct child of an fo:multi-properties, merges the applicable property definitions on the fo:multi-property-set siblings.

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.19 "id"]

6.9.7 fo:multi-property-set

• Common use:

  The fo:multi-property-set is used to specify an alternative set of formatting properties that can be used to provide an alternate presentation of the children flow objects of the parent of this fo:multi-property-set that are not of the fo:multi-property-set class.

• Type of Area:

  The fo:multi-property-set does not generate any area, but simply holds a set of properties.

• Content:

  EMPTY
  

• Properties:

  • [7.19.19 "id"]
  • [7.18.11 "dom-state"]

6.10 Out-of-Line Formatting Objects

Issue (out-of-line):

This section is incomplete and may be inconsistent with other sections of this draft.

6.10.1 Introduction

6.10.1.1 Conditional Regions

Conditional regions specify region-masters that are used to generate region reference-areas. These region reference-areas are called conditional reference-areas. Conditional reference-areas are generated only when one or more areas that would be descendant from these reference-areas are present on the page from which the conditional reference-area is descendant. The descendants of a conditional reference-area are out-of-line areas that are returned by formatting objects, such as footnotes and floats, which have children that generate areas that are not placed in the normal flow of areas.

Conditional regions are subdivisions of a region. They specify how space can be borrowed from that region either at the top or bottom of that region. The region from which the conditional region borrows space is called the containing region. When a region-master that contains conditional regions is used to generate a reference-area, some of the region reference-areas that correspond to the conditional regions may be generated as well.

Whether a conditional reference-area is generated depends on the presence of out-of-line areas that should be descendent from that conditional reference-area. If there are out-of-line areas, such as areas generated by an fo:footnote or fo:float, then the conditional reference-areas may be generated. Whether or not the conditional reference-areas are actually generated depends, additionally, on whether there is sufficient space left in the reference-area from which the space is being borrowed and whether constraints on the relationship between the placement of the out-of-line areas and the normal areas generated by the same formatting object are met. For example, a constraint on footnotes requires that the footnote begin on the same page as the reference to the footnote. In addition, constraints on other portions of the content on the page may produce an over-constrained situation; for example, if there is a long, unbreakable paragraph that contains the footnote reference and just fits on a page.

When one or more conditional reference-areas are generated, the parent reference-area must be subdivided. This subdivision gives meaning to the phrase, "a conditional region borrows space from the containing region". The subdivision preserves the original reference-area generated using the region-master. This original area is the parent area of the subdivision areas. Subdivision generates two or more reference-areas that are children of the original reference-area. All but one of these reference-areas are conditional reference-areas. These conditional reference-areas are aligned with the before-edge or after-edge, respectively of the content-rectangle of the parent reference-area.

The remaining reference-area corresponds to the remaining space after the borrowing done by the conditional regions. The traits of the remaining reference-area are set as they would be if the reference-area were generated by a region with no specified properties that was the child of the containing region. This insures that there is a transparent background and no margin, border, or padding; and that inherited properties are set as they would be when the region-master for the containing region is used to generate a reference-area. The block-progression-dimension (this is "height" when the writing-mode is "lr-tb") of the remaining reference-area is set equal to the block-progression-dimension of the parent reference-area minus the sum of the sizes in the block-progression-direction of the allocation-rectangles of the conditional reference-areas. The remaining reference-area is positioned to immediately follow the after edge of the allocation-rectangle of the last of the conditional reference-areas that are before the remaining reference-area. This positions the after-edge of the remaining reference-area to coincide with the before-edge of the allocation-rectangle of the first of the conditional reference-areas that are after the remaining reference-area. The areas that would have been children of the parent reference-area are made children of the remaining reference-area. In addition to the constraints normally determined by the original region, the inline-progression-dimension (this is "width" when the writing-mode is "lr-tb") of that region is constrained to match inline-progression-dimension of the remaining reference-area.

Issue (out-of-line-intro-space):

Should space-before and space-after be taken into account for the space consumed by the conditional regions. The allocation-rectangle size in the block-progression-direction does not include these.

There may be limits on how much space conditional regions can borrow from the containing region.

The association of out-of-line content (areas) with particular conditional regions (areas) is specified in the descriptions of the formatting objects that initially return the out-of-line content (areas).

6.10.1.2 Floats and Footnotes

The region-body region has an implicit conditional float region at the before-edge of the region and an implicit conditional footnote region at the after-edge of the region.

When an fo:footnote formatting object appears in a flow, it returns at least two kinds of areas. One kind of area is a normal inline-area to accommodate the footnote citation. This inline-area is generated in sequence with the areas generated by the flow objects preceding and following the fo:footnote formatting object. It is, therefore, assigned to the reference-area generated using the region-master associated with the flow in which the fo:footnote occurs.

The second kind of area that is returned by the fo:footnote formatting object is an out-of-line area. It becomes a descendant of the reference-area generated by the implicit conditional footnote region associated with the region to which the flow in which the fo:footnote occurs is assigned.

The conditional reference-area which has as its descendant the first (and usually only) out-of-line area returned by the fo:footnote is constrained to be a sibling of the reference-area which has as its descendant the first of normal areas returned by the fo:footnote. That is, the footnote must begin in the same instance of the containing region in which the footnote citation occurs.

NOTE:

The actual areas generated by the descendants of the fo:footnote formatting object are determined by the formatting objects that comprise the descendant subtree. For example, if one wanted to format the footnote with a label and an indented body, then one could use the fo:list-block formatting object to format the content of the footnote.

Issue (out-of-sequence-hot-links):

This text need to be adapted to allow an interactive user agent to create "hot links" to the footnotes from the footnote citation instead of realizing conditional regions. The same holds true below for floats, only floats would need a manufactured "citation" to make hot.

When an fo:float formatting object appears in a flow, it returns out-of-line areas. These areas become descendants of reference-areas generated by the implicit conditional float region associated with the region to which the flow in which the fo:float occurs is assigned.

Issue (out-of-sequence-intro-error):

Should it be an error if an fo:float occurs in a flow that is not assigned to a region that has an implicit conditional "float" region. If it is an error is there a reasonable fallback, say put the float inline at the point of occurrence. This issue also applies to footnotes. Note that this would consistent with the fallback listed in the conformance summary since footnotes and floats are not in the "basic" formatting object set.

The constraint on the areas returned by an fo:float is that they may only be descendant from conditional reference-areas that are (a) descendant from areas generated using the region-masters for the region to which the flow that has the fo:float as a descendant is assigned, and (b) are descendent from the same page as the page in which normal areas returned by the fo:float would be descendants, or descendant from a page following that page in the sequence of pages that are children of the area tree root.

NOTE:

Future versions of this specification will describe the above semantics as special cases of a more general mechanism that allows out-of-line areas to be assigned to conditional regions and the expression of constraints between the occurrences of normal areas and out-of-line areas.

6.10.1.3 Examples

TBD

6.10.2 fo:float

• Common use:

  The fo:float formatting object holds a sequence formatting objects that is to be presented in a conditional-area at the top of an instance of a region with the same name as the region into which the fo:float flow object is distributed. The content of the fo:float flow object is not placed where the flow object is distributed, but is instead placed, out-of-line, in the next instance of the region with the same name for which there is room for the content of the fo:float. Such content might be a figure, a table or other chunk of content that is to be kept together and need not disrupt the flow of the content around it.

  NOTE:

  Issue: Floating to the top of the same page should not be prohibited for systems that can support it.

• Type of area:

  The fo:float flow object generates a block-area that is placed in a conditional-area anchored on the before edge of the region into which the fo:float flow object is distributed. The placement of the block-area generated by the fo:float into the conditional regions is called, "out-of-line" placement.

  NOTE:

  Issue: Does it generate a block-area?!

• Determination of trait values:

  The coordinate system for the conditional-area for floats is set to the same orientation as the coordinate system of the region that contains the conditional-area. The writing-mode for the conditional-rererence-area is similarly copied from the region which contains it. Currently, there is no way to specify any of the common-border-padding-and-background-properties so the conditional region has no padding, borders or background.

• Distribution of content:

  The fo:floats which are distributed into a given region all generate a float block-area in a conditional-area for floats in the region into which they are distributed or in some subsequent instance of a region with the same name. That is, the content of the fo:float flow object is not distributed where the fo:float is distributed, but is instead formatted into a block-area that is placed, out-of-line, in the same or a subsequent region of the same name as the one in which the fo:float flow object was distributed.

  The size of the conditional-area for floats, in the block-progression-direction, shall not exceed the computed value of the "max-height" property on the fo:float flow object.

  The content of each fo:float is distributed into a single block-area whose height and width is determined by the common-margin-properties-block and the common-border-padding-and-background-properties. The conditional-area for floats is the reference-area into which this block-area is placed. The normal rules for space resolution apply to these blocks. The block-areas for floats are placed in conditional-areas for floats in the order in which the fo:float flow objects were distributed in the content distribution of the flow in which they occur. If a the block-area for a given float will not fit into the current conditional-area for floats, then it will be distributed into a conditional area for floats in a subsequent region of the same name as the current region. Instances of page-masters with a region of the same name will continue to be generated as long as there are float block-areas to be placed.

  NOTE:

  Issue: What is to happen if there is a float that can never fit within the "max-height" of the conditional-area for floats. Should that float be split? Should it be ignored?

• Content:

  (%block;)+
  

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.19.19 "id"]
  • [7.9 Common Margin Properties-Block]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.16.2 "clear"]
  • [7.19.1 "clip"]
  • [7.16.1 "float"]
  • [7.19.25 "overflow"]
  • [7.19.15 "maximum-block-progression-dimension"]
  • [7.19.12 "max-height"]
  • [7.19.33 "span"]
  • [7.19.38 "visibility"]
  • [7.19.52 "z-index"]

6.10.3 fo:footnote

• Common use:

  The fo:footnote formatting object represents both the place of occurrence of the footnote reference (or citation) and the content of the footnote itself. The footnote citation occurs where the fo:footnote flow object occurs; that is, the footnote citation is formatted inline. The footnote itself is formatted out of line; it is floated to the bottom of the page on which the footnote citation occurs.

  The content of the fo:footnote is structured into two pieces. There is an fo:footnote-citation flow object which is an inline flow object that is used to specify the properties to be used in formatting the footnote citation. The remaining content of the fo:footnote flow object is the content of the footnote itself. If the footnote itself is to have a label and a body, then this content should be structured using the fo:list-block flow object containing an fo:list-label and an fo:list-body.

  NOTE:

  Issue: The last sentence should be moved to a note and also stress that the use of list formatting objects is only when such a layout is desired.

• Type of area:

  The fo:footnote formatting object generates two areas. The citation generates at least one inline-area into which the content of the fo:footnote-citation is distributed. This distribution into one or more inline-areas shall be consistent with the constraints determined by the properties applicable to the fo:footnote-citation flow object.

  The fo:footnote flow object generates a block-area that is placed in a conditional-area anchored on the after edge of the region into which the fo:footnote-citation is distributed. The placement of the block-area generated by the fo:footnote into the conditional regions is called, "out-of-line" placement.

  NOTE:

  Issue: Does it generate a block-area?!

• Determination of trait values:

  The coordinate system for the conditional-area for footnotes is set to the same orientation as the coordinate system of the region that contains the conditional-area. The writing-mode for the conditional-reference-area is similarly copied from the region which contains it. Currently, there is no way to specify any of the common-border-padding-and-background-properties so the conditional region has no padding, borders or background.

  NOTE:

  Issue: Should there be a way to establish borders and/or padding and backgrounds for the conditional footnote areas?

• Distribution of content:

  The content of the fo:footnote-citation is distributed as specified in the description of the fo:footnote-citation flow object.

  The fo:footnotes which have a citation distributed into a given region all generate a footnote block-area in the conditional-area for footnotes for the region into which they are distributed. One condition on the distribution of the footnote-citation inline-areas into a region is that footnote conditional-area for that region is large enough to hold the footnote block-areas for all the footnote-citations distributed to that region. In addition, the size of that conditional-area in the block-progression-direction shall not exceed the computed value of the "max-height" property on the fo:footnote flow object.

  The content of each fo:footnote, excluding the fo:footnote-citation, is distributed into a single block-area whose height and width is determined by the common-margin-properties-block and the common-border-padding-and-background-properties. The conditional-area for footnotes is the reference-area into which this block-area is placed. The normal rules for space resolution apply to these blocks which are placed in the conditional-area for footnotes in the order in which the fo:footnote flow objects occurred in the content distributed into the region to which the footnote is attached.

• Content:

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.9 Common Margin Properties-Block]
  • [7.19.1 "clip"]
  • [7.19.19 "id"]
  • [7.19.15 "maximum-block-progression-dimension"]
  • [7.19.12 "max-height"]
  • [7.19.25 "overflow"]
  • [7.19.33 "span"]
  • [7.19.38 "visibility"]
  • [7.19.52 "z-index"]

6.10.4 fo:footnote-citation

Issue (footnote-citation):

This formatting object will be removed.

• Common use:

  The fo:footnote-citation flow object specifies the properties used format the footnote reference (or citation) itself. The footnote citation occurs where its parent fo:footnote flow object occurs; that is, the footnote citation is formatted inline.

• Type of area:

  The fo:footnote-citation formatting object generates at least one inline-area into which the content of the fo:footnote-citation is distributed.

• Distribution of content:

  The content of the fo:footnote-citation is distributed into one or more inline-areas in the current block. If all the content can be distributed into a single line, then only one inline-area is generated; otherwise the content of the footnote-citation is split into more than one inline-area provided that the constraints specified by the properties applicable to the fo:footnote-citation are satisfied.

  The fo:footnotes which have a citation distributed into a given region all generate a footnote block-area in the conditional-area for footnotes for the region into which they are distributed. One condition on the distribution of the footnote-citation inline-areas into a region is that footnote conditional-area for that region is large enough to hold the footnote block-areas for all the footnote-citations distributed to that region. In addition, the size of that conditional-area in the block-progression-direction shall not exceed the computed value of the "max-height" property on the fo:footnote flow object that is the parent of the fo:footnote-citation flow object.

• Content:

• Properties:

  • [7.2 Common Accessibility Properties]
  • [7.4 Common Aural Properties]
  • [7.5 Common Border, Padding, and Background Properties]
  • [7.6 Common Font Properties]
  • [7.10 Common Margin Properties-Inline]
  • [7.19.19 "id"]
  • [7.19.20 "inhibit-line-breaks"]
  • [7.13.2 "letter-spacing"]
  • [7.19.23 "line-height"]
  • [7.19.22 "line-height-shift-adjustment"]
  • [7.19.31 "score-spaces"]
  • [7.13.6 "text-decoration"]
  • [7.13.7 "text-shadow"]
  • [7.13.8 "text-transform"]
  • [7.19.37 "vertical-align"]
  • [7.13.3 "word-spacing"]

6.11 Other Formatting Objects

6.11.1 Introduction

The following example shows the use of the fo:wrapper formatting object that has no semantics but acts as a "carrier" for inherited properties.

6.11.1.1 Example

Input sample:

<doc>
<p>This is an <emph>important word</emph> in this
sentence that also refers to a <code>variable</code>.</p>
</doc>

The "emph" elements are to be presented using a bold font and the "code" elements are using a Courier font.

XSL Stylesheet:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<xsl:template match="p">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="emph">
  <fo:wrapper font-weight="bold">
    <xsl:apply-templates/>
  </fo:wrapper>
</xsl:template>

<xsl:template match="code">
  <fo:wrapper font-family="Courier">
    <xsl:apply-templates/>
  </fo:wrapper>
</xsl:template>

</xsl:stylesheet>

fo: element and attribute tree:

<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format">This is an
<fo:wrapper font-weight="bold">important word</fo:wrapper>
in this sentence that also refers to a
<fo:wrapper font-family="Courier">variable</fo:wrapper>.
</fo:block>

6.11.2 fo:wrapper

• Common use:

  The fo:wrapper formatting object is used to specify inherited properties for a group of formatting objects.

• Area type:

  The fo:wrapper formatting object does not directly generate any area. However, each of its children is individually formatted to produce a series of areas.

• Determination of trait values:

  The fo:wrapper has no properties that are directly used by it. However, it does serve as a carrier to hold inheritable properties that are utilized by its children.

• Content:

  (#PCDATA|%inline;|%block;)*
  

• Properties:

  • [7.19.19 "id"]

7 Formatting Properties

7.1 Description of Property Groups

The following sections describe the properties of the XSL formatting objects.

• The first eight sets of property definitions have been arranged into groups based on similar functionality and the fact that they apply to many formatting objects. In the formatting-object descriptions the group name is referred to rather than referring to the individual properties.

  • Common Absolute Position Properties

    This set of properties controls the position and size of formatted areas with absolute or relative positioning (areas displaced from the default positioning in the text block). This property group appears on all formatting objects that produce visible renderings.

  • Common Aural Properties

    This group of properties controls the aural rendition of the content of a formatting object. They appear on all formatting objects that contain content and other formatting objects that group other formatting objects and where that grouping is necessary for the understanding of the aural rendition. An example of the latter is fo:table-and-caption.

  • Common Border, Padding, and Background Properties

    This set of properties controls the backgrounds and borders on the block-areas and inline-areas. This property group appears on all formatting objects that produce visible renderings.

  • Common Font Properties

    This set of properties controls the font selection on all formatting objects that can contain text. Appears on fo:block, fo:first-line-marker, and on inline formatting objects that contain or generate text.

  • Common Hyphenation Properties

    Low-level control of line-breaking, including hyphenation and language selection. Appears on fo:block and fo:title.

  • Common Keeps and Breaks Properties

    Controls page/column breaks before/after block-level formatting objects. Appears on most block-level formatting objects.

  • Common Margin Properties-Block

    These properties set the spacing and indents surrounding block-level formatting objects.

  • Common Margin Properties-Inline

    These properties set the spacing surrounding inline formatting objects.

• The remaining properties are used on a small number of formatting objects. These are arranged into clusters of similar functionality to organize the property descriptions. In the formatting object description the individual properties are referenced.

  • Pagination Properties

    These properties govern the sequencing, layout, and instantiation of pages, including: the page size and orientation, sizes of regions on the page-master, the identification and selection of page-masters, division of the body region into columns, and the assignment of content flows to layout regions.

  • Table Properties

    Properties governing the layout and presentation of tables.

  • Character Properties

    Properties governing the presentation of text-characters.

  • Rule Properties

    Properties governing the construction of rules (graphic lines).

  • Page-related Properties

    These properties augment the common-keeps-and-breaks-properties group by adding controls for widows, orphans, and page/column breaks within block-level formatting objects that contain text.

  • Float-related properties

    Properties governing the placement of floats and controlling the wrapping (runaround) of text that may be adjacent to the float.

    Issue (unify-floats):

    Determine if unification of floats will impair underlying model or not.

  • Properties for Number-to-String Conversions

    Properties used in the construction of page-numbers and other formatter-based numbering.

  • Properties for Links

    Properties governing the presentation and actions associated with links.

  • Miscellaneous Properties

    These properties did not reasonably fit into any of the other categories.

7.2 Common Accessibility Properties

7.2.1 "source-document"

XSL Definition:

Values have the following meanings:

none

The source document is transient, unknown, or unspecified.

<uri>

A list of space-separated URIs, indicating the XML document(s) used as input to the stylesheet.

This property provides a pointer back to the original XML document(s) used to create this formatting-object tree. It is useful for for alternate renderers (aural readers, etc) whenever the structure of the formatting-object tree is inappropriate for that renderer.

7.2.2 "role"

XSL Definition:

It is used by all formatting objects that can be contained in fo:flow or fo:static-content (all formatting objects that can be directly created from an XML source element).

Values have the following meanings:

none

Indicates that no semantic tag is cited by this formatting object.

<string>

The value is a string representing a semantic that may be used in rendering this formatting object. It can, for example, be an element name in some known semantic vocabulary, such as HTML, or a particular Web Accessibility Initiative (WAI) semantic vocabulary.

This provides a hint for alternate renderers (aural readers, etc) as to the role and potential alternate presentation of the content of this formatting object.

This property is not inherited, but all subsidiary nodes of this formatting object that do not bear a role property should utilize the same alternate presentation properties. (It is not inherited because knowledge of the start and end of the formatting-object subtree generated by the element may be needed by the renderer.)

7.3 Common Absolute Position Properties

7.3.1 "position"

XSL modifications to the CSS definition:

The following additional restrictions apply for paged presentations:

• Only objects with position="static" or position="relative" may have page/column breaks.

  For relative-positioned objects that break over a page boundary, only the portion that would have been on a given page originally is included in the repositioned area on that page. Any portion of the repositioned area that was originally on the current page, but falls off the current page due to repositioning is "off" (typically clipped), thus does not fall onto any other page.

• Objects that have position="absolute" or position="fixed" generate a single new reference-area on the page where the first mark from the object would have been placed had the object had static positioning.

  The entire object and its descendants are formatted into that reference-area.

  Page/column breaking is disabled for these objects and the associated keep and break properties are ignored.

  The "margin" and "space-before" properties are also ignored on fixed or absolutely positioned objects.

• Objects with position="fixed" are positioned at a fixed location in the current page or viewport.

7.3.2 "top"

XSL modifications to the CSS definition:

See definition of property left ([7.3.5 "left"]).

7.3.3 "right"

XSL modifications to the CSS definition:

See definition of property left ([7.3.5 "left"]).

7.3.4 "bottom"

XSL modifications to the CSS definition:

See definition of property left ([7.3.5 "left"]).

7.3.5 "left"

XSL modifications to the CSS definition:

These properties set the position of the content-rectangle of the associated area.

If both "top" and "bottom" are specified, the height of the content rectangle is overridden. If both "left" and "right" are specified, the width of the content-rectangle is overridden.

Issue (height-width-overrides):

There appears to be a contradiction in the CSS spec. 10.3.7 and 9.3.2. SZilles to request clarfication from CSS.

Clarify. CSS spec says, "If you specify opposing edges, the edge toward 'end' will be disregarded." Clarify if this is based on text-align or writing-direction (writing-mode). We believe it to be based solely on writing-mode.

7.4 Common Aural Properties

7.4.1 "azimuth"

7.4.2 "cue"

7.4.3 "cue-after"

7.4.4 "cue-before"

7.4.5 "elevation"

7.4.6 "pause"

7.4.7 "pause-after"

7.4.8 "pause-before"

7.4.9 "pitch"

7.4.10 "pitch-range"

7.4.11 "play-during"

7.4.12 "richness"

7.4.13 "speak"

7.4.14 "speak-header"

7.4.15 "speak-numeral"

7.4.16 "speak-punctuation"

7.4.17 "speech-rate"

7.4.18 "stress"

7.4.19 "voice-family"

7.4.20 "volume"

7.5 Common Border, Padding, and Background Properties

The following common-border-padding-and-background-properties are taken from CSS2. Those "border", "padding", and "background" properties that have a before, after, start, or end suffix are writing-mode relative and are XSL-only properties.

Interrelated shorthands and individual properties:

CSS indicates that the user must specify the order of processing for combinations of multiple interrelated shorthands and individual interrelated properties. In XML, attributes are defined as unordered. To resolve this issue, XSL defines the following precedence order when multiple interrelated shorthand properties or a shorthand property and an interrelated individual property are specified:

• If multiple, interrelated shorthand properties are specified on a given formatting object, process them in order of increasing precision (border is less precise than border-top, which is less precise than border-top-color).

  For the remaining ambiguous case, XSL defines the ordering to be:

  1. Process "border" first.

  2. Process "border-style", "border-color", and "border-width" second.

  3. Process "border-top", "border-bottom", "border-right", and "border-left" third.

     (For XSL border-top is deemed to be more precise than border-color.)

  4. Process "border-*-*" last.

• Process the shorthand as follows:

  • Set all properties that can be set by the shorthand to their initial values.

  • If the shorthand is set to "inherit": set each property that can be set by the shorthand to the computed value of the corresponding property in the parent. (Shorthand properties do not inherit from the shorthand on the parent. Instead, the computed values of all the individual properties are forced to inherit.)

    If the value of the shorthand is not inherit: determine which individual properties are to be set/overridden, and replace the initial-value with the computed value derived from the specified value.

• Finally, process any individual properties that could also be set by the shorthand. (If both the "background" property and the "background-color" property are specified on a given formatting object: process the "background" shorthand then process the "background-color" property.)

7.5.1 "background"

7.5.2 "background-attachment"

XSL modifications to the CSS definition:

7.5.3 "background-color"

XSL modifications to the CSS definition:

Issue (color-props):

Shall we include proposed SVG properties: color-profile and rendering-intent in XSL? If so, what is appropriate syntax? Is there an extended syntax to specify both ICC and SVG color?

7.5.4 "background-image"

7.5.5 "background-repeat"

XSL modifications to the CSS definition:

7.5.6 "background-position"

7.5.7 "border-before-color"

7.5.8 "border-before-style"

7.5.9 "border-before-width"

7.5.10 "border-after-color"

7.5.11 "border-after-style"

7.5.12 "border-after-width"

7.5.13 "border-start-color"

7.5.14 "border-start-style"

7.5.15 "border-start-width"

7.5.16 "border-end-color"

7.5.17 "border-end-style"

7.5.18 "border-end-width"

7.5.19 "border-top-color"

7.5.20 "border-top-style"