Table of contents

Appendices

6.4 Declarations and Pagination and Layout Formatting Objects

Introduction[top]

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.

Page-sequence-masters[top]

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.

Page-masters[top]

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 effect 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 "span-reference-areas" whose number depends upon the number of spans (i.e. block-areas with span="all") occurring on the page. These in turn are subdivided by having child-areas designated as "normal-flow-reference-areas", whose number depends on the number of columns specified.

Page Generation[top]

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. An fo:page-sequence references a page-master if either the fo:page-sequence directly references the page-master via the "master-reference" property or that property references an fo:page-sequence-master that references the page-master.

Flows and Flow Mapping[top]

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 that is given by its "flow-name" property. No two flows 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 "flow-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 [pg-out-of-line] .

Constraints on Page Generation[top]

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 with two exceptions: 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.

Pagination Tree Structure[top]

The result tree structure is shown below.

Tree Representation of the Formatting Objects for Pagination

fo:root[top]

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 [area-genorder] .)

Contents:

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

The following properties apply to this formatting object:

• [media-usage]

fo:declarations[top]

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

The fo:declarations flow object may have additional child elements in a non-XSL namespace. Their presence does not, however, change the semantics of the XSL namespace objects and properties. The permitted structure of these non-XSL namespace elements is defined for their namespace(s).

fo:color-profile[top]

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 rgb-icc function [expr-color-functions] ), 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 ( [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:

• [src]
• [color-profile-name]
• [rendering-intent]

fo:page-sequence[top]

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 (consisting of the single fo:flow and any fo:static-content flow objects) of the fo:page-sequence. The layout of these pages comes from the fo:page-sequence-master or page-master referenced by the master-reference 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. It may also generate a title-area.

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-reference trait of the fo:page-sequence or a page-master that was directly identified by the master-reference 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 [area-linebuild] and [area-inlinebuild] .

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

If a title-area is generated the following constraints must be satisfied:

• Completeness. All areas returned by formatting object descendants of the fo:title child of the fo:page-sequence become descendants of the title-area generated by the fo:page-sequence, with the exception of glyph-areas subject to deletion or substitution as in Sections [area-linebuild] and [area-inlinebuild] .

• Stacking. The areas returned by children of the fo:title are properly stacked within the title-area.

The default ordering constraint of section [area-genorder] does not apply to the fo:page-sequence. The default ordering constraints apply to the flow object children inside the single fo:flow; special ordering constraints apply to the child fo:static-content objects.

Contents:

(title?,static-content*,flow)

The following properties apply to this formatting object:

• [country]
• [format]
• [language]
• [letter-value]
• [grouping-separator]
• [grouping-size]
• [id]
• [initial-page-number]
• [force-page-count]
• [master-reference]

fo:layout-master-set[top]

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

fo:page-sequence-master[top]

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 a sequence of sub-sequences of pages that map one-to-one to an initial sub-sequence of the sequence of sub-sequence-specifiers that are the children of the fo:page-sequence-master and, (b) for each sub-sequence of pages in the partition, that sub-sequence satisfies the constraints of the corresponding sub-sequence-specifier. 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:

• [master-name]

fo:single-page-master-reference[top]

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

• [master-reference]

fo:repeatable-page-master-reference[top]

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-reference 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 consists 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:

• [master-reference]
• [maximum-repeats]

fo:repeatable-page-master-alternatives[top]

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

Contents:

(conditional-page-master-reference+)

The following properties apply to this formatting object:

• [maximum-repeats]

fo:conditional-page-master-reference[top]

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-reference 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 nor last) 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, if (1) the 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; if (2) the 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 if (3) the 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:

• [master-reference]
• [page-position]
• [odd-or-even]
• [blank-or-not-blank]

fo:simple-page-master[top]

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 ( [fo_region-body] , [fo_region-before] , [fo_region-after] , [fo_region-start] , and [fo_region-end] ) for the details on the generation of these areas.)

Region-viewport-areas

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

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 block-progression-dimension and inline-progression-dimension of the content-rectangle of the page-viewport-area are determined using the computed values of the "page-height" and "page-width" properties.

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 media-usage trait is paginate, or the value of the overflow trait is visible, hidden, or error-if-overflow, 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.

• If the value of the media-usage trait is bounded-in-one-dimension or unbounded, and the value of the overflow trait is scroll or auto, then there is no constraint on the block-progression-dimension of the region-reference-area.

Contents:

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

The following properties apply to this formatting object:

• [common-margin-properties-block]
• [master-name]
• [page-height]
• [page-width]
• [reference-orientation]
• [writing-mode]

fo:region-body[top]

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

The main-reference-area has as its children a sequence of span-reference-areas. These are reference-area block-areas with zero border and padding, whose inline-progression-dimension is equal to that of the main-reference-area, and which are normally stacked within the main-reference-area.

Each span-reference-area has one or more reference-area children, designated as normal-flow-reference-areas. The number and placement of the children of a span-reference-area depends on the column-count trait of the span-reference-area. In turn, the formatter must generate precisely enough of these span-reference-areas, and so set their column-count traits, that block-areas returned from the fo:flow with a span of "all" are children of span-reference-areas with column-count equal to 1, and block-areas returned from the fo:flow with a span of "none" are children of span-reference-areas with column-count equal to the refined value of the column-count property of the associated region-reference-area.

For each span-reference-area, the number N of normal-flow-reference-area children is equal to the value of the column-count trait.

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 span-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 span-reference-area.

NOTE: 

As noted above, the block-progression-dimension of the span-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, or if there is more than one span-reference-area child of the main-reference-area.

The normal-flow-reference-areas are positioned within the span-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 span-reference-area. The content-rectangle of the Jth normal-flow-reference-area child of the span-reference-area is positioned with its before-edge coincident with the before-edge of the content-rectangle of the span-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 span-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 of 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.

The traits on the span-reference-areas and on the normal-flow-reference-areas are determined, in the same manner as described in [refinement] , from a set of properties where each property has its initial value except for reference-orientation, writing-mode, and display-align that have the value from the fo:region-body.

Constraints:

The constraints applicable to all regions (see [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 [fo_simple-page-master] .

Contents:

EMPTY

The following properties apply to this formatting object:

• [common-border-padding-and-background-properties]
• [common-margin-properties-block]
• [clip]
• [column-count]
• [column-gap]
• [display-align]
• [overflow]
• [region-name]
• [reference-orientation]
• [writing-mode]

fo:region-before[top]

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

In version 1.0 of this Recommendation, the values of the padding and border-width traits must be "0".

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-edge and end-edge 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 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 of 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 [fo_simple-page-master] .

Contents:

EMPTY

The following properties apply to this formatting object:

• [common-border-padding-and-background-properties]
• [clip]
• [display-align]
• [extent]
• [overflow]
• [precedence]
• [region-name]
• [reference-orientation]
• [writing-mode]

fo:region-after[top]

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

In version 1.0 of this Recommendation, the values of the padding and border-width traits must be "0".

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-edge and end-edge 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 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 of 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 [fo_simple-page-master] .

Contents:

EMPTY

The following properties apply to this formatting object:

• [common-border-padding-and-background-properties]
• [clip]
• [display-align]
• [extent]
• [overflow]
• [precedence]
• [region-name]
• [reference-orientation]
• [writing-mode]

fo:region-start[top]

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

In version 1.0 of this Recommendation, the values of the padding and border-width traits must be "0".

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 these exist; otherwise it is determined as if the value of the precedence trait was false. 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 of 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 [fo_simple-page-master] .

Contents:

EMPTY

The following properties apply to this formatting object:

• [common-border-padding-and-background-properties]
• [clip]
• [display-align]
• [extent]
• [overflow]
• [region-name]
• [reference-orientation]
• [writing-mode]

fo:region-end[top]

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

In version 1.0 of this Recommendation, the values of the padding and border-width traits must be "0".

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 these exist; otherwise it is determined as if the value of the precedence trait was false. 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 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 of 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 [fo_simple-page-master] .

Contents:

EMPTY

The following properties apply to this formatting object:

• [common-border-padding-and-background-properties]
• [clip]
• [display-align]
• [extent]
• [overflow]
• [region-name]
• [reference-orientation]
• [writing-mode]

fo:flow[top]

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:

• [flow-name]

fo:static-content[top]

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 [area-genorder] 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:

• [flow-name]

fo:title[top]

Common Usage:

The fo:title formatting object is used to associate a title with a given page-sequence. This title may be used by an interactive User Agent to identify the pages. 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 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;)*

An fo:title is not permitted to have an fo:float, fo:footnote or fo:marker as a descendant.

Additionally, an fo:title 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:

• [common-accessibility-properties]
• [common-aural-properties]
• [common-border-padding-and-background-properties]
• [common-font-properties]
• [common-margin-properties-inline]
• [color]
• [line-height]
• [visibility]