[Accessibility conventions are described at the bottom of the page]
8. Flows, static content and page geometry sequencing
[> 9.][< 7.4.4][^^^]
8.0 Extended page model for pagination
[> 8.1][> 9.][< 8.][^^][^^^]
Bounded areas (pages) repeat to accommodate an arbitrary amount of content (flow)
[[1] - pagination differentiates XSL-FO semantics from web browser display semantics
]
[F1.0]Exactly one paginating flow is defined in XSL-FO 1.0
[[1] - an implicit flow map corresponds flow names to region names
[1] - only serpentine flow is through equal-width evenly-spaced columns
]
[F1.1]One or more paginating flows can be defined in XSL-FO 1.1
[[1] - a stylesheet-defined flow map arbitrarily corresponds flow names to region names for desired effects
[1] - the same 1.0 implicit flow map corresponds flow names to region names when the stylesheet does not provide an explicit flow
map
[1] - multiple body regions allow the stylesheet to place many regions arbitrarily on the page
]
[Figure 8.1: Multiple flows in XSL-FO 1.1
Four pairs of pages are shown with the following titles on the pairs:
[[1] - One flow - one region
[[2] - there is one region on each page and one serpentine path of one flow leading from the bottom of the left page to the top of
the right page
][1] - Two flows- one region
[[2] - there is one region on each page and one serpentine path of two consecutive flows leading from the bottom of the left page
to the top of the right page
][1] - Two flows - two regions
[[2] - there are two regions on each page and two serpentine paths, one each of two different flows, the left path leading from the
bottom of the left region of the left page to the top of the left region on the right page, and the right path leading from
the bottom of the right region on the left page to the top of the right region on the right page
][1] - One flow - two regions
[[2] - there are two regions on each page and one serpentine path leading from the bottom of the right region on the left page to
the left region on the left page to the right region of the right page to the left region on the left page (as a kind of "backwards
columns" presentation")
]]
]
The pages in the collection need navigational aids repeated on each page
[[1] - used to understand a page's role when not in the context of neighboring pages
[1] - page numbers and page number citations
[[2] - a focus on the specific bounded area of a piece of information
[2] - used on the given page for navigation
[2] - used on other pages for citations to the given page
[[3] - e.g. cross references
[3] - e.g. index information
]][1] - headers and footers
[[2] - contextual information about a collection of pages in which the page is found
[2] - e.g. chapter title repeated in the header
][1] - cited information found from the page being formatted can be contextual information
[[2] - information that would not be known about a page by the stylesheet at the time of transformation, possibly changing for each
page generated
[[3] - the act of pagination dictates the page boundaries, not the transformation of the source information
][2] - e.g. dictionary headers (finding one of many items on a page)
[2] - e.g. subsection citations (finding breaks not triggering new pages)
]]
Every page sequence starts a new page and has its own definitions for static content
[[1] - all candidate uses of static content must be defined for each page sequence
[1] - necessary for the stylesheet writer to repeat the definitions in each page sequence if the same behavior is desired
[1] - every page sequence begins on a new page
[[2] - changing a header or footer in the middle of a page sequence requires manipulating the dynamic content that can be placed
within static content
]]
Static content and paginated flow are associated with a region's name, not position
[[1] - association of the flow name through the flow map to the region name
[1] - must organize the desired region names in each page geometry
[1] - must bind in each page sequence the static content and flows for named regions
[1] - all flows are used for only the named regions found on each page geometry used
[[2] - it is not an error to supply static content or flow for a region that isn't used
][1] - static content can be supplied for named sub-regions triggered by the formatter
]
Differences in page geometry are allowed when more than one page being rendered
[[1] - supports tests for differences to be performed within each page sequence construct's flow when the flow triggers the need
for a new page
[1] - different named geometries can be identical to others or have differences such as:
[[2] - the change of physical dimensions
[2] - the choice of region dimensions and names
[2] - the change of margins
[2] - the presence of headers and/or footers
[2] - the count of columns
[2] - the orientation of regions
[2] - the backgrounds of regions
[2] - the absence of flowed content (to utilize an entire page of static content)
]]
Can describe a sequence with odd and even page number parity differences
[[1] - e.g. alternating headers and footers
[1] - two different static contents are defined with the page number to be rendered on the outside edge of each side of a bound
publication
[[2] - differences in headers and footers of the geometries alternate the names of the flows for the static content between odd and
even numbered pages
]]
Can describe a sequence with first, last, and middle page differences
[[1] - to utilize differences based on where a given formatted page is within its containing page sequence
[1] - e.g. no heading on the first page of a chapter sequence
]
Can describe a sequence to replace absent content for forced un-flowed blank pages
[[1] - to accommodate a requirement for a specified parity of pages in a given sequence, or the need for the subsequent page sequence
to start on a page following the page after the end of a page sequence's flow
[1] - i.e. "this page intentionally left blank"
[1] - by definition, a forced page is made up entirely of static content
]
Each page sequence points to a defined sequence of page geometries
[[1] - the stylesheet writer choreographs the page geometries by the anticipated needs for the quantity of flow expected to be formatted
[1] - all static content definitions needed for a page sequence must be present in that sequence
[[2] - often requires stylesheet writing techniques that copy information repeatedly
]]
Consider the choreography in each of two possible page plans for a TOC and chapters:
[[1] - a single-sided presentation on the left with all page sequences consecutive:
[[2] - document title centered at the top of document content pages (but not the TOC)
[2] - page number and total page count centered at the bottom of all pages
][1] - a double-sided presentation on the right with contents starting on right-hand page:
[[2] - requires the table of contents to be an even number of pages
[2] - document title at bottom left of odd pages and bottom right of even pages
[2] - chapter title at top right of odd pages and top left of even pages
[2] - page number and total page count centered at the bottom of all pages
]]
[Figure 8.2: Page sequence and static content planning
Two candidate page sequences are shown as described in the text.
]
The XSL-FO objects covered in this chapter are summarized as follows.
Formatting objects related to static content:
[[1] - <[region-before]> ([6.4.15])
[[2] - the definition of the body region perimeter area whose before-edge is co-incident with the before-edge of the page's content
rectangle
[[3] - in lr-tb mode this is the header at the top of the page
]][1] - <[region-after]> ([6.4.16])
[[2] - the definition of the body region perimeter area whose after-edge is co-incident with the after-edge of the page's content
rectangle
[[3] - in lr-tb mode this is the footer at the bottom of the page
]][1] - <[region-start]> ([6.4.17])
[[2] - the definition of the body region perimeter area whose start-edge is co-incident with the start-edge of the page's content
rectangle
[[3] - in lr-tb mode this is the sidebar at the left of the page
]][1] - <[region-end]> ([6.4.18])
[[2] - the definition of the body region perimeter area whose end-edge is co-incident with the end-edge of the page's content rectangle
[[3] - in lr-tb mode this is the sidebar at the right of the page
]][1] - <[static-content]> ([6.4.20])
[[2] - the definition of content that is primarily unchanged from page to page in a page sequence
[[3] - entire sequence is repeated on each page except for page numbers and user-defined markers
]][1] - <[page-number]> ([6.6.10])
[[2] - an inline-level place holder replaced with the page number of the current page
][1] - [F1.1]<[folio-prefix]> ([6.6.13])
[[2] - a sequence of text defined to prefix page numbers of a page sequence
][1] - [F1.1]<[folio-suffix]> ([6.6.14])
[[2] - a sequence of text defined to suffix page numbers of a page sequence
][1] - <[retrieve-marker]> ([6.13.6])
[[2] - an inline-level place holder for perimeter regions, replaced with the formatting objects of the indicated marker
][1] - [F1.1]<[retrieve-table-marker]> ([6.13.7])
[[2] - an inline-level place holder for tables, replaced with the formatting objects of the indicated marker
][1] - <[marker]> ([6.13.5])
[[2] - the replacement formatting object content for a marker retrieved in static content
]]
Formatting objects related to page geometry sequencing:
[[1] - <[page-sequence-master]> ([6.4.8])
[[2] - the definition and name of a particular sequence of using page-masters
][1] - <[single-page-master-reference]> ([6.4.9])
[[2] - the specification of the single use of a page-master within a sequence of page-masters
][1] - <[repeatable-page-master-reference]> ([6.4.10])
[[2] - the specification of the repeated use of a page-master within a sequence of page-masters
][1] - <[repeatable-page-master-alternatives]> ([6.4.11])
[[2] - the collection of possible page-master references from which one is to be used based on status conditions detected by the
formatter
][1] - <[conditional-page-master-reference]> ([6.4.12])
[[2] - a page-master choice available to the formatter when selecting from a collection of candidate page-masters
]]
Formatting objects related to flow maps:
[[1] - [F1.1]<[flow-map]> ([6.4.22])
[[2] - specifies a collection of assignments of a set of named flows to a set of named regions
][1] - [F1.1]<[flow-assignment]> ([6.4.23])
[[2] - specifies a single assignment of a set of named flows to a set of named regions
][1] - [F1.1]<[flow-source-list]> ([6.4.24])
[[2] - specifies a set of named flows in a single flow assignment
][1] - [F1.1]<[flow-name-specifier]> ([6.4.25])
[[2] - specifies a single named flow in a set of named flows
][1] - [F1.1]<[flow-target-list]> ([6.4.26])
[[2] - specifies a set of named regions in a single flow assignment
][1] - [F1.1]<[region-name-specifier]> ([6.4.27])
[[2] - specifies a single named region in a set of named regions
]]
8.1 Page regions, headers, and footers
[> 8.2][< 8.0][^^][^^^]
8.1.1 Region dimensions
[> 8.1.2][> 8.2][> 9.][< 8.0][^^][^^^]
Neither the page nor regions have border or padding rectangles
[[1] - may in future versions of XSL-FO have border and padding
]
Page definition is slightly different than region definitions
[[1] - the page reference edges are top, bottom, left and right relative to the physical medium
[[2] - region reference edges are relative to the reference orientation
][1] - the page's viewport-area is larger than the page's reference-area
[[2] - a region's viewport-area is equal to the region's reference-area
]]
The perimeter region incursions must be accommodated explicitly by the body region
[[1] - the incursion is illustrated in [Figure 4.2]
[[2] - precedence determines which perimeter region occupies the before or after pairs of corners of a page
[2] - note the default is to keep before/after region boundaries between start/end regions
][1] - must move border of body region within extents of perimeter regions for border not to interfere
[[2] - this is not automatic and will result in overwritten content if not accommodated
]]
[Figure 8.3: Incursion of perimeter regions into the body region
A number of labels of different areas point to the edges of a page and regions within the page.
The page viewport-area points to the edge of the page. The page reference-area points to the edge of the region-body. A perimeter
region is drawn with one edge co-incident with the region-body. Both the perimeter region's viewport-area and reference-area point to the boundary of the perimeter region.
The extent of the perimeter region's incursion into the region-body is indicated through the extent property and the margin of the region-body is indicated as being slightly larger (though could be any value).
Both the region-body's viewport-area and reference-area point to the area created within the margins of the region-body.
]
8.1.2 <region-before> Object
[> 8.1.3][> 8.2][> 9.][< 8.1.1][^][^^][^^^]
Purpose:
[[1] - the definition of the perimeter area whose before edge is co-incident with the before edge of the page's content rectangle
]
Content:
[[1] - ([6.4.15]) EMPTY
[1] - Referring object:
[[2] - <[simple-page-master]>([6.4.13];[Section 4.3.3 <simple-page-master> Object])
]]
Property sets:
[[1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
]
Other required property:
[region-name=]([7.27.17];[Section D.3.3 Property summary])
Other optional properties:
[clip=]([7.21.1];[Section D.3.3 Property summary])
[display-align=]([7.14.4];[Section D.3.3 Property summary])
[extent=]([7.27.4];[Section D.3.3 Property summary])
[overflow=]([7.21.2];[Section D.3.3 Property summary])
[precedence=]([7.27.16];[Section D.3.3 Property summary])
[reference-orientation=]([7.21.3];[Section D.3.3 Property summary])
[writing-mode=]([7.29.7];[Section D.3.3 Property summary])
Properties of note:
[[1] - the [region-name]= property is required but the default name of "xsl-region-before" is used as this required property if a name is not supplied in the XSL-FO instance
[1] - [precedence]= defaults to "false" indicating the before region does not override the start and end regions, but can be changed to "true" to stretch the region to the content rectangle of the page reference area
[1] - even though [padding]= and [border-width]= properties are indicated as available indirectly through the common property set, these values are fixed at "0pt" in XSL-FO 1.0
[1] - [display-align]= is used to keep the information in the region snug against the before edge, snug against the after edge, or centered in the
middle of the two in the block progression direction
]
The placement of this region is illustrated in [Figure 4.2]
8.1.3 <region-after> Object
[> 8.1.4][> 8.2][> 9.][< 8.1.2][^][^^][^^^]
Purpose:
[[1] - the definition of the perimeter area whose after-edge is co-incident with the after-edge of the page's content rectangle
]
Content:
[[1] - ([6.4.16]) EMPTY
[1] - Referring object:
[[2] - <[simple-page-master]>([6.4.13];[Section 4.3.3 <simple-page-master> Object])
]]
Property sets:
[[1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
]
Other required property:
[region-name=]([7.27.17];[Section D.3.3 Property summary])
Other optional properties:
[clip=]([7.21.1];[Section D.3.3 Property summary])
[display-align=]([7.14.4];[Section D.3.3 Property summary])
[extent=]([7.27.4];[Section D.3.3 Property summary])
[overflow=]([7.21.2];[Section D.3.3 Property summary])
[precedence=]([7.27.16];[Section D.3.3 Property summary])
[reference-orientation=]([7.21.3];[Section D.3.3 Property summary])
[writing-mode=]([7.29.7];[Section D.3.3 Property summary])
Properties of note:
[[1] - the [region-name]= property is required but the default name of "xsl-region-after" is used as this required property if a name is not supplied in the XSL-FO instance
[1] - [precedence]= defaults to "false" indicating the after region does not override the start and end regions, but can be changed to "true" to stretch the region to the content rectangle of the page reference area
[1] - even though [padding]= and [border-width]= properties are indicated as available indirectly through the common property set, these values are fixed at "0pt" in XSL-FO 1.0
[1] - [display-align]= is used to keep the information in the region snug against the before edge, snug against the after edge, or centered in the
middle of the two in the block progression direction
]
The placement of this region is illustrated in [Figure 4.2]
[Example 8-1: Regions on a page
Excerpts from a draft of a training rendition of this material:
01 <layout-master-set>
02 <simple-page-master master-name="frame-left"
03 page-height="11in" page-width="8.5in"
04 margin-top=".45in - .3in" margin-bottom=".45in - .3in"
05 margin-left=".6in" margin-right=".6in">
06 <region-body region-name="pages-body"
07 margin-top=".3in" margin-bottom=".3in"/>
08 <region-before extent=".3in" region-name="pages-before"/>
09 <region-after extent=".3in" region-name="pages-after-left"/>
10 </simple-page-master>
11 <simple-page-master master-name="frame-right"
12 page-height="11in" page-width="8.5in"
13 margin-top=".45in - .3in" margin-bottom=".45in - .3in"
14 margin-left=".6in" margin-right=".6in">
15 <region-body region-name="pages-body"
16 margin-top=".3in" margin-bottom=".3in"/>
17 <region-before extent=".3in" region-name="pages-before"/>
18 <region-after extent=".3in" region-name="pages-after-right"/>
19 </simple-page-master>
20 ...
]
Note that perimeter regions are defined after the body region
[[1] - some processors accept this without error while others can properly report an error
]
8.1.4 <region-start> Object
[> 8.1.5][> 8.2][> 9.][< 8.1.3][^][^^][^^^]
Purpose:
[[1] - the definition of the perimeter area whose start-edge is co-incident with the start-edge of the page's content rectangle
]
Content:
[[1] - ([6.4.17]) EMPTY
[1] - Referring object:
[[2] - <[simple-page-master]>([6.4.13];[Section 4.3.3 <simple-page-master> Object])
]]
Property sets:
[[1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
]
Other required property:
[region-name=]([7.27.17];[Section D.3.3 Property summary])
Other optional properties:
[clip=]([7.21.1];[Section D.3.3 Property summary])
[display-align=]([7.14.4];[Section D.3.3 Property summary])
[extent=]([7.27.4];[Section D.3.3 Property summary])
[overflow=]([7.21.2];[Section D.3.3 Property summary])
[reference-orientation=]([7.21.3];[Section D.3.3 Property summary])
[writing-mode=]([7.29.7];[Section D.3.3 Property summary])
Properties of note:
[[1] - the [region-name]= property is required but the default name of "xsl-region-start" is used as this required property if a name is not supplied in the XSL-FO instance
[1] - even though [padding]= and [border-width]= properties are indicated as available indirectly through the common property set, these values are fixed at "0pt" in XSL-FO 1.0
]
The placement of this region is illustrated in [Figure 4.2]
8.1.5 <region-end> Object
[> 8.2][> 9.][< 8.1.4][^][^^][^^^]
Purpose:
[[1] - the definition of the perimeter area whose end-edge is co-incident with the end-edge of the page's content rectangle
]
Content:
[[1] - ([6.4.18]) EMPTY
[1] - Referring object:
[[2] - <[simple-page-master]>([6.4.13];[Section 4.3.3 <simple-page-master> Object])
]]
Property sets:
[[1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
]
Other required property:
[region-name=]([7.27.17];[Section D.3.3 Property summary])
Other optional properties:
[clip=]([7.21.1];[Section D.3.3 Property summary])
[display-align=]([7.14.4];[Section D.3.3 Property summary])
[extent=]([7.27.4];[Section D.3.3 Property summary])
[overflow=]([7.21.2];[Section D.3.3 Property summary])
[reference-orientation=]([7.21.3];[Section D.3.3 Property summary])
[writing-mode=]([7.29.7];[Section D.3.3 Property summary])
Properties of note:
[[1] - the [region-name]= property is required but the default name of "xsl-region-end" is used as this required property if a name is not supplied in the XSL-FO instance
[1] - even though [padding]= and [border-width]= properties are indicated as available indirectly through the common property set, these values are fixed at "0pt" in XSL-FO 1.0
]
The placement of this region is illustrated in [Figure 4.2]
8.2 Content definition
[> 8.3][< 8.1.5][^^][^^^]
8.2.1 Flowed content vs. static content
[> 8.2.2][> 8.3][> 9.][< 8.1.5][^^][^^^]
The paginated content and all static contents are assigned to flows
[[1] - not assigned to regions or region positions
[1] - geometry defines at which position (if any) a named region is on the page
[1] - the target of flowed or static content is specified by [flow-name]=
[1] - regions are just well-defined areas of the page into which content can be placed
[1] - regions have default names but can be renamed
[[2] - the same names can be used for the same regions in different page definitions
]]
[F1.0]Flows are named the same as the region name
[[1] - the content of pagination, headers, and footers is placed into regions by the region name
]
[F1.1]Flows can be mapped by flow name to a region by region name
[[1] - [F1.1]<[flow-map]> describes a mapping
[1] - the content of pagination, headers, and footers is grouped in an arbitrary number of flows
[1] - the selection of regions accepting a flow is arbitrarily ordered and grouped
[1] - the process flows content into the different regions, moving to the next region available on the page when a given region
on the page is full
[1] - see [Figure 8.1] for an illustration
[1] - naming a flow that is not in the flow map is not an error
[[2] - the content of the flow disappears
][1] - naming a flow more than once in a flow map is an error
[[2] - there is no automated duplication of flow content
]]
Only flowed content triggers the pages to be produced from a <[page-sequence]>
[[1] - each <[page-sequence]> construct must have exactly one paginated flow specified
[[2] - must indicate the region (by name) to which the content is targeted
][1] - content fills a region (any region) until the region overflows
[[2] - the [overflow]= property dictates whether another page is generated to create a new region
[2] - can choose to error on overflow
][1] - a page geometry in the page sequence need not have the named region accepting the flow
[[2] - such a page is produced using only static content for the regions named on the page definition
[2] - the next page is obtained from the page sequence and examined for the named region accepting the flow
]]
The formatter generates a page using the next page geometry in the page sequence
[[1] - the amount of the flowed content dictates how many pages get generated for the sequence
[1] - the page geometry or pattern of page geometries dictate which regions are on each page generated to accommodate the paginated
flow
[1] - all of the static content assigned to named regions found in the geometry is rendered
]
Static content is repeated in the named regions that appear on each page generated
[[1] - <[static-content]>
[1] - each <[page-sequence]> construct may have any number of static content specifications
[[2] - must indicate the region (by name) to which the content is targeted
][1] - it is common to include a <[page-number]/> object in the static content
[[2] - cannot be placed in a flow; can only be placed in static content
[2] - generates a sequence of character areas reflecting the page number
[2] - the choice in characters used in the generated areas is governed by properties of the <[page-sequence]> object
[[3] - formal definition of properties of page number characters comes from XSLT
[3] - [F1.1]folio prefix and suffix included when citing and using page numbers
][2] - the generated areas inherit properties ancestral to the referencing object, not the referred object
[2] - page numbers cannot be used in any kind of arithmetic or conditional test
]]
[F1.1]Each page sequence can have its page numbers prefixed and suffixed
[[1] - [F1.1]<[folio-prefix]>
[[2] - defines what precedes the rendering of a page number when displayed or cited
][1] - [F1.1]<[folio-suffix]>
[[2] - defines what precedes the rendering of a page number when displayed or cited
]]
Flowed and static content are defined on a page-sequence basis
[[1] - every page-sequence must have its own definitions of flowed content and static content
[[2] - cannot point to another page-sequence's content
][1] - <[flow]> and <[static-content]> constructs are children of the <[page-sequence]> construct
]
It is not an error when content is defined for a named region and that region is not present on the page being generated
[[1] - nothing is rendered from the definition of the flowed content
[1] - if there is no region for the flowed content, the static content (if any) is rendered and a new page is generated
[1] - e.g. consider the example where one interleaves a page of normally flowed content with a page entirely made of static content
of a set of ruled lines: the result is in a workbook-like format where the page opposite of the material is used for keeping
notes
]
8.2.2 Flow maps
[> 8.2.3][> 8.3][> 9.][< 8.2.1][^][^^][^^^]
[F1.1]<[flow-map]> is a very simple structure
[[1] - maps flows by flow name to regions by region name
[1] - stored as a child of <[layout-master-set]>
[1] - when needed it is named in <[page-sequence]>
]
[Figure 8.4: The nesting of flow map constructs
A series of nested boxes reflects the hierarchy of formatting objects in the implicit flow map (described next).
]
For example, an excerpt from flows.fo with the flows illustrated on [Figure 8.1]:
[Example 8-2: 01 <flow-map flow-map-name="n-flows-n-regions">
02 <flow-assignment>
03 <flow-source-list>
04 <flow-name-specifier flow-name-reference="A"/>
05 </flow-source-list>
06 <flow-target-list>
07 <region-name-specifier region-name-reference="P"/>
08 </flow-target-list>
09 </flow-assignment>
10 <flow-assignment>
11 <flow-source-list>
12 <flow-name-specifier flow-name-reference="B"/>
13 </flow-source-list>
14 <flow-target-list>
15 <region-name-specifier region-name-reference="Q"/>
16 </flow-target-list>
17 </flow-assignment>
18 </flow-map>
]
[[1] - note that the regions in the flows.fo test file are not positioned as illustrated for the "one flow - n regions" example, but any positioning is acceptable.
]
When a <[page-sequence]> does not specify a flow map, an implicit flow map is used:
[[1] - every flow name is implicitly matched with the region of the same name
]
8.2.3 <flow-map> Object
[> 8.2.4][> 8.3][> 9.][< 8.2.2][^][^^][^^^]
Purpose:
[[1] - specifies a collection of assignments of a set of named flows to a set of named regions
]
Content:
[[1] - [F1.1]([6.4.22]) ([flow-assignment]+)
[1] - Child object:
[[2] - [F1.1]<[flow-assignment]>([6.4.23];[Section 8.2.4 <flow-assignment> Object])
][1] - Referring object:
[[2] - <[layout-master-set]>([6.4.7];[Section 3.3.9 <layout-master-set> Object])
]]
Required property:
[F1.1][flow-map-name=]([7.27.18];[Section D.3.3 Property summary])
8.2.4 <flow-assignment> Object
[> 8.2.5][> 8.3][> 9.][< 8.2.3][^][^^][^^^]
Purpose:
[[1] - specifies a single assignment of a set of named flows to a set of named regions
]
Content:
[[1] - [F1.1]([6.4.23]) ([flow-source-list],[flow-target-list])
[1] - Child objects (alphabetical):
[[2] - [F1.1]<[flow-source-list]>([6.4.24];[Section 8.2.5 <flow-source-list> Object])
[2] - [F1.1]<[flow-target-list]>([6.4.26];[Section 8.2.7 <flow-target-list> Object])
][1] - Referring object:
[[2] - [F1.1]<[flow-map]>([6.4.22];[Section 8.2.3 <flow-map> Object])
]]
No properties are defined for this formatting object.
8.2.5 <flow-source-list> Object
[> 8.2.6][> 8.3][> 9.][< 8.2.4][^][^^][^^^]
Purpose:
[[1] - specifies a set of named flows in a single flow assignment
]
Content:
[[1] - [F1.1]([6.4.24]) ([flow-name-specifier]+)
[1] - Child object:
[[2] - [F1.1]<[flow-name-specifier]>([6.4.25];[Section 8.2.6 <flow-name-specifier> Object])
][1] - Referring object:
[[2] - [F1.1]<[flow-assignment]>([6.4.23];[Section 8.2.4 <flow-assignment> Object])
]]
No properties are defined for this formatting object.
8.2.6 <flow-name-specifier> Object
[> 8.2.7][> 8.3][> 9.][< 8.2.5][^][^^][^^^]
Purpose:
[[1] - specifies a single named flow in a set of named flows
]
Content:
[[1] - [F1.1]([6.4.25]) EMPTY
[1] - Referring object:
[[2] - [F1.1]<[flow-source-list]>([6.4.24];[Section 8.2.5 <flow-source-list> Object])
]]
Required property:
[F1.1][flow-name-reference=]([7.27.20];[Section D.3.3 Property summary])
8.2.7 <flow-target-list> Object
[> 8.2.8][> 8.3][> 9.][< 8.2.6][^][^^][^^^]
Purpose:
[[1] - specifies a set of named regions in a single flow assignment
]
Content:
[[1] - [F1.1]([6.4.26]) ([region-name-specifier]+)
[1] - Child object:
[[2] - [F1.1]<[region-name-specifier]>([6.4.27];[Section 8.2.8 <region-name-specifier> Object])
][1] - Referring object:
[[2] - [F1.1]<[flow-assignment]>([6.4.23];[Section 8.2.4 <flow-assignment> Object])
]]
No properties are defined for this formatting object.
8.2.8 <region-name-specifier> Object
[> 8.2.9][> 8.3][> 9.][< 8.2.7][^][^^][^^^]
Purpose:
[[1] - specifies a single named region in a set of named regions
]
Content:
[[1] - [F1.1]([6.4.27]) EMPTY
[1] - Referring object:
[[2] - [F1.1]<[flow-target-list]>([6.4.26];[Section 8.2.7 <flow-target-list> Object])
]]
Required property:
[F1.1][region-name-reference=]([7.27.21];[Section D.3.3 Property summary])
8.2.9 Headers and footers
[> 8.2.10][> 8.3][> 9.][< 8.2.8][^][^^][^^^]
It is a common requirement for different pages to have different static content
[[1] - consider the need for rendering page numbers on alternate sides of the footer
[[2] - on the right side of odd pages
[2] - on the left side of even pages
][1] - use different region names for the same regions on different pages
[[2] - the odd page <[region-after]> constructs could be named "footer-odd"
[2] - the even page <[region-after]> constructs could be named "footer-even"
[2] - the page sequence would then define two different <[static-content]> constructs
[[3] - the construct flowed to the region named "footer-odd" would place the page number citation on the right
[3] - the construct flowed to the region named "footer-even" would place the page number citation on the left
]]]
It is a common requirement for different pages to have the same content in different places
[[1] - consider the need for rendering information in the outside edge of all pages
[[2] - the same content but alternating the right side on odd pages and the left side on even pages
][1] - cannot use the same region name for different regions on different pages
[[2] - each time you use a given custom name in the set of page geometries, it must always be for the same body or perimeter region
wherever else that name is used in other page geometries
][1] - must duplicate the content if there are two differently named regions in two page geometries in order to obtain identical
results
[[2] - the odd page <[region-end]> construct could be named "outside-odd"
[2] - the even page <[region-start]> construct could be named "outside-even"
[2] - the page sequence would define two identical <[static-content]> constructs to get the same appearance in both regions
[2] - the same results would be better obtained by using the same region names in the two geometries
]]
It is the stylesheet writer's responsibility to supply in each page sequence the definitions of all content desired for the
possible regions triggered by the sequence of pages
[[1] - stylesheets are often repetitive in order to satisfy this requirement
]
8.2.10 <static-content> Object
[> 8.2.11][> 8.3][> 9.][< 8.2.9][^][^^][^^^]
Purpose:
[[1] - the definition of content that is primarily unchanged from page to page in a page sequence
]
Content:
[[1] - ([6.4.20]) ([%block;])+
[1] - Child object:
[[2] - [%block;]([6.2];[Section 3.4.2 Block-level objects])
][1] - Referring object:
[[2] - <[page-sequence]>([6.4.5];[Section 3.3.10 <page-sequence> Object])
]]
Required property:
[flow-name=]([7.27.5];[Section D.3.3 Property summary])
Optional properties:
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[Example 8-3: Static content definition of regions
Excerpts from a draft of a training rendition of this material:
01 <page-sequence id="fo_region-before" master-reference="frames">
02 <static-content flow-name="pages-before" font-style="italic">
03 <block text-align="center">Practical Formatting
04 Using XSL-FO</block></static-content>
05 <static-content flow-name="pages-after-right"
06 font-style="italic" font-size="9pt">
07 <table>...<block text-align="start">Slide 173 of
08 287 <inline font-size="8pt"><frame_static-content></inline
09 ></block>...<block text-align="center">
10 <inline font-size="8pt" font-style="normal"
11 >Information subject to restrictive legend on title page.</inline>
12 </block>...
13 <block text-align="end">Page <page-number/> of
14 <page-number-citation ref-id="N0"/></block>...
15 </table></static-content>
16 <static-content flow-name="pages-after-left"
17 font-style="italic" font-size="9pt">
18 <table>...<block text-align="start">Page <page-number/> of
19 <page-number-citation ref-id="N0"/></block>...
20 <block text-align="center">
21 <inline font-size="8pt" font-style="normal"
22 >Information subject to restrictive legend on title page.</inline>
23 </block>...
24 <block text-align="end"><inline
25 font-size="8pt"><frame_static-content></inline> Slide 173 of
26 287</block>...</table></static-content>
27 <flow>...
]
Of note:
[[1] - the header is a single centered title
[1] - two footers are defined, one for each of the right-hand and left-hand pages
[[2] - the right-hand footer has the page number on the right hand side of the page
[2] - the left-hand footer has the page number on the left hand side of the page
][1] - each footer is a table of three columns
[[2] - the start-side column is aligned to the start edge
[2] - the center column is aligned to the center
[2] - the end-side column is aligned to the end edge
]]
8.2.11 <page-number> Object
[> 8.2.12][> 8.3][> 9.][< 8.2.10][^][^^][^^^]
Purpose:
[[1] - an inline-level placeholder replaced with the page number of the current page
[1] - there are no methods of incorporating a formatted page number in arithmetic of any kind or explicitly in any kind of conditional
test
]
Content:
[[1] - ([6.6.10]) EMPTY
]
Property sets:
[[1] - [Common Accessibility Properties]([7.5];[Section D.1.2 Common Accessibility Properties])
[1] - [Common Aural Properties]([7.7];[Section D.1.3 Common Aural Properties])
[1] - [Common Border, Padding, and Background Properties]([7.8];[Section D.1.4 Common Border, Padding, and Background Properties])
[1] - [Common Font Properties]([7.9];[Section D.1.5 Common Font Properties])
[1] - [Common Margin Properties-Inline]([7.12];[Section D.1.8 Common Margin Properties-Inline])
[1] - [Common Relative Position Properties]([7.13];[Section D.1.9 Common Relative Position Properties])
]
Other optional properties:
[alignment-adjust=]([7.14.1];[Section D.3.3 Property summary])
[alignment-baseline=]([7.14.2];[Section D.3.3 Property summary])
[baseline-shift=]([7.14.3];[Section D.3.3 Property summary])
[dominant-baseline=]([7.14.5];[Section D.3.3 Property summary])
[id=]([7.30.8];[Section D.3.3 Property summary])
[F1.1][index-class=]([7.24.1];[Section D.3.3 Property summary])
[F1.1][index-key=]([7.24.2];[Section D.3.3 Property summary])
[keep-with-next=]([7.20.4];[Section D.3.3 Property summary])
[keep-with-previous=]([7.20.5];[Section D.3.3 Property summary])
[letter-spacing=]([7.17.2];[Section D.3.3 Property summary])
[line-height=]([7.16.4];[Section D.3.3 Property summary])
[score-spaces=]([7.30.15];[Section D.3.3 Property summary])
[text-altitude=]([7.29.4];[Section D.3.3 Property summary])
[text-decoration=]([7.17.4];[Section D.3.3 Property summary])
[text-depth=]([7.29.5];[Section D.3.3 Property summary])
[text-shadow=]([7.17.5];[Section D.3.3 Property summary])
[text-transform=]([7.17.6];[Section D.3.3 Property summary])
[visibility=]([7.30.17];[Section D.3.3 Property summary])
[word-spacing=]([7.17.8];[Section D.3.3 Property summary])
[wrap-option=]([7.16.13];[Section D.3.3 Property summary])
Shorthands influencing the above properties:
[font=]([7.31.13];[Section D.3.3 Property summary])
[page-break-after=]([7.31.16];[Section D.3.3 Property summary])
[page-break-before=]([7.31.17];[Section D.3.3 Property summary])
[vertical-align=]([7.31.22];[Section D.3.3 Property summary])
Of note:
[[1] - the formatter supplies to the flow the characters as <[character]> objects
[[2] - the characters used by the formatter are specified by the [format]= property of the <[page-sequence]> for the page
]]
8.2.12 <folio-prefix> Object
[> 8.2.13][> 8.3][> 9.][< 8.2.11][^][^^][^^^]
Purpose:
[[1] - describe the content flowed immediately preceding the characters of a page number in the page sequence
[1] - also used by citations into the page sequence
]
Content:
[[1] - [F1.1]([6.6.13]) (#PCDATA|[%inline;])*
[1] - Child object:
[[2] - [%inline;]([6.2];[Section 3.4.3 Inline-level objects])
][1] - Referring object:
[[2] - <[page-sequence]>([6.4.5];[Section 3.3.10 <page-sequence> Object])
]]
No properties are defined for this formatting object.
Child of a <[page-sequence]> formatting object
An example from the XSL-FO specification:
[Example 8-4: 01 <fo:page-sequence id="glossary" initial-page-number="1">
02 <fo:page-number-folio-prefix>
03 <fo:inline>G-</fo:inline>
04 </fo:page-number-folio-prefix>
05 <fo:flow>...</fo:flow>
06 </fo:page-sequence>
]
8.2.13 <folio-suffix> Object
[> 8.2.14][> 8.3][> 9.][< 8.2.12][^][^^][^^^]
Purpose:
[[1] - describe the content flowed immediately following the characters of a page number in the page sequence
[1] - also used by citations into the page sequence
]
Content:
[[1] - [F1.1]([6.6.14]) (#PCDATA|[%inline;])*
[1] - Child object:
[[2] - [%inline;]([6.2];[Section 3.4.3 Inline-level objects])
][1] - Referring object:
[[2] - <[page-sequence]>([6.4.5];[Section 3.3.10 <page-sequence> Object])
]]
No properties are defined for this formatting object.
Child of a <[page-sequence]> formatting object
8.2.14 Dynamic content in static content
[> 8.2.15][> 8.3][> 9.][< 8.2.13][^][^^][^^^]
It is often necessary to redefine header information more often than once per page sequence
[[1] - starting a new page sequence starts a new page
[1] - a page sequence of chapter content may require section headings to change when section breaks do not start a new page
[1] - "dictionary heads" are used in a dictionary presentation of many entries
[[2] - the top left of the left-page header indicates the first word found on the page
[2] - the top right of the right-page header indicates the last word found on the page
[2] - the formatter must be told which of the possibilities is desired for choosing the first and last entry on the page
[[3] - is it the first or last definition that begins on the page?
[3] - is it the first or last definition where any part of the definition is on the page?
]]]
Dynamic content that is a candidate for inclusion in static content is captured in the flow in a marker using the <[marker]> object
[[1] - the marker's parent's total area is called a "qualifying area" for the marker
[[2] - the marker is associated with all of the non-normal areas in the qualifying area
][1] - the "containing page" is that page with the first of the areas that would have been rendered for the marker if the marker
were rendered in place
[[2] - marker descendants do not inherit inheritable properties of the marker or its ancestors
[2] - marker descendants do inherit inheritable properties of where the marker is retrieved
][1] - two markers with the same parent object must not have the same [marker-class-name]= property
[[2] - all markers must be the first children of its parent object
]]
Necessary to have canvas information duplicated to be retrieved
[[1] - the marker definition is not rendered on the canvas, only the retrieval
[1] - if the static content needs to be the same as the canvas content, the content must be duplicated in the flow
]
Preference is afforded to the parents of nested markers based on their position in the area tree hierarchy
[[1] - areas higher in the tree (pre-order traversal) are considered preferred over areas lower in the tree
[1] - higher preference is given to a page than to the page that precedes it
]
Areas in area tree have associated markers for each marker class
[[1] - the retrieval algorithm notes the first, last or any areas of a marker on a page
[1] - a page may validly not contain any first or last area for a given marker class
]
Consider this figure that shows four pages generated in the area tree
[Figure 8.5: Adding to the area tree the first, last, and other areas for a marker
Nested formatting objects are shown on the left: three blocks each with markers of class "X" and differentiated by the labels
"A", "B" and "C".
In the upper right, the object tree shows the hierarchy of the nested blocks for groups "A", "B" and "C".
In the lower right, the area tree shows a hierarchy of areas below four pages. The areas from the objects labeled "A" are
seen at the end of the first page, all through the second page, and the start of the third page. An area from the object labeled
"B" follows on the third page. The areas from the objects labeled "C" are seen at the end of the third page and the start
of the fourth page.
The first and last areas of each labeled set of areas are indicated as the "first area" and "last area" respectively.
]
[[1] - the first page has only one first or last area associated with any marker
[[2] - "A" is the first and last marker whose first area is on the page
][1] - the second page doesn't have the first or last area associated with any marker
[[2] - "A" is the only marker with any area on the page
][1] - the third page has a number of such areas
[[2] - "A" is the first marker where any of its areas is on the page
[2] - "B" is the first marker whose first area is on the page
[2] - "B" is the last marker whose last area is on the page
[2] - "C" is the last marker whose first area is on the page
][1] - the fourth page has only one first or last area associated with any marker
[[2] - "C" is the first and last marker whose last area or any area is on the page
]]
Only static content may contain <[retrieve-marker]/> constructs
[[1] - references the marker named by the [retrieve-class-name]= property
[[2] - the marker's content is added to the static content in place of the retrieval construct
]]
Dynamic content inherits properties ancestral to the referencing <[retrieve-marker]> construct
[[1] - inherits properties as if the formatting objects of the marker content existed at the retrieval point
]
Can scope the search for a marker to be retrieved by using [retrieve-boundary]= property
[[1] - looking only on the page
[1] - looking either on the page or on an earlier page in the same page sequence (default)
[1] - looking either on the page or on any earlier page in the document
]
Can ask for the areas of a particular marker based on the marker's position by using [retrieve-position]= property
[[1] - first marker where any area within its parent is in the scope
[1] - first marker whose first area within its parent is in the scope (default)
[1] - last marker whose last area within its parent is in the scope
[1] - last marker whose first area within its parent is in the scope
]
Consider the production of "dictionary heads" where every entry in the dictionary includes a <[marker]> child and the header reflects the first and last entry on the page for navigation purposes:
[Figure 8.6: Options for retrieving markers
Three pages with greeked text are shown in a similar pattern to a dictionary where each page has two columns of definitions.
The last definition on each of the two left pages overflows to the following page. Each definition shows a bolded line of
greeked text at the start of the block. The page in the middle has information at the left of the header and at the right
of the header that comes from the content of the pages.
Four attribute values for the [retrieve-position]= property are associated with four of bolded lines from the content of the pages. Two of these point to the header information
on the left and two point to the header information on the right.
The last bold content from the left page is connected to the left header information and attributed to the property value
"first-including-carryover" with the text "first marker where any area within its parent is on the page."
The first bold content from the middle page is connected to the left header information and attributed with the property value
"first-starting-within-page" with the text "first marker whose first area within its parent is on the page."
The second last bold content from the middle page is connected to the right header information and attributed to the property
value "last-ending-within-page" with the text "last marker whose last area within its parent is on the page."
The last bold content from the middle page is connected to the right header information and attributed to the property value
"last-starting-within-page" with the text "last marker whose first area within its parent is on the page."
]
Recall the identification of first and last qualifying areas for a given marker shown on [Figure 8.5].
[F1.1]Only table headers and footers may contain <[retrieve-table-marker]> constructs
[[1] - alternatively, a header or footer itself may be replaced by a marker retrieval
[[2] - this isn't true for perimeter regions
]]
Can scope the search for a marker to be retrieved by using [retrieve-boundary-within-table]=
[[1] - looking within the table fragment with the marker on the given page
[1] - looking to the start of the table (default)
[1] - looking within all table fragments on the given page
]
Can ask for the areas of a particular marker based on the marker's position by using [retrieve-position-within-table]= property
[[1] - these are the same concepts and effects as happens with page marker retrievals
[[2] - see [Figure 8.6]
[2] - the table fragments are considered in the same way the pages are depicted
][1] - first marker where any area within its parent is in the scope
[1] - first marker whose first area within its parent is in the scope (default)
[1] - last marker whose last area within its parent is in the scope
[1] - last marker whose first area within its parent is in the scope
]
8.2.15 <marker> Object
[> 8.2.16][> 8.3][> 9.][< 8.2.14][^][^^][^^^]
Purpose:
[[1] - the replacement formatting object content for a marker retrieved in static content
[1] - associated with all of the areas generated by its parent formatting object
]
Content:
[[1] - ([6.13.5]) (#PCDATA|[%inline;]|[%block;])*
[1] - Child objects (alphabetical):
[[2] - [%block;]([6.2];[Section 3.4.2 Block-level objects])
[2] - [%inline;]([6.2];[Section 3.4.3 Inline-level objects])
]]
[[1] - content validity dependent on the context of the corresponding <[retrieve-marker]> object the <[marker]> object replaces
]
Required property:
[marker-class-name=]([7.25.1];[Section D.3.3 Property summary])
[Example 8-5:
Defining markers
An excerpt from the samp/marker.fo sample:
01 <page-sequence master-reference="frame">
02 <static-content flow-name="frame-before">
03 <block text-align="end" ...>
04 <retrieve-marker retrieve-class-name="section"/>
05 </block>
06 </static-content>
07 <static-content flow-name="frame-after">
08 <block text-align="end" font-style="italic" font-size="12pt">
09 <retrieve-marker retrieve-class-name="continued"
10 retrieve-position="last-starting-within-page"/>
11 </block>
12 </static-content>
13 ...
14 <flow flow-name="frame-body">
15 ...
16 <block>
17 <marker marker-class-name="section">Section One - 1.</marker>
18 <marker marker-class-name="continued">(continued...)</marker>
19 <block>1. Section One</block>
20 <block space-before="1em">This is a test</block>
21 ...
22 <block space-before="1em">This is a test</block>
23 </block>
24 <block>
25 <marker marker-class-name="continued"></marker>
26 </block>
27
28 <block space-before="2em">
29 <marker marker-class-name="section">Section Two - 2.</marker>
30 <marker marker-class-name="continued">(continued...)</marker>
31 <block>2. Section Two</block>
32 <block space-before="1em">This is a test</block>
33 ...
34 <block space-before="1em">This is a test</block>
35 </block>
36 <block>
37 <marker marker-class-name="continued"></marker>
38 </block>
]
Of note:
[[1] - a surrounding block wraps all the blocks of the section for a section heading
[[2] - the marker is the first child of the surrounding block, thus associating the marker with all of the contained blocks
[2] - the arrangement of the information in the marker can be (and typically would be) different than that used in the body of the
page
][1] - the continuing marker is always retrieved but is defined to be empty at the end of the section
]
8.2.16 <retrieve-marker> Object
[> 8.2.17][> 8.3][> 9.][< 8.2.15][^][^^][^^^]
Purpose:
[[1] - an inline-level placeholder replaced with the formatting objects of the indicated marker
[1] - only allowed as a descendant of static content
]
Content:
[[1] - ([6.13.6]) EMPTY
]
Required property:
[retrieve-class-name=]([7.25.3];[Section D.3.3 Property summary])
Optional properties:
[retrieve-boundary=]([7.25.5];[Section D.3.3 Property summary])
[retrieve-position=]([7.25.4];[Section D.3.3 Property summary])
Properties of note
[[1] - [retrieve-position]= indicates the marker desired by its qualifying areas (default is the first marker whose first qualifying area is on the page)
as illustrated on [Figure 8.5] and [Figure 8.6]
[1] - [retrieve-boundary]= indicates limiting the search for a marker within the page, to the beginning of the page sequence (default), or to the beginning
of the document
]
[Example 8-6:
Retrieving markers
An excerpt from the samp/marker.fo sample:
01 <page-sequence master-reference="frame">
02 <static-content flow-name="frame-before">
03 <block text-align="end" font-weight="bold"
04 color="silver" font-size="12pt">
05 <retrieve-marker retrieve-class-name="section"/>
06 </block>
07 </static-content>
08 <static-content flow-name="frame-after">
09 <block text-align="end" font-style="italic" font-size="12pt">
10 <retrieve-marker retrieve-class-name="continued"
11 retrieve-position="last-starting-within-page"/>
12 </block>
13 </static-content>
14 ...
15 <flow flow-name="frame-body">
16 ...
17 <block>
18 <marker marker-class-name="section">Section One - 1.</marker>
19 <marker marker-class-name="continued">(continued...)</marker>
20 <block>1. Section One</block>
21 <block space-before="1em">This is a test</block>
22 ...
23 <block space-before="1em">This is a test</block>
24 </block>
25 <block>
26 <marker marker-class-name="continued"></marker>
27 </block>
28
29 <block space-before="2em">
30 <marker marker-class-name="section">Section Two - 2.</marker>
31 <marker marker-class-name="continued">(continued...)</marker>
32 <block>2. Section Two</block>
33 <block space-before="1em">This is a test</block>
34 ...
35 <block space-before="1em">This is a test</block>
36 </block>
37 <block>
38 <marker marker-class-name="continued"></marker>
39 </block>
]
8.2.17 <retrieve-table-marker> Object
[> 8.2.18][> 8.3][> 9.][< 8.2.16][^][^^][^^^]
Purpose:
[[1] - an inline-level placeholder replaced with the formatting objects of the indicated marker
[1] - only allowed as a replacement for or descendant of table headers and table footers
]
Content:
[[1] - [F1.1]([6.13.7]) EMPTY
]
Required property:
[retrieve-class-name=]([7.25.3];[Section D.3.3 Property summary])
Optional properties:
[F1.1][retrieve-boundary-within-table=]([7.25.2];[Section D.3.3 Property summary])
[F1.1][retrieve-position-within-table=]([7.25.6];[Section D.3.3 Property summary])
Properties of note
[[1] - [retrieve-position-within-table]= indicates the marker desired by its qualifying areas
[1] - [retrieve-boundary-within-table]= indicates limiting the search for a marker within the table fragment, to the beginning of the table (default), or to only
those on the page
]
8.2.18 Planning a simple page sequence specification
[> 8.3][> 9.][< 8.2.17][^][^^][^^^]
Planning ahead can make page sequence specifying an easier task
[[1] - consider planning a book with a table of contents followed by content in separate page sequences each using the same page
geometry for before and after regions
[1] - a single-sided presentation with the page number at the bottom of all pages
[[2] - static content indicating the current and last page numbers
][1] - different formatting of headers for table of contents and for chapter contents
[[2] - document title in the content page sequences but not in the TOC page sequence
[[3] - the TOC page sequence has a different definition of static content than the content page sequences
]]]
[Figure 8.7: Page sequence planning simple example
Stylesheet constructs are shown at the left, with a <[simple-page-master]> named "bookpage" that has <[region-before]> and <[region-after]> regions named "before" and "after".
A <[block]> containing the sequence "Page ", <[page-number]>, " of ", <[page-number-citation]> is shown belonging in the center of the after regions of every page.
The document title is shown belonging at the center of every before region on the pages of content after the table of contents.
]
8.3 Page Sequence Master Interleave (PSMI)
[> 8.4][< 8.2.18][^^][^^^]
8.3.1 Changing the page geometry based on authored content
[> 8.4][> 9.][< 8.2.18][^^][^^^]
Sometimes it is necessary to change page geometry based on content
[[1] - the XML source author may arbitrarily request a change in the page geometry
[1] - consider the need to change the geometry for a lengthy landscaped table
[[2] - cannot use a rotated table because the table length is limited by the container
[2] - must switch to a landscape body region so the lengthy table flows to subsequent pages
][1] - consider the need to flow certain figures into double-sized pages
[[2] - must selectively choose a geometry with the different dimensions
][1] - the construct may be deep within the structure of the document being processed
]
To use XSL-FO one must package all content for each page geometry for the flow of a page sequence
[[1] - this can involve a difficult and wasteful recursive process
[[2] - finding all information up to the change in geometry
[2] - package the information up in a page sequence
[2] - package up the special constructs in a different page sequence
[2] - recursively find all information up to the next change in geometry
][1] - this breaks the XSLT model of hierarchical processing
[[2] - susceptible to development and maintenance problems
]]
A two-step process can make this very easy to implement
[[1] - the first step creates the flow with supplemental indications of the need to change geometries
[[2] - can come from any depth of processing of the source document
[2] - block level constructs of a page are the immediate children of the flow
][1] - the second step repackages flow children in as many sequences as necessary
[[2] - recursively checks all flow child constructs for any changes in geometry
[2] - not necessary to check any depth deeper than the children
][1] - the resulting document is then processed by a standard XSL-FO engine
]
The Page Sequence Master Interleave (PSMI) semantic implements this algorithm
[[1] - public resource freely available from Crane Softwrights Ltd.
[[2] - [http://www.CraneSoftwrights.com/links/res-pfux.htm]
][1] - one-element vocabulary designed to express the semantic of this two-step intermediate process
[1] - an XSLT stylesheet to implement the semantic for any XSL-FO+PSMI sequence
]
Consider the need to flow a landscape table in a portrait page geometry
[[1] - could rotate a short table in a block container to present in landscape
[[2] - a long table would overflow and not trigger a new page in pagination
][1] - using PSMI one could flow the landscape table into an interleaved page geometry where the body region of that geometry is
landscape
[1] - the PSMI stylesheet reads the XSL-FO+PSMI instance and produces a pure XSL-FO instance where three page sequences are created
where one was before
[1] - a long table in the landscape body region will correctly trigger new pages in pagination
]
[Figure 8.8: Page Sequence Master Interleave (PSMI)
A page sequence in portrait orientation is shown with blocks on the first page, a block container on the middle page, and
blocks on the third page. The block container is rotated with the top being on the left. A table in the block container is
longer than will fit on the page, and an overflow condition exists with only that portion of the table that fits being visible.
The second page sequence shows a PSMI page sequence containing the table instead of the block container. The PSMI page sequence
points to a landscaped page geometry.
The third page sequence shows the result of processing the second page sequence through the PSMI stylesheet. Three page sequences
are created from the one with the table construct flowed inside of the landscaped page geometry. Those constructs outside
the PSMI construct of the second page sequence are still in portrait orientation.
]
The end result of PSMI transformation is a pure XSL-FO instance:
[[1] - the parent XSL-FO page-sequence of the PSMI page-sequence is split
[1] - a new XSL-FO page-sequence is created for the PSMI page-sequence and contains its blocks
[1] - the preceding siblings of the PSMI page-sequence are put in the preceding page sequence
[1] - the following siblings of the PSMI page-sequence are put in the following page sequence
[1] - the process accommodates any number of PSMI children of an XSL-FO page-sequence
]
[Figure 8.9: Block nesting when using PSMI
A pair of nested block diagrams is shown, where child elements are smaller boxes shown inside larger parent boxes.
The boxes on the left show the PSMI page sequence nested at the top of the flow in an XSL-FO page sequence.
The boxes on the right show only XSL-FO page sequences, where the old XSL-FO page sequence has been split into two new page
sequences, one before the XSL-FO page sequence generated from the PSMI page sequence, and one after.
]
The two-step process involves:
[[1] - the user's stylesheet to produce the XSL-FO+PSMI intermediate sequence
[1] - the PSMI stylesheet to produce a pure XSL-FO instance
]
[Figure 8.10: PSMI Use With XSLT
A flow diagram shows the user's transformation script and source document being processed by XSLT to produce an XSL-FO+PSMI
intermediate document. This document is then processed by XSLT with the PSMI stylesheet to produce a pure XSL-FO instance.
The pure XSL-FO instance can then be processed by any conforming XSL-FO engine.
]
[Example 8-7:
PSMI constructs in example
An example of flow implementing the change in page geometry:
01 <simple-page-master master-name="frame-portraitbody" ...>
02 <region-body region-name="frame-body" .../>
03 <region-before region-name="frame-before" .../>
04 <region-after region-name="frame-after" .../>
05 </simple-page-master>
06 <simple-page-master master-name="frame-landbody" ...>
07 <region-body region-name="frame-body"
08 reference-orientation="90" .../>
09 <region-before region-name="frame-before" .../>
10 <region-after region-name="frame-after" .../>
11 </simple-page-master>
12 ...
13 <page-sequence master-reference="frame-portraitbody">
14 <flow flow-name="frame-body">
15 <block>Portrait information</block>
16 ...
17 <block>Next is landscaped</block>
18 <psmi:page-sequence master-reference="frame-landbody"
19 xmlns:psmi="http://www.CraneSoftwrights.com/resources/psmi">
20 <flow flow-name="frame-body">
21 <table>
22 <table-body>
23 <table-row>
24 <table-cell border="solid">
25 <block>This is a test</block>
26 <block>This is a test</block>
27 ...
28 <block>This is a test</block>
29 <block>This is a test</block>
30 </table-cell>
31 </table-row>
32 </table-body>
33 </table>
34 </flow>
35 </psmi:page-sequence>
36 <block>Back to portrait</block>
37 ...
38 </flow>
]
8.4 Page geometry sequencing
[> 9.][< 8.3.1][^^][^^^]
8.4.1 Changing the page geometry based on a pattern of geometries
[> 8.4.2][> 9.][< 8.3.1][^^][^^^]
Every different page geometry must be in a separate <[simple-page-master]> construct
[[1] - each master is uniquely named
[1] - not all regions utilized in the page sequence need be defined on every page geometry
]
A <[page-sequence]> defines the flow for a sequence of pages
[[1] - can create a new page sequence for a change in static content
[1] - can create a new page sequence to start the flow on a new page
[1] - the page sequence utilizes page geometries referenced by the [master-reference]= property
[1] - can force a sequence to create a blank page at end if necessary
[[2] - so the page sequence automatically accommodates the first page number of the following page sequence (default)
[[3] - the following page sequence may be forced to start on an odd or even page number thereby requiring a filler page between the
end of the given page sequence
][2] - so the total number of pages in the page sequence is an even or odd count
[2] - so the last of the page sequence is an even or odd page number
]]
The simplest case is not to sequence the pages
[[1] - a <[page-sequence]> that points to a <[simple-page-master]> repeats that one page for the entire sequence
]
A <[page-sequence-master]> defines an ordering of sub-sequences of page geometries
[[1] - a <[page-sequence]> that points to a <[page-sequence-master]> obtains each page geometry from the specified ordering
[1] - the need for new pages in the flow takes the next page geometry from the next ordered sub-sequence in the master
[[2] - each <[page-sequence-master]> must specify at least one sub-sequence of geometries
][1] - the formatter may signal an error if it exhausts available sub-sequences
[[2] - could otherwise just repeat the last sub-sequence
[2] - to prevent possible error a robust stylesheet should provide an infinitely repeatable sub-sequence as the last sub-sequence
][1] - each master is uniquely named and is also unique from the page geometry names
]
A single required <[layout-master-set]> specifies all masters
[[1] - both single-page masters and page-sequence masters
[1] - there is no semantic order to the set of layout masters
]
8.4.2 Overview of page sequence specifications
[> 8.4.3][> 9.][< 8.4.1][^][^^][^^^]
A complex (and contrived) page sequence could be as complex as depicted in this diagram:
[Figure 8.11: Page sequence specification options
Five boxes representing different page sequences of contained flow are shown, each pointing to one of four boxes representing
<[simple-page-master]> and <[page-sequence-master]> objects. The child objects of the <[page-sequence-master]> objects each point to one of the <[simple-page-master]> objects.
The three objects within one of the <[page-sequence-master]> objects are: <[single-page-master-reference]>, <[repeatable-page-master-reference]>, and <[repeatable-page-master-alternatives]>. The last of which contains a number of <[conditional-page-master-reference]> objects.
]
Note there are only two specifications of actual page geometry, while many and various sequencing patterns of using that geometry
are defined and utilized by the five page sequence specifications
[[1] - all subsequences are composed only of references to page geometries
]
8.4.3 Page geometry sub-sequences
[> 8.4.4][> 9.][< 8.4.2][^][^^][^^^]
A sub-sequence defines some or all of the page geometries used in a page sequence
[[1] - the first page of flow comes from the first qualifying geometry of the first sub-sequence of the page sequence
[1] - when one sub-sequence is exhausted, the next page uses the first qualifying geometry from the next sub-sequence
]
A sub-sequence can specify the use of only one geometry
[[1] - use <[single-page-master-reference]/> to use one geometry once
[1] - use <[repeatable-page-master-reference]/> to use one geometry more than once
[[2] - can be unbounded (default) or bounded to a maximum repetition
]]
A sub-sequence can specify the choice of one of a set of geometries
[[1] - use <[repeatable-page-master-alternatives]> to collect the set of geometries from which to choose
[1] - use <[conditional-page-master-reference]/> to specify the criteria of a choice
[1] - each criterion of a choice is tested in the document order of choices specified in the set
[[2] - the first choice where all criteria test true specifies the geometry used for the page of the flow
][1] - the set of choices is repeated indefinitely by default
[[2] - can be bounded to a maximum repetition
]]
The choice criteria is made up of three sub-conditions
[[1] - all three criteria must be true for the choice to be used
[1] - an unspecified criterion is considered "any" which is true for each test
[[2] - one need only specify the criteria desired for uniqueness
][1] - all criteria values are unambiguous
[[2] - it doesn't matter which order the criteria are specified
[2] - each page tests true for exactly one value for each criterion
]]
A criterion can be based on the parity of the page number
[[1] - use [odd-or-even]= to test the criterion
[1] - "any" (initial value) tests true for all pages
[1] - "odd" tests true of the page number is odd
[1] - "even" tests true if the page number is even
]
A criterion can be based on the position of the page within the page sequence
[[1] - use [page-position]= to test the criterion
[1] - "any" (initial value) tests true for all pages
[1] - "first" tests true if the page is the first in the page sequence
[1] - "last" tests true if the page is the last in the page sequence
[1] - "rest" tests true if the page is neither the first nor the last in the page sequence
[1] - note that a one-page page sequence will test true for both values "first" and "last"
[[2] - requires the stylesheet writer to decide which of the two possible geometries is desired for a one-page page-sequence
[2] - the tests in the alternatives must be ordered such that the desired geometry is selected for the one-page page sequence situation
before the undesired geometry would be selected
]]
A criterion can be based on the page being generated by the flow or not
[[1] - use [blank-or-not-blank]= to test the criterion
[1] - "any" (initial value) tests true for all pages
[1] - "not-blank" tests true if the page contains flow
[1] - "blank" tests true if the page does not contain flow because of the page being generated to meet sequence conditions (i.e. a "forced"
page)
[[2] - e.g. ensuring the last page of a chapter is on an even page number
]]
8.4.4 Forced blank pages
[> 8.4.5][> 9.][< 8.4.3][^][^^][^^^]
A forced blank page is a page not containing any paginated flow, but created by the formatter in response to page sequencing
requirements
[[1] - referred to as a "blank page" in a page sequence
[[2] - tested in <[conditional-page-master-reference]> using [blank-or-not-blank]=
][1] - if no page master is supplied for a blank page, a page with no content is rendered
[1] - always rendered as the last page in a page sequence
]
Two ways a blank page can be triggered by sequencing
[[1] - the page parity of the last page in the given page sequence
[[2] - [force-page-count]=
[2] - all values except no-force can require a blank page to be created
[2] - note this is an extended conformance property and may not be available in all implementations
][1] - the page parity of the first page of the following page sequence
[[2] - a value of [force-page-count]=="auto" on the given page sequence will cause a final blank page to be created based on the parity of the page number of the first
page of the following page sequence
[2] - [initial-page-number]= includes "auto-odd" and "auto-even"
[2] - the following page sequence value is tested for odd or even (including a specified value of "1") forcing the given page sequence
to end on even or odd respectively
[2] - it is common that a blank page appears "unexpectedly" when the conditions of the following page sequence are the actual trigger
[2] - note this is a basic conformance property and must be available in all implementations
]]
Four ways a blank page can be triggered by breaking to a new page
[[1] - using [break-before]="odd-page" or [break-after]="odd-page" when in the middle of an odd page
[1] - using [break-before]="even-page" or [break-after]="even-page" when in the middle of an even page
[1] - it is important to remember that using two [break-before]="page" or [break-after]="page" blocks in a row does not constitute a blank page for the purposes of geometry testing
[[2] - it is a "not-blank" page since there is an empty area on the page from the first of the two blocks
]]
Forcing every second page to be blank in the flow is different
[[1] - cannot be triggered by stylesheet injection of breaks
[[2] - no knowledge of the formatted page boundaries during transformation
][1] - cannot be tested by [blank-or-not-blank]= because there is candidate flow for the even pages
]
It is acceptable to sequence a page geometry not containing any region for the flow
[[1] - the formatter always obtains "the next" page in a sequence of patterned pages when the flow overflows a page boundary
[1] - a page is populated by all of the targeted content for the regions on the page
[[2] - all static content for regions on the page is always formatted
[2] - if no region on the page is for the flow, none of the flow is consumed
[2] - the formatter is then finished with the page and goes to the next geometry in the sequence without changing its position in
the flowed content
]]
Also useful for pages of visible static content
[[1] - e.g. a ruled "Notes by the reader" page on the left hand side opposite content on the right hand side
[1] - label the <[region-body]> on the un-flowed page for use by static content
[1] - define the entire page body content in the static content for the flow
]
8.4.5 <page-sequence-master> Object
[> 8.4.6][> 9.][< 8.4.4][^][^^][^^^]
Purpose:
[[1] - the definition and name of a particular sequence of using page-masters
]
Content:
[[1] - ([6.4.8]) ([single-page-master-reference]|[repeatable-page-master-reference]|[repeatable-page-master-alternatives])+
[1] - Child objects (alphabetical):
[[2] - <[repeatable-page-master-alternatives]>([6.4.11];[Section 8.4.8 <repeatable-page-master-alternatives> Object])
[2] - <[repeatable-page-master-reference]>([6.4.10];[Section 8.4.7 <repeatable-page-master-reference> Object])
[2] - <[single-page-master-reference]>([6.4.9];[Section 8.4.6 <single-page-master-reference> Object])
][1] - Referring object:
[[2] - <[layout-master-set]>([6.4.7];[Section 3.3.9 <layout-master-set> Object])
]]
Required property:
[master-name=]([7.27.8];[Section D.3.3 Property summary])
[Example 8-8: A master of a sequence of pages
Excerpts from a draft XSLT stylesheet for producing training material:
01 <layout-master-set>
02 <simple-page-master master-name="frame-left" ...>
03 <region-body region-name="pages-body" .../>
04 <region-before extent=".3in" region-name="pages-before"/>
05 <region-after extent=".3in" region-name="pages-after-left"/>
06 </simple-page-master>
07 <simple-page-master master-name="frame-right" ...>
08 <region-body region-name="pages-body" .../>
09 <region-before extent=".3in" region-name="pages-before"/>
10 <region-after extent=".3in" region-name="pages-after-right"/>
11 </simple-page-master>
12 <page-sequence-master master-name="frames">
13 <repeatable-page-master-alternatives
14 maximum-repeats="no-limit">
15 <conditional-page-master-reference
16 master-reference="frame-right" odd-or-even="odd"/>
17 <conditional-page-master-reference
18 master-reference="frame-left" odd-or-even="even"/>
19 </repeatable-page-master-alternatives>
20 </page-sequence-master>
21 </layout-master-set>
22 ...
23 <page-sequence master-reference="frames" ...>
]
The page sequence used in this example prepares to alternately use differently-named page masters
[[1] - each page master has the same name for the before region and a different name for the after region
[1] - the page sequence defines the static content to be rendered for every possible named region in all simple page masters triggered
by the page sequence master
[1] - only that static content for the regions that are used on a given page are rendered
[[2] - any defined static content for regions that are not on the page is ignored
]]
8.4.6 <single-page-master-reference> Object
[> 8.4.7][> 9.][< 8.4.5][^][^^][^^^]
Purpose:
[[1] - the specification of the single use of a page-master within a sequence of page-masters
]
Content:
[[1] - ([6.4.9]) EMPTY
[1] - Referring object:
[[2] - <[page-sequence-master]>([6.4.8];[Section 8.4.5 <page-sequence-master> Object])
]]
Required property:
[master-reference=]([7.27.9];[Section D.3.3 Property summary])
8.4.7 <repeatable-page-master-reference> Object
[> 8.4.8][> 9.][< 8.4.6][^][^^][^^^]
Purpose:
[[1] - the specification of the repeated use of a page-master within a sequence of page-masters
]
Content:
[[1] - ([6.4.10]) EMPTY
[1] - Referring object:
[[2] - <[page-sequence-master]>([6.4.8];[Section 8.4.5 <page-sequence-master> Object])
]]
Required property:
[master-reference=]([7.27.9];[Section D.3.3 Property summary])
Optional property:
[maximum-repeats=]([7.27.10];[Section D.3.3 Property summary])
8.4.8 <repeatable-page-master-alternatives> Object
[> 8.4.9][> 9.][< 8.4.7][^][^^][^^^]
Purpose:
[[1] - the collection of candidate page-master references from which the first one in document order is to be used based on successful
status conditions detected by the formatter
]
Content:
[[1] - ([6.4.11]) ([conditional-page-master-reference]+)
[1] - Child object:
[[2] - <[conditional-page-master-reference]>([6.4.12];[Section 8.4.9 <conditional-page-master-reference> Object])
][1] - Referring object:
[[2] - <[page-sequence-master]>([6.4.8];[Section 8.4.5 <page-sequence-master> Object])
]]
Optional property:
[maximum-repeats=]([7.27.10];[Section D.3.3 Property summary])
Of note:
[[1] - child <[conditional-page-master-reference]> objects are tested in document order of the stylesheet
[1] - stylesheet writer must order the children to ensure the first child that tests true for all conditions refers to the desired
page geometry
[1] - special consideration for a one-page page sequence:
[[2] - a page-sequence of only one page tests true for both the first page of the sequence and the last page of the sequence
[2] - stylesheet writer decides how to treat a one-page page sequence and orders that choice in document order before the undesirable
choice
]]
[Example 8-9: A master of a sequence of pages
Excerpts from a draft XSLT stylesheet for this training material document:
01 <layout-master-set>
02 <simple-page-master master-name="frame-left" ...>
03 <region-body region-name="pages-body" .../>
04 <region-before extent=".3in" region-name="pages-before"/>
05 <region-after extent=".3in" region-name="pages-after-left"/>
06 </simple-page-master>
07 <simple-page-master master-name="frame-right" ...>
08 <region-body region-name="pages-body" .../>
09 <region-before extent=".3in" region-name="pages-before"/>
10 <region-after extent=".3in" region-name="pages-after-right"/>
11 </simple-page-master>
12 <page-sequence-master master-name="frames">
13 <repeatable-page-master-alternatives
14 maximum-repeats="no-limit">
15 <conditional-page-master-reference
16 master-reference="frame-right" odd-or-even="odd"/>
17 <conditional-page-master-reference
18 master-reference="frame-left" odd-or-even="even"/>
19 </repeatable-page-master-alternatives>
20 </page-sequence-master>
21 </layout-master-set>
22 ...
23 <page-sequence master-reference="frames" ...>
]
8.4.9 <conditional-page-master-reference> Object
[> 8.4.10][> 9.][< 8.4.8][^][^^][^^^]
Purpose:
[[1] - a page-master choice available to the formatter when selecting from a collection of candidate page-masters
]
Content:
[[1] - ([6.4.12]) EMPTY
[1] - Referring object:
[[2] - <[repeatable-page-master-alternatives]>([6.4.11];[Section 8.4.8 <repeatable-page-master-alternatives> Object])
]]
Required property:
[master-reference=]([7.27.9];[Section D.3.3 Property summary])
Optional properties:
[blank-or-not-blank=]([7.27.1];[Section D.3.3 Property summary])
[odd-or-even=]([7.27.12];[Section D.3.3 Property summary])
[page-position=]([7.27.14];[Section D.3.3 Property summary])
[Example 8-10: A master of a sequence of pages
Excerpts from a draft XSLT stylesheet for training material:
01 <layout-master-set>
02 <simple-page-master master-name="frame-left" ...>
03 <region-body region-name="pages-body" .../>
04 <region-before extent=".3in" region-name="pages-before"/>
05 <region-after extent=".3in" region-name="pages-after-left"/>
06 </simple-page-master>
07 <simple-page-master master-name="frame-right" ...>
08 <region-body region-name="pages-body" .../>
09 <region-before extent=".3in" region-name="pages-before"/>
10 <region-after extent=".3in" region-name="pages-after-right"/>
11 </simple-page-master>
12 <page-sequence-master master-name="frames">
13 <repeatable-page-master-alternatives
14 maximum-repeats="no-limit">
15 <conditional-page-master-reference
16 master-reference="frame-right" odd-or-even="odd"/>
17 <conditional-page-master-reference
18 master-reference="frame-left" odd-or-even="even"/>
19 </repeatable-page-master-alternatives>
20 </page-sequence-master>
21 </layout-master-set>
22 ...
23 <page-sequence master-reference="frames" ...>
]
8.4.10 Planning a more complex page sequence specification
[> 9.][< 8.4.9][^][^^][^^^]
Planning ahead helps more when considering more complex requirements
[[1] - consider planning a book with a table of contents and the contents each starting on the right-hand page
[1] - different formatting of headers and footers for table of contents and for contents
[[2] - table of contents with only the page number centered in the footer and an even number of pages in total count (to ensure the
content starts on an odd page)
[2] - other pages with document title at bottom left of odd pages and bottom right of even pages, and chapter title at top right
of odd pages and top left of even pages
]]
[Figure 8.12: Page sequence planning complex example
Stylesheet constructs are shown at the top left, with a <[page-sequence-master]> named "bookpage" being defined as a <[repeatable-page-master-alternatives]> containing a <[conditional-page-master-reference]> for odd pages pointing to the <[simple-page-master]> named "bookpage-right", and a <[conditional-page-master-reference]> for even pages pointing to the <[simple-page-master]> named "bookpage-left". These simple page masters have respective <[region-before]> and <[region-after]> regions named "before-right", "after-right", "before-left", and "after-left".
A <[block]> containing the sequence "Page ", <[page-number]>, " of ", <[page-number-citation]> is shown belonging in the center of the after regions of every page.
The document title is shown belonging at the left of every after region on the odd pages, and the right of every after region
on the even pages.
The chapter title is shown belonging at the right of every before region on the odd pages, and the left of every before region
on the even pages.
]
This is an accessible version of Crane's commercial training material.
The content has been specifically designed to assist screen reader software
in viewing the entire textual content. Figures are replaced with text
narratives.
Navigation hints are in square brackets:
[Tx.x] and [Fx.x] are textual representations of the applicability icons;
[digit] indicates list depth for nested lists;
[link [URL]] indicates the URL of a hyperlink if different than link;
[EXAMPLE] indicates an example listing of code;
[FIGURE] indicates the presence of a figure replaced by its description;
[>] jumps forward;
[<] jumps backward;
[^] jumps to start of the section;
[^^] jumps to the start of the chapter;
[^^^] jumps to the table of contents.
Suggestions for improvement are welcome:
[info@CraneSoftwrights.com]
Book sales: [http://www.CraneSoftwrights.com/links/trn-acc.htm]
Information: [http://www.CraneSoftwrights.com/links/info-acc.htm]
This content is protected by copyright and, as there are no means to protect
this accessible version from plagiarism, please do not make any
commercial edition available to others.
+//ISBN 978-1-894049::CSL::Courses::PFUX//DOCUMENT Practical Formatting Using XSL-FO 2008-01-27 17:30UTC//EN
Practical Formatting Using XSL-FO
Seventh Edition - 2008-01-27
ISBN 978-1-894049-19-1
Copyright © Crane Softwrights Ltd.