7 Formatting Properties

7.1 Description of Property Groups

The following sections describe the properties of the XSL formatting objects.

A number of properties are copied from the CSS2 specification. In addition, the CSS2 errata all apply. See [CSS2].

Properties copied from CSS2 are placed in a box with wide black borders, and properties derived from CSS2 properties are placed in a box with thin black borders.

• The first nine sets of property definitions have been arranged into groups based on similar functionality and the fact that they apply to many formatting objects. In the formatting object descriptions the group name is referred to rather than referring to the individual properties.

  • Common Accessibility Properties

    This set of properties are used to support accessibility.

  • Common Absolute Position Properties

    This set of properties controls the position and size of formatted areas with absolute positioning.

  • Common Aural Properties

    This group of properties controls the aural rendition of the content of a formatting object. They appear on all formatting objects that contain content and other formatting objects that group other formatting objects and where that grouping is necessary for the understanding of the aural rendition. An example of the latter is fo:table-and-caption.

  • Common Border, Padding, and Background Properties

    This set of properties controls the backgrounds and borders on the block-areas and inline-areas.

  • Common Font Properties

    This set of properties controls the font selection on all formatting objects that can contain text.

  • Common Hyphenation Properties

    Control of hyphenation for line-breaking, including language, script, and country.

  • Common Margin Properties-Block

    These properties set the spacing and indents surrounding block-level formatting objects.

  • Common Margin Properties-Inline

    These properties set the spacing surrounding inline-level formatting objects.

  • Common Relative Position Properties

    This set of properties controls the position of formatted areas with relative positioning.

• The remaining properties are used on a number of formatting objects. These are arranged into clusters of similar functionality to organize the property descriptions. In the formatting object description the individual properties are referenced.

  • Area Alignment Properties

    Properties that control the alignment of inline-areas with respect to each other, particularly in relation to the mixing of different baselines for different scripts. In addition, there are two properties: "display-align" and "relative-align" that control the placement of block-areas.

  • Area Dimension Properties

    Properties that control the dimensions of both block-areas and inline-areas.

  • Block and Line-related Properties

    Properties that govern the construction of line-areas and the placement of these line-areas within containing block-areas.

  • Character Properties

    Properties that govern the presentation of text, including word spacing, letter spacing, and word space treatment and suppression.

  • Color-related Properties

    Properties that govern color and color-model selection.

  • Float-related properties

    Properties governing the placement of both side-floats (start- and end-floats) and before-floats ("top" floats in "lr-tb" writing-mode).

  • Keeps and Breaks Properties

    Properties that control keeps and breaks across pages, columns, and lines, including widow and orphan control and keeping content together.

  • Layout-related Properties

    These properties control what is "top" ("reference-orientation") as well as clipping, overflow, and column-spanning conditions.

  • Leader and Rule Properties

    Properties governing the construction of leaders and horizontal rules.

  • Properties for Dynamic Effects

    Properties governing the presentation and actions associated with links and other dynamic effects.

  • Properties for Markers

    Properties governing the creation and retrieval of markers. Markers are used typically for "dictionary" headers and footers.

  • Properties for Number to String Conversions

    Properties used in the construction of page-numbers and other formatter-based numbering.

  • Pagination and Layout Properties

    These properties govern the sequencing, layout, and instantiation of pages, including: the page size and orientation, sizes of regions on the page-master, the identification and selection of page-masters, division of the body region into columns, and the assignment of content flows to layout regions.

  • Table Properties

    Properties governing the layout and presentation of tables.

  • Writing-mode-related Properties

    Properties related to various aspects of "directionality" and writing-mode influencing block-progression-direction and inline-progression-direction.

  • Miscellaneous Properties

    These properties did not reasonably fit into any of the other categories.

• Shorthand Properties

  Shorthand properties that are part of the complete conformance set. Shorthands expand to the individual properties that may be used in place of shorthands.

7.2 XSL Areas and the CSS Box Model

This section describes how to interpret property descriptions which incorporate the CSS2 definition of the same property. In CSS2, "boxes" are generated by "elements" in the same way that XSL areas are generated by formatting objects. Any references in the CSS2 definition to "boxes" are to be taken as referring to "areas" in the XSL area model, and where "element" appears in a CSS2 definition, except in the "Applies to" summary, it should be taken to refer to a "formatting object".

The CSS term, positioned element will in XSL be taken as referring to an XSL FO that has one of the following: an "absolute-position" property with a computed value other than "auto" and/or a "relative-position" property with a computed value other than "static".

The position and size of a box are normally taken to refer to the position and size of the area's content-rectangle. Additional correspondences between the CSS2 Box Model and the XSL Area Model are contained in the following table.

Box margins map to area traits in accordance with the description of how area traits are computed from property values in [5 Property Refinement / Resolution].

7.3 Reference Rectangle for Percentage Computations

Allowed conversions for percentages, specified on the property definition, is typically in terms of the content-rectangle of some area. That area is determined as follows:

1. For properties defined in CSS2 referring to the "containing block" the content-rectangle of the closest ancestor block-area that is not a line-area is used.

2. For properties defined by XSL, the property definition specifies which area's content-rectangle is used.

3. Exceptions to the rules above for determining which area is used are:

   1. When used on fo:root, fo:page-sequence, and fo:title and any descendant of fo:title where there is no ancestor block-area the rectangle used has the dimensions corresponding to the "auto" value of the "page-height" and "page-width" properties. The block-progression-dimension and inline-progression-dimension is then determined based on the computed value of the reference-orientation and writing-mode on the formatting object for which the percentage is computed, or on fo:title in the case of a descentdant of fo:title.

   2. When used on fo:static-content and fo:flow the content rectangle used is based on the region on the first page into which the content is directed. For region-body it is the normal-flow-reference-area and for the other regions it is the region-reference-area.

   3. When used on fo:footnote-body, and fo:float that generates an area with area-class "xsl-before-float" the rectangle used is the content rectangle of the footnote-reference-area and the before-float-reference-area respectively.

   4. When used on fo:float that generates an area with area-class "xsl-side-float" the content rectangle used is the closest ancestor block-area that is not a line-area of the area of area-type "xsl-anchor" that was generated by the fo:float.

   5. When the absolute-position is "fixed", the containing block is defined by the nearest ancestor viewport area. If there is no ancestor viewport area, the containing block is defined by the user agent.

   6. When the absolute-position is "absolute", the containing block is established by the nearest ancestor area A which has an area-class different from xsl-normal or a relative-position of "relative".

      In the case where A is a block-area, the rectangle used is the padding-rectangle of A.

      In the case where A is an inline-area, generated by some formatting object F, the rectangle used is a virtual rectangle whose before-edge and start-edge are the before-edge and start-edge of the first area generated by F, and whose after-edge and end-edge are the after-edge and end-edge of the last area generated by F. This "rectangle" may have negative extent.

4. If the formatting object generating the identified area generates a sequence of such areas the first area is used for the conversion.

7.4 Common Accessibility Properties

7.4.1 "source-document"

XSL Definition:

It is used by all formatting objects that can be contained in fo:flow or fo:static-content (all formatting objects that can be directly created from an XML source element).

Values have the following meanings:

none

The source document is transient, unknown, or unspecified.

<uri-specification>

A URI-specification giving a reference to the (sub)resource used as input to the stylesheet.

This property provides a pointer back to the original XML document(s) used to create this formatting object tree, in accordance with the Dublin Core definition of "Source" ("A Reference to a resource from which the present resource is derived." See: http://purl.org/DC/documents/rec-dces-19990702.htm.) The value is not validated by and has no inherent standardized semantics for any XSL processor.

W3C Accessibility guidelines, http://www.w3.org/TR/WCAG20/, http://www.w3.org/TR/ATAG10/, and http://www.w3.org/TR/UAAG10/, strongly encourage the use of this property either on the fo:root or on the first formatting object generated from a given source document.

The URI reference is useful for alternate renderers (aural readers, etc.) whenever the structure of the formatting object tree is inappropriate for that renderer.

7.4.2 "role"

XSL Definition:

It is used by all formatting objects that can be contained in fo:flow or fo:static-content (all formatting objects that can be directly created from an XML source element).

Values have the following meanings:

none

Indicates that no semantic tag is cited by this formatting object.

<string>

The value is a string representing a semantic identifier that may be used in rendering this formatting object.

<uri-specification>

A URI-specification, indicating an RDF resource [RDF]; that is, an XML object that is syntactically valid with respect to the RDF grammar.

This property provides a hint for alternate renderers (aural readers, etc.) as to the role of the XML element or elements that were used to construct this formatting object, if one could be identified during XSLT tree construction. This information can be used to prepare alternate renderings when the normal rendering of a formatting object is not appropriate or satisfactory; for example, the role information can be used to provide better aural renderings of visually formatted material.

To aid alternate renderers, the <string> value should be the qualified name (QName [XML Names]) of the element from which this formatting object is constructed. If a QName does not provide sufficient context, the <uri-specification> can be used to identify an RDF resource that describes the role in more detail. This RDF resource may be embedded in the result tree and referenced with a relative URI or fragment identifier, or the RDF resource may be external to the result tree. This specification does not define any standard QName or RDF vocabularies; these are frequently application area dependent. Other groups, for example the Dublin Core, have defined such vocabularies.

This property is not inherited, but all subsidiary nodes of this formatting object that do not bear a role property should utilize the same alternate presentation properties. (It is not inherited because knowledge of the start and end of the formatting object subtree generated by the element may be needed by the renderer.)

7.5 Common Absolute Position Properties

7.5.1 "absolute-position"

7.5.2 "top"

XSL modifications to the CSS definition:

See definition of property left ([7.5.5 "left"]).

7.5.3 "right"

XSL modifications to the CSS definition:

See definition of property left ([7.5.5 "left"]).

7.5.4 "bottom"

XSL modifications to the CSS definition:

See definition of property left ([7.5.5 "left"]).

7.5.5 "left"

XSL modifications to the CSS definition:

These properties set the position of the content-rectangle of the associated area.

If both "left" and "right" have a value other than "auto", then if the "width" is "auto" the width of the content-rectangle is overridden; else the geometry is overconstrained and is resolved in accordance with [5.3.4 Overconstrained Geometry]. Similarly, if both "top" and "bottom" have a value other than "auto", then if the "height" is "auto" the height of the content-rectangle is overridden; else the geometry is overconstrained and is resolved in accordance with [5.3.4 Overconstrained Geometry].

7.6 Common Aural Properties

7.6.1 "azimuth"

7.6.2 "cue-after"

XSL modifications to the CSS definition:

The <uri> value has been changed to a <uri-specification>.

7.6.3 "cue-before"

XSL modifications to the CSS definition:

The <uri> value has been changed to a <uri-specification>.

7.6.4 "elevation"

7.6.5 "pause-after"

7.6.6 "pause-before"

7.6.7 "pitch"

7.6.8 "pitch-range"

7.6.9 "play-during"

XSL modifications to the CSS definition:

The <uri> value has been changed to a <uri-specification>.

7.6.10 "richness"

7.6.11 "speak"

7.6.12 "speak-header"

7.6.13 "speak-numeral"

7.6.14 "speak-punctuation"

7.6.15 "speech-rate"

7.6.16 "stress"

7.6.17 "voice-family"

7.6.18 "volume"

7.7 Common Border, Padding, and Background Properties

The following common-border-padding-and-background-properties are taken from CSS2. Those "border", "padding", and "background" properties that have a before, after, start, or end suffix are writing-mode relative and are XSL-only properties.

7.7.1 "background-attachment"

XSL modifications to the CSS definition:

The last paragraph in the CSS description does not apply.

7.7.2 "background-color"

XSL modifications to the CSS definition:

XSL adds an "rgb-icc" function (see [5.10.2 Color Functions]) as a valid value of this property.

7.7.3 "background-image"

XSL modifications to the CSS definition:

The <uri> value has been changed to a <uri-specification>.

7.7.4 "background-repeat"

XSL modifications to the CSS definition:

"Horizontal" and "vertical" are defined relative to the reference-orientation; "horizontal" is "left" to "right", and "vertical" is "top" to "bottom".

7.7.5 "background-position-horizontal"

XSL modifications to the CSS definition:

"Left" and "right" are defined relative to the reference-orientation.

7.7.6 "background-position-vertical"

XSL modifications to the CSS definition:

"Top" and "bottom" are defined relative to the reference-orientation.

7.7.7 "border-before-color"

7.7.8 "border-before-style"

7.7.9 "border-before-width"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the border for the before-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the border should be 0pt or retained if its associated edge is a leading-edge in a reference-area for areas generated from this formatting object that have an is-first value of "false". See [4.3 Spaces and Conditionality] for further details. The initial value of the .conditionality component is "discard".

If border-before-width is specified using <length>, the formatter shall convert the single value to components as follows:

• border-before-width.length: the resultant computed value of the <length>.

• border-before-width.conditional: discard.

If border-before-width is specified using one of the width keywords the .conditional component is set to "discard" and the .length component to a User Agent dependent length.

7.7.10 "border-after-color"

7.7.11 "border-after-style"

7.7.12 "border-after-width"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the border for the after-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the border should be 0 or retained if its associated edge is a trailing-edge in a reference-area for areas generated from this formatting object that have an is-last value of "false". See [4.3 Spaces and Conditionality] for further details. The initial value of the .conditionality component is "discard".

7.7.13 "border-start-color"

7.7.14 "border-start-style"

7.7.15 "border-start-width"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the border for the start-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the border should be 0 or retained if its associated edge is a leading-edge in a line-area for areas generated from this formatting object that have an is-first value of "false". See [4.3.1 Space-resolution Rules] for further details. The initial value of the .conditionality component is "discard".

7.7.16 "border-end-color"

7.7.17 "border-end-style"

7.7.18 "border-end-width"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the border for the end-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the border should be 0 or retained if its associated edge is a trailing-edge in a line-area for areas generated from this formatting object that have an is-last value of "false". See [4.3.1 Space-resolution Rules] for further details. The initial value of the .conditionality component is "discard".

7.7.19 "border-top-color"

7.7.20 "border-top-style"

7.7.21 "border-top-width"

7.7.22 "border-bottom-color"

7.7.23 "border-bottom-style"

7.7.24 "border-bottom-width"

7.7.25 "border-left-color"

7.7.26 "border-left-style"

7.7.27 "border-left-width"

7.7.28 "border-right-color"

7.7.29 "border-right-style"

7.7.30 "border-right-width"

7.7.31 "padding-before"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the padding for the before-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the padding should be 0 or retained if its associated edge is a leading-edge in a reference-area for areas generated from this formatting object that have an is-first value of "false". See [4.3 Spaces and Conditionality] for further details. The initial value of the .conditionality component is "discard".

7.7.32 "padding-after"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the padding for the after-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the padding should be 0 or retained if its associated edge is a trailing-edge in a reference-area for areas generated from this formatting object that have an is-last value of "false". See [4.3 Spaces and Conditionality] for further details. The initial value of the .conditionality component is "discard".

7.7.33 "padding-start"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the padding for the start-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the padding should be 0 or retained if its associated edge is a leading-edge in a line-area for areas generated from this formatting object that have an is-first value of "false". See [4.3.1 Space-resolution Rules] for further details. The initial value of the .conditionality component is "discard".

7.7.34 "padding-end"

XSL modifications to the CSS definition:

The following value type has been added for XSL:

<length-conditional>

A compound value specifying the width and any conditionality of the padding for the end-edge.

The .length component is a <length>. It may not be negative. The .conditionality component may be set to "discard" or "retain" to control if the padding should be 0 or retained if its associated edge is a trailing-edge in a line-area for areas generated from this formatting object that have an is-last value of "false". See [4.3.1 Space-resolution Rules] for further details. The initial value of the .conditionality component is "discard".

7.7.35 "padding-top"

7.7.36 "padding-bottom"

7.7.37 "padding-left"

7.7.38 "padding-right"

7.8 Common Font Properties

The following common-font-properties all are taken from CSS2. The reference to CSS2 is: http://www.w3.org/TR/REC-CSS2/fonts.html

7.8.1 Fonts and Font Data

XSL uses an abstract model of a font. This model is described in this section and is based on current font technology as exemplified by the OpenType specification [OpenType].

A font consists of a collection of glyphs together with the information, the font tables, necessary to use those glyphs to present characters on some medium. A glyph is a recognizable abstract graphic symbol which is independent of any specific design. The combination of the collection of glyphs and the font tables is called the font data.

The font tables include the information necessary to map characters to glyphs, to determine the size of glyph areas and to position the glyph area. Each font table consists of one or more font characteristics, such as the font-weight and font-style.

The geometric font characteristics are expressed in a coordinate system based on the em box. (The em is a relative measure of the height of the glyphs in the font; see [5.9.7.2 Relative Lengths].) This box that is 1 em high and 1 em wide is called the design space. Points in this design space are expressed in geometric coordinates in terms of fractional units of the em.

The coordinate space of the em box is called the design space coordinate system. For scalable fonts, the curves and lines that are used to draw a glyph are represented using this coordinate system.

XSL assumes that the font tables will provide at least three font characteristics: an ascent, a descent and a set of baseline-tables. The coordinate values for these are given in the design space coordinate system. The ascent is given by the vertical coordinate of the top of the em box; the descent is given by the vertical coordinate of the bottom of the em box. The baseline-table is explained below.

The glyphs of a given script are positioned so that a particular point on each glyph, the alignment-point, is aligned with the alignment-points of the other glyphs in that script. The glyphs of different scripts are typically aligned at different points on the glyph. For example, Western glyphs are aligned on the bottoms of the capital letters, certain Indic glyphs (including glyphs from the Devanagari, Gurmukhi and Bengali scripts) are aligned at the top of a horizontal stroke near the top of the glyphs and Far Eastern glyphs are aligned either at the bottom or center of the em box of the glyph. Within a script and within a line of text having a single font-size, the sequence of alignment-points defines, in the inline-progression-direction, a geometric line called a baseline. Western and most other alphabetic and syllabic glyphs are aligned to an "alphabetic" baseline, the above Indic glyphs are aligned to a "hanging" baseline and the Far Eastern glyphs are aligned to an "ideographic" baseline.

A baseline-table specifies the position of one or more baselines in the design space coordinate system. The function of the baseline table is to facilitate the alignment of different scripts with respect to each other when they are mixed on the same text line. Because the desired relative alignments may depend on which script is dominant in a line (or block), there may be a different baseline table for each script. In addition, different alignment positions are needed for horizontal and vertical writing modes. Therefore, the font may have a set of baseline tables: typically, one or more for horizontal writing-modes and zero or more for vertical writing-modes.

The font tables for a font include font characteristics for the individual glyphs in the font. XSL assumes that the font tables include, for each glyph in the font, one width value, one alignment-baseline and one alignment-point for the horizontal writing-modes. If vertical writing-modes are supported, then each glyph must have another width value, alignment-baseline and alignment-point for the vertical writing-modes. (Even though it is specified as a width, for vertical writing-modes the width is used in the vertical direction.)

The script to which a glyph belongs determines an alignment-baseline to which the glyph is to be aligned. The position of this baseline in the design space coordinate system determines the default block-progression-direction position of the alignment-point. The inline-progression-direction position of the alignment-point is on the start-edge of the glyph. (These positions are adjusted according to the specifications in [7.13.1 "alignment-adjust"] when an instance of a glyph is used in an inline or block formatting object. The "space-start" and/or the "space-end" properties of the fo:character that maps to the glyph may be adjusted to effect "kerning" with respect to adjacent glyphs.)

In addition to the font characteristics required above, a font may also supply substitution and positioning tables that can be used by a formatter to re-order, combine, and position a sequence of glyphs to make one or more composite glyphs. The combination may be as simple as a ligature, or as complex as an Indic syllable which combines, usually with some re-ordering, multiple consonants and vowel glyphs. See [4.7.2 Line-building].

7.8.2 "font-family"