3.3 Formatting object XML vocabulary

3.3.1 Vocabulary structure

The semantics of a formatting object are defined in terms of the areas it generates and their traits. The Recommendation describes which areas each object generates (if any), where the areas are placed in the branches of the area tree hierarchy, and how the areas interact with areas generated by other objects.

To trigger the semantics desired, formatting objects and their properties are specified using elements, attributes, and text. This information may be reified in a standalone XML instance being interpreted by a formatter, or it may be represented in a node tree resulting from a transformation process such as XSLT.

All XSL-FO elements input to the processor must be in the namespace with the URI " http://www.w3.org/1999/XSL/Format ", and may use the default namespace for this URI.

The "X" in XSL-FO does represent "Extensible," so an XSL-FO instance may include extension elements and attributes that are recognized by the formatting processor. Any other processor is not obliged to support an extension recognized by a given processor. Extension elements must be in a namespace other than the XSL-FO namespace. Extension attributes must have a non-null prefix. Extension constructs must be ignored if not recognized by an XSL-FO processor.

The element-type and attribute names are all specified with letters in lowercase (remember that XML is case sensitive). Hyphens separate multiple words in a single name and dots separate names from their compound components . Some abbreviations are used in XSL-FO if the name is already used in XML or HTML.

Any property is allowed to be specified on any object in the elements and attributes of the input. This flexibility provides for inheritance in the formatting object tree. Only those traits meaningful to a formatting object are in the refined formatting object tree and are utilized by the areas created by the object. Some properties not defined to be inheritable by default can be inherited if their values explicitly specify this.

Every object may have a unique identifier specified using the id property. This is used as the target of references from other objects. This value is never inherited from other objects and is assigned to the first child area generated by the object. For the reference to work properly, the identifier must be found somewhere in the area tree, so if the object doesn't generate any areas, the identifier is lost and the reference is broken.

Extension objects and/or properties are allowed in any namespace other than the XSL-FO namespace. For example, xmlns:rx="http://www. renderx .com/XSL/Extensions" is recognized by the RenderX formatter tool for unique objects and properties implemented by it, while xmlns:axf="http://www.antennahouse.com/names/XSL/Extensions" is recognized by the Antenna House, Inc. formatter tool for yet other different objects and properties implemented by that tool. Vendors can implement any semantics they wish and have any vocabulary they wish to represent a user 's intent to engage those extended semantics. There is no obligation on any tool to support any vendor's extension semantics.

Note:

This is an important portability issue. A user who engages extension semantics cannot assume these semantics will be available on any other tool than that which implements the semantics. Taking advantage of an extension will most likely lock a user into a particular brand of formatting engine. This may have repercussions on the user's ability to distribute stylesheets to other users who may not be in a position to take advantage of the custom extension.

Non-XSL-FO namespaces are allowed in an XSL-FO instance when used to embed the representation of a graphic image in the flow. For example, xmlns:svg="http://www.w3.org/2000/svg" is W3C's two-dimensional graphics XML vocabulary that can be embedded in allowed places in an XSL-FO instance. It is up to the rendering process in the formatter to recognize the non-XSL-FO namespace and realize the image in the result.

3.3.2 Direct vs. constraint property specification

Properties influence the behavior of an object in the creation of areas for the formatted result. Properties are specified in an XSL-FO XML instance or node tree as attributes and become traits in the area tree.

Properties can be strategically placed in the hierarchy (or specified algorithmically by the stylesheet writer) in order to promote maintainability or consistency in the formatted result.

Some properties directly specify a formatting result, such as the color property. The interpretation of a direct property is not influenced by the context of the areas surrounding the area with the property. In this example, the foreground color trait of the area is the given value regardless of where it is used.

Some properties constrain the formatting result based on an interpretation of context in the area tree, such as the space-before property. The interpretation of a constraint property specified identically for two areas may be different based on the context of the generated areas (not on the context of the objects that generated the areas). In this example, the amount of space left before an area is constrained, but should that area be at the top of a reference area (say, a page), and the area's conditionality allows to discard the space before, then the actual value used is zero because the space before is discarded.

Compound properties have components for fine-grained specification. These often originate from the CSS2 specification but they specify too many aspects of formatting in a single specification. XSL-FO allows for the components to be individually specified. An example is the space-before.optimum , space-before.minimum , space-before.maximum , space-before.conditionality , and space-before.precedence components of the space-before property.

It is not necessary to know all properties to get effective formatted results. A complete alphabetical list of formatting properties is in Section D.4.

3.3.3 Property value expressions

A property's value can be the evaluation of an expression of either fixed values, such as space-before="20pt div 2" , or contextually-sensitive values, such as space-before="from-parent(font-size) div 2" .

The expression language is similar to that of XPath 1.0 in that it includes the same operators and the same operands, but it also includes length values as operands that are not allowed in XPath 1.0.

Expressions that are influenced by the font size evaluate the font size before evaluating any other components of the expression.

XSL-FO defines a core function library useful for property expressions.

Some functions give access to property values of the current node, such as inherited-property-value( property-name ) . This obtains a value that may be specified on the current node or may be inherited from the closest ancestral node that specifies the value.

Some functions give access to property values of other nodes, such as from-parent( property-name ) or merge-property-values( property-name ) . The former obtains the property value directly from the parent object specification, and the latter looks for the property value in the particular sibling object specification corresponding to a given state of the user interface.

There are numerous property data types including both simple-valued and compound-valued types that are summarized in Section D.2.1 on page 334.

3.3.4 Inherited properties

Inheritable properties need not be specified for a formatting object because during refinement, the formatting object tree is examined for the closest specifications of such properties to obtain values for a given object. All inheritance is completed before the area tree is created. See Section D.3.1 for a list of all inherited properties.

Inheritance goes "through" block-level or out-of-line constructs because of the location of such constructs in the formatting object tree. This is often the source of unexpected results in a stylesheet's result. For example, the same start-indent property used to indent a table is inherited by the table's cell's content because the table is an ancestor of the cell . In another common example, a footnote's body inherits properties from the block in which the footnote is specified, again because of the ancestral relationship in the formatting object tree. Without explicitly setting the indentation on a footnote's body, any indentation of the block in which the footnote is cited will be inherited by the footnote body's blocks. One's intuition might be that the blocks at the bottom of the page have no relationship to the blocks in the middle of the page, but that is true only for the result of area tree creation from the hierarchically related constructs.

Some functions can obtain property values from outside the ancestry, looking at siblings of ancestral constructs for the traits for the areas the object is generating. Two examples of such functions are merge-property-values() and from-table-column() .

Some properties look like they are inherited, but do not go "through" block-level or out-of-line constructs. For example, text-decoration is used to underscore text in a block and all inline descendants of the block, but not any descendants of any footnotes or tables found in the block.

3.3.5 Shorthand properties

Shorthand properties specify a number of standalone properties using a single specification. This is different from a compound property in that a shorthand property represents a set of standalone properties whereas a compound property is comprised of a set of components. For example, one specification font="italic small-caps bold 40pt/50pt Courier" sets each of font-style , font-variant , font-weight , font-size , line-height , and font-family in order with a single specification.

Individual properties of a shorthand property are supported severally in that a shorthand property can be used in conjunction with individual properties: those that are specified are more precise than those that are inferred.

Shorthand properties are processed in the order of increasing precision. The precedence order is independent of attribute specification order (remember that in XML, attributes are unordered). A more-specific attribute name has higher precedence than less-specific attribute name. For example, border-color is more precise than border , and border-bottom-color is more precise than border-color .

Named-edge border specifications have higher precedence than generic border specifications, even though they have the same specificity, so that border-bottom is more precise than border-style .

A processor is not obliged to support shorthand properties. See Section D.3.2 for a list of all shorthand properties. It is common problem when writing stylesheets to get no effect from a given formatter because it doesn't support a shorthand you were using with other formatters.

3.3.6 Conformance

There are three levels of conformance defined in the Recommendation: complete, extended, and basic.

• Claiming complete conformance requires the implementation to support the entire Recommendation.

• Claiming extended conformance does not require an implementation to support shorthand properties or a very few esoteric positioning- and font-related properties. The remainder of the Recommendation must be fully supported.

• Claiming basic conformance requires a minimum level of visual pagination or aural rendering support. Fallback behaviors are defined for the unsupported extended facilities.

In a given medium, a processor must support all formatting objects and properties specified for the conformance level claimed. The conformance levels are described for two rendering class distinctions: visual media and aural media. A processor can implement fallback processing in media not supported, but conformance qualification does not include fallback processing.

3.3.7 Top-level formatting objects

All XSL-FO instances must have the root and layout-master-set formatting objects. The root is the document element of an XSL-FO instance. It is a handy location for document-wide inherited attributes to be placed. The layout-master-set collects definitions of page geometries available to use for pagination as well as definitions of patterns of geometry sequencing for nuances in changes of page layout.

All XSL-FO instances must have at least one page sequence with flowed content to be paginated . Each page-sequence object begins a new page with some content to be paginated using a sequence of page geometries. It defines properties and content common to all pages in the sequence, such as the formatting of page numbers in the sequence and the definitions of any static content (i.e. headers, footers, etc.) for the page geometries selected for the page sequence.

As many pages will be created as is needed to accommodate the flow given for the sequence. An exception is when the number of pages of the sequence or the starting page number of the following sequence is constrained to be an even or odd number, in which case the formatter may need to generate a blank page to accommodate the criterion. This blank page can be defined with static content to inform the reader that the page is intentionally left blank. Also, the use of break-before and break-after in a sequence can cause information to start at the top of a page in the middle of the sequence.

The formatter will use either the page geometry or the pattern of geometry sequencing to select the pages, in order to accommodate the content and any blank pages.

The flow object contains the content to be paginated in a sequence of pages of a given geometry or geometry sequence. This object can only contain block-level formatting objects as its top-level child objects.

3.3.8 The root object

Purpose

• This is the document element of an XSL-FO instance;

• it returns areas generated by children as a sequence of page viewport areas;

  • such areas are ordered but there is no geometric relationship between areas.

Content

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

• child objects (listed alphabetically ):

  • declarations ( 6.4.3 ; 297),

  • layout-master-set ( 6.4.6 ; 65),

  • page-sequence ( 6.4.5 ; 65).

Optional property

• media-usage ( 7.25.11 ; 395).

A property of interest

• media-usage is used when establishing either pagination with bounded page length or no pagination with infinite page length.

An XSL-FO instance's document element is shown in Example 3-1.

Example 3-1 The document element

 Line 01 <?xml version="1.0" encoding="utf-8"?>      02  <root xmlns="http://www.w3.org/1999/XSL/Format" font-size="16pt">  03   <layout-master-set>      04     <simple-page-master master-name="bookpage"       05                         page-height="297mm" page-width="210mm"      06                         margin-top="15mm" margin-bottom="15mm"      07                         margin-left="15mm" margin-right="15mm">      08       <region-body region-name="bookpage-body"       09                    margin-top="5mm" margin-bottom="5mm"/>      10     </simple-page-master>      11   </layout-master-set>      12   <page-sequence master-reference="bookpage">      13     <title>Hello world example</title>      14     <flow flow-name="bookpage-body">      15       <block>Hello XSL-FO!</block>      16     </flow>      17   </page-sequence>      18  </root>  

3.3.9 The layout-master-set object

Purpose

• This is the collection of definitions of page geometries, available regions , and page selection patterns.

Content

• ( 6.4.6 ) ( simple-page-master page-sequence-master)+,

• child objects (listed alphabetically):

  • page-sequence-master ( 6.4.7 ; 220),

  • simple-page-master ( 6.4.12 ; 114),

• referring object:

  • root ( 6.4.2 ; 64).

No properties are defined for this formatting object.

A set of layout masters is shown in Example 3-2.

Example 3-2 The collection of all possible page layouts and their respective regions

 Line 01 <?xml version="1.0" encoding="utf-8"?>      02 <root xmlns="http://www.w3.org/1999/XSL/Format" font-size="16pt">      03  <layout-master-set>  04     <simple-page-master master-name="bookpage"       05                         page-height="297mm" page-width="210mm"      06                         margin-top="15mm" margin-bottom="15mm"      07                         margin-left="15mm" margin-right="15mm">      08       <region-body region-name="bookpage-body"       09                    margin-top="5mm" margin-bottom="5mm"/>      10     </simple-page-master>      11  </layout-master-set>  12   <page-sequence master-reference="bookpage">      13     <title>Hello world example</title>      14     <flow flow-name="bookpage-body">      15       <block>Hello XSL-FO!</block>      16     </flow>      17   </page-sequence>      18 </root> 

3.3.10 The page-sequence object

Purpose

• This is the definition of information for a sequence of pages with common static information.

• It implies generating as many pages as necessary to accommodate the flowed content that is supplied.

• Each new page sequence begins the flow at the top of a new page;

  • examples include starts of chapters, front matter, back matter, etc.

Content

• ( 6.4.5 ) ( title?, static-content *, flow),

• child objects (listed alphabetically):

  • flow ( 6.4.18 ; 67),

  • static-content ( 6.4.19 ; 202),

  • title ( 6.4.20 ; 117),

• referring object:

  • root ( 6.4.2 ; 64).

Required property

• master-reference ( 7.25.9 ; 394).

Optional properties

• country ( 7.9.1 ; 371),

• force-page-count ( 7.25.6 ; 380),

• format ( 7.24.1 ; 380),

• grouping-separator ( 7.24.2 ; 381),

• grouping-size ( 7.24.3 ; 382),

• id ( 7.28.2 ; 384),

• initial- page-number ( 7.25.7 ; 385),

• language ( 7.9.2 ; 387),

• letter-value ( 7.24.4 ; 390).

Shorthand influencing the object's properties

• xml:lang ( 7.29.24 ; 429).

Properties of interest

• master-reference selects the page geometry or sequencing of page geometry and the available regions within those page definitions;

  • it cannot change the page geometry based on content found in the flow.

• format governs how the page number is represented as a sequence of glyphs;

  • it applies to page numbers used

  • on the page itself,

  • in citations to the page;

• it can specify numbers, roman numerals, etc.

  • by utilizing grouping-size , grouping-separator , country , and language if appropriate;

• it is formally defined by reference to XSLT (see page ).

A sequence of pages is shown in Example 3-3.

Example 3-3 A sequence of pages

 Line 01 <?xml version="1.0" encoding="utf-8"?>      02 <root xmlns="http://www.w3.org/1999/XSL/Format" font-size="16pt">      03   <layout-master-set>      04     <simple-page-master master-name="bookpage"       05                         page-height="297mm" page-width="210mm"      06                         margin-top="15mm" margin-bottom="15mm"       07                         margin-left="15mm" margin-right="15mm">      08       <region-body region-name="bookpage-body"       09                    margin-top="5mm" margin-bottom="5mm"/>      10     </simple-page-master>      11   </layout-master-set>      12  <page-sequence master-reference="bookpage">  13     <title>Hello world example</title>      14     <flow flow-name="bookpage-body">      15       <block>Hello XSL-FO!</block>      16     </flow>      17  </page-sequence>  18 </root> 

3.3.11 The flow object

Purpose

• This is the content that is flowed to as many pages as required to fit;

  • flowed content is not repeated by the formatter;

• the length of the flow governs the length of the page sequence.

Content

• ( 6.4.18 ) (%block;)+ ,

• child object:

  • %block; ( 6.2 ; 69),

• referring object:

  • page-sequence ( 6.4.5 ; 65),

• any number of marker children at the beginning.

Required property

• flow-name ( 7.25.5 ; 376).

Property use

• flow-name indicates into which area on the page the child information is to be flowed.

  • The area does not have to exist in the particular page geometry being rendered;

    • this is the method to ignore a flow on particular pages.

A flow of information for an area is shown in Example 3-4.

Example 3-4 The flow of information for an area

 Line 01 <?xml version="1.0" encoding="utf-8"?>      02 <root xmlns="http://www.w3.org/1999/XSL/Format" font-size="16pt">      03   <layout-master-set>      04     <simple-page-master master-name="bookpage"       05                         page-height="297mm" page-width="210mm"      06                         margin-top="15mm" margin-bottom="15mm"      07                         margin-left="15mm" margin-right="15mm">      08       <region-body region-name="bookpage-body"       09                    margin-top="5mm" margin-bottom="5mm"/>      10     </simple-page-master>      11   </layout-master-set>      12   <page-sequence master-reference="bookpage">      13     <title>Hello world example</title>      14  <flow flow-name="bookpage-body">  15       <block>Hello XSL-FO!</block>      16  </flow>  17   </page-sequence>      18 </root> 

3.3.12 Grouping of formatting objects for the flow

There are five groups of formatting objects that can be used in the flow of information being paginated: block-level, inline-level, neutral, out-of-line, and out-of-line inline-level.

Objects of each kind dictate how the areas created by these objects stack next to each other. Areas are added to branches of the area tree and interact with adjacent areas in the area tree. This interaction on the rendered page is the stacking of areas, and stacking can be either in the block-progression direction (e.g. top-to-bottom of the page in a Western European writing direction) or in the inline-progression direction (e.g. left-to-right of the page in a Western European writing direction).

Block-level objects stack next to siblings in the block-progression direction. This has the effect of restarting the flow of information in the block-progression direction, preventing siblings from being "beside" each other in the inline-progression direction. The block object is a very frequently used construct, used for typographical constructs such as paragraphs, headings, captions, table cell contents, etc.

Inline-level objects stack next to siblings in the inline-progression direction. These objects do not restart the flow of information in the block-progression direction. Inline objects specify portions of content to be flowed into the lines of the parent block, where such portions are distinct from their sibling portions, such as bold or italic text fragments .

Neutral objects are allowed anywhere and do not impact the stacking of sibling objects, nor interrupt the progression direction of the parent object.

Out-of-line objects generate areas on branches of the area tree different from those of their sibling objects. As such, the areas of these objects stack out of line relative to the areas of sibling objects. These objects do not break the flow of information in any progression direction.

Out-of-line inline-level objects are similar to out-of-line objects in that they generate areas on branches of the area tree different from those of their sibling objects, but they are restricted to be used solely as inline-level constructs and never as block-level constructs.

3.3.13 Block-level objects

These objects, represented by the %block; parameter entity in content models, include

• block ( 6.5.2 ; 100):

  • is the formatting specification for a block of lines, distinct from any preceding block of lines,

• block-container ( 6.5.3 ; 109):

  • is the specification of a block-level reference area for contained descendant blocks,

• list-block ( 6.8.2 ; 131):

  • is the parent object of a related set of child list members ,

• table-and-caption ( 6.7.2 ; 170):

  • is the parent object of a captioned collection of tabular content,

• table ( 6.7.3 ; 173):

  • is the parent object of an uncaptioned collection of tabular content.

These objects are allowed as children of the flow object;

• they may also be nested inside other constructs.

Block-level objects are stacked in the block-progression direction of flow;

• they restart the block-progression flow of information;

• two block-level objects cannot be positioned next to each other in the inline-progression direction within the same containing object;

• note that block-container can, selectively, be absolutely positioned outside of the flow and its areas will then not stack with its sibling areas.

3.3.14 Inline-level objects

These objects, represented by the %inline; parameter entity in content models, include

• basic-link ( 6.9.2 ; 145):

  • is the inline content of the start of a unidirectional link to a single end point,

• bidi-override ( 6.6.2 ; 293):

  • overrides the inherent Unicode text direction for a sequence of characters ,

• character ( 6.6.3 ; 294):

  • is both the abstract formatting object implied by a simple character in an XSL-FO instance and the concrete formatting object available to be used in place of a simple character,

• external-graphic ( 6.6.5 ; 139):

  • is the inline display of graphical or other externally-supplied information,

• inline ( 6.6.7 ; 103):

  • is the formatting specification for inline content that is distinct from its preceding content within a line generated in a block,

• inline-container ( 6.6.8 ; 108):

  • is an inline reference area for contained blocks,

• instream-foreign-object ( 6.6.6 ; 141):

  • is the inline display of graphical or other instance-supplied information,

• leader ( 6.6.9 ; 152):

  • is the inline display of a rule or a sequence of glyphs,

• multi-toggle ( 6.9.5 ; 276):

  • is the definition of interaction-sensitive objects within a candidate rendered sequence of formatting objects,

• page-number ( 6.6.10 ; 204):

  • is an inline-level placeholder replaced with the page number of the current page,

• page-number-citation ( 6.6.11 ; 105):

  • is an inline-level placeholder replaced with the page number of the first normal area of the cited formatting object.

These blocks are not allowed as children of the flow object;

• they may be nested inside constructs (including other inline constructs).

Inline-level objects are stacked in the inline-progression direction of flow;

• they do not restart the block-progression flow of information;

• they reside in the line areas generated by the formatter.

3.3.15 Neutral objects

These objects, typically allowed anywhere where #PCDATA , %inline; , or %block; constructs are allowed, include

• multi-properties ( 6.9.6 ; 268):

  • is the collection of candidate property sets from which exactly one set influences the properties of a formatting object based on its status or the status of user interaction,

• multi-switch ( 6.9.3 ; 271):

  • is the collection of candidate formatting object sequences from which exactly one is rendered at any given time based on an interactive condition influenced by the user while being tracked by the formatter,

• retrieve-marker ( 6.11.4 ; 209):

  • is a placeholder replaced with the formatting objects of the indicated marker and allowed only within static content,

• wrapper ( 6.11.2 ; 100):

  • is a generic container construct for specifying inherited properties for descendent constructs.

Note that individual flow objects above may have constraints preventing their use in particular objects.

Areas returned by the interpretation of these objects are stacked in the progression direction of the siblings of these objects.

• Except for retrieve-marker , the others may be children of the flow object.

3.3.16 Out-of-line objects

These objects, typically allowed anywhere where #PCDATA , %inline; , or %block; constructs are allowed, include

• float ( 6.10.2 ; 233):

  • is the content to be rendered towards either the before, start, or end edges of a region regardless of where in the region the content is defined.

These objects are not stacked in the progression direction of the sibling objects;

• areas returned are contained within and governed by ancestral page-sequence object.

Out-of-line objects are allowed as children of the flow object;

• they may also be nested inside other constructs.

3.3.17 Out-of-line inline-level objects

Out-of-line objects allowed only inline, i.e. anywhere where #PCDATA or %inline; constructs are allowed, include

• footnote ( 6.10.3 ; 237):

  • is the content to be rendered towards the after edge of a region regardless of where in the region the content is defined.

One of the two generated areas is stacked in the progression direction of the sibling inline objects;

• the other area returned is contained within and governed by ancestral page-sequence object.

Out-of-line inline objects are not allowed as children of the flow object;

• they must be placed in a block to behave at the block level.