Extensible Stylesheet Language (XSL)
Version 1.0

W3C Working Draft 27 March 2000

This version:

http://www.w3.org/TR/2000/WD-xsl-20000327/
( XML file, HTML (one large file), ZIP file )

Latest version:

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

Previous version:

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

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>
Paul Grosso (ArborText) <paul@arbortext.com>
Eduardo Gutentag (Sun) <eduardo.gutentag@eng.sun.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. The XSL Working Group considers that this draft is stable and ready to move to Candidate Recommendation status, following the successful resolution of comments. This is therefore the last call for comments on this Working Draft. Please send detailed comments to xsl-editors@w3.org before 30 April 2000; archives of the comments are available. More general public discussion of XSL takes place on the XSL-List mailing list.

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).

Table of contents

Appendices

1 Introduction and Overview

This specification defines the Extensible Stylesheet Language (XSL). XSL is a language for expressing stylesheets. Given a class of arbitrarily structured XML [W3C XML] documents or data files, designers use an XSL stylesheet to express their intentions about how that structured content should be presented; that is, how the source content should be styled, laid out, and paginated onto some presentation medium, such as a window in a Web browser or a hand-held device, or a set of physical pages in a catalog, report, pamphlet, or book.

1.1 Processing a Stylesheet

An XSL stylesheet processor accepts a document or data in XML and an XSL stylesheet and produces the presentation of that XML source content that was intended by the designer of that stylesheet. There are two aspects of this presentation process: first, constructing a result tree from the XML source tree and second, interpreting the result tree to produce formatted results suitable for presentation on a display, on paper, in speech, or onto other media. The first aspect is called tree transformation and the second is called formatting. The process of formatting is performed by the formatter. This formatter may simply be a rendering engine inside a browser.

Tree transformation allows the structure of the result tree to be significantly different from the structure of the source tree. For example, one could add a table-of-contents as a filtered selection of an original source document, or one could rearrange source data into a sorted tabular presentation. In constructing the result tree, the tree transformation process also adds the information necessary to format that result tree.

Formatting is enabled by including formatting semantics in the result tree. Formatting semantics are expressed in terms of a catalog of classes of formatting objects. The nodes of the result tree are formatting objects. The classes of formatting objects denote typographic abstractions such as page, paragraph, table, and so forth. Finer control over the presentation of these abstractions is provided by a set of formatting properties, such as those controlling indents, word- and letter-spacing, and widow, orphan, and hyphenation control. In XSL, the classes of formatting objects and formatting properties provide the vocabulary for expressing presentation intent.

The XSL processing model is intended to be conceptual only. An implementation is not mandated to provide these as separate processes. Furthermore, implementations are free to process the source document in any way that produces the same result as if it were processed using the conceptual XSL processing model. A diagram depicting the detailed conceptual model is shown below.

1.1.1 Tree Transformations

Tree transformation constructs the result tree. In XSL, this tree is called the element and attribute tree, with objects primarily in the "formatting object" namespace. In this tree, a formatting object is represented as an XML element, with the properties represented by a set of XML attribute-value pairs. The content of the formatting object is the content of the XML element. Tree transformation is defined in the XSLT Recommendation [XSLT]. A diagram depicting this conceptual process is shown below.

The XSL stylesheet is used in tree transformation. A stylesheet contains a set of tree construction rules. The tree construction rules have two parts: a pattern that is matched against elements in the source tree and a template that constructs a portion of the result tree. This allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

1.1.2 Formatting

Formatting interprets the result tree in its formatting object tree form to produce the presentation intended by the designer of the stylesheet from which the XML element and attribute tree in the "fo" namespace was constructed.

The vocabulary of formatting objects supported by XSL - the set of fo: element types - represents the set of typographic abstractions available to the designer. Semantically, each formatting object represents a specification for a part of the pagination, layout, and styling information that will be applied to the content of that formatting object as a result of formatting the whole result tree. Each formatting object class represents a particular kind of formatting behavior. For example, the block formatting object class represents the breaking of the content of a paragraph into lines. Other parts of the specification may come from other formatting objects; for example, the formatting of a paragraph (block formatting object) depends on both the specification of properties on the block formatting object and the specification of the layout structure into which the block is placed by the formatter.

The properties associated with an instance of a formatting object control the formatting of that object. Some of the properties, for example "color", directly specify the formatted result. Other properties, for example 'space-before', only constrain the set of possible formatted results without specifying any particular formatted result. The formatter may make choices among other possible considerations such as esthetics.

Formatting consists of the generation of a tree of geometric areas, called the area tree. The geometric areas are positioned on a sequence of one or more pages (a browser typically uses a single page). Each geometric area has a position on the page, a specification of what to display in that area and may have a background, padding, and borders. For example, formatting a single character generates an area sufficiently large enough to hold the glyph that is used to present the character visually and the glyph is what is displayed in this area. These areas may be nested. For example, the glyph may be positioned within a line, within a block, within a page.

Rendering takes the area tree, the abstract model of the presentation (in terms of pages and their collections of areas), and causes a presentation to appear on the relevant medium, such as a browser window on a computer display screen or sheets of paper. The semantics of rendering are not described in detail in this specification.

The first step in formatting is to "objectify" the element and attribute tree obtained via an XSLT transformation. Objectifying the tree basically consists of turning the elements in the tree into formatting object nodes and the attributes into property specifications. The result of this step is the formatting object tree.

As part of the step of objectifying, the characters that occur in the result tree are replaced by fo:character nodes. The first phase of the Unicode Bidirectional Algorithm is used to convert implicit Bidirectional mark-up to explicit nodes with the appropriate directional properties. Care is taken to insure that the explicit nodes so introduced are properly nested in the formatting object tree.

The second phase in formatting is to refine the formatting object tree to produce the refined formatting object tree. The refinement process handles the mapping from properties to traits. This consists of: (1) shorthand expansion into individual properties, (2) mapping of corresponding properties, (3) determining computed values (may include expression evaluation), and (4) inheritance. Details on refinement are found in [5 Property Refinement / Resolution].

The refinement step is depicted in the diagram below.

The third step in formatting is the construction of the area tree. The area tree is generated as described in the semantics of each formatting object. The traits applicable to each formatting object class control how the areas are generated. Although every formatting property may be specified on every formatting object, for each formatting object class, only a subset of the formatting properties are used to determine the traits for objects of that class.

Area generation is depicted in the diagram below.

1.2 Benefits of XSL

Unlike the case of HTML, element names in XML have no intrinsic presentation semantics. Absent a stylesheet, a processor could not possibly know how to render the content of an XML document other than as an undifferentiated string of characters. XSL provides a comprehensive model and a vocabulary for writing such stylesheets using XML syntax.

This document is intended for implementors of such XSL processors. Although it can be used as a reference manual for writers of XSL style sheets, it is not tutorial in nature.

XSL builds on the prior work on Cascading Style Sheets [CSS2] and the Document Style Semantics and Specification Language [DSSSL]. While many of XSL's formatting objects and properties correspond to the common set of properties, this would not be sufficient by itself to accomplish all the goals of XSL. In particular, XSL introduces a model for pagination and layout that extends what is currently available and that can in turn be extended, in a straightforward way, to page structures beyond the simple page models described in this specification.

1.2.1 Paging and Scrolling

Doing both scrollable document windows and pagination introduces new complexities to the styling (and pagination) of XML content. Because pagination introduces arbitrary boundaries (pages or regions on pages) on the content, concepts such as the control of spacing at page, region, and block boundaries become extremely important. There are also concepts related to adjusting the spaces between lines (to adjust the page vertically) and between words and letters (to justify the lines of text). These do not always arise with simple scrollable document windows, such as those found in today's browsers. However, there is a correspondence between a page with multiple regions, such as a body, header, footer, and left and right side-bars, and a Web presentation using "frames". The distribution of content into the regions is basically the same in both cases, and XSL handles both cases in an analogous fashion.

XSL was developed to give designers control over the features needed when documents are paginated as well as to provide an equivalent "frame" based structure for browsing on the Web. To achieve this control, XSL has extended the set of formatting objects and formatting properties. In addition, the selection of XML source components that can be styled (elements, attributes, text nodes, comments, and processing instructions) is based on XSLT and XPath, thus providing the user with an extremely powerful selection mechanism.

The design of the formatting objects and properties extensions was first inspired by DSSSL. The actual extensions, however, do not always look like the DSSSL constructs on which they were based. To either conform more closely with the CSS2 specification or to handle cases more simply than in DSSSL, some extensions have diverged from DSSSL.

There are several ways in which extensions were made. In some cases, it sufficed to add new values, as in the case of those added to reflect a variety of writing-modes, such as top-to-bottom and bottom-to-top, rather than just left-to-right and right-to-left.

In other cases, common properties that are expressed in CSS2 as one property with multiple simultaneous values, are split into several new properties to provide independent control over independent aspects of the property. For example, the "white-space" property was split into four properties: a "space-treatment" property that controls how white-space is processed, a "line-feed" property that controls how line-feeds are processed, a "white-space-collapse" property that controls how multiple consecutive spaces are collapsed, and a "wrap-option" property that controls whether lines are automatically wrapped when they encounter a boundary, such as the edge of a column. The effect of splitting a property into two or more (sub-)properties is to make the equivalent existing CSS2 property a "shorthand" for the set of sub-properties it subsumes.

In still other cases, it was necessary to create new properties. For example, there are a number of new properties that control how hyphenation is done. These include identifying the script and country the text is from as well as such properties as "hyphenation-character" (which varies from script to script).

Some of the formatting objects and many of the properties in XSL come from the CSS2 specification, ensuring compatibility between the two.

There are four classes of XSL properties that can be identified as:

1. CSS properties by copy (unchanged from their CSS2 semantics)

2. CSS properties with extended values

3. CSS properties broken apart and/or extended

4. XSL only properties

1.2.2 Selectors and Tree Construction

As mentioned above, XSL uses XSLT and XPath for tree construction and pattern selection, thus providing a high degree of control over how portions of the source content are presented, and what properties are associated with those content portions, even where mixed namespaces are involved.

For example, the patterns of XPath allow the selection of a portion of a string or the Nth text node in a paragraph. This allows users to have a rule that makes all third paragraphs in procedural steps appear in bold, for instance. In addition, properties can be associated with a content portion based on the numeric value of that content portion or attributes on the containing element. This allows one to have a style rule that makes negative values appear in "red" and positive values appear in "black". Also, text can be generated depending on a particular context in the source tree, or portions of the source tree may be presented multiple times with different styles.

1.2.3 An Extended Page Layout Model

There is a set of formatting objects in XSL to describe both the layout structure of a page or "frame" (how big is the body; are there multiple columns; are there headers, footers, or side-bars; how big are these) and the rules by which the XML source content is placed into these "containers".

The layout structure is defined in terms of one or more instances of a "simple-page-master" formatting object. This formatting object allows one to define independently filled regions for the body (with multiple columns), a header, a footer, and side-bars on a page. These simple-page-masters can be used in page sequences that specify in which order the various simple-page-masters shall be used. The page sequence also specifies how styled content is to fill those pages. This model allows one to specify a sequence of simple-page-masters for a book chapter where the page instances are automatically generated by the formatter or an explicit sequence of pages such as used in a magazine layout. Styled content is assigned to the various regions on a page by associating the name of the region with names attached to styled content in the result tree.

In addition to these layout formatting objects and properties, there are properties designed to provide the level of control over formatting that is typical of paginated documents. This includes control over hyphenation, and expanding the control over text that is kept with other text in the same line, column, or on the same page.

1.2.4 A Comprehensive Area Model

The extension of the properties and formatting objects, particularly in the area on control over the spacing of blocks, lines, and page regions and within lines, necessitated an extension of the CSS2 box formatting model. This extended model is described in [4 Area Model] of this specification. The CSS2 box model is a subset of this model. See the mapping of the CSS2 box model terminology to the XSL Area Model terminology in [7.2 XSL Areas and the CSS Box Model]. The area model provides a vocabulary for describing the relationships and space-adjustment between letters, words, lines, and blocks.

1.2.5 Internationalization and Writing-Modes

There are many scripts, in particular in the Far East, that are typically set with words proceeding from top-to-bottom and lines proceeding either from right-to-left (most common) or from left-to-right. Other directions are also used. Properties expressed in terms of a fixed, absolute frame of reference (using top, bottom, left, and right) and which apply only to a notion of words proceeding from left to right or right to left do not generalize well to the languages based on these scripts.

For this reason XSL (and before it DSSSL) uses a relative frame of reference for the formatting object and property descriptions. Just as the CSS2 frame of reference has four directions (top, bottom, left and right), so does the XSL relative frame of reference have four directions (before, after, start, and end), but these are relative to the "writing-mode". The "writing-mode" property is a way of controlling the directions needed by a formatter to correctly place glyphs, words, lines, blocks, etc. on the page or screen. The "writing-mode" expresses the basic directions noted above. There are writing-modes for "left-to-right - top-to-bottom" (denoted as "lr-tb"), "right-to-left - top-to-bottom" (denoted as "rl-tb"), "top-to-bottom - right-to-left" (denoted as "tb-rl") and more, see [7.35.7 "writing-mode"] for the description of the "writing-mode" property. Typically, the writing-mode value specifies two directions, the first is the inline-progression-direction which determines the direction in which words will be placed and the second is the block-progression-direction which determines the direction in which blocks (and lines) are placed one after another.

Besides the directions that are explicit in the name of the value of the "writing-mode" property, the writing-mode determines other directions needed by the formatter, such as the shift-direction (used for sub- and super-scripts), etc.

1.2.6 Linking

Because XML, unlike HTML, has no built-in semantics, there is no built-in notion of a hypertext link. Therefore, XSL has a formatting object that expresses the dual semantics of formatting the content of the link reference and the semantics of following the link.

XSL provides a few mechanisms for changing the presentation of a link target that is being visited. One of these mechanisms permits indicating the link target as such; another allows for control over the placement of the link target in the viewing area; still another permits some degree of control over the way the link target is displayed in relationship to the originating link anchor.

XSL also provides a general mechanism for changing the way elements are formatted depending on their active state. This is particularly useful in relation to links, to indicate whether a given link reference has already been visited, or to apply a given style depending on whether the mouse, for instance, is hovering over the link reference or not.

2 Introduction to XSL Transformation

2.1 Tree Construction

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. Constraints might conflict to the point where it is impossible to satisfy them all. In that case, it is implementation-defined which constraints should be relaxed and in what order to satisfy the others.

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, 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,

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 are intermediate steps of constructing a formatting object tree (containing formatting objects and their properties) and refinement; these steps 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 returned to an fo:root formatting object are page-viewport-areas, 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 side floats, before 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 (see section [4.10.2 Line-building]).

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. Traits whose values are copied from property of the same or a corresponding name are listed in [C Property Index] and [5 Property Refinement / Resolution]; other traits are listed in [4.14 List of Traits on Areas].

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 block-area children or inline-area children as determined by the generating formatting object, but a given area's children must all be of one type. 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 its 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 baseline shifts are applied. Also the glyph-orientation defines the orientation of glyph-images in the rendered result.

The Boolean trait is-reference-area determines whether or not an area establishes a coordinate system for specifying indents. An area for which this trait is true is called a reference-area. Only a reference-area may have a block-progression-direction which is different from that of its parent. A reference-area may be either a block-area or an inline-area.

The Boolean trait is-viewport-area determines whether or not an area establishes an opening through which its descendant areas can be viewed, and can be used to present clipped or scrolled material; for example, in printing applications where bleed and trim is desired. An area for which this trait is true is called a viewport-area.

A common construct is a viewport/reference pair. This is a block-area viewport-area V and a block-area reference-area R, where R is the sole child of V and where the start-edge and end-edge of the content-rectangle of R coincide with the start-edge and end-edge of the content-rectangle of V.

Each element has the traits top-position, bottom-position, left-position, and right-position which represent the distance from the edges of its content-rectangle to the like-named edges of the nearest ancestor reference-area (or the page-viewport-area in the case of areas generated by descendants of formatting objects whose absolute-position is fixed); the left-offset and top-offset determine the amount by which a relatively-positioned area is shifted for rendering. These traits receive their values during the formatting process, or in the case of absolutely positioned areas, during refinement.

The block-progression-dimension and inline-progression-dimension of an area represent the extent of the content-rectangle of that area in each of the two relative dimensions

Other traits include:

• the is-first and is-last traits, which are Boolean traits indicating the order in which areas are generated and returned by a given formatting object. is-first is true for the first area (or only area) generated and returned by a formatting object, and is-last is true for the last area (or only area).

• 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, background-image, and other background traits.

  NOTE:

  "Before", "after", "start", and "end" refer to relative directions and are defined below.

• a set of font traits (see "Common Font Properties") which determine the nominal-font that is deemed to be used within that area.

Unless otherwise specified, the traits of a formatting object are present on each of its generated areas, and with the same value. (However, see sections [4.10.2 Line-building] and [4.12.4 Border, Padding, and Background].)

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.

For a block-area, the allocation-rectangle extends to the border-rectangle in the block-progression-direction and outside the content-rectangle in the inline-progression-direction by an amount equal to the end-indent, and in the opposite direction by an amount equal to the start-indent.

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.

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 position-point determined by the formatter, 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 preferred baseline (see below). This is script-dependent and does not necessarily correspond to the (0,0) coordinate point used for the data describing the glyph shape.

4.2.4 Tree 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.

In any ordered tree, this sibling order extends to an ordering of the entire tree in at least two ways.

• In the pre-order traversal order of a tree, the children of each node (their order unchanged relative to one another) follow the node, but precede any following siblings of the node or of its ancestors.

• In the post-order traversal order of a tree, the children of each node precede the node, but follow any preceding siblings of the node or of its ancestors.

"Preceding" and "following", when applied to non-siblings, will depend on the extension order used, which must be specified. However, in either of these given orders, the leaves of the tree (nodes without children) are unambiguously ordered.

4.2.5 Stacking Constraints

This section defines the notion of block-stacking constraints and inline-stacking constraints involving areas. These are defined as ordered relations, i.e., if A and B have a stacking constraint it does not necessarily mean that B and A have a stacking constraint.

The area-class trait is an enumerated value which is xsl-normal for an area which is stacked with other areas in sequence. A normal area is an area for which this trait is xsl-normal. A page-level-out-of-line area is an area with area-class xsl-footnote, xsl-before-float, or xsl-fixed; placement of these areas is controlled by the fo:page-sequence ancestor of its generating formatting object. A reference-level-out-of-line area is an area with area-class xsl-side-float or xsl-absolute; placement of these areas is controlled by the formatting object generating the relevant reference-area. Areas with area-class equal to one of xsl-normal, xsl-footnote, or xsl-before-float are defined to be stackable, indicating that they are supposed to be properly stacked.

If P is a block-area, then there is a fence-before P if P is a reference-area or if the border-before-width or padding-before-width of P are non-zero. Similarly, there is a fence-after P if P is a reference-area or if the border-after-width or padding-after-width of P are non-zero.

If A and B are stackable areas, and S is a sequence of space-specifiers, it is defined that A and B have block-stacking constraint S if any of the following conditions holds:

1. B is a block-area which is the first normal child of A, and S is the sequence consisting of the space-before of B.

2. A is a block-area which is the last normal child of B, and S is the sequence consisting of the space-after of A.

3. A and B are both block-areas, and either

   a. B is the next stackable sibling area of A, and S is the sequence consisting of the space-after of A and the space-before of B;

   b. B is the first normal child of a block-area P, there is no fence-before P, A and P have a block-stacking constraint S', and S consists of S' followed by the space-before of B; or

   c. A is the last normal child of a block-area P, there is no fence-after P, P and B have a block-stacking constraint S'', and S consists of the space-after of A followed by S''.

NOTE:

The use of "stackable" in two places in the above definition allows block-stacking constraints to apply between areas of area-class xsl-before-float or xsl-footnote.

When A and B have a block-stacking constraint, the adjacent edges of A and B are an ordered pair recursively defined as:

• In case 1, the before-edge of the content-rectangle of A and the before-edge of the allocation-rectangle of B.

• In case 2, the after-edge of the content-rectangle of A and the after-edge of the allocation-rectangle of B.

• In case 3a, the after-edge of the allocation-rectangle of A and the before-edge of the allocation-rectangle of B.

• In case 3b, the first of the adjacent edges of A and P, and the before-edge of the allocation-rectangle of B.

• In case 3c, the after-edge of the allocation-rectangle of A and the second of the adjacent edges of P and B.

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, and none of the areas are reference-areas. Then P and A have a block-stacking constraint, as do A and B, A and C, B and C, C and D, D and B, B and E, D and E, and E and P; these are the only pairs in the diagram having block-stacking constraints. If B had non-zero padding-after, then D and E would not have any block-stacking constraint (though B and E would continue to have a block-stacking constraint).

Inline-stacking constraints. This section will recursively define the inline-stacking constraints between two inline-areas, together with the notion of fence-before and fence-after; these definitions are interwoven with one another. This parallels the definition for block-stacking constraints, but with the additional complication that we may have a stacking constraint between inline-areas which are stacked in opposite inline-progression-directions. (This is not an issue for block-stacking constraints because a block-area which is not a reference-area may not have block-progression-direction different from that of its parent.)

If P and Q have an inline-stacking constraint, then P has a fence-before Q if P is a reference-area or has non-zero border-width or padding-width at the first adjacent edge of P and Q. Similarly, Q has a fence-after P if Q is a reference-area or has non-zero border-width or padding-width at the second adjacent edge of P and Q.

If A and B are normal inline-areas, and S is a sequence of space-specifiers, it is defined that A and B have inline-stacking constraint S if any of the following conditions holds:

1. B is an inline-area which is the first normal child of A, and S is the sequence consisting of the space-start of B.

2. A is an inline-area which is the last normal child of B, and S is the sequence consisting of the space-end of A.

3. A and B are both inline-areas, and either

   a. B is the next normal sibling area of A, and S is the sequence consisting of the space-end of A and the space-start of B;

   b. B is the first normal child of an inline-area P, P has no fence-after A, A and P have an inline-stacking constraint S', the inline-progression-direction of P is the same as the inline-progression-direction of the nearest common ancestor area of A and P, and S consists of S' followed by the space-start of B.

   c. A is the last normal child of a block-area P, P has no fence-before B, P and B have an inline-stacking constraint S'', the inline-progression-direction of P is the same as the inline-progression-direction of the nearest common ancestor area of A and P, and S consists of the space-end of A followed by S''.

   d. B is the last normal child of an inline-area P, P has no fence-after A, A and P have an inline-stacking constraint S', the inline-progression-direction of P is opposite to the inline-progression-direction of the nearest common ancestor area of A and P, and S consists of S' followed by the space-end of B.

   e. A is the first normal child of a block-area P, P has no fence-before B, P and B have an inline-stacking constraint S'', the inline-progression-direction of P is opposite to the inline-progression-direction of the nearest common ancestor area of A and P, and S consists of the space-start of A followed by S''.

When A and B have an inline-stacking constraint, the adjacent edges of A and B are an ordered pair defined as:

• In case 1, the start-edge of the content-rectangle of A and the start-edge of the allocation-rectangle of B.

• In case 2, the end-edge of the content-rectangle of A and the end-edge of the allocation-rectangle of B.

• In case 3a, the end-edge of the allocation-rectangle of A and the start-edge of the allocation-rectangle of B.

• In case 3b, the first of the adjacent edges of A and P, and the start-edge of the allocation-rectangle of B.

• In case 3c, the end-edge of the allocation-rectangle of A and the second of the adjacent edges of P and B.

• In case 3d, the first of the adjacent edges of A and P, and the end-edge of the allocation-rectangle of B.

• In case 3e, the start-edge of the allocation-rectangle of A and the second of the adjacent edges of P and B.

Two areas are adjacent if they have a block-stacking constraint or an inline-stacking constraint. It follows from the definitions that areas of the same type (inline or block) can be adjacent only if all their non-common ancestors are also of the same type (up to but not including their nearest common ancestor). Thus, for example, two inline-areas which reside in different line-areas are never adjacent.

An area A begins an area P if A is a descendant of P and P and A have either a block-stacking constraint or an inline-stacking constraint. In this case the second of the adjacent edges of P and A is defined to be a leading edge in P. A space-specifier which applies to the leading edge is also defined to begin P

Similarly, An area A ends an area P if A is a descendant of P and A and P have either a block-stacking constraint or an inline-stacking constraint. In this case the first of the adjacent edges of A and P is defined to be a trailing edge in P. A space-specifier which applies to the trailing edge is also defined to end P

4.2.6 Font Baseline Tables

Each script has its preferred "baseline" for aligning glyphs from that script. Western scripts typically use a "alphabetic" baseline that touches at or near the bottom of capital letters. Further, for each font there is a preferred way of aligning embedded characters from different scripts, e.g., for a Western font there is a separate baseline for aligning embedded ideographic or Indic characters.

Each block-area and inline-area has a dominant-baseline trait which is a baseline-type, an enumerated type corresponding to the type of alignment expected for the nominal font for that area. Similarly, each inline-area has a baseline-identifier trait, corresponding to the type of alignment preferred for that area. The geometric line identified by this trait is called the preferred baseline of the inline-area.

Associated to each font is a table of baseline shifts, called the baseline table, which associates to each pair of possible baseline types the distance between the corresponding baselines in that font.

Example. For a Western font, the baseline table would associate to the pair <alphabetic, hanging> a distance approximately equal to the ascent of the font, representing the offset from the alphabetic baseline of the designated alignment-point for embedded hanging-aligned characters.

Some font standards, e.g., OpenType, define a baseline table as part of the font data.

Certain baselines which are not part of the registered set of baselines are defined as follows. The offset of the text-before-edge baseline is determined by the ascent of the nominal-font relative to the dominant-baseline. The text-after-edge baseline offset is defined to be the descent of the nominal-font.

For each line-area, the offset of the "before-edge" baseline is determined by ignoring all inline-areas whose baseline-identifier is before-edge. The "before-edge" baseline offset is set to the maximum extent in the direction opposite the block-progression-direction, of the before-edges of the remaining inline-areas. If all the inline-areas in a line-area are aligned "before-edge" then use "text-before-edge" as the "before-edge" alignment offset. The determination of the "after-edge" baseline is analogous.

For each area before-baseline-height and after-baseline-height are defined to be the respective distances from the area's dominant-baseline to the before-edge and after-edge baselines. The text-before-baseline-height and the text-after-baseline-height are defined to be the respective distances from the area's dominant-baseline to the text-before-edge and text-after-edge baselines.

4.3 Spaces and Conditionality

A space-specifier is a compound datatype whose components are 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 an enumerated value which controls whether a space-specifier has effect at the beginning or end of a reference-area or a line-area. Possible values are retain and discard; a conditional space-specifier is one for which this value is discard.

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.

4.3.1 Space-resolution Rules

To compute the resolved space-specifier of a given space-specifier S, consider the maximal inline-stacking constraint or block-stacking constraint containing S. The resolved space-specifier of S is a non-conditional space-specifier computed in terms of this sequence.

1. If any of the space-specifiers (in the maximal sequence) is conditional, and begins a reference-area or line-area, then it is suppressed, which means that its resolved space-specifier is zero. Further, any conditional space-specifiers which consecutively follow it in the sequence are also suppressed.

   If a conditional space-specifier ends a reference-area or line-area, then it is suppressed together with any other conditional space-specifiers which consecutively precede it in the sequence.

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 numerically 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, when there are at two or more space-specifiers all of the same highest precedence and the same (largest) optimum, 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 discard; second, a space with value 4 points and conditionality retain; and third, a space with value 5 points and conditionality discard; 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.

The padding of a block-area does not interact with the any space-specifier (except that by definition, the presence of padding at the before- or after-edge prevents areas on either side of it from having a stacking constraint.)

The border or padding at the before-edge or after-edge of a block-area may be specified as conditional. If so, then it is set to zero if its associated edge is a leading or trailing edge in a reference-area. In this case, the border or padding is taken to be zero for purposes of the stacking constraint definitions.

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. 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 areas have these traits, but they only have relevance for areas which have stacked line-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 its block-progression-dimension to accommodate its descendants. Alternatively the generating formatting object may specify a block-progression-dimension 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 block-areas. However, formatting objects are free to specify other methods of positioning child areas of areas which they generate, for example list-items or tables.

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. For each block-area B 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 (where R is the closest ancestor reference-area of B), and offset from it inward 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 inward 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.

2. For each pair of normal areas B and B' in the subtree below P, if B and B' have a block-stacking constraint S, then the distance between the adjacent edges of B and B' is consistent with the constraint imposed by the resolved values of the space-specifiers in S.

NOTE:

The start-intrusion-adjustment and end-intrusion-adjustment are traits used to deal with intrusions from floats in the inline-progression-direction. 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.

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.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. Inline-areas are stacked within a line-area relative to a baseline-start-point which is a point determined by the formatter, on the start-edge of its content-rectangle.

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 whose start-edge and end-edge are parallel to and coincident with the start-edge and end-edge of the content-rectangle of the parent block-area (as modified by typographic properties such as indents), whose before-edge is separated from the baseline-start-point by the text-before-baseline-height, and whose after-edge is separated from the baseline-start-point by the text-after-baseline-height. It has the same block-progression-dimension for each line-area child of a block-area.

The maximum-line-rectangle for a line-area is the rectangle whose start-edge and end-edge are parallel to and coincident with the start-edge and end-edge of the nominal-requested-line-rectangle, and whose extent in the block-progression-direction is the minimum required to enclose both the nominal-requested-line-rectangle and the allocation-rectangles of all the inline-areas stacked within the line-area; this may vary depending on the descendants of the line-area.

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 block-progression-dimension. The expanded-rectangle of an inline-area is the rectangle with start-edge and end-edge coincident with those of its allocation-rectangle, and whose before-edge and after-edge are outside those of its allocation-rectangle by a distance equal to the half-leading. The per-inline-height-rectangle is then defined to have the minimum block-progression-dimension required to enclose both the nominal-requested-line-rectangle and the expanded-rectangles of all the inline-areas stacked within the line-area; this 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.

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 baseline table for its nominal-font. It has a dominant-baseline trait which determines how its stacked inline-area descendants are to be aligned.

An inline-area may or may not have child areas, and if so it may or may not be a reference-area. The dimensions of the content-rectangle for an inline-area without children is computed as specified by the generating formatting object, as are those of an inline-area with block-area children.

An inline-area with inline-area 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 from its position-point by at least the after-baseline-height in the block-progression-direction, and in the opposite direction by at least the before-baseline-height from its position-point (these latter quantities derived from the nominal-font of the area, as defined in section [4.2.6 Font Baseline Tables]).

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 inline-areas.

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 inline-area descendant I of P, the start-edge, end-edge, before-edge and after-edge of the allocation-rectangle of I are parallel to corresponding edges of the content-rectangle of the nearest ancestor reference-area of I.

2. For each pair of normal areas I and I' in the subtree below P, if I and I' have an inline-stacking constraint S, then the distance between the adjacent edges of I and I' is consistent with the constraint imposed by the resolved values of the space-specifiers in S.

3. For any 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 distance between the dominant-baseline of P and the preferred baseline of I (as determined by the dominant-baseline table of P), plus the sum of the baseline-shifts for I and all of its ancestors which are descendants of P. This alignment is done with respect to the line-area's dominant-baseline, and not with respect to the baseline of any intermediate area.

   The first summand is computed to compensate for mixed writing systems with different nominal glyph baselines, and the other summands involve deliberate baseline shifts for things like superscripts and subscripts.

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 an associated nominal-font, determined by the area's typographic traits, which apply to its character data, and a glyph-orientation determined by its writing-mode and reference-orientation, which determine the orientation of the glyph when it is rendered.

The position-point and preferred baseline of a glyph-area are assigned according to the writing-system in use (e.g., the glyph baseline in Western 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 writing systems.

A glyph-area has no children. Its block-progression-dimension and baseline table are the same for all glyphs in a font.

4.10 Ordering Constraints

4.10.1 General Ordering Constraints

A subset S of the areas returned to a formatting object is called properly ordered if the areas in that subset have the same order as their generating formatting objects. Specifically, if A₁ and A₂ are areas in S, returned by child formatting objects F₁ and F₂ where F₁ precedes F₂, then A₁ must precede A₂ in the pre-order traversal order of the area tree. If F₁ equals F₂ and A₁ is returned prior to A₂, then A₁ must precede A₂ in the pre-order-traversal of the area tree.

For each formatting object F and each area-class C, the subset consisting of the areas returned to F with area-class C must be properly ordered, except where otherwise specified.

4.10.2 Line-building

This section describes the ordering constraints that apply to formatting an fo:block or similar block-level object.

A block-level formatting object F which constructs lines does so by constructing block-areas which it returns to its parent formatting object, and placing normal areas returned to F by its child formatting objects as children of those block-areas or of line-areas which it constructs as children of those block-areas.

For each such formatting object F, it must be possible to form an ordered partition P consisting of ordered subsets S₁, S₂, ..., S_n of the normal areas returned by the child formatting objects, such that the following are all satisfied:

1. Each subset consists of a sequence of inline-areas, or of a single block-area.

2. The ordering of the partition follows the ordering of the formatting object tree. Specifically, if A is in S_i and B is in S_j with i < j, or if A and B are both in the same subset S_i with A before B in the subset order, then either A is returned by a preceding sibling formatting object of B, or A and B are returned by the same formatting object with A being returned before B.

3. The partitioning occurs at legal line-breaks. Specifically, if A is the last area of S_i and B is the first area of S_i+1, then the rules of the language and script in effect must permit a line-break between A and B, within the context of all areas in S_i and S_i+1.

4. The partition follows the ordering of the area tree, except for certain glyph substitutions and deletions. Specifically, if B₁, B₂, ..., B_p are the normal child areas of the area or areas returned by F, (ordered in the pre-order traversal order of the area tree) then there is a one-to-one correspondence between these child areas and the partition subsets (i.e., n = p), and for each i,

   • if S_i consists of a single block-area then B_i is that block-area, and

   • if S_i consists of inline-areas then B_i is a line-area whose child areas are the same as the inline-areas in S_i, and in the same order, except that where the rules of the language and script in effect call for glyph-areas to be substituted, inserted, or deleted, then the substituted or inserted glyph-areas appear in the area tree in the corresponding place, and the deleted glyph-areas do not appear in the area tree. Deletions occur when a glyph-area which is first or last within a subset, has a suppress-at-line-break value of suppress. Insertions and substitutions may occur because of addition of hyphens or spelling changes due to hyphenation, or glyph image construction from syllabification, or ligature formation.

Substitutions that replace a sequence of glyph-areas with a single glyph-area should only occur when the margin, border, and padding in the inline-progression-direction (start- and end-), baseline-shift, and letter-spacing values are zero, treat-as-word-space is false, and the values of all other relevant traits match (i.e., alignment-adjust, baseline-identifier, color trait, background traits, dominant-baseline, font traits, font-height-override-after, font-height-override-before, glyph-orientation-horizontal, glyph-orientation-vertical, line-height, line-height-shift-adjustment, text-decoration, text-shadow).

NOTE:

Line-areas do not receive the background traits or text-decoration of their generating formatting object, or any other trait that requires generation of a mark during rendering.

4.10.3 Inline-building

This section describes the ordering constraints that apply to formatting an fo:inline or similar inline-level object.

An inline-level formatting object F which constructs one or more inline-areas does so by placing normal inline-areas returned to F by its child formatting objects as children of inline-areas which it generates.

For each such formatting object F, it must be possible to form an ordered partition P consisting of ordered subsets S₁, S₂, ..., S_n of the normal inline-areas returned by the child formatting objects, such that the following are all satisfied:

1. Each subset consists of a sequence of inline-areas

2. The ordering of the partition follows the ordering of the formatting object tree, as defined above.

3. The partitioning occurs at legal line-breaks, as defined above.

4. The partition follows the ordering of the area tree, except for certain glyph substitutions and deletions, as defined above (except that the case where S_i is a block-area does not arise).

4.11 Keeps and Breaks

Keep and break conditions apply to a class of areas, which are typically page-reference-areas, column-areas, and line-areas. The appropriate class for a given condition is referred to as a context and an area in this class is a context-area. As defined in Section [6.4.1 Introduction], page-reference-areas are areas generated by an fo:page-sequence using the specifications in a fo:page-master, and column-areas are reference-areas generated from a region-master.

A keep or break condition is an open statement about a formatting object and the tree relationships of the areas it generates with the relevant context-areas. These tree relationships are defined mainly in terms of leading or trailing areas. If A is a descendant of P, then A is defined to be leading in P if A has no preceding sibling which is a normal area, nor does any of its ancestor areas up to but not including P. Similarly, A is defined to be trailing in P if A has no following sibling which is a normal area, nor does any of its ancestor areas up to but not including P. For any given formatting object, the next formatting object in the flow is the first formatting object following (in the pre-order traversal order) which generates and returns normal areas.

Break conditions are either break-before or break-after conditions. A break-before condition is satisfied if the first area generated and returned by the formatting object is leading within a context-area. A break-after condition depends on the next formatting object in the flow; it is satisfied if either there is no such next formatting object, or if the first normal area generated and returned by that formatting object is leading in a context-area.

Break conditions are imposed by the break-before and break-after properties. A refined value of page for these traits imposes a break condition with a context consisting of the page-reference-areas; a value of even-page or odd-page imposes a break condition with a context of even-numbered page-reference-areas or odd-numbered page-reference-areas, respectively; a value of column imposes a break condition with a context of column-areas. A value of auto in a break-before or break-after trait imposes no break condition.

Keep conditions are either keep-with-previous, keep-with-next, or keep-together conditions. A keep-with-previous condition on an object is satisfied if the first area generated and returned by the formatting object is not leading within a context-area, or if there are no preceding areas in a post-order traversal of the area tree. A keep-with-next condition is satisfied if the last area generated and returned by the formatting object is not trailing within a context-area, or if there are no following areas in a pre-order traversal of the area tree. A keep-together condition is satisfied if all areas generated and returned by the formatting object are descendants of a single context-area.

Keep conditions are imposed by the "within-page", "within-column", and "within-line" components of the keep-with-previous, keep-with-next, and keep-within properties. The refined value of each component specifies the strength of the keep condition imposed, with higher numbers being stronger than lower numbers and the value always being stronger than all numeric values. A component with value auto does not impose a keep condition. A "within-page" component imposes a keep-condition with context consisting of the page-reference-areas; "within-column", with context consisting of the column-areas; and "within-line" with context consisting of the line-areas.

The area tree is constrained to satisfy all break conditions imposed. Each keep condition must also be satisfied, except when this would cause a break condition or a stronger keep condition to fail to be satisfied. If not all of a set of keep conditions of equal strength can be satisfied, then some maximal satisfiable subset of conditions of that strength must be satisfied (together with all break conditions and maximal subsets of stronger keep conditions, if any).

4.12 Rendering Model

This section makes explicit the relationship between the area tree and visually rendered output.

Areas generate three types of marks: (1) the area background, if any, (2) the marks intrinsic to the area (a glyph, image, or decoration) if any, and (3) the area border, if any.

An area tree is rendered by causing marks to appear on an output medium in accordance with the areas in the area tree. This section describes the geometric location of such marks, and how conflicts between marks are to be resolved.

4.12.1 Geometry

Each area is rendered in a particular location. Formatting object semantics describe the location of instrinsic marks relative to the object's location, i.e., the left, right, top and bottom edges of its content-rectangle. This section describes how the area's location is determined, which determines the location of its intrinsic marks.

For each page, the page-viewport-area corresponds isometrically to the output medium.

The page-reference-area is offset from the page-viewport-area as described below in section [4.12.2 Viewport Geometry].

All areas in the tree with an area-class of xsl-fixed are positioned such that the left-, right-, top-, and bottom-edges of its content-rectangle are offset inward from the content-rectangle of its ancestor page-viewport-area by distances specified by the left-position, right-position, top-position, and bottom-position traits, respectively.

Any area in the tree which is the child of a viewport-area is rendered as described in section [4.12.2 Viewport Geometry].

All other areas in the tree are positioned such that the left-, right-, top-, and bottom-edges of its content-rectangle are offset inward from the content-rectangle of its nearest ancestor reference-area by distances specified by the left-position, right-position, top-position, and bottom-position traits, respectively. These are shifted left and down by the values of the top-offset and left-offset traits, respectively, if the area has a relative-position of relative.

4.12.2 Viewport Geometry

A reference-area which is the child of a viewport-area is positioned such that the start-edge and end-edge of its content-rectangle are coincident with the start-edge and end-edge of the content-rectangle of its parent viewport-area, and the before-edge of its content-rectangle is offset from the before-edge of the content-rectangle of its parent viewport-area by a scroll-amount.

If the block-progression-dimension of the reference-area is larger than that of the viewport-area and the overflow trait for the reference-area is scroll, then the scroll-amount is determined by a scrolling mechanism, if any, provided by the user agent. Otherwise, the scroll-amount is zero.

4.12.3 Visibility

The visibility of marks depends upon the location of the marks, the visibility of the area, and the overflow of any ancestor viewport-areas.

If an area has visibility hidden it generates no marks.

If an area has an overflow of hidden, or when the environment is non-dynamic and the overflow is scroll then the area determines a clipping rectangle, which is defined to be the rectangle determined by the value of the clip trait of the area, and for any mark generated by one of its descendant areas, portions of the mark lying outside the clipping rectangle do not appear.

4.12.4 Border, Padding, and Background

The border- and padding-rectangles are determined relative to the content-rectangle by the values of the common padding and border width traits (border-before-width, etc.).

For any area which is not a child of a viewport-area, the border is rendered between the border-rectangle and the padding-rectangle in accordance with the common border color and style traits. For a child of a viewport-area, the border is not rendered.

For an area which is not part of a viewport/reference pair, the background is rendered. For an area that is either a viewport-area or a reference-area in a viewport/reference pair, if the refined value of background-attachment is scroll and the block-progression-dimension of the reference-area is larger than that of the viewport-area, then the background is rendered on the reference-area and not the viewport-area, and otherwise it is rendered on the viewport-area and not the reference-area.

The background, if any, is rendered in the padding-rectangle, in accordance with the background-image, background-color, background-repeat, background-position-vertical, and background-position-horizontal traits.

4.12.5 Intrinsic Marks

For each class of formatting objects, the marks intrinsic to its generated areas are specified in the formatting object description. For example, an fo:character object generates a glyph-area, and this is rendered by drawing a glyph within that area's content-rectangle in accordance with the area's font traits and glyph-orientation and blink traits.

In addition, other traits (for example the various score and score-color traits) specify other intrinsic marks. In the case of score traits (underline-score, overline-score and through-score), the score thickness and position are specified by the nominal-font in effect; where the font fails to specify these quantities, they are implementation-dependent.

4.12.6 Layering and Conflict of Marks

Marks are layered as described below, which defines a partial ordering of which marks are beneath which other marks.

Two marks are defined to conflict if they apply to the same point in the output medium. When two marks conflict, the one which is beneath the other does not affect points in the output medium where they both apply.

Marks generated by the same area are layered as follows: the area background is beneath the area's intrinsic marks, and the intrinsic marks are beneath the border. Layering among the area's intrinsic marks is defined by the semantics of the area's generating formatting object and its properties. For example, a glyph-area's glyph drawing comes beneath the marks generated for text-decoration.

If A and B are areas, and the z-index of A is less than the z-index of B, then all marks generated by A are beneath all marks generated by B.

If A and B are areas with the same z-index, the backgrounds of A and B come beneath all other marks generated by A and B. Further, if A is an ancestor of B (still with the same z-index), then the background of A is beneath all the areas of B, and all the areas of B are beneath the intrinsic areas (and border) of A.

If A and B have the same z-index and neither is an ancestor of the other, then it is an error if either their backgrounds conflict or if a non-background mark of A conflicts with a non-background mark of B. An implementation may recover by proceeding as if the marks from the first area in the pre-order traversal order are beneath those of the other area.

4.13 Sample Area Tree

4.14 List of Traits on Areas

• block-progression-direction

• inline-progression-direction

• shift-direction

• glyph-orientation

• is-reference-area

• is-viewport-area

• left-position

• right-position

• top-position

• bottom-position

• left-offset

• top-offset

• is-first

• is-last

• position-point

• area-class

• start-intrusion-adjustment

• end-intrusion-adjustment

• generated-by

• returned-by

• page-number

• blink

• underline-score

• overline-score

• through-score

• underline-score-color

• overline-score-color

• through-score-color

5 Property Refinement / Resolution

During refinement the set of properties that apply to a formatting object is transformed into a set of traits that define constraints on the result of formatting. For many traits there is a one-to-one correspondence with a property; for other traits the transformation is more complex. Details on the transformation are described below.

The first step in refinement of a particular formatting object is to obtain the effective value of each property that applies to the object. Any shorthand property specified on the formatting object is expanded into the individual properties. This is further described in [5.2 Shorthand Expansion]. For any property that has not been specified on the object the inherited (see [5.1.4 Inheritance]) or initial value, as applicable, is used as the effective value. The second step is to transform this property set into traits.

NOTE:

Although the refinement process is described in a series of 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.

5.1 Specified, Computed, and Actual Values, and Inheritance

For every property that is applicable to 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-construction process. A specified value may not be in a form that is directly usable; for example, it may be a percentage or other expression 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 medium 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 specified on the formatting object. In general, this is an error.

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%"), or they may be expressions. 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 a relative unit (em) must be made absolute by multiplying with the appropriate font 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. The computed value of any property that controls a border width where the style of the border is "none" is forced to be "0pt".

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 [5.3 Computing the Values of Corresponding Properties].

In most cases, elements inherit computed values. However, there are some properties whose specified value may be inherited (e.g., the 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.1.4 Inheritance

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 formatting object tree from a parent to each child. (These properties 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 descendants until explicitly re-set in a lower descendant); 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.2 Shorthand Expansion

In XSL there are two kinds of shorthand properties; those originating from CSS, such as "border", and those that arise from breaking apart and/or combining CSS properties, such as "page-break-inside". In XSL both types of shorthands are handled in the same way.

NOTE:

Shorthands are only included in the highest XSL conformance level; "complete".

The conformance level for each property is shown in [C.3 Property Table: Part II].

Shorthand properties do not inherit from the shorthand on the parent. Instead the individual properties that the shorthand expands into may inherit.

Some CSS shorthands are interrelated; their expansion has one or more individual properties in common. 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 a precedence order when multiple interrelated shorthand properties or a shorthand property and an interrelated individual property are specified:

They are processed in increasing precision (i.e., "border" is less precise than "border-top", which is less precise than "border-top-color"). The individual properties are always more precise than any shorthand. For the remaining ambiguous case, XSL defines the ordering to be:

1. "border-style", "border-color", and "border-width" is less precise than

2. "border-top", "border-bottom", "border-right", and "border-left".

Processing is conceptually in the following steps:

1. Set the effective value of all properties to their initial values.

2. Process all shorthands in increasing precision.

   If the shorthand is set to "inherit": set the effective value of each property that can be set by the shorthand to the computed value of the corresponding property in the parent.

   If the value of the shorthand is not "inherit": determine which individual properties are to be set, and replace the initial-value with the computed value derived from the specified value.

3. Process all specified individual properties.

4. Carry out any inheritance for properties that were not given a value other than by the first step.

NOTE:

For example, if both the "background" and the "background-color" properties are specified on a given formatting object: process the "background" shorthand, then process the "background-color" property.

5.3 Computing the Values of Corresponding Properties

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 on the object. See description below.

The correspondance mapping from absolute to relative property is as follows:

If the "writing-mode" specifies a block-progression-direction of "top-to-bottom": "top" maps to "before", and "bottom" maps to "after".

If the "writing-mode" specifies a block-progression-direction of "bottom-to-top": "top" maps to "after", and "bottom" maps to "before".

If the "writing-mode" specifies a block-progression-direction of "left-to-right": "left" maps to "before", and "right" maps to "after".

If the "writing-mode" specifies a block-progression-direction of "right-to-left": "left" maps to "after", and "right" maps to "before".

If the "writing-mode" specifies an inline-progression-direction of "left-to-right": "left" maps to "start", and "right" maps to "end".

If the "writing-mode" specifies an inline-progression-direction of "right-to-left": "left" maps to "end", and "right" maps to "start".

If the "writing-mode" specifies an inline-progression-direction of "top-to-bottom": "top" maps to "start", and "bottom" maps to "end".

If the "writing-mode" specifies an inline-progression-direction of "bottom-to-top": "top" maps to "end", and "bottom" maps to "start".

If the "writing-mode" specifies an inline-progression-direction of "left-to-right" for odd-numbered lines, and "right-to-left" for even-numbered lined: "left" maps to "start", and "right" maps to "end".

NOTE:

"reference-orientation" is a rotation and does not influence the correspondance mapping.

5.3.1 Border and Padding Properties

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".

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 corresponding relative property.

Note that if both the absolute and the relative properties are not explicitly specified, then the rules for determining the specified 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 Margin, Space, and Indent Properties

The "space-before", and "space-after" properties (block-level formatting objects), "space-start", and "space-end" properties (inline-level formatting objects) are handled in the same way as the properties immediately above, but the corresponding absolute properties are in the set: "margin-top", "margin-bottom", "margin-left", and "margin-right".

There are two more properties, "end-indent" and "start-indent" (block-level formatting objects), 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 "start-indent", and "end-indent" properties are as follows (where "margin-corresponding" is a variable 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 explicitly 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.3.3 Height, and Width Properties

Based on the writing-mode in effect for the formatting object, either the "height", "min-height", and "max-height" properties, or the "width", "min-width", and "max-width" properties are converted to the corresponding block-progression-dimension, or inline-progression-dimension.

The "height" properties are absolute and indicate the dimension from "top" to "bottom"; the width properties the dimension from "left" to "right".

If the "writing-mode" specifies a block-progression-direction of "top-to-bottom" or "bottom-to-top" the conversion is as follows:

• If any of "height", "min-height", or "max-height" is specified:

  • If "height" is specified then first set:

    block-progression-dimension.minimum=<height>

    block-progression-dimension.optimum=<height>

    block-progression-dimension.maximum=<height>

  • If "height" is not specified, then first set:

    block-progression-dimension.minimum=auto

    block-progression-dimension.optimum=auto

    block-progression-dimension.maximum=auto

  • Then, if "min-height" is specified, reset:

    block-progression-dimension.minimum=<min-height>

  • Then, if "max-height" is specified, reset:

    block-progression-dimension.minimum=<max-height>

  • However, if "max-height" is specified as "none", reset:

    block-progression-dimension.minimum=auto

• If any of "width", "min-width", or "min-width" is specified:

  • If "width" is specified then first set:

    inline-progression-dimension.minimum=<width>

    inline-progression-dimension.optimum=<width>

    inline-progression-dimension.maximum=<width>

  • If "width" is not specified, then first set:

    inline-progression-dimension.minimum=auto

    inline-progression-dimension.optimum=auto

    inline-progression-dimension.maximum=auto

  • Then, if "min-width" is specified, reset:

    inline-progression-dimension.minimum=<min-width>

  • Then, if "max-width" is specified, reset:

    inline-progression-dimension.minimum=<max-width>

  • However, if "max-width" is specified as "none", reset:

    inline-progression-dimension.minimum=auto

If the "writing-mode" specifies a block-progression-direction of "left-to-right" or "right-to-left" the conversion is as follows:

• If any of "height", "min-height", or "max-height" is specified:

  • If "height" is specified then first set:

    inline-progression-dimension.minimum=<height>

    inline-progression-dimension.optimum=<height>

    inline-progression-dimension.maximum=<height>

  • If "height" is not specified, then first set:

    inline-progression-dimension.minimum=auto

    inline-progression-dimension.optimum=auto

    inline-progression-dimension.maximum=auto

  • Then, if "min-height" is specified, reset:

    inline-progression-dimension.minimum=<min-height>

  • Then, if "max-height" is specified, reset:

    inline-progression-dimension.minimum=<max-height>

  • However, if "max-height" is specified as "none", reset:

    inline-progression-dimension.minimum=auto

• If any of "width", "min-width", or "min-width" is specified:

  • If "width" is specified then first set:

    block-progression-dimension.minimum=<width>

    block-progression-dimension.optimum=<width>

    block-progression-dimension.maximum=<width>

  • If "width" is not specified, then first set:

    block-progression-dimension.minimum=auto

    block-progression-dimension.optimum=auto

    block-progression-dimension.maximum=auto

  • Then, if "min-width" is specified, reset:

    block-progression-dimension.minimum=<min-width>

  • Then, if "max-width" is specified, reset:

    block-progression-dimension.minimum=<max-width>

  • However, if "max-width" is specified as "none", reset:

    block-progression-dimension.minimum=auto

5.3.4 Overconstrained Geometry

The sum of the start-indent, end-indent, and inline-progression-dimension of the content-rectangle of an area should be equal to the inline-progression-dimension of the content-rectangle of the closest ancestor reference-area. In the case where a specification would lead to them being different the end-indent (and thus the corresponding margin) is adjusted such that the equality is true.

5.4 Simple Property to Trait Mapping

The majority of the properties map into traits of the same name. Most of these also simply copy the value from the property. These are classified as "Rendering", "Formatting", "Specification", "Font selection", "Reference", and "Action" in the property table in [C.3 Property Table: Part II]. For example, the property font-style="italic" is refined into a font-style trait with a value of "italic".

Some traits have a value that is different from the value of the property. These are classified as "Value change" in the property table. For example, the property background-position-horizontal="left" is refined into a background-position-horizontal trait with a value of "0pt". The value mapping for these traits is given below.

5.4.1 Background-position-horizontal and background-position-vertical Properties

A value of "top", "bottom", "left", "right", or "center" is converted to a length as specified in the property definition.

5.4.2 Column-number Property

If a value has not been specified on a formatting object to which this property applies the initial value is computed as specified in the property definition.

5.4.3 Text-align Property

A value of "left", or "right" is converted to the writing-mode relative value as specified in the property definition.

5.4.4 Text-align-last Property

A value of "left", or "right" is converted to the writing-mode relative value as specified in the property definition.

5.4.5 z-index Property

The value is converted to one that is absolute; i.e., the refined value is the specified value plus the refined value of z-index of its parent formatting object, if any.

5.5 Complex Property to Trait Mapping

A small number of properties influence traits in a more complex manner. Details are given below.

5.5.1 Word-spacing and Letter-spacing Properties

These properties may set values for the start-space and end-space traits, as described in the property definitions.

5.5.2 Reference-orientation Property

• If this area sets a reference-area:

  1. Let A be the area whose traits are being determined;

  2. Let F be the formatting object that generates area A;

  3. Let N be the nearest ancestor formatting object, including self, to F such that N generates a reference-area that is an ancestor of A in the area tree:

     Then, the reference-orientation trait for A is set to the modulo-360 sum of the "reference-orientation" property on F and the value established by the "reference-orientation" property of formatting object N (recursively).

• All other areas:

  1. Let A be the area whose traits are being determined;

  2. Let F be the formatting object that generates area A;

  3. Let N be the nearest ancestor formatting object, including self, to F such that N generates a reference-area that is an ancestor of A in the area tree:

     Then, the reference-orientation trait for A is set to the value established by the "reference-orientation" property of formatting object N.

5.5.3 Writing-mode and Direction Properties

The direction traits on an area are indirectly derived from the "writing-mode", "direction" and "unicode-bidi" properties on the formatting object that generates the area or the formatting object ancestors of that formatting object. The exact derivation depends on the trait.

• block-progression-direction trait:

  • Let A be the area whose traits are being determined;

  • Let F be the formatting object that generates area A;

  • Let N be the nearest ancestor formatting object, including self, to F such that N generates a reference-area that is an ancestor of A in the area tree:

    Then, the block-progression-direction trait for A is set to the block-progression-direction established by the "writing-mode" property of formatting object N.

• inline-progression-direction trait:

  • Let A be the area whose traits are being determined;

  • Let F be the formatting object that generates area A;

  • Let N be the nearest ancestor formatting object, including self, to F such that at least one of the following conditions is satisfied:

    • N generates a reference-area that is an ancestor to A in the area tree, or

    • N is a block-level formatting object and the glyph-orientation of N is either 0 or 180 degrees, in which case, the "direction" property establishes the inline-progression-direction for N, or

      NOTE:

      The above condition is complex because direction changes in vertical text only affect the rotated non-ideographic text; that is they only affect the Latin or Arabic/Hebrew half-width characters.

    • N is an inline formatting object and has a "unicode-bidi" property with a value of either "embed" or "override", in which case, the "direction" property establishes an inline-progression-direction for N.

    Then, the inline-progression-direction trait for A is set to the inline-progression-direction established by formatting object N. If N has both a "writing-mode" and a "direction" property that establishes the inline-progression-direction then the "direction" property's overrides that established by the "writing-mode".

    The final inline-progression-direction-trait may be further modified by the formatter's application of the unicode-bidi rule, and for alternating lines in the extended set of international writing-modes.

• shift-direction trait:

  • Let A be the area whose traits are being determined;

  • Let F be the formatting object that generates area A;

  • Let N be the nearest ancestor formatting object, including self, to F such that N generates a reference-area that is an ancestor of A in the area tree:

    Then, the shift-direction trait for A is set to the shift-direction established by the "writing-mode" property of formatting object N.

    The shift-direction-trait may be further modified by the formatter for inverted lines in the extended set of international writing-modes.

5.5.4 Absolute-position Property

If absolute-position = "absolute" or "fixed", the values of the left-position, top-position, etc. traits are copied directly from the values of the "left", "top", etc. properties. Otherwise these traits' values are left undefined during refinement and determined during composition.

5.5.5 Relative-position Property

If relative-position = "relative" then the values of the left-offset and top-offset traits are copied directly from the "left" and "top" properties. If the "right" property is specified but "left" is not, then left-offset is set to the negative of the value of "right". If neither "left" nor "right" is specified the left-offset is 0. If the "bottom" property is specified but "top" is not, then top-offset is set to the negative of the value of "bottom". If neither "top" nor "bottom" is specified the top-offset is 0.

5.5.6 Text-decoration Property

The "text-decoration" property value provides values for the blink trait and a set of score and score-color traits. The specified color has the value of the color trait of the formatting object for which the "text-decoration" property is being refined.

A property value containing the token "underline" sets a value of "yes" to the underline-score trait, and a value of specified color to the underline-score-color trait.

A property value containing the token "overline" sets a value of "yes" to the overline-score trait, and a value of specified color to the overline-score-color trait.

A property value containing the token "line-through" sets a value of "yes" to the through-score trait, and a value of specified color to the through-score-color trait.

A property value containing the token "blink" sets a value of "yes" to the blink trait.

A property value containing the token "no-underline" sets a value of "no" to the underline-score trait, and a value of specified color to the underline-score-color trait.

A property value containing the token "no-overline" sets a value of "no" to the overline-score trait, and a value of specified color to the overline-score-color trait.

A property value containing the token "no-line-through" sets a value of "no" to the through-score trait, and a value of specified color to the through-score-color trait.

A property value containing the token "no-blink" sets a value of "no" to the blink trait.

5.6 Non-property Based Trait Generation

The is-reference-area trait is set to "true" for the following formatting objects: "simple-page-master", "title", "region-body", "region-before","region-after", "region-start", "region-end", "block-container", "inline-container", "table", "table-caption", and "table-cell". For all other formatting objects it is set to "false".

5.7 Property Based Transformations

5.7.1 Text-transform Property

The case changes specified by this property are carried out during refinement by changing the value of the "character" property appropriately.

NOTE:

The use of the "text-transform" property is deprecated in XSL due to its severe internationalization issues.

5.8 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.8.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.8.12 Expression Value Conversions].

5.8.2 Evaluation Order

When a set of properties is being evaluated for a specific formatting object in the formatting object 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 parent element. 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.8.3 Basics

5.8.4 Function Calls

5.8.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 would mean 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.8.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 the operation be absolute 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 expected 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.8.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.8.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.8.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.7.2 "font-size"]

5.8.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.8.12 Expression Value Conversions].

5.8.9 Colors

A color is a set of values used to identify a particular color from a color space. Only RGB and ICC colors are included in this Recommendation.

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

5.8.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.8.10.1 inherit

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

5.8.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.8.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.8.13 Definitions of Units of Measure

The units of measure in this recommendation have the following definitions:

5.8.13.1 Pixels

XSL interprets a 'px' unit to be a request for the formatter to choose a device-dependent measurement that approximates viewing one pixel on a typical computer monitor. This interpretation is follows:

1. The preferred definition of one 'px' is:

   • The actual distance covered by the largest integer number of device dots (the size of a device dot is measured as the distance between dot centers) that spans a distance less-than-or-equal-to the distance specified by the arc-span rule in CSS-2 [... CSS2/syndata.html#x39] (for print, desktop computer monitors, and hand-held devices viewed at normal viewing distances this is assumed to be 0.28mm [approximately 1/90]).

   • A minimum of the size of 1 device dot should be used.

   • This calculation is done separately in each axis, and may have a different value in each axis.

2. However, implementors may instead simply pick a fixed conversion factor, treating 'px' as an absolute unit of measurement (such as 1/92" or 1/72").

NOTE:

Pixels should not be mixed with other absolute units in expressions as they may cause undesirable effects. Also, particular caution should be used with inherited property values that may have been specified using pixels.

If the User Agent chooses a measurement for a 'px' that does not match an integer number of device dots in each axis it may produce undesirable effects, such as:

• moiré patterns in scaled raster graphics

• unrenderable overlapping areas when the renderer rounds fonts or graphics sizes upward to its actual dot-size

• large spaces between areas when the renderer rounds fonts or graphics sizes downward to its actual dot-size

• unreadable results including unacceptably small text/layout (for example, a layout was done at 72 dpi [dots per inch], but the renderer assumed the result was already specified in device dots and renders it at 600 dpi).

Stylesheet authors should understand a pixel's actual size may vary from device to device:

• stylesheets utilizing 'px' units may not produce consistent results across different implementations or different output devices from a single implementation

• even if stylesheets are expresses entirely in 'px' units the results may vary on different devices

5.9 Core Function Library

5.9.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 expression 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.9.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 icc-color(numeric , numeric , numeric , NCName , numeric , numeric)

The icc-color function returns a specific color from the an ICC Color Profile. The color profile is specified by the name parameter (the fourth parameter). This color profile must have been declared in the fo:declarations formatting object using an fo:color-profile formatting object.

The first three parameters specify a fallback color from the sRGB color space. This color is used when the color profile is not available.

The color is specified by a sequence of one or more color values (real numbers) specified after the name parameter. These values are specific to the color profile

Function: color system-color( NCName)

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

5.9.3 Font Functions

Function: object system-font( NCName , NCName)

The system-font functions 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.9.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 xml result tree in the fo namespace. 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.

Function: numeric proportional-column-width( numeric)

The proportional-column-width function returns proportional factor (the argument) units of proportional measure. The column widths are first determined ignoring the proportional measures. The difference between the table-width and the sum of the column widths is the available proportional width. One unit of proportional measure is the available proportional width divided by the sum of the proportional factors. It is an error to use this function on formatting objects other than an fo:table-column. It is also an error to use this function if the fixed table layout is not used.

Function: object merge-property-values( NCName)

The merge-property-values function returns a value of the property whose name matches the argument. The value returned is the specified value on the last fo:multi-property-set, of the parent fo:multi-properties, that applies to the User Agent state. If there is no such value, the computed value of the parent fo:multi-properties is returned.

NOTE:

The test for applicability of a User Agent state is specified using the "active-state" property.

It is an error to use this function on formatting objects other than an fo:wrapper that is the child of an fo:multi-properties.

5.10 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.optimum="3.0pt"
space-before.maximum="4.0pt"
space-before.precedence="0"
space-before.conditionality="discard"

A short form of compound value specification may be used, in cases where the datatype has some numeric components. Such a specification consists of giving a numeric value to an attribute with a name matching a property name. Such a specification gives that value to each of the numeric components and the initial value to all the non-numeric components. For example:

space-before="4.0pt"

is equivalent to a specification of

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

Short forms may be used together with complete forms; the complete forms having precedence over the expansion of a short form. For example:

space-before="4.0pt"
space-before.maximum="6.0pt"

is equivalent to a specification of

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

Compound values of properties are inherited as a unit and not as individual components.

The following datatypes are defined:

<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: minimum, optimum, maximum. Each component is a <length>. A property may define additional constraints on the values.

<length-conditional>

A compound datatype, with components: length, conditionality. The length component is a <length>. The conditionality component is either "discard" or "retain". A property may define additional constraints on the values.

<length-bp-ip-direction>

A compound datatype, with components: block-progression-direction, and inline-progression-direction. Each component is a <length>. A property may define additional constraints on the values.

<space>

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

<keep>

A compound datatype, with components: within-line, within-column, and within-page. The value of each component is either "auto", "always", or an <integer>.

<angle>

An <integer> representing an angle.

<percentage>

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

<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>

Either a string of characters representing a keyword or a color function defined in [5.9.2 Color Functions]. The list of keyword color names is: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, and yellow.

<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.

<uri-reference>

A sequence of characters conforming to a "URI-reference" as defined in RFC 2396.

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 auxiliary 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, or is a substituted form of one of the areas thus generated, as specified in section [4.10.2 Line-building].

In the case of substituted glyph-areas, the generating formatting object is deemed to be the formatting object which generated the glyph-area which comes first in the sequence of substituted glyph-areas. In the case of an inserted glyph-area (e.g., an automatically-generated hyphen) the generating formatting object is deemed to be the generating formatting object of the last glyph-area preceding the inserted glyph-area in the pre-order traversal of the area tree.

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", "xsl-absolute", "xsl-footnote", "xsl-side-float", or "xsl-before-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. (See section [4.2.5 Stacking Constraints].)

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 expressible 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-foreign-object
     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 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.

color-profile

Used to declare a color profile for a stylesheet.

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.

declarations

Used to group global declarations for a stylesheet.

external-graphic

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

float

The fo:float serves two purposes. It can be used so that during the normal placement of content, some related content is formatted into a separate area at beginning of the page (or of some following page) where it is available to be read without immediately intruding on the reader. Alternatively, it can be used when an area is intended to float to one side, with normal content flowing alongside.

flow

The content of the fo:flow formatting object is a sequence of flow objects that provides the flowing text content that is distributed into pages.

footnote

The fo:footnote is used to produce a footnote citation and the corresponding footnote.

footnote-body

The fo:footnote-body is used to generate the content of the footnote.

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-foreign-object

The fo:instream-foreign-object flow object is used for an inline graphic or other "generic" object where the object data resides as descendants of the fo:instream-foreign-object.

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 may be used for connecting two text formatting objects.

list-block

The fo:list-block flow object is used to format 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.

marker

The fo:marker is used in conjunction with fo:retrieve-marker to produce running headers or footers.

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 User Agent 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 normal area returned 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/reference pair 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.

retrieve-marker

The fo:retrieve-marker is used in conjunction with fo:marker to produce running headers or footers.

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.

title

The fo:title formatting object is used to associate a title with a given document. This title may be used by an interactive User Agent to identify the document. For example, the content of the fo:title can be formatted and displayed in a "title" window or in a "tool tip".

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 Declarations and 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, an optional fo:declarations, 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 (contained in fo:flow and fo:static-content), provide the content that is distributed into the pages. The fo:declarations object is a wrapper for formatting objects whose content is to be used as a resource to the formatting process. 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 any 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-repeats" 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 viewport/reference pair in which the viewport-area is a child of the area tree root. A page-viewport-area is defined to be the viewport-area of a page, and a page-area is defined to be the unique child of a page-viewport-area.

The page-viewport-area is defined by the output medium; the page-area holds the page contents and has the affect of positioning the page contents on the output medium.

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 be used by the fo:page-sequence to 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, in generating viewport/reference pair consisting of a region-viewport-area and a region-reference-area. The region-viewport-area is always a child of a page-area generated using the parent of the region-master.

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 region-viewport-areas generated using the region formatting object. The positioning of the viewport is relative to its page-area parent.

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.

Some types of region have conditional sub-regions associated with them, and the associated region-reference-areas are divided up by having child areas corresponding to the sub-regions, including a "main-reference-area" for the region. For region-masters to which the column-count property applies, the main-reference-area is further subdivided by having child-areas designated as "normal-flow-reference-areas", corresponding to the number of columns specified, as specified in the region-master descriptions.

6.4.1.3 Page Generation

Pages are generated by the formatter's processing of fo:page-sequences. As noted above, each page is a viewport/reference pair in which the viewport-area is a child of the area tree root. Each page is generated using a page-master to define the region-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 a page-master. If the reference is to a page-master, this is interpreted as if it were a reference to an fo:page-sequence-master that repeats the referenced 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 a flow-map. The flow-map is 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 this recommendation, 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-body, region-before, region-after, region-start, and region-end have the default names "xsl-region-body", "xsl-region-before", "xsl-region-after", "xsl-region-start", and "xsl-region-end", respectively.

In addition, an fo:static-content formatting object may have a "region-name" property value of "xsl-before-float-separator" or "xsl-footnote-separator". If a conditional sub-region of the region-body is used to generate a reference-area on a particular page, the fo:static-content whose name corresponds to the conditional sub-region shall be formatted into the reference-area associated with the sub-region, as specified in section [6.10.1.3 Conditional Sub-Regions].

6.4.1.5 Constraints on Page Generation

The areas that are descendants of a page-area are constrained by the page-master used to generate the page-area and the flows that are assigned to the regions specified on the page-master. 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. 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, except that for a fo:static-content with a flow-name of xsl-before-float-separator, the processing is repeated only for those page-reference-areas which have descendant areas with an area-class of xsl-before-float, and for a fo:static-content with a flow-name of xsl-footnote-separator, the processing is repeated only for those page-reference-areas which have descendant areas with an area-class of xsl-footnote.

6.4.1.6 Pagination Tree Structure

The result tree structure is shown below.

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), an optional fo:declarations, 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-viewport-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-viewport-areas returned by the fo:page-sequence children of the fo:root. The set of all areas returned by the fo:page-sequence children is properly ordered. (See Section [4.10.1 General Ordering Constraints].)

Contents:

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

6.4.3 fo:declarations

Common Usage:

The fo:declarations formatting object is used to group global declarations for a stylesheet.

Areas:

The fo:declarations formatting object does not generate or return any areas.

Constraints:

None.

Contents:

(color-profile)+

6.4.4 fo:color-profile

Common Usage:

The fo:color-profile formatting object is used to declare an ICC Color Profile for a stylesheet. The color-profile is referenced again via the name specified in the "color-profile-name" property.

The color-profile is identified by the URI specified in the "src" property value. This URI may identify an internally recognized color-profile or it may point to a ICC Color Profile encoding that should be loaded and interpreted.

When the color-profile is referenced (e.g., via the icc-color function), the following rules are used:

1. If the color-profile is available, the color value identified from the color-profile should be used.

2. If the color-profile is not available, the sRGB fallback must be used.

Areas:

The fo:color-profile formatting object does not generate or return any areas.

Constraints:

None.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.36.7 "src"]
• [7.15.2 "color-profile-name"]
• [7.15.3 "rendering-intent"]

6.4.5 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 or page-master referenced by the master-name trait 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 a sequence of viewport/reference pairs, and returns the page-viewport-areas. For each page-reference-area, and each region specified in the page-master used to generate that page-reference-area, the fo:page-sequence object also generates the viewport/reference pair for the occurrence of that region in that page-reference-area, and may generate a before-float-reference-area, footnote-reference-area, and main-reference-area, and one or more normal-sequence-reference-areas. The generation of these further areas is described in the descriptions of the fo:simple-page-master and region-masters.

All areas generated by an fo:page-sequence have area-class "xsl-absolute".

Constraints:

Each page-viewport-area/page-reference-area pair is generated using a page-master that satisfies the constraints of the page-sequence-master identified by the master-name trait of the fo:page-sequence or a page-master that was directly identified by the master-name trait. The region-viewport-area children of such a page-reference-area must correspond to the regions that are children of that page-master.

The areas generated by the fo:page-sequence have as their descendants the areas returned by the flows that are children of the fo:page-sequence.

The areas returned to the fo:page-sequence by a flow must satisfy four types of constraints:

• Completeness. All areas returned by formatting object descendants of the flow children of the fo:page-sequence become descendants of areas generated by the fo:page-sequence, with the exception of glyph-areas subject to deletion or substitution as in Sections [4.10.2 Line-building] and [4.10.3 Inline-building].

• Flow-map association. All areas returned by flow children of the fo:page-sequence become descendants of region-reference-areas generated from column-areas associated to the flow by the flow-map in effect, except for areas returned from a fo:static-content with a flow-name of xsl-before-float-separator or xsl-footnote-separator.

  Areas returned from an fo:static-content with a flow-name of xsl-before-float-separator become children of the before-float-reference-area of an area associated to an fo:region-body, following all sibling areas of area-class xsl-before-float. Areas returned from an fo:static-content with a flow-name of xsl-footnote-separator become children of the footnote-reference-area of an area associated to an fo:region-body, preceding all sibling areas of area-class xsl-footnote.

• Area-class association. Areas returned by flow children of an fo:page-sequence are distributed as follows: all areas of area-class xsl-footnote must be descendants of a footnote-reference-area; areas of area-class xsl-before-float must be descendants of a before-float-reference-area; all other areas (including normal areas) must be descendants of a main-reference-area for a region.

• Stacking. The stackable areas of a given class returned by children of each flow are properly stacked within the appropriate reference-area, as described above.

The default ordering constraint of section [4.10.1 General Ordering Constraints] does not apply to the fo:page-sequence. The default ordering constraints apply to the child fo:flow objects; special ordering constraints apply to the child fo:static-content objects.

Contents:

(title?,static-content*,flow)

The following properties apply to this formatting object:

• [7.8.1 "country"]
• [7.32.1 "format"]
• [7.8.2 "language"]
• [7.32.4 "letter-value"]
• [7.32.2 "grouping-separator"]
• [7.32.3 "grouping-size"]
• [7.36.2 "id"]
• [7.33.7 "initial-page-number"]
• [7.33.6 "force-page-count"]
• [7.33.8 "master-name"]

6.4.6 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 fo:layout-master-set formatting object generates no area directly. 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 trait on each child of the fo:layout-master-set must be unique within the set.

Contents:

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

6.4.7 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:

The fo:page-sequence-master formatting object generates no area directly. It 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-master 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.

It is an error if the entire sequence of sub-sequence-specifiers children is exhausted while some areas returned by an fo:flow are not placed. Implementations may recover, if possible, by re-using the sub-sequence-specifier that was last used to generate a page.

Contents:

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

The following properties apply to this formatting object:

• [7.33.8 "master-name"]

6.4.8 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:

The fo:single-page-master-reference formatting object generates no area directly. It 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 trait 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

The following properties apply to this formatting object:

• [7.33.8 "master-name"]

6.4.9 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 generates no area directly. It 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 trait on the fo:repeatable-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 consist of zero or more pages, (b) each page is generated using the fo:simple-page-master referenced by the fo:repeatable-page-master-reference, and (c) length of the sub-sequence is less than or equal to the value of maximum-repeats.

If no region-master child of the fo:repeatable-page-master has a region-name associated to any flow in an fo:page-sequence, then the sub-sequence is constrained to have length zero.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.33.8 "master-name"]
• [7.33.9 "maximum-repeats"]

6.4.10 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 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 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 length of the sub-sequence is less than or equal to the value of maximum-repeats.

If the conditions on all alternatives to extend a sub-sequence are false, then the sub-sequence may not be extended.

Contents:

(conditional-page-master-reference+)

The following properties apply to this formatting object:

• [7.33.9 "maximum-repeats"]

6.4.11 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 be different as well.

Areas:

The fo:conditional-page-master-reference formatting object generates no area directly. It 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 trait on the fo:conditional-page-master-reference.

There are three traits, page-position, odd-or-even, and blank-or-not-blank 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, the properties from which these traits are derived are not inherited and the initial value of all the properties makes the corresponding sub-condition true, this really means that the subset of traits that are derived from properties with specified values must make the corresponding sub-condition true.

The sub-condition corresponding to the page-position trait is true, if the page generated using the fo:conditional-page-master-reference has the specified position in the 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-reference is a descendant.

The sub-condition corresponding to the odd-or-even trait is true, if the value of the odd-or-even trait is "any" or if the value matches the parity of the page number of the page generated using the fo:conditional-page-master-reference.

The sub-condition corresponding to the blank-or-not-blank trait is true, (1) if value of the trait is "not-blank" and the page generated using the fo:conditional-page-master-reference has areas generated by descendants of the fo:flow formatting object; (2) if value of the trait is "blank" and the page generated using the fo:conditional-page-master-reference is such that there are no areas from the fo:flow to be put on that page (e.g., (a) to maintain proper page parity due to (i) a break-after or break-before value of "even-page" or "odd-page" or (ii) at the start or end of the page-sequence or (b) because the constraints on the areas generated by descendants of the fo:flow formatting object would not be satisfied if they were descendant from this page); or (3) if value of the trait is "any".

NOTE:

If any page-master referenced from a conditional-page-master-reference with blank-or-not-blank="true" provides a region in which to put fo:flow content, no content is put in that region.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.33.8 "master-name"]
• [7.33.12 "page-position"]
• [7.33.10 "odd-or-even"]
• [7.33.1 "blank-or-not-blank"]

6.4.12 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 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 recommendation will support more complex page layouts constructed using the fo:page-master formatting object.

Areas:

The fo:simple-page-master formatting object generates no area directly. It is used in the generation of pages by an fo:page-sequence.

When the fo:simple-page-master is used to generate a page, a viewport/reference pair is generated, consisting of a page-viewport-area and a page-reference-area. The page-viewport-area represents the physical bounds of the output medium. The page-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, viewport/reference pairs that correspond to the regions that are the children of the fo:simple-page-master are also generated. (See the formatting object specifications for the five regions for the details on the generation of these areas.)

Trait Derivation:

In version 1.0 of this recommendation, borders and padding are not allowed with a page-reference-area. The remaining traits on the page-reference-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 page-viewport-area are determined using the computed values of the "page-height" and "page-width" properties. If the "page-height" and "page-width" properties have explicit values, they are used to set the corresponding height and width trait on the page-viewport-area. If the "page-height" and/or "page-width" are set to "auto", the size of the page-viewport-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.

A User Agent may provide a way to declare the media for which formatting is to be done. This may be different from the media on which the formatted result is viewed. For example, a browser User Agent may be used to preview pages that are formatted for sheet media. In that case, the size calculation is based on the media for which formatting is done rather than the media being currently used.

The traits derived from the margin properties determine the size and position of the content-rectangle of the page-viewport-area. The traits derived from the "margin-top", "margin-bottom", "margin-left" and "margin-right" properties are used to indent the page-reference-area content-rectangle from the corresponding edge of the content-rectangle of the page-viewport-area. Here "top", "bottom", "left" and "right" are determined by the computed values of the "page-height" and "page-width" properties. For sheet media, these values determine the orientation of the sheet; "page-height" is measured from "top" to "bottom" For display media, the display window is always upright; the top of the display screen is "top".

NOTE:

The reference points for the page-viewport-area content-rectangle are in terms of the "top", "bottom", "left", and "right" rather than "before-edge", "after-edge", "start-edge", and "end-edge" because users see the media relative to its orientation and not relative to the writing-mode currently in use.

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-number trait. 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, country, and language traits 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.

If the block-progression-dimension of the properly stacked region-reference-area is greater than the block-progression-dimension of the region-viewport-area that is its parent, then the constraints on the relationship between the region-viewport-area and the region-reference-area depend on values of the overflow trait on the region-master 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 there is no constraint on the block-progression-dimension of the region-reference-area.

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

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

• If the value of the overflow trait is hidden, paginate, error-if-overflow, 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 region-viewport-area.

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

Contents:

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

The following properties apply to this formatting object:

• [7.9 Common Margin Properties-Block]
• [7.33.8 "master-name"]
• [7.33.11 "page-height"]
• [7.33.13 "page-width"]
• [7.18.3 "reference-orientation"]
• [7.35.7 "writing-mode"]

6.4.13 fo:region-body

Common Usage:

Used in constructing a simple-page-master. This region specifies a viewport/reference pair that is located in the "center" of the fo:simple-page-master. The overflow trait controls how much of the underlying region-reference-area is visible; that is, whether the region-reference-area is clipped by the its parent region-viewport-area.

NOTE:

Typically, for paged media, the 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 page-areas for which the page-master included an fo:region-body. If the fo:flow flow is assigned to some other region, then the areas returned by the fo:flow are constrained to be descendants of region-reference-areas generated using the assigned region-master.

NOTE:

The body region should be sized and positioned within the fo:simple-page-master so that there is room for the areas returned by 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-reference-area. The margins on the fo:region-body are used to position the region-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 trait on the side regions from the trait that corresponds to the "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 trait 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 region-viewport-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. A scrolling mechanism shall be provided, in an implementation-defined manner, if the value of the overflow trait is "scroll".

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

The region-reference-area generated using an fo:region-body is the child of the region-viewport-area. The reference-orientation trait 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 page-reference-area generated by fo:simple-page-master (and, therefore, relative to the viewport positioned in that latter coordinate system).

In addition to the viewport/reference pair, when the region-body is used to generate areas, at least one and up to three additional reference-areas are generated. These reference-areas are the optional before-float-reference-area, the optional footnote-reference-area, and the main-reference-area. The latter reference-area comprises the space left after space is borrowed for the other two reference-areas. The main-reference-area has no padding, border, or space associated with it.

NOTE:

If there is no before-float-reference-area or footnote-reference-area child of the region-reference-area, then the content-rectangle of the main-reference-area is coterminous with the content-rectangle of the region-reference-area.

If the column-count trait has a value N, then N additional reference-areas are generated as children of the main-reference-area. These N reference-areas are the normal-flow-reference-areas.

It is an error to specify a column-count other than 1 if the "overflow" property has the value "scroll". An implementation may recover by behaving as if "1" had been specified.

The inline-progression-dimension of each of these normal-flow-reference-areas is determined by subtracting (N-1) times the column-gap trait from the inline-progression-dimension of the main-reference-area and dividing that result by N. Using "body-in-size" for the name of the inline-progression-dimension of the main-reference-area and "column-in-size" for the name of the size of the normal-flow-reference-areas in the inline-progression-direction, the formula is:

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

The block-progression-dimension of the normal-flow-reference-areas is the same as that of the parent main-reference-area.

NOTE:

As noted above, the block-progression-dimension of the main-reference-area may be less than the size of the region-reference-area if a before-float-reference-area or footnote-reference-area are present.

The normal-flow-reference-areas are positioned within the main-reference-area as follows: The first column is positioned with the before-edge and start-edge of its content-rectangle coincident with the before-edge and start-edge of the content-rectangle of the main-reference-area. The content-rectangle of the Jth normal-flow-reference-area child of the main-reference-area is positioned with its before-edge coincident with the before-edge of the content-rectangle of the main-reference-area and with is start-edge at ((J-1)*(column-in-size + column-gap)) in the inline-progression-direction. This results in the end-edge of the content-rectangle of the Nth normal-flow-reference-area being coincident with the end-edge of the content-rectangle of the main-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.

All areas generated by using the fo:region-body are of area-class "xsl-absolute".

Trait Derivation:

The reference-orientation of the region-viewport-area is taken from the value the reference-orientation trait on the region-master which specifies the region. reference-orientation of the region-reference-area is set to "0" and is, therefore, the same as the orientation established by the region-viewport-area.

The remaining traits on the region-viewport-area and region-reference-area are set according to normal rules for determining the values of traits.

Constraints:

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

The inline-progression-dimension of the region-viewport-area is determined by the inline-progression-dimension of the content-rectangle of the page-reference-area minus the values of the start-indent and end-indent traits of the region-master. The start-edge and end-edge of the content-rectangle of the region-viewport-area are determined by the reference-orientation trait on the page-master.

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

The values of the space-before and start-indent traits are used to position the region-viewport-area relative to the before-edge and start-edge of the content-rectangle of the page-reference-area.

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 [6.4.12 fo:simple-page-master].

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.6 Common Border, Padding, and Background Properties]
• [7.9 Common Margin Properties-Block]
• [7.18.1 "clip"]
• [7.33.2 "column-count"]
• [7.33.3 "column-gap"]
• [7.11.4 "display-align"]
• [7.18.2 "overflow"]
• [7.33.15 "region-name"]
• [7.18.3 "reference-orientation"]
• [7.35.7 "writing-mode"]

6.4.14 fo:region-before

Common Usage:

Used in constructing a simple-page-master. This region specifies a viewport/reference pair that is located on the "before" side of the page-reference-area. In lr-tb writing-mode, this region corresponds to the header region. The overflow trait controls how much of the underlying region-reference-area is visible; that is, whether the region-reference-area is clipped by the its parent region-viewport-area.

Areas:

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

The before-edge of the content-rectangle of this region-viewport-area is positioned coincident with the before-edge of the content-rectangle of the page-reference-area generated using the parent fo:simple-page-master. The block-progression-dimension of the region-viewport-area is determined by the extent trait on the fo:region-before formatting object.

The inline-progression-dimension of the region-viewport-area is determined by the precedence trait on the fo:region-before. If the value of the precedence trait is true, then the inline-progression-dimension extends up to the start- and after-edges of the content-rectangle of the page-reference-area. In this case, the region-before region-viewport-area acts like a float into areas generated by the region-start and region-end. If the value of the precedence trait 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 region-reference-area lies on a canvas underneath the region-viewport-area. The reference-orientation trait is used to orient the coordinate system of the region-reference-area relative to the page-reference-area.

The size of the region-reference-area depends on the setting of the overflow trait on the region. If the value of that trait is "auto", "hidden", "error-if-overflow", "paginate", or "visible" then the size of the reference-area is the same as the size of the viewport. If the value of the overflow trait 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 has no constraint in the block-progression-direction (which implies that it grows to to hold the distribution of all the content bound to the region).

Trait Derivation:

The reference-orientation of the region-viewport-area is taken from the value the reference-orientation trait on the region-master which specifies the region. reference-orientation of the region-reference-area is set to "0" and is, therefore, the same as the orientation established by the region-viewport-area.

The remaining traits on the region-viewport-area and region-reference-area are set according to normal rules for determining the values of traits.

Constraints:

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

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.6 Common Border, Padding, and Background Properties]
• [7.18.1 "clip"]
• [7.11.4 "display-align"]
• [7.33.4 "extent"]
• [7.18.2 "overflow"]
• [7.33.14 "precedence"]
• [7.33.15 "region-name"]
• [7.18.3 "reference-orientation"]
• [7.35.7 "writing-mode"]

6.4.15 fo:region-after

Common Usage:

Used in constructing a simple-page-master. This region specifies a viewport/reference pair that is located on the "after" side of the page-reference-area. In lr-tb writing-mode, this region corresponds to the footer region. The overflow trait controls how much of the underlying region-reference-area is visible; that is, whether the region-reference-area is clipped by the its parent region-viewport-area.

Areas:

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

The after-edge of the content-rectangle of this region-viewport-area is positioned coincident with the after-edge of the content-rectangle of the page-reference-area generated using the parent fo:simple-page-master. The block-progression-dimension of the region-viewport-area is determined by the extent trait on the fo:region-after formatting object.

The inline-progression-dimension of the region-viewport-area is determined by the precedence trait on the fo:region-after. If the value of the precedence trait is true, then the inline-progression-dimension extends up to the start- and after-edges of the content-rectangle of the page-reference-area. In this case, the region-after region-viewport-area acts like a float into areas generated by the region-start and region-end. If the value of the precedence trait 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 region-reference-area lies on a canvas underneath the region-viewport-area. The reference-orientation trait is used to orient the coordinate system of the region-reference-area relative to the page-reference-area.

The size of the region-reference-area depends on the setting of the overflow trait on the region. If the value of that trait is "auto", "hidden", "error-if-overflow", "paginate", or "visible" then the size of the reference-area is the same as the size of the viewport. If the value of the overflow trait 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 has no constraint in block-progression-direction (which implies that it grows to to hold the distribution of all the content bound to the region).

Trait Derivation:

The reference-orientation of the region-viewport-area is taken from the value the reference-orientation trait on the region-master which specifies the region. reference-orientation of the region-reference-area is set to "0" and is, therefore, the same as the orientation established by the region-viewport-area.

The remaining traits on the region-viewport-area and region-reference-area are set according to normal rules for determining the values of traits.

Constraints:

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

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.6 Common Border, Padding, and Background Properties]
• [7.18.1 "clip"]
• [7.11.4 "display-align"]
• [7.33.4 "extent"]
• [7.18.2 "overflow"]
• [7.33.14 "precedence"]
• [7.33.15 "region-name"]
• [7.18.3 "reference-orientation"]
• [7.35.7 "writing-mode"]

6.4.16 fo:region-start

Common Usage:

Used in constructing a simple-page-master. This region specifies a viewport/reference pair that is located on the "start" side of the page-reference-area. In lr-tb writing-mode, this region corresponds to a left sidebar. The overflow trait controls how much of the underlying region-reference-area is visible; that is, whether the region-reference-area is clipped by the its parent region-viewport-area.

Areas:

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

The start-edge of the content-rectangle of this region-viewport-area is positioned coincident with the start-edge of the content-rectangle of the page-reference-area generated using the parent fo:simple-page-master. The inline-progression-dimension of the region-viewport-area is determined by the extent trait on the fo:region-after formatting object.

The block-progression-dimension of the region-viewport-area is determined by the precedence trait on the adjacent fo:region-before and the fo:region-after. If the value of the precedence trait of the fo:region-before (or, respectively, fo:region-after) is false, then the block-progression-dimension extends up to the before- (or, respectively, after-) edge of the content-rectangle of the page-reference-area. In this case, the region-start acts like a float into areas generated by the region-before (respectively, the region-after). If the value of the precedence trait 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 trait equal to true.

The region-reference-area lies on a canvas underneath the region-viewport-area. The reference-orientation trait is used to orient the coordinate system of the region-reference-area relative to the page-reference-area.

The size of the region-reference-area depends on the setting of the overflow trait on the region. If the value of that trait is "auto", "hidden", "error-if-overflow", "paginate", or "visible" then the size of the reference-area is the same as the size of the viewport. If the value of the overflow trait 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 has no constraint in block-progression-direction (which implies that it grows to hold the distribution of all the content bound to the region).

Trait Derivation:

The reference-orientation of the region-viewport-area is taken from the value the reference-orientation trait on the region-master which specifies the region. reference-orientation of the region-reference-area is set to "0" and is, therefore, the same as the orientation established by the region-viewport-area.

The remaining traits on the region-viewport-area and region-reference-area are set according to normal rules for determining the values of traits.

Constraints:

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

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.18.1 "clip"]
• [7.6 Common Border, Padding, and Background Properties]
• [7.11.4 "display-align"]
• [7.33.4 "extent"]
• [7.18.2 "overflow"]
• [7.33.15 "region-name"]
• [7.18.3 "reference-orientation"]
• [7.35.7 "writing-mode"]

6.4.17 fo:region-end

Common Usage:

Used in constructing a simple-page-master. This region specifies a viewport/reference pair that is located on the "end" side of the page-reference-area. In lr-tb writing-mode, this region corresponds to a right sidebar. The overflow trait controls how much of the underlying region-reference-area is visible; that is, whether the region-reference-area is clipped by the its parent region-viewport-area.

Areas:

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

The end-edge of the content-rectangle of this region-viewport-area is positioned coincident with the end-edge of the content-rectangle of the page-reference-area generated using the parent fo:simple-page-master. The inline-progression-dimension of the region-viewport-area is determined by the extent trait on the fo:region-after formatting object.

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

The region-reference-area lies on a canvas underneath the region-viewport-area. The reference-orientation trait is used to orient the coordinate system of the region-reference-area relative to the page-reference-area.

The size of the region-reference-area depends on the setting of the overflow trait on the region. If the value of that trait is "auto", "hidden", "error-if-overflow", "paginate", or "visible" then the size of the reference-area is the same as the size of the viewport. If the value of the overflow trait 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 has no constraint in block-progression-direction (which implies that it grows to to hold the distribution of all the content bound to the region).

Trait Derivation:

The reference-orientation of the region-viewport-area is taken from the value the reference-orientation trait on the region-master which specifies the region. reference-orientation of the region-reference-area is set to "0" and is, therefore, the same as the orientation established by the region-viewport-area.

The remaining traits on the region-viewport-area and region-reference-area are set according to normal rules for determining the values of traits.

Constraints:

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

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.18.1 "clip"]
• [7.6 Common Border, Padding, and Background Properties]
• [7.11.4 "display-align"]
• [7.33.4 "extent"]
• [7.18.2 "overflow"]
• [7.33.15 "region-name"]
• [7.18.3 "reference-orientation"]
• [7.35.7 "writing-mode"]

6.4.18 fo:flow

Common Usage:

The content of the fo:flow formatting object is a sequence of flow objects that provides the flowing text content that is distributed into pages.

Areas:

The fo:flow formatting object does not generate any areas. The fo:flow formatting object returns a 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.

Contents:

(%block;)+

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.33.5 "flow-name"]

6.4.19 fo:static-content

Common Usage:

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.

This 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:static-content. 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.

The fo:static-content may be processed multiple times and thus the default ordering constraint of section [4.10.1 General Ordering Constraints] does not apply to the fo:static-content. Instead, it must satisfy the constraint on a per-page basis. Specifically, if P is a page-reference-area C is an area-class, and S is the set of all descendants of P of area-class C returned to the fo:static-content descendant, then S must be properly-ordered.

Contents:

(%block;)+

The following properties apply to this formatting object:

• [7.33.5 "flow-name"]

6.4.20 fo:title

Common Usage:

The fo:title formatting object is used to associate a title with a given document. This title may be used by an interactive User Agent to identify the document. For example, the content of the fo:title can be formatted and displayed in a "title" window or in a "tool tip".

Areas:

This formatting object returns the sequence of areas returned by the flow children of this formatting object.

Constraints:

The sequence of returned areas must be the concatenation of the sub-sequences of areas returned by each of the flow children of the fo:title formatting object in the order in which the children occur.

Contents:

(#PCDATA|%inline;)*

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.3 "baseline-shift"]
• [7.15.1 "color"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.36.8 "visibility"]
• [7.36.9 "z-index"]

6.5 Block-level Formatting Objects

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:

The fo:block formatting object generates one or more normal block-areas. The fo:block returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:block.

Trait Derivation:

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

Constraints:

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

The children of each normal area returned by an fo:block must satisfy the constraints specified in [4.10.2 Line-building].

In addition the constraints imposed by the traits derived from the properties applicable to this formatting object must be satisfied. The geometric constraints are rigorously defined in [4 Area Model].

Contents:

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

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children, optionally followed by an fo:initial-property-set.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.8 Common Hyphenation Properties]
• [7.9 Common Margin Properties-Block]
• [7.17.1 "break-after"]
• [7.17.2 "break-before"]
• [7.15.1 "color"]
• [7.35.2 "font-height-override-after"]
• [7.35.3 "font-height-override-before"]
• [7.13.1 "hyphenation-keep"]
• [7.13.2 "hyphenation-ladder-count"]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.13.3 "last-line-end-indent"]
• [7.13.7 "linefeed-treatment"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.13.6 "line-stacking-strategy"]
• [7.17.6 "orphans"]
• [7.18.4 "relative-position"]
• [7.13.8 "space-treatment"]
• [7.18.5 "span"]
• [7.13.9 "text-align"]
• [7.13.10 "text-align-last"]
• [7.13.11 "text-indent"]
• [7.36.8 "visibility"]
• [7.13.12 "white-space-collapse"]
• [7.17.7 "widows"]
• [7.13.13 "wrap-option"]
• [7.36.9 "z-index"]

6.5.3 fo:block-container

Common Usage:

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.

Areas:

The fo:block-container formatting object generates one or more viewport/reference pairs. The fo:block-container returns these areas and any page-level-out-of-line areas returned by the children of the fo:block-container.

Trait Derivation:

The areas generated by the fo:block-container formatting object have a value of "true" for the is-reference-area.

The size of the viewport-area and 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 generated by this flow object are placed.

Constraints:

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

The children of each reference-area generated by an fo:block-container formatting object must be normal block-areas returned by the children of the fo:block-container, must be properly stacked, and must be properly ordered.

Any reference-level-out-of-line areas returned by the children of the fo:block-container are handled as described in [6.10.2 fo:float].

Contents:

(%block;)+

In addition an fo:block-container that does not generate an absolutely positioned area may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.4 Common Absolute Position Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.9 Common Margin Properties-Block]
• [7.12.1 "block-progression-dimension"]
• [7.17.1 "break-after"]
• [7.17.2 "break-before"]
• [7.18.1 "clip"]
• [7.11.4 "display-align"]
• [7.12.4 "height"]
• [7.36.2 "id"]
• [7.12.5 "inline-progression-dimension"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.18.2 "overflow"]
• [7.18.3 "reference-orientation"]
• [7.18.5 "span"]
• [7.12.12 "width"]
• [7.35.7 "writing-mode"]

6.6 Inline-level Formatting Objects

6.6.1 Introduction

Inline-level 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 src="{@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 src="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 Usage:

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.

Areas:

The fo:bidi-override formatting object generates one or more normal inline-areas. The fo:bidi-override returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:bidi-override.

Trait Derivation:

The direction traits are derived from the "writing-mode", "direction", and "unicode-bidi" properties as described in [5.5.3 Writing-mode and Direction Properties].

Constraints:

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

The children of each normal area returned by an fo:bidi-override must satisfy the constraints specified in [4.10.3 Inline-building].

Contents:

(#PCDATA|%inline;)*

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.5 Common Aural Properties]
• [7.7 Common Font Properties]
• [7.15.1 "color"]
• [7.35.1 "direction"]
• [7.36.2 "id"]
• [7.14.2 "letter-spacing"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.36.6 "score-spaces"]
• [7.14.5 "text-shadow"]
• [7.14.6 "text-transform"]
• [7.35.6 "unicode-bidi"]
• [7.14.8 "word-spacing"]

6.6.3 fo:character

Common Usage:

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.

Areas:

The fo:character formatting object generates and returns a single normal inline-area.

Constraints:

The dimensions of the area is determined by the font metrics for the glyph.

When formatting an fo:character with a "treat-as-wordspace" value of "yes", the User Agent may use a different method for determining the inline-progression-dimension of the area.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.8 Common Hyphenation Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.14.7 "treat-as-word-space"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.14.1 "character"]
• [7.15.1 "color"]
• [7.11.5 "dominant-baseline"]
• [7.35.2 "font-height-override-after"]
• [7.35.3 "font-height-override-before"]
• [7.35.4 "glyph-orientation-horizontal"]
• [7.35.5 "glyph-orientation-vertical"]
• [7.36.2 "id"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.14.2 "letter-spacing"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.36.6 "score-spaces"]
• [7.14.3 "suppress-at-line-break"]
• [7.14.4 "text-decoration"]
• [7.14.5 "text-shadow"]
• [7.14.6 "text-transform"]
• [7.14.8 "word-spacing"]

6.6.4 fo:initial-property-set

Common Usage:

The fo:initial-property-set auxiliary formatting object 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.

Areas:

The fo:initial-property-set formatting object does not generate or return any areas. It simply holds a set of traits that are applicable to the first line-area of the area that has a value of "true" for the is-first trait and that was generated by the parent fo:block of the fo:initial-property-set.

Trait Derivation:

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

Constraints:

None.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.15.1 "color"]
• [7.36.2 "id"]
• [7.14.2 "letter-spacing"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.36.6 "score-spaces"]
• [7.14.4 "text-decoration"]
• [7.14.5 "text-shadow"]
• [7.14.6 "text-transform"]
• [7.14.8 "word-spacing"]

6.6.5 fo:external-graphic

Common Usage:

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

Areas:

The fo:external-graphic formatting object generates and returns one inline-level viewport-area and one reference-area containing the external graphic.

Constraints:

The viewport's size is determined by the height and width traits. For values of "auto", the content size of the graphic is used.

The content size of a graphic is determined by taking the intrinsic size of the graphic and scaling as specified by the content-height, content-width, and scaling traits. If one of the content-height or content-width is not "auto", the same scale factor (as calculated from the specified non-auto value) is applied equally to both directions.

Once scaled, the reference-area is aligned with respect to the viewport-area using the text-align and vertical-align traits. If it is too large for the viewport-area, the graphic is aligned as if it would fit and the overflow trait controls the clipping, scroll bars, etc.

In the case when the graphics format does not specify an intrinsic size of the graphic the size is determined in an implementation-defined manner.

NOTE:

For example, using a size of 1/96" as the size of one pixel for rasterized images.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.12.1 "block-progression-dimension"]
• [7.12.2 "content-height"]
• [7.36.1 "content-type"]
• [7.12.3 "content-width"]
• [7.11.5 "dominant-baseline"]
• [7.12.4 "height"]
• [7.36.2 "id"]
• [7.12.5 "inline-progression-dimension"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.18.2 "overflow"]
• [7.12.10 "scaling"]
• [7.12.11 "scaling-method"]
• [7.36.7 "src"]
• [7.12.12 "width"]

6.6.6 fo:instream-foreign-object

Common Usage:

The fo:instream-foreign-object flow object is used for an inline graphic or other "generic" object where the object data resides as descendants of the fo:instream-foreign-object, typically as an XML element subtree in a non-XSL namespace.

NOTE:

A common format is SVG.

Areas:

The fo:instream-foreign-object formatting object generates and returns one inline viewport-area and one reference-area containing the instream-foreign-object.

Constraints:

See [6.6.5 fo:external-graphic].

Contents:

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

The fo:instream-foreign-object flow object may have additional attributes in the non-XSL namespace. These are made available to the processor of the content of the flow object. Their semantics is defined by that namespace.

The viewport's size is determined by the height and width traits. For values of "auto", the content size of the instream foreign object is used.

The content size of an instream-foreign-object is determined by taking the intrinsic size of the object and scaling as specified by the content-height, content-width, and scaling traits. If one of the content-height or content-width is not "auto", the same scale factor (as calculated from the specified non-auto value) is applied equally to both directions.

Once scaled, the reference-area is aligned with respect to the viewport-area using the text-align and vertical-align traits. If it is too large for the viewport-area, the instream-foreign-object is aligned as if it would fit and the overflow trait controls the clipping, scroll bars, etc.

In the case when the instream-foreign-object does not specify an intrinsic size of the object, the size is determined in an implementation defined manner.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.12.1 "block-progression-dimension"]
• [7.12.2 "content-height"]
• [7.36.1 "content-type"]
• [7.12.3 "content-width"]
• [7.11.5 "dominant-baseline"]
• [7.12.4 "height"]
• [7.36.2 "id"]
• [7.12.5 "inline-progression-dimension"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.2 "overflow"]
• [7.18.4 "relative-position"]
• [7.12.10 "scaling"]
• [7.12.11 "scaling-method"]
• [7.12.12 "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:

The fo:inline formatting object generates one or more normal inline-areas. The fo:inline returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:inline.

Constraints:

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

The children of each normal area returned by an fo:inline must satisfy the constraints specified in [4.10.3 Inline-building].

In addition the constraints imposed by the traits derived from the properties applicable to this formatting object must be satisfied. The geometric constraints are rigorously defined in [4 Area Model].

Contents:

(#PCDATA|%inline;)*

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.15.1 "color"]
• [7.11.5 "dominant-baseline"]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.14.4 "text-decoration"]
• [7.36.8 "visibility"]
• [7.36.9 "z-index"]

6.6.8 fo:inline-container

Common Usage:

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.

Areas:

The fo:inline-container formatting object generates one or more viewport/reference pairs. The viewport-areas generated by the fo:inline-container are normal inline-level areas. The fo:inline-container returns these areas and any page-level-out-of-line areas returned by the children of the fo:inline-container.

Trait Derivation:

The areas generated by the fo:inline-container formatting object have a value of "true" for the is-reference-area.

The size of the viewport-area and 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 generated by this flow object are placed.

Constraints:

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

The children of each reference-area generated by an fo:inline-container formatting object must be normal block-areas returned by the children of the fo:inline-container, must be properly stacked, and must be properly ordered.

Any reference-level-out-of-line areas returned by the children of the fo:inline-container are handled as described in [6.10.2 fo:float].

Contents:

(%block;)+

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.6 Common Border, Padding, and Background Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.12.1 "block-progression-dimension"]
• [7.18.1 "clip"]
• [7.11.4 "display-align"]
• [7.11.5 "dominant-baseline"]
• [7.12.4 "height"]
• [7.36.2 "id"]
• [7.12.5 "inline-progression-dimension"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.2 "overflow"]
• [7.18.3 "reference-orientation"]
• [7.18.4 "relative-position"]
• [7.12.12 "width"]
• [7.35.7 "writing-mode"]

6.6.9 fo:leader

Common Usage:

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

Areas:

The fo:leader formatting object generates and returns a single normal inline-area.

Trait Derivation:

If the value of the leader-pattern is "use-content" the block-progression-dimension of the content-rectangle is determined in the same manner as for line-areas; otherwise it is determined by the rule-thickness trait.

Constraints:

If the leader's minimum length is too long to place in the line-area, 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 trait.

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

NOTE:

If the value of the leader-pattern trait 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 trait of any inline-areas generated by fo:leaders.

If the value of the leader-pattern trait 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 trait, 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 traits.

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

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 alignment 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 alphabetic baseline.

NOTE:

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

Contents:

(#PCDATA|%inline;)*

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

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.15.1 "color"]
• [7.11.5 "dominant-baseline"]
• [7.35.2 "font-height-override-after"]
• [7.35.3 "font-height-override-before"]
• [7.36.2 "id"]
• [7.19.1 "leader-alignment"]
• [7.19.4 "leader-length"]
• [7.19.2 "leader-pattern"]
• [7.19.3 "leader-pattern-width"]
• [7.18.4 "relative-position"]
• [7.19.5 "rule-style"]
• [7.19.6 "rule-thickness"]
• [7.14.2 "letter-spacing"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.14.5 "text-shadow"]
• [7.36.8 "visibility"]
• [7.14.8 "word-spacing"]
• [7.36.9 "z-index"]

6.6.10 fo:page-number

Common Usage:

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

Areas:

The fo:page-number formatting object generates and returns a single normal inline-area.

Constraints:

The child areas of this inline-area are 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 and with only the "character" property specified.

The page-number string is obtained by converting the page-number for the page on which the inline-area is placed in accordance with the number to string conversion properties specified on the ancestor fo:page-sequence.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.11.5 "dominant-baseline"]
• [7.36.2 "id"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.14.2 "letter-spacing"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.36.6 "score-spaces"]
• [7.14.4 "text-decoration"]
• [7.14.5 "text-shadow"]
• [7.14.6 "text-transform"]
• [7.14.8 "word-spacing"]

6.6.11 fo:page-number-citation

Common Usage:

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

NOTE:

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

Areas:

The fo:page-number-citation formatting object generates and returns a single normal inline-area.

Constraints:

The cited page-number is the number of the page containing, as a descendant, the first normal area returned by the formatting object with an id trait matching the ref-id trait of the fo:page-number-citation (the referenced formatting object).

The cited page-number string is obtained by converting the cited page-number in accordance with the number to string conversion properties specified on the ancestor fo:page-sequence of the referenced formatting object.

The child areas of the generated inline-area are the same as the result of formatting a result-tree fragment consisting of fo:character flow objects; one for each character in the cited page-number string and with only the "character" property specified.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.7 Common Font Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.11.5 "dominant-baseline"]
• [7.36.2 "id"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.14.2 "letter-spacing"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.36.5 "ref-id"]
• [7.18.4 "relative-position"]
• [7.36.6 "score-spaces"]
• [7.14.4 "text-decoration"]
• [7.14.5 "text-shadow"]
• [7.14.6 "text-transform"]
• [7.14.8 "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

6.7.1.1.1 Simple Table with CALS Column-width Specifications

This example is using a simple, "CALS-like", markup for the table elements. The column-widths are specificed using the full CALS column-width specification.

Input sample:

<doc>
<table>
<tgroup cols="3">
<colspec colname="col1" colwidth="1*"/>
<colspec colname="col2" colwidth="2*+2pi"/>
<colspec colname="col3" colwidth="72"/>
<tbody>
<row>
<entry colnum="1" valign="top"><p>Cell 1</p></entry>
<entry colnum="2" valign="middle" align="center"><p>Cell 2</p></entry>
<entry colnum="3" align="center"><p>Cell 3</p></entry>
</row>
</tbody>
</tgroup>
</table>
</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>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="table">
  <fo:table width="12cm" table-layout="fixed">
    <xsl:apply-templates/>
  </fo:table>
</xsl:template>

<xsl:template match="colspec">
  <fo:table-column>
    <xsl:attribute name="column-number">
      <xsl:number count="colspec"/>
    </xsl:attribute>
    <xsl:attribute name="column-width">
      <xsl:call-template name="calc.column.width">
        <xsl:with-param name="colwidth">
          <xsl:value-of select="@colwidth"/>
        </xsl:with-param>
      </xsl:call-template>
    </xsl:attribute>
  </fo:table-column>
</xsl:template>

<xsl:template match="tbody">
  <fo:table-body>
    <xsl:apply-templates/>
  </fo:table-body>
</xsl:template>

<xsl:template match="row">
  <fo:table-row>
    <xsl:apply-templates/>
  </fo:table-row>
</xsl:template>

<xsl:template match="entry">
  <fo:table-cell column-number="{@colnum}">
    <xsl:if test="@valign">
      <xsl:choose>
        <xsl:when test="@valign='middle'">
          <xsl:attribute name="display-align">center</xsl:attribute>
        </xsl:when>
        <xsl:otherwise>
          <xsl:attribute name="display-align">
            <xsl:value-of select="@valign"/>
          </xsl:attribute>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:if>
    <xsl:if test="@align">
      <xsl:attribute name="text-align">
        <xsl:value-of select="@align"/>
      </xsl:attribute>
    </xsl:if>
    <xsl:apply-templates/>
  </fo:table-cell>
</xsl:template>


<xsl:template name="calc.column.width">
<!-- **
     * <p>Calculate an XSL FO table column-width specification from a
     * CALS table column-width specification.</p>
     *
     * <p>CALS expresses table column-widths in the following basic
     * forms:</p>
     *
     * <ul>
     * <li><b>99.99units</b>, a fixed length-specifier.</li>
     * <li><b>99.99</b>, a fixed length-specifier without any units.</li>
     * <li><b>99.99*</b>, a relative length-specifier.</li>
     * <li><b>99.99*+99.99units</b>, a combination of both.</li>
     * </ul>
     *
     * <p>The CALS units are points (pt), picas (pi), centimeters (cm),
     * millimeters (mm), and inches (in). These are the same units as XSL,
     * except that XSL abbreviates picas "pc" instead of "pi". If a length
     * specifier has no units, the CALS default unit (pt) is assumed.</p>
     *
     * <p>Relative length-specifiers are represented in XSL with the
     * proportional-column-width() function.</p>
     *
     * <p>Here are some examples:</p>
     *
     * <ul>
     * <li>"36pt" becomes "36pt"</li>
     * <li>"3pi" becomes "3pc"</li>
     * <li>"36" becomes "36pt"</li>
     * <li>"3*" becomes "proportional-column-width(3)"</li>
     * <li>"3*+2pi" becomes "proportional-column-width(3)+2pc"</li>
     * <li>"1*+2" becomes "proportional-column-width(1)+2pt"</li>
     * </ul>
     *
     * @param colwidth The CALS column width specification.
     *
     * @returns The XSL column width specification.
     * -->
  <xsl:param name="colwidth">1*</xsl:param>

  <!-- Ok, the colwidth could have any one of the following forms: -->
  <!--        1*       = proportional width -->
  <!--     1unit       = 1.0 units wide -->
  <!--         1       = 1pt wide -->
  <!--  1*+1unit       = proportional width + some fixed width -->
  <!--      1*+1       = proportional width + some fixed width -->

  <!-- If it has a proportional width, translate it to XSL -->
  <xsl:if test="contains($colwidth, '*')">
    <xsl:text>proportional-column-width(</xsl:text>
    <xsl:value-of select="substring-before($colwidth, '*')"/>
    <xsl:text>)</xsl:text>
  </xsl:if>

  <!-- Now get the non-proportional part of the specification -->
  <xsl:variable name="width-units">
    <xsl:choose>
      <xsl:when test="contains($colwidth, '*')">
        <xsl:value-of
             select="normalize-space(substring-after($colwidth, '*'))"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="normalize-space($colwidth)"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:variable>

  <!-- Now the width-units could have any one of the following forms: -->
  <!--                 = <empty string> -->
  <!--     1unit       = 1.0 units wide -->
  <!--         1       = 1pt wide -->
  <!-- with an optional leading sign -->

  <!-- Get the width part by blanking out the units part and discarding -->
  <!-- whitespace. -->
  <xsl:variable name="width"
       select="normalize-space(translate($width-units,
                                         '+-0123456789.abcdefghijklmnopqrstuvwxyz',
                                         '+-0123456789.'))"/>

  <!-- Get the units part by blanking out the width part and discarding -->
  <!-- whitespace. -->
  <xsl:variable name="units"
       select="normalize-space(translate($width-units,
                                         'abcdefghijklmnopqrstuvwxyz+-0123456789.',
                                         'abcdefghijklmnopqrstuvwxyz'))"/>

  <!-- Output the width -->
  <xsl:value-of select="$width"/>

  <!-- Output the units, translated appropriately -->
  <xsl:choose>
    <xsl:when test="$units = 'pi'">pc</xsl:when>
    <xsl:when test="$units = '' and $width != ''">pt</xsl:when>
    <xsl:otherwise><xsl:value-of select="$units"/></xsl:otherwise>
  </xsl:choose>
</xsl:template>

</xsl:stylesheet>

Result Instance: elements and attributes in the fo: namespace

<fo:table width="12cm" table-layout="fixed">
  <fo:table-column column-number="1" column-width="proportional-column-width(1)">
  </fo:table-column>
  <fo:table-column column-number="2" column-width="proportional-column-width(2)+2pc">
  </fo:table-column>
  <fo:table-column column-number="3" column-width="72pt">
  </fo:table-column>
  <fo:table-body>
    <fo:table-row>
      <fo:table-cell column-number="1" display-align="top">
        <fo:block>Cell 1
        </fo:block>
      </fo:table-cell>
      <fo:table-cell column-number="2" display-align="center" text-align="center">
        <fo:block>Cell 2
        </fo:block>
      </fo:table-cell>
      <fo:table-cell column-number="3" text-align="center">
        <fo:block>Cell 3
        </fo:block>
      </fo:table-cell>
    </fo:table-row>
  </fo:table-body>
</fo:table>

6.7.2 fo:table-and-caption

Common Usage:

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.

NOTE:

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

Areas:

The fo:table-and-caption formatting object generates one or more normal block-areas. The fo:table-and-caption returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:table-and-caption.

Constraints:

No area may have more than one normal child area returned by the same fo:table-and-caption formatting object.

The children of the areas generated by the fo:table-and-caption are one or two 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 trait. They are placed relative to the content-rectangle of the generated area as specified by the text-align trait.

Contents:

(table-caption?,table)

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.9 Common Margin Properties-Block]
• [7.34.3 "caption-side"]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]
• [7.18.4 "relative-position"]

6.7.3 fo:table

Common Usage:

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 one or more rows in the table grid.

Areas:

The fo:table formatting object generates one or more normal block-areas. The fo:table returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:table.

The areas generated by the fo:table formatting object have as children:

• Areas, with only background, corresponding to the column-groups, columns, and rows.

• Areas returned by the fo:table-cell formatting objects.

These areas have a z-index controlling the rendering order determined in accordance with 17.5.1 of the CSS2 specification.

NOTE:

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

Trait Derivation:

The areas generated by the fo:table formatting object have a value of "true" for the is-reference-area.

The column-progression-direction and row-progression-direction are determined by the writing-mode trait. Columns use the inline-progression-direction, and rows use the block-progression-direction.

The method for deriving the border traits 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-separation" 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.

Constraints:

The inline-progression-dimension of the content-rectangle of the table is the sum of the inline-progression-dimensions of the columns in the table grid. The method used to determine these inline-progression-dimensions is governed by the values of the table-layout and the inline-progression-dimension traits in the following manner:

inline-progression-dimension="auto" table-layout="auto"

The automatic table layout shall be used.

inline-progression-dimension="auto" table-layout="fixed"

The automatic table layout shall be used.

inline-progression-dimension=<length> table-layout="auto"

The automatic table layout shall be used.

inline-progression-dimension=<length> table-layout="fixed"

The fixed table layout shall be used.

The automatic table layout and fixed table layout is defined in 17.5.2 of the CSS2 specification.

The method for determining the block-progression-dimension of the table is governed by the block-progression-dimension trait.

NOTE:

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

NOTE:

The use of the "proportional-column-width()" function is only permitted when the fixed table layout is used.

Contents:

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

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.9 Common Margin Properties-Block]
• [7.12.1 "block-progression-dimension"]
• [7.34.1 "border-collapse"]
• [7.34.2 "border-separation"]
• [7.17.1 "break-after"]
• [7.17.2 "break-before"]
• [7.36.2 "id"]
• [7.12.5 "inline-progression-dimension"]
• [7.12.4 "height"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.18.4 "relative-position"]
• [7.34.12 "table-layout"]
• [7.34.13 "table-omit-footer-at-break"]
• [7.34.14 "table-omit-header-at-break"]
• [7.12.12 "width"]
• [7.35.7 "writing-mode"]

6.7.4 fo:table-column

Common Usage:

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

Areas:

The fo:table-column formatting object does not generate or return any areas. It holds a set of traits that provide constraints on the column widths and a specification of some presentation characteristics. Inheritable properties may also be specified on the fo:table-column. These can be referenced by the from-table-column() function in an expression.

Constraints:

None.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.6 Common Border, Padding, and Background Properties]
• [7.34.4 "column-number"]
• [7.34.5 "column-width"]
• [7.34.8 "number-columns-repeated"]
• [7.34.9 "number-columns-spanned"]
• [7.36.8 "visibility"]

6.7.5 fo:table-caption

Common Usage:

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

Areas:

The fo:table-caption formatting object generates one or more normal reference-areas. The fo:table-caption returns these reference-areas and any page-level-out-of-line areas returned by the children of the fo:table-caption.

Trait Derivation:

The areas generated by the fo:table-caption formatting object have a value of "true" for the is-reference-area.

Constraints:

For the case when the value of the caption-side trait is "before" or "after" the inline-progression-dimension of the content-rectangle of the generated reference-area is equal to the inline-progression-dimension of the content-rectangle of the reference-area that encloses it.

When the value is "start" or "end" the inline-progression-dimension of the generated reference-area is constrained by the value of the width trait.

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

The children of each normal area returned by an fo:table-caption formatting object must be normal block-areas returned by the children of the fo:table-caption, must be properly stacked, and must be properly ordered.

Any reference-level-out-of-line areas returned by the children of the fo:table-caption are handled as described in [6.10.2 fo:float].

Contents:

(%block;)+

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.12.1 "block-progression-dimension"]
• [7.12.4 "height"]
• [7.36.2 "id"]
• [7.12.5 "inline-progression-dimension"]
• [7.17.3 "keep-together"]
• [7.18.4 "relative-position"]
• [7.12.12 "width"]

6.7.6 fo:table-header

Common Usage:

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

Areas:

The fo:table-header formatting object does not generate any areas. The fo:table-header formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:table-header.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:table-header is the same order as the children are ordered under the fo:table-header.

Contents:

(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.

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.36.2 "id"]
• [7.18.4 "relative-position"]

6.7.7 fo:table-footer

Common Usage:

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

Areas:

The fo:table-footer formatting object does not generate any areas. The fo:table-footer formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:table-footer.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:table-footer is the same order as the children are ordered under the fo:table-footer.

Contents:

(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.

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.36.2 "id"]
• [7.18.4 "relative-position"]

6.7.8 fo:table-body

Common Usage:

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

Areas:

The fo:table-body formatting object does not generate any areas. The fo:table-body formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:table-body.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:table-body is the same order as the children are ordered under the fo:table-body.

Contents:

(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.

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.36.2 "id"]
• [7.18.4 "relative-position"]

6.7.9 fo:table-row

Common Usage:

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.

Areas:

The fo:table-row formatting object does not generate any areas. The fo:table-row formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:table-row.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:table-row is the same order as the children are ordered under the fo:table-row.

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

Contents:

(table-cell+)

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.12.1 "block-progression-dimension"]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.17.1 "break-after"]
• [7.17.2 "break-before"]
• [7.36.2 "id"]
• [7.12.4 "height"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.18.4 "relative-position"]

6.7.10 fo:table-cell

Common Usage:

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

Areas:

The fo:table-cell formatting object generates one or more normal reference-areas. The fo:table-cell returns these reference-areas and any page-level-out-of-line areas returned by the children of the fo:table-cell.

Trait Derivation:

The areas generated by the fo:table-cell formatting object have a value of "true" for the is-reference-area.

The method for deriving the border for a cell is specified by the border-collapse trait.

If the value of the border-collapse trait 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-separation trait. It is filled in accordance with the background trait 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 trait 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.

Constraints:

A table-cell occupies one or more grid units in the row-progression-direction and column-progression-direction. 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 trait is "separate": half the value of the border-separation trait; otherwise 0.

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

• The cell padding.

The method for determining the block-progression-dimension of the cell in the grid is governed by the row-height trait.

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

The children of each normal area returned by an fo:table-cell formatting object must be normal block-areas returned by the children of the fo:table-cell, must be properly stacked, and must be properly ordered.

Any reference-level-out-of-line areas returned by the children of the fo:table-cell are handled as described in [6.10.2 fo:float].

Contents:

(%block;)+

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.12.1 "block-progression-dimension"]
• [7.34.4 "column-number"]
• [7.11.4 "display-align"]
• [7.11.6 "relative-align"]
• [7.34.6 "empty-cells"]
• [7.34.7 "ends-row"]
• [7.12.4 "height"]
• [7.36.2 "id"]
• [7.34.9 "number-columns-spanned"]
• [7.34.10 "number-rows-spanned"]
• [7.18.4 "relative-position"]
• [7.34.11 "starts-row"]
• [7.12.12 "width"]

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 appropriate 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">
    <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">

  <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">
  <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">
  <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">
    <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 Usage:

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

Areas:

The fo:list-block formatting object generates one or more normal block-areas. The fo:list-block returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:list-block.

Constraints:

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

The children of each normal area returned by an fo:list-block formatting object must be normal block-areas returned by the children of the fo:list-block, must be properly stacked, and must be properly ordered.

Contents:

(list-item+)

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.9 Common Margin Properties-Block]
• [7.17.1 "break-after"]
• [7.17.2 "break-before"]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.36.4 "provisional-distance-between-starts"]
• [7.36.3 "provisional-label-separation"]
• [7.18.4 "relative-position"]

6.8.3 fo:list-item

Common Usage:

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

Areas:

The fo:list-item formatting object generates one or more normal block-areas. The fo:list-item returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:list-item.

Constraints:

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

The children of each normal area returned by an fo:list-block formatting object must be normal block-areas returned by the fo:list-item-label and the fo:list-item-body flow objects and must be properly ordered. Those returned by the fo:list-item-label must be properly stacked and those returned by the fo:list-item-body must be properly stacked.

The children of each normal area returned by an fo:list-block formatting object returned by the fo:list-item-label and fo:list-item-body objects are positioned in the block-progression-direction with respect to each other according to the relative-align trait.

In the inline-progression-direction these areas are positioned in the usual manner for properly stacked areas. It is an error if the content-rectangles of 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.

Contents:

(list-item-label,list-item-body)

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.9 Common Margin Properties-Block]
• [7.17.1 "break-after"]
• [7.17.2 "break-before"]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.11.6 "relative-align"]
• [7.18.4 "relative-position"]

6.8.4 fo:list-item-body

Common Usage:

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

Areas:

The fo:list-item-body formatting object does not generate any areas. The fo:list-item-body formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:list-item-body.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:list-item-body is the same order as the children are ordered under the fo:list-item-body.

Contents:

(%block;)+

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]

6.8.5 fo:list-item-label

Common Usage:

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.

Areas:

The fo:list-item-label formatting object does not generate any areas. The fo:list-item-label formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:list-item-label.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:list-item-label is the same order as the children are ordered under the fo:list-item-label.

Contents:

(%block;)+

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.36.2 "id"]
• [7.17.3 "keep-together"]

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 a User Agent state, such as "hover".

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.

Switching between different property values is achieved by using the fo:multi-properties and fo:multi-property-set formatting objects, and the merge-property-values() function. For example, an fo:multi-property-set can be used to specify various properties for each of the possible values of the active-state property, and merge-property-values() can be used to apply them on a given formatting object.

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 preceded 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.1.1.2 Expandable/Collapsible Table of Contents

Input sample:

<p>Follow this <xlink:mylink xmlns:xlink="http://www.w3.org/1999/xlink"
        xlink:href="http://w3.org/TR"
        xlink:title="An Example"
        xlink:show="new"
        xlink:actuate="onRequest">link</xlink:mylink> to access all
TRs of the W3C.</p>

In this example an fo:simple-link contains a series of fo:multi-property-sets that specify various colors or text-decorations depending on the active state, and a wrapper around the fo:simple-link that allows for the merging of the properties of the fo:multi-properties with those of the appropriate fo:multi-property-sets.

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="xlink:mylink" xmlns:xlink="http://www.w3.org/1999/xlink">
    <xsl:variable name="show"><xsl:value-of select="@xlink:show"/>
    </xsl:variable>
     <fo:multi-properties text-decoration="underline">
        <fo:multi-property-set active-state="link" color="blue"/>
        <fo:multi-property-set active-state="visited" color="red"/>
        <fo:multi-property-set active-state="active" color="green"/>
        <fo:multi-property-set active-state="hover" text-decoration="blink"/>
        <fo:multi-property-set active-state="focus" color="yellow"/>
        <fo:wrapper color="merge-property-values()"
                    text-decoration="merge-property-values()">
              <fo:simple-link external-destination="http://w3.org/TR"
                              show-destination="{$show}">
                  <xsl:attribute name="role">
                      <xsl:value-of select="@xlink:title"/>
                  </xsl:attribute>
                  <xsl:apply-templates/>
              </fo:simple-link>
        </fo:wrapper>
      </fo:multi-properties>
</xsl:template>

</xsl:stylesheet>

Result Instance: elements and attributes in the fo: namespace

<fo:block">Follow this
  <fo:multi-properties text-decoration="underline">
    <fo:multi-property-set active-state="link" color="blue">
    </fo:multi-property-set>
    <fo:multi-property-set active-state="visited" color="red">
    </fo:multi-property-set>
    <fo:multi-property-set active-state="active" color="green">
    </fo:multi-property-set>
    <fo:multi-property-set active-state="hover" text-decoration="blink">
    </fo:multi-property-set>
    <fo:multi-property-set active-state="focus" color="yellow">
    </fo:multi-property-set>
    <fo:wrapper color="merge-property-values()"
      text-decoration="merge-property-values()">
      <fo:simple-link external-destination="http://w3.org/TR"
        show-destination="new" role="An Example">link
      </fo:simple-link>
    </fo:wrapper>
  </fo:multi-properties> to access all
TRs of the W3C.
</fo:block>

6.9.2 fo:simple-link

Common Usage:

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.

Areas:

The fo:simple-link formatting object generates one or more normal inline-areas. The fo:simple-link returns these areas, any page-level-out-of-line areas, and any reference-level-out-of-line areas returned by the children of the fo:simple-link.

NOTE:

An fo:simple-link may be displayed by enclosing it in an fo:block.

Constraints:

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

The children of each normal area returned by an fo:simple-link must satisfy the constraints specified in [4.10.3 Inline-building].

Contents:

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

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.5 Common Aural Properties]
• [7.6 Common Border, Padding, and Background Properties]
• [7.10 Common Margin Properties-Inline]
• [7.11.1 "alignment-adjust"]
• [7.11.2 "baseline-identifier"]
• [7.11.3 "baseline-shift"]
• [7.24 "destination-placement-offset"]
• [7.11.5 "dominant-baseline"]
• [7.25 "external-destination"]
• [7.36.2 "id"]
• [7.26 "indicate-destination"]
• [7.27 "internal-destination"]
• [7.17.4 "keep-with-next"]
• [7.17.5 "keep-with-previous"]
• [7.13.4 "line-height"]
• [7.13.5 "line-height-shift-adjustment"]
• [7.18.4 "relative-position"]
• [7.28 "show-destination"]

6.9.3 fo:multi-switch

Common Usage:

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.

Areas:

The fo:multi-switch formatting object does not generate any areas. The fo:multi-switch formatting object returns the sequence of areas returned by the currently visible fo:multi-case. If there is no currently visible fo:multi-case no areas are returned.

Trait Derivation:

The currently-visible-multi-case trait has as initial value a reference to the first fo:multi-case child that has a value of "show" of the starting-state trait. If there is no such child, it has a value indicating that there is no currently visible fo:multi-case. The trait value may be changed by actuating an fo:multi-toggle.

Constraints:

The order of the sequence of areas returned by the fo:multi-switch is the same as the order of the areas returned by the currently visible fo:multi-case.

Contents:

(multi-case+)

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.21 "auto-restore"]
• [7.36.2 "id"]

6.9.4 fo:multi-case

Common Usage:

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

Areas:

The fo:multi-case formatting object does not generate any areas. The fo:multi-case formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:multi-case.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:multi-case is the same order as the children are ordered under the fo:multi-case.

Contents:

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

The fo:multi-case may contain any formatting objects that are permitted in the context 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.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.36.2 "id"]
• [7.29 "starting-state"]
• [7.22 "case-name"]
• [7.23 "case-title"]

6.9.5 fo:multi-toggle

Common Usage:

The fo:multi-toggle is typically used to establish an area that when actuated (for example implemented as "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.

Areas:

The fo:multi-toggle formatting object does not generate any areas. The fo:multi-toggle formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:multi-toggle. Each of the areas returned by the fo:multi-toggle has a switch-to trait with the same value as on the returning fo:multi-toggle.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:multi-toggle is the same order as the children are ordered under the fo:multi-toggle.

Activating an area returned by an fo:multi-toggle causes a change to the value of the currently-visible-multi-case of the closest fo:multi-switch.

Contents:

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

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.36.2 "id"]
• [7.30 "switch-to"]

6.9.6 fo:multi-properties

Common Usage:

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

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.

The direct children of an fo:multi-properties formatting object is an ordered set of fo:multi-property-set formatting objects followed by a single fo:wrapper formatting object. The properties, specified on the fo:wrapper, that have been specified with a value of "merge-property-values()" will take a value that is a merger of the value on the fo:multi-properties and the specified values on the fo:multi-property-set formatting objects that apply.

Areas:

The fo:multi-properties formatting object does not generate any areas. The fo:multi-properties formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:multi-properties.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:multi-properties is the same order as the children are ordered under the fo:multi-properties.

Contents:

(multi-property-set+,wrapper)

The properties that should take a merged value shall be specified with a value of "merge-property-values()". 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.

The following properties apply to this formatting object:

• [7.3 Common Accessibility Properties]
• [7.36.2 "id"]

6.9.7 fo:multi-property-set

Common Usage:

The fo:multi-property-set auxiliary formatting object 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 fo:wrapper child of the parent of this fo:multi-property-set.

Areas:

The fo:multi-property-set formatting object does not generate or return any areas. It simply holds a set of traits that may be accessed by expressions.

Constraints:

None.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.36.2 "id"]
• [7.20.1 "active-state"]

6.10 Out-of-Line Formatting Objects

6.10.1 Introduction

6.10.1.1 Floats

The fo:float formatting object is used for two distinct purposes. First, so that during the normal placement of content, some related content is formatted into a separate area at the beginning of a page where it is available to be read without immediately intruding on the reader. The areas generated by this kind of fo:float are called before-floats. An fo:float is specified to generate before-floats if it has a "float" property value of "before". The constraints on placing before-floats on a page are described in the [6.10.1.3 Conditional Sub-Regions] section of this introduction and in the description of the fo:float formatting object.

Second, the fo:float formatting object is used when an area is intended to float to one side, with normal content flowing alongside the floated area. The areas generated by this kind of fo:float are called side-floats. A side-float is always made a child of the nearest ancestor reference-area. The edge of the reference-area towards which the side-float floats is controlled by the value of the "float" property.

Flowing normal content flowing alongside side-floats is realized by increasing the start-intrusion-adjustment or the end-intrusion-adjustment of normal child areas of the parent reference-area of the side-float.

The "clear" property applies to any block-level formatting object. If the value of this property for a particular formatting object is any value other than "none", then the areas generated by the block will be positioned to ensure that their border-rectangles do not overlap the allocation-rectangles of the applicable side-floats as determined by the "clear" property value.

6.10.1.2 Footnotes

The fo:footnote formatting object is used to generate both a footnote and its citation. The fo:footnote has two children, which are both required to be present. The first child is an fo:inline formatting object, which is formatted to produce the footnote citation. The second child is an fo:footnote-body formatting object which generates the content (or body) of the footnote.

The actual areas generated by the descendants of the fo:footnote-body formatting object are determined by the formatting objects that comprise the descendant subtree. For example, the footnote could be formatted with a label and an indented body by using the fo:list-block formatting object within the fo:footnote-body.

6.10.1.3 Conditional Sub-Regions

The region-body has two conditional sub-regions which implicitly specify corresponding reference-areas called before-float-reference-area and footnote-reference-area. These reference-areas are conditionally generated as children of the region-reference-area. The before-float-reference-area is generated only if the page contains one or more areas with area-class "xsl-before-float". The footnote-reference-area is generated only if the page contains one or more areas with area-class "xsl-footnote".

The conditionally generated areas borrow space in the block-progression-dimension (this is "height" when the writing-mode is "lr-tb") within the region-reference-area, at the expense of the main-reference-area. Whether or not a conditionally generated area is actually generated depends, additionally, on whether there is sufficient space left in the main-reference-area.

There may be limits on how much space conditionally generated areas can borrow from the region-reference-area. It is left to the user agent to decide these limits.

The block-progression-dimension of the main-reference-area is set equal to the block-progression-dimension of the allocation-rectangle of the region-reference-area minus the sum of the sizes in the block-progression-direction of the allocation-rectangles of the conditionally generated reference-areas that were actually generated. The main-reference-area is positioned to immediately follow the after-edge of the allocation-rectangle of the before-float-reference-area. This positions the after-edge of the main-reference-area to coincide with the before-edge of the allocation-rectangle of the footnote-reference-area. In addition to the constraints normally determined by the region-reference-area, the inline-progression-dimension (this is "width" when the writing-mode is "lr-tb") of a conditionally generated reference-area is constrained to match the inline-progression-dimension of the main-reference-area.

Each conditionally generated reference-area may additionally contain a sequence of areas used to separate the reference-area from the main-reference-area. The sequence of areas is the sequence returned by formatting a fo:static-content specified in the page-sequence that is being used to format the page.

If there is a fo:static-content in a page-sequence whose "region-name" property value is "xsl-before-float-separator", then the areas returned by formatting the fo:static-content are inserted in the proper order as the last children of a before-float-reference-area that is generated using the same page-master, provided the main-reference-area on the page is not empty.

If there is an fo:static-content whose "region-name" property value is "xsl-footnote-separator", then the areas returned by formatting the fo:static-content are inserted in the proper order as the initial children of a footnote-reference-area that is generated using the same page-master.

An interactive user agent may choose to create "hot links" to the footnotes from the footnote-citation, or create "hot links" to the before-floats from an implicit citation, instead of realizing conditional sub-regions.

The generation of areas with area-class "xsl-before-float" or "xsl-footnote" is specified in the descriptions of the formatting objects that initially return areas with those area-classes.

6.10.2 fo:float

Common Usage:

The fo:float formatting object is typically used either to cause an image to be positioned in a separate area at the beginning of a page, or to cause an image to be positioned to one side, with normal content flowing around and along-side the image.

Areas:

The fo:float generates a single normal inline-area with no children, and one or more block-areas that all share the same area-class, which is either "xsl-before-float", "xsl-side-float" or "xsl-normal" as specified by the "float" property. (An fo:float generates normal block-areas if its "float" property value is "none".)

An area with area-class "xsl-side-float" is placed as a child of the nearest ancestor reference-area.

An area with area-class "xsl-before-float" is placed as a child of a "before-float-reference-area".

Constraints:

The normal inline-area generated by the fo:float shall be placed in the area tree as though the fo:float had a "keep-with-previous" property with value "always". The inline-area has a length of zero for both the inline-progression-dimension and block-progression-dimension.

The term anchor-area is used here to mean the normal inline-area generated by the fo:float.

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

Areas with area-class "xsl-before-float" must be properly ordered within the area tree relative to other areas with the same area-class.

The padding-, border-, and content-rectangles of the block-areas generated by fo:float all coincide. That is, the padding and border are zero at all edges of the area.

The following constraints apply to fo:float formatting objects that generate areas with area-class "xsl-before-float":

• It is an error if the fo:float occurs as a descendant of an fo:static-flow, or of an fo:flow that is not assigned to a region-body, or of an fo:block-container that generates absolutely positioned areas. In either case, the fo:float shall be formatted as though its "float" property was "none".

• A block-area generated by the fo:float may only be descendant from a "before-float-reference-area" that is (a) descendant from a "region-reference-area" generated using the region-master for the region to which the flow that has the fo:float as a descendant is assigned, and (b) is descendant from the same page containing the anchor-area, or from a page following that page.

• The fo:float may not generate any additional block-areas unless the page containing the preceding block-area generated by the fo:float contains no other areas with area-class "xsl-before-float", has an empty main-reference-area, and does not contain a "footnote-reference-area".

• The "clear" property does not apply.

The following constraints apply to fo:float formatting objects that generate areas with area-class "xsl-side-float":

• The block-areas generated by the fo:float are placed as children of the reference-area generated by the nearest ancestor formatting object that generates a reference-area.

• A block-area generated by one fo:float may not be placed so that it overlaps another area with area-class "xsl-side-float".

• The description in section 9.5 of [CSS2] shall be used to determine the formatting of the fo:float and the rendering of normal line-areas that overlap a block-area generated by the fo:float, with these modifications:

  • All references to left and right shall be interpreted as their corresponding writing-mode relative directions "start" and "end". The "float" property will additionally have the writing-mode relative values "start" and "end".

  • All references to top and bottom shall be interpreted as their corresponding writing-mode relative directions "before" and "after".

  • The phrase "current line box" shall be interpreted to mean the line-area that contains the anchor-area.

  • The areas generated by the fo:float derive their length in the inline-progression-dimension intrinsically from their child areas; the length is not determined by an explicit property value.

  • The length of an area generated by the fo:float, in the inline-progression-dimension, increases either the start-intrusion-adjustment or the end-intrusion-adjustment, depending on which side the area floats to, of each child area of the nearest ancestor reference-area, provided the border-rectangle of the child area overlaps the floated area in the inline-progression-direction.

Contents:

(%block;)+

An fo:float is not permitted to have an fo:float, fo:footnote or fo:marker as a descendant.

Additionally, an fo:float is not permitted to have as a descendant an fo:block-container that generates an absolutely positioned area.

The following properties apply to this formatting object:

• [7.16.2 "float"]
• [7.16.1 "clear"]

6.10.3 fo:footnote

Common Usage:

The fo:footnote is typically used to produce footnote-citations within the region-body of a page and the corresponding footnote in a separate area nearer the after-edge of the page.

Areas:

The fo:footnote formatting object does not generate any areas. The fo:footnote formatting object returns the areas generated and returned by its child fo:inline formatting object.

Additionally the fo:footnote formatting object returns the block-areas with area class "xsl-footnote" generated by its fo:footnote-body child. An area with area-class "xsl-footnote" is placed as a child of a "footnote-reference-area".

Constraints:

The term anchor-area is defined to mean the last area that is generated and returned by the fo:inline child of the fo:footnote.

A block-area returned by the fo:footnote is only permitted as a descendant from a "footnote-reference-area" that is (a) descendant from a "region-reference-area generated using the region-master for the region to which the flow that has the fo:footnote as a descendant is assigned, and (b) is descendant from the same page that contains the anchor-area, or from a page following the page that contains the anchor-area.

The second block-area and any additional block-areas returned by an fo:footnote must be placed on the immediately subsequent pages to the page containing the first block-area returned by the fo:foonote, before any other content is placed. If a subsequent page does not contain a region-body, the user agent must use the region-master of the last page that did contain a region-body to hold the additional block-areas.

It is an error if the fo:footnote occurs as a descendant of an fo:static-flow, or of an fo:flow that is not assigned to a region-body, or of an fo:block-container that generates absolutely positioned areas. In either case, the block-areas generated by the fo:footnote-body child of the fo:footnote shall be returned to the parent of the fo:footnote and placed in the area tree as though they were normal block-level areas.

Contents:

(inline,footnote-body)

An fo:footnote is not permitted to have an fo:float, fo:footnote, or fo:marker as a descendant.

Additionally, an fo:footnote is not permitted to have as a descendant an fo:block-container that generates an absolutely positioned area.

6.10.4 fo:footnote-body

Common Usage:

The fo:footnote-body is used to generate the footnote content.

Areas:

The fo:footnote-body generates and returns one or more block-level areas with area-class "xsl-footnote".

Constraints:

The fo:footnote-body is only permitted as a child of an fo:footnote.

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

Areas with area-class "xsl-footnote" must be properly ordered within the area tree relative to other areas with the same area-class.

Contents:

(%block;)+

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 Usage:

The fo:wrapper formatting object is used to specify inherited properties for a group of formatting objects.

Areas:

The fo:wrapper formatting object does not generate any areas. The fo:wrapper formatting object returns the sequence of areas created by concatenating the sequences of areas returned by each of the children of the fo:wrapper.

Trait Derivation:

Except for "id", 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.

Constraints:

The order of concatenation of the sequences of areas returned by the children of the fo:wrapper is the same order as the children are ordered under the fo:wrapper.

Contents:

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

In addition this formatting object may have a sequence of zero or more fo:markers as its initial children.

The following properties apply to this formatting object:

• [7.36.2 "id"]

6.11.3 fo:marker

Common Usage:

The fo:marker is used in conjunction with fo:retrieve-marker to produce running headers or footers. Typical examples include:

• dictionary headers showing the first and last word defined on the page.

• headers showing the page's chapter and section titles.

Areas:

The fo:marker does not directly produce any area. Its children may be retrieved and formatted from within an fo:static-content, using an fo:retrieve-marker whose "retrieve-class-name" property value is the same as the "marker-class-name" property value of this fo:marker.

Constraints:

An fo:marker is only permitted as the descendant of an fo:flow.

Note: Property values set on an fo:marker or its ancestors will not be inherited by the children of the fo:marker when they are retrieved by an fo:retrieve-marker.

It is an error if two or more fo:markers that share the same parent have the same "marker-class-name" property value.

Contents:

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

An fo:marker may contain any formatting objects that are permitted as a replacement of any fo:retrieve-marker that retrieves the fo:marker's children.

The following properties apply to this formatting object:

• [7.31.1 "marker-class-name"]

6.11.4 fo:retrieve-marker

Common Usage:

The fo:retrieve-marker is used in conjunction with fo:marker to produce running headers or footers. Typical examples include:

• dictionary headers showing the first and last word defined on the page.

• headers showing the page's chapter and section titles.

Areas:

The fo:retrieve-marker does not directly generate any area. It is (conceptually) replaced by the children of the fo:marker that it retrieves.

Trait Derivation:

The properties and traits specified on the ancestors of the fo:retrieve-marker are taken into account when formatting the children of the retrieved fo:marker as if the children had the same ancestors as the fo:retrieve-marker.

Constraints:

An fo:retrieve-marker is only permitted as the descendant of an fo:static-content.

The fo:retrieve-marker specifies that the children of a selected fo:marker shall be formatted as though they replaced the fo:retrieve-marker in the formatting tree.

The properties of the fo:retrieve-marker impose a hierarchy of preference on the areas of the area tree. Each fo:marker is conceptually attached to each normal area returned by the fo:marker's parent formatting object. Additionally, an fo:marker is conceptually attached to each non-normal area that is directly generated by the fo:marker's parent formatting object. Conversely, areas generated by any descendant of an fo:flow may have zero or more fo:marker's conceptually attached. The fo:marker whose children are retrieved is the one which is (conceptually) attached to the area that is at the top of this hierarchy.

Every area in the hierarchy is considered preferential to, or "better" than, any area below it in the hierarchy. When comparing two areas to determine which one is better, the terms "first" and "last" refer to the pre-order traversal order of the area tree.

The term "containing page" is used here to mean the page that contains the first area generated or returned by the children of the retrieved fo:marker.

An area that has an attached fo:marker whose "marker-class-name" property value is the same as the "retrieve-class-name" property value of the fo:retrieve-marker is defined to be a qualifying area. Only qualifying areas have positions in the hierarchy.

A qualifying area within a page is better than any qualifying area within a preceding page, except that areas do not have a position in the hierarchy if they are within pages that follow the containing page. If the "retrieve-boundary" property has a value of "page-sequence", then an area does not have a position in the hierarchy if it is on a page from a page-sequence preceding the page-sequence of the containing page. If the "retrieve-boundary" property has a value of "page", then an area does not have a position in the hierarchy if it is not on the containing page.

If the value of the "retrieve-position" property is "first-starting-within-page", then the first qualifying area in the containing page whose "is-first" trait has a value of "true" is better than any other area. If there is no such area, then the first qualifying area in the containing page is better than any other area.

If the value of the "retrieve-position" property is "first-including-carryover", then the first qualifying area in the containing page is better than any other area.

If the value of the "retrieve-position" property is "last-starting-within-page", then the last qualifying area in the containing page whose "is-first" trait has a value of "true" is better than any other area. If there is no such area, then the last qualifying area in the containing page is better than any other area.

If the value of the "retrieve-position" property is "last-ending-within-page", then the last qualifying area in the containing page whose "is-last" trait has a value of "true" is better than any other area. If there is no such area, then the last qualifying area in the containing page is better than any other area.

If the hierarchy of areas is empty, no formatting objects are retrieved.

Contents:

EMPTY

The following properties apply to this formatting object:

• [7.31.2 "retrieve-class-name"]
• [7.31.3 "retrieve-position"]
• [7.31.4 "retrieve-boundary"]

7 Formatting Properties

7.1 Description of Property Groups

The following sections describe the properties of the XSL formatting objects.

A number of properties are copied from the CSS2 specification. In addition, the CSS2 errata all apply. See [CSS2].

• 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 positioning.

  • 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.

  • Common Font Properties

    This set of properties controls the font selection on all formatting objects that can contain text.

  • Common Hyphenation Properties

    Control of hyphenation for line-breaking, including language, script, and country.

  • 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-level formatting objects.

• The remaining properties are used on a 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.

  • Area Alignment Properties

    Properties that control the alignment of inline-areas with respect to each other, particularly in relation to the mixing of different baselines for different scripts. In addition, there are two properties: "display-align" and "relative-align" that control the placement of block-areas.

  • Area Dimension Properties

    Properties that control the dimensions of both block-areas and inline-areas.

  • Block and Line-related Properties

    Properties that govern the construction of line-areas and the placement of these line-areas within containing block-areas.

  • Character Properties

    Properties that govern the presentation of text, including word-spacing, letter-spacing, and word-space treatment and suppression.

  • Color-related Properties

    Properties that govern color and color-model selection.

  • Float-related properties

    Properties governing the placement of both side-floats (start- and end-floats) and before-floats ("top" floats in "lr-tb" writing-mode).

  • Keeps and Breaks Properties

    Properties that control keeps and breaks across pages, columns, and lines, including widow and orphan control and keeping content together.

  • Layout-related Properties

    These properties control what is "top" ("reference-orientation") as well as clipping, overflow, and column-spanning conditions.

  • Leader and Rule Properties

    Properties governing the construction of leaders and horizontal rules.

  • Properties for Links

    Properties governing the presentation and actions associated with links.

  • Properties for Markers

    Properties governing the creation and retrieval of markers. Markers are used typically for "dictionary" headers and footers.

  • Properties for Number to String Conversions

    Properties used in the construction of page-numbers and other formatter-based numbering.

  • Pagination and Layout 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.

  • Writing-mode-related Properties

    Properties related to various aspects of "directionality" and writing-mode influencing block-progression-direction and inline-progression-direction.

  • Miscellaneous Properties

    These properties did not reasonably fit into any of the other categories.

• Shorthand Properties

  Shorthand properties that are part of the complete conformance set. Shorthands expand to the individual properties that may be used in place of shorthands.

7.2 XSL Areas and the CSS Box Model

This section describes how to interpret property descriptions which incorporate the CSS2 definition of the same property. In CSS2, "boxes" are generated by "elements" in the same way that XSL areas are generated by formatting objects. Any references in the CSS2 definition to "boxes" are to be taken as referring to "areas" in the XSL area model, and where "element" appears in a CSS2 definition it should be taken to refer to a "formatting object".

The position and size of a box are normally taken to refer to the position and size of the area's content-rectangle. Additional correspondences between the CSS2 Box Model and the XSL Area Model are contained in the following table.

Box margins map to area traits in accordance with the description of how area traits are computed from property values in[5 Property Refinement / Resolution].

7.3 Common Accessibility Properties

7.3.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 alternate renderers (aural readers, etc.) whenever the structure of the formatting object tree is inappropriate for that renderer.

7.3.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.4 Common Absolute Position Properties

7.4.1 "absolute-position"

7.4.2 "top"