Extensible Stylesheet Language (XSL)

2.4.1 Root Node

The root node is the root of the tree. It does not occur anywhere else in the tree. It has a single child which is the element node for the document element of the document.

The value of the root node is the value of the document element.

2.4.2 Element Nodes

There is an element node for every element in the document. An element has an expanded name consisting of a local name and a possibly null URI (see [W3C XML Names]); the URI will be null if the element type name has no prefix and there is no default namespace in scope.

The children of an element node are the element nodes and characters for its content. Entity references to both internal and external entities are expanded. Character references are resolved.

The descendants of an element node are the character children, the element node children, and the descendants of the element node children.

The value of an element node is the string that results from concatenating all characters that are descendants of the element node in the order in which they occur in the document.

The set of all element nodes in a document can be ordered according to the order of the start-tags of the elements in the document; this is known as document order.

<xsl:id attribute="name"/>

2.4.3 Attribute Nodes

Each element node has an associated set of attribute nodes. A defaulted attribute is treated the same as a specified attribute. If an attribute was declared for the element type, but the default was declared as #IMPLIED, and the attribute was not specified on the element, then the element's attribute set does not contain a node for the attribute.

An attribute node has an expanded name and has a string value. The expanded name consists of a local name and a possibly null URI (see [W3C XML Names]); the URI will be null if the specified attribute name did not have a prefix. The value is the normalized value as specified by the XML Recommendation [W3C XML]. An attribute value whose value is of zero length is not treated specially.

There are no attribute nodes for attributes that declare namespaces (see [W3C XML Names]).

2.4.4 Namespace Nodes

Each element has an associated set of namespace nodes, one for each namespace prefix that is in scope for element and one for the default namespace if one is in scope for the element. This means that an element will have a namespace node:

• for every attribute on the element whose name starts with xmlns:;

• for every attribute on an ancestor element whose name starts xmlns: unless the element itself or a nearer ancestor redeclares the prefix;

• for an xmlns attribute, unless its value is the empty string.

  NOTE: An attribute xmlns="" "undeclares" the default namespace (see [W3C XML Names]).

A namespace node has a name which is a string giving the prefix. This is empty if the namespace node is for the default namespace. A namespace node also has a value which is the namespace URI. If the namespace declaration specifies a relative URI, then the resolved absolute URI is used as the value.

When writing an element node in the result tree out as XML, an XSL processor must add sufficient namespace-declaring attributes to the start-tag to ensure that if a tree were recreated from the XML, then the set of namespace nodes on the element node in the recreated tree would be equal to or a superset of the set of namespace nodes of the element node in the result tree.

2.4.5 Processing Instruction Nodes

There is a processing instruction node for every processing instruction.

A processing instruction has a name. This is a string equal to the processing instruction's target. It also has a value. This is a string equal to the part of the processing instruction following the target and any whitespace. It does not include the terminating ?>.

2.4.6 Comment Nodes

There is a comment node for every comment.

A comment has a value. This is a string equal to the text of the comment not including the opening <!-- or the closing -->.

2.4.7 Text Nodes

Character data is grouped into text nodes. As much character data as possible is grouped into each text node: a text node never has an immediately following or preceding sibling that is a text node. The value of a text node is the character data.

Each character within a CDATA section is treated as character data. Thus <![CDATA[<]]> in the source document will treated the same as <. Characters inside comments or processing instructions are not character data. Line-endings in external entities are normalized to #xA as specified in the XML Recommendation [W3C XML].

2.4.8 Whitespace Stripping

After the tree has been constructed, but before it is otherwise processed by XSL, some text nodes may be stripped. The stripping process takes as input a set of element types for which whitespace must be preserved. The stripping process is applied to both stylesheets and source documents, but the set of whitespace-preserving element types is determined differently for stylesheets and for source documents.

A text node is preserved if any of the following apply:

• The element type of the parent of the text node is in the set of whitespace-preserving element types.

• The text node contains at least one non-whitespace character. As in XML, a whitespace character is #x20, #x9, #xD or #xA.

• An ancestor element of the text node has an xml:space attribute with a value of preserve, and no closer ancestor element has xml:space with a value of default.

Otherwise the text node is stripped.

The xml:space attributes are not stripped from the tree.

For stylesheets, the set of whitespace-preserving element types consists of just xsl:text.

For source documents, the set of whitespace-preserving element types is determined using the stylesheet as follows:

• If the xsl:stylesheet element specifies a default-space attribute with a value of strip, then the set is initially empty. Otherwise the set initially contains all element types that occur in the document.

• The xsl:strip-space element causes an element type to be removed from the set of whitespace-preserving element types. The element attribute gives the name of the element type.

• The xsl:preserve-space element causes an element type to be added to the set whitespace-preserving element types. The element attribute gives the name of the element type.

The xsl:stylesheet element can include an indent-result attribute with values yes or no. If the stylesheet specifies indent-result="yes", then the XSL processor may add whitespace to the result tree (possibly based on whitespace stripped from either the source document or the stylesheet) in order to indent the result nicely; if indent-result="no", it must not add any whitespace to the result. When adding whitespace with indent-result="yes", the XSL processor can use any algorithm provided that the result is the same as the result with indent-result="no" after whitespace is stripped from both using the process described with the set of whitespace-preserving element types consisting of just xsl:text.

2.5.1 Conflict Resolution for Template Rules

It is possible for a source node to match more than one template rule. The template rule to be used is determined as follows:

1. First, all matching template rules that are less important than the most important matching template rule or rules are eliminated from consideration.

2. Next, all matching template rules that have a lower priority than the matching template rule or rules with the highest priority are eliminated from consideration. The priority of a rule is specified by the priority attribute on the rule. The value of this must be a real number (positive or negative). The default priority is 0.

   Ed. Note: Say exactly what syntax is allowed for real numbers.

   Issue (default-priority): Should there be a more complicated way of calculating the default priority? For example, -1 for *, 0 for just an element type name, and 1 for more complex patterns.

It is an error if this leaves more than one matching template rule. An XSL processor may signal the error; if it does not signal the error, it must recover by choosing from amongst the matching template rules that are left the one that occurs last in the stylesheet.

2.5.2 Built-in Template Rules

There is a built-in template rule to allow recursive processing to continue in the absence of a successful pattern match by an explicit rule in the stylesheet. This rule applies to both element nodes and the root node. The following shows the equivalent of the built-in template rule:

<xsl:template match="*|/">
  <xsl:apply-templates/>
</xsl:template>

There is also a built-in template rule for text nodes that copies text through:

<xsl:template match="text()">
  <xsl:value-of select="."/>
</xsl:template>

The built-in rule does not apply to processing instructions and comments. When a comment or processing instruction is processed, and no rule is matched, nothing is created.

The built-in template rules are treated as if they were imported implicitly before the stylesheet and so are considered less important than all other template rules. Thus the author can override a built-in rule by including an explicit rule with match="*|/" or match="text()".

2.6.1 Introduction

This section introduces the syntax and semantics of XSL patterns. The formal, definitive specification is in the following section.

A pattern is a string which selects a set of nodes in a source document. The selection is relative to the current node. The simplest pattern is an element type name; it selects all the child elements of the current node with that element type name. For example, the pattern chapter selects all the chapter child elements of the current node.

A pattern can also be matched against a node. If a node could be selected by a pattern, then the node is considered to match the pattern. More precisely, for any pattern and any document there is a matching set of nodes; this is the union, for each node in the document, of the set of nodes selected by the pattern with that node as the current node. For example, a pattern chapter matches any chapter element because if the current node was the parent of the chapter element, the chapter element would be one of the nodes selected by the pattern chapter. This includes the case where the chapter element is the document element, because the root node is the parent of the document element.

The | operator can be used to express alternatives. For example, the pattern emph|b matches both emph elements and b elements.

Patterns can be composed together with the / operator in a path-like manner. For example, a pattern chapter/section selects the chapter child elements of the current node, and then for each selected chapter element, selects the section children; in other words, it selects the section grandchildren of the current node that have chapter parents. A node would match a pattern chapter/section if it was a section element with a chapter parent.

/ binds more tightly than |. Thus the pattern ol/li|ul/li matches li elements that have an ol or ul parent.

Whitespace can be used around operators in patterns to improve readability. Thus ol/li|ul/li can be written as ol/li | ul/li.

* can be used instead of an element type name as a wildcard. For example, a pattern * would select all element children of the current node; a pattern */section would select all section grandchildren of the current node. A pattern chapter/* would match any element that has a chapter parent.

A // can be used instead of / to select from descendants instead of from children. For example, a pattern chapter//p selects all the p descendants of chapter children of the current node, and it matches all p elements that have a chapter ancestor.

A pattern . selects the current node. This is useful with //. For example, .//div selects all div descendant elements of the current node.

Similarily .. selects the parent of the current node. For example, ../item selects the item sibling elements of the current node.

Other types of node are treated in a similar way to elements.

• The attributes of an element are treated like the child elements; an attribute is distinguished from a child element by prefixing its name with @. For example, @date will select the date attribute of the current element; employee/@salary will select the salary attribute of each employee child element of the current node. A wildcard @* is allowed just as with elements; a pattern @* selects all attributes of the current node.

• A pattern comment() selects all comment children of the current node. Thus a pattern comment() will match any comment node.

• A pattern pi() selects all processing instruction children of the current node. An argument can be used to specify the target. Thus pi("xml-stylesheet") matches any processing instruction with a target xml-stylesheet. Note that the argument must be quoted.

The set of nodes selected by a pattern can be refined by following the pattern by a test in square brackets ([]). Each node in the set is tested. The result includes only those nodes for which a test succeeds. The following are allowed as tests:

• A pattern can be used a test; the test succeeds if the pattern selects one or more nodes when the node being tested is the current node. For example, a pattern list[@type] matches a list element with a type attribute; a pattern book[editor] selects book children elements of the current node that have at least one editor child element.

• A pattern can be compared to a string. For example, a pattern list[@type="ordered"] would match any list with an attribute type with value ordered; a pattern employee[location="USA"] would select employee children of the current element that have a location child with value equal to USA.

• The position of a node relative to its siblings can be tested.

  • first-of-any() succeeds if the node being tested is the first element child

  • last-of-any() succeeds if the node being tested is the last element child

  • first-of-type() succeeds if the node being tested is the first element child of its element type

  • last-of-type() succeeds if the node being tested is the first element child of its element type

• A test can be negated using not(). For example, list[not(@type)] matches any list element without a type attribute.

• Tests can be combined with and and or. For example,

  back/div[first-of-type() and last-of-type()]
  

  matches a div element with a back parent, when it is the only div child of its parent.

The [] operator binds more tightly than |. Thus the pattern ol|list[@type="ordered"] matches either list elements with a type attribute with value ordered or ol elements.

The root node is treated is specially. A / at the beginning of a pattern selects the root node (not the document element). For example, a pattern that is just / matches the root node; a pattern /div will match the document element it is a div element; a pattern /* will match the document element whatever is. When a pattern starts with / the current node is irrelevant.

A pattern can also start with //. //foo means the same as /.//foo: it selects the foo descendants of the root node, which implies that it selects all foo elements. When a pattern starts with // the current node is irrelevant.

The ancestor function allows selection of an ancestor of the current node. The argument is a match pattern. It selects the first ancestor of the current node that matches the argument. For example, ancestor(chapter)/title will select the title children of the first ancestor of the current node that is a chapter.

The id function allows ID references to be followed. The argument can be a literal string. For example, id('foo') will select the element with ID foo; if there is no such element, the empty node set will be returned. Multiple whitespace separated IDs are also allowed; this id('foo bar') would select elements with an ID foo or bar. The argument can be a pattern instead of a literal string; for each node selected by the pattern, the value of the node is treated as whitespace separated list of ID references. For example, if the current node is an element with an IDREF or IDREFS attribute named ref, then a pattern id(@ref) would select the elements referenced by the ref attribute.

2.6.2 Syntax and Semantics

An expression is evaluated with respect to a context, which is a single node. The result of evaluating an expression is a set of nodes or a boolean.

In the following grammar, the nonterminal QName is defined in [W3C XML Names], and S is defined in [W3C XML].

A select pattern must match the production for SelectExpr; it returns the list of nodes that results from evaluating the SelectExpr with the current node as context; the nodes are in the list are in document order.

A match pattern must match the production for MatchExpr; a node matches the match pattern if the MatchExpr returns true when evaluated with that node as context.

The result of the MatchExpr is true if, for any node in the document that contains the context of the MatchExpr, the result of evaluating the SelectExpr with that node as context contains the context of the MatchExpr. Otherwise the result is false.

The context of the right hand side expressions is the context of the left hand side expression. The results of the right hand side expressions are node sets. The result of the left hand side UnionExpr is the union of the results of the right hand side expressions.

The context of the right hand side expressions is the context of the left hand side expression. The result of the left hand side is the result of the right hand side. The result is a node set.

If the SubtreeExpr is present, then the context for the SubtreeExpr is the root node, and the result is the result of the SubtreeExpr. Otherwise the result is the root node.

If the / is present, then the result SubtreeExpr is the union, for each node in the subtree rooted at the context of the SubtreeExpr, of the result of evaluating the ComposeExpr with that node as context. Otherwise the SubtreeExpr is equivalent to ComposeExpr.

The context of the FilterExpr is the context of the ComposeExpr. If the SubtreeExpr is present, then, for each node in the result of the FilterExpr, the SubtreeExpr is evaluated with that node as the context; the result of the ComposeExpr is the union of the results of evaluating the SubtreeExpr. Otherwise the result is the result of the FilterExpr.

The context of the NodeExpr is the context of the FilterExpr. If the BooleanExpr is present, then for each node in the result of the NodeExpr, the BooleanExpr is evaluated with that node as context; the result consists of those nodes for which the BooleanExpr evaluates to true.

The context of the right hand side expressions is the context of the left hand side expression. The results of the right hand side expressions are node sets. The result of the left hand side is the result of the left hand side expression.

If * is specified, then the result is the child elements of the context of the ElementExpr. Otherwise, the result is the set of all elements that are the children of the context of ElementExpr and whose name is equal to QName.

When comparing the name of an element to a QName, the QName is expanded into a local name and a possibly null URI. This expansion is done in the same way as for element type names in start and end-tags except that the default namespace declared with xmlns is not used: if the QName does not have a prefix, then the URI is null (this is the same way attribute names are expanded). The expanded element type names are compared (see Section 2.4.2: Element Nodes).

If * is specified, the result is the set of attribute nodes of the context of the AttributeExpr. If a QName is specified, the result is the attribute node of the context of the AttributeExpr named QName, or the empty node set if there is no such attribute node. When matching attribute names, the expanded names are compared (see Section 2.4.3: Attribute Nodes). The QName is expanded in the same way as a QName in an ElementExpr.

If the Literal is present, the result is the set of processing instruction nodes which are children of the context of the PiExpr and whose target is equal to the value of Literal. Otherwise the result is the set of processing instruction nodes which are children of the context of the PiExpr.

The result is the set of all text nodes whose parent is a node in the context of the TextExpr.

The result is the set of all comment nodes which are children of the context of the CommentExpr.

The context of the SelectExpr is the context of the IdExpr. A set of names is computed from the argument as follows:

• If it is a ConstantIdExpr, then the value of the Literal is treated as a whitespace-separated list of names; the set of names consists of the members of the list.

• Otherwise, the value of each node in the result of the SelectExpr is treated as a whitespace-separated list of names; the set of names is the union for each node of the members of the list.

The result is the set of element nodes whose ID (see Section 2.4.2.1: Unique IDs) is one of the names in the set of names specified by the argument.

The result of an AncestorExpr is the first ancestor of the context of the AncestorExpr such that MatchExpr, when evaluated with that ancestor as the context, has a result of true. If there is no such ancestor, the result is the empty node set.

With ancestor-or-self, a node is treated as the first of its ancestors. Thus if the MatchExpr evaluates to true with the context of the AncestorOrSelfExpr, then the result of the AncestorOrSelfExpr is the context, otherwise the result is the same as the result of an AncestorExpr.

The result is the context of the IdentityExpr.

The result is the parent of the context of the ParentExpr. If the context is the root node, then the result is the empty node set.

The result of a BooleanExpr is true or false. The context of the right hand side expressions is the context of the BooleanExpr. The result of the BooleanExpr is the result of the right hand side.

The context for each BooleanPrimaryExpr is the context of the AndExpr. The result is true if the result of all of the BooleanPrimaryExprs is true; otherwise the result is false.

The context for each BooleanPrimaryExpr is the context of the OrExpr. The result is true if the result of any of the BooleanPrimaryExprs is true; otherwise the result is false.

The result of the left hand side is the result of the right hand side. The context of the right hand side is the context of the left hand side.

The result of the NotExpr is true if the result of the BooleanExpr is false; otherwise the result is false.

The context of the PositionalExpr is a single node.

• For first-of-type(), the result is true if the context node is an element and the element has no preceding siblings that are elements with the same element type name, and false otherwise.

• For first-of-any(), the result is true if the context node is an element and the element has no preceding siblings that are elements, and false otherwise.

• For last-of-type(), the result is true if the context node is an element and the element has no following siblings that are elements with the same element type name, and false otherwise.

• For last-of-any(), the result is true if the context node is an element and the element has no following siblings that are elements, and false otherwise.

The context of the SelectExpr is the context of the EqualityExpr. The result of the TestExpr is true if the result of the SelectExpr is non-empty. Otherwise the result is false.

The context of the SelectExpr is the context of the EqualityExpr. The result is true if there is a node in the result of the SelectExpr whose value is equal to the value of the Literal.

The value of the Literal is the sequence of characters inside the " or ' characters>.

For readability, whitespace may be used in patterns even though not explicitly allowed by the grammar: PatternWhitespace may be freely added within patterns before or after any PatternToken.

A FunctionName token is recognized only when the following token is (. An OperatorName token is recognized only when there is a preceding token and the preceding token is not one of @, /, |, (, [ or an OperatorName. A string that is equal to an OperatorName or a FunctionName can be used in an ElementExpr or an AttributeExpr. For example, and[not and or] matches a element named and with an element child named not and an element child named or.

2.7.1 Overview

When the rule that is to be applied to the source element has been identified, the rule's template is instantiated. A template can contain literal result elements, character data and instructions for creating fragments of the result tree. Instructions are represented by elements in the XSL namespace.

The xsl:apply-templates instruction can select descendant nodes for processing. Without any attribute, the xsl:apply-templates instruction processes the immediate children nodes of the source element; a select attribute can be used to process nodes selected by a specified pattern.

<xsl:template match="chapter/title">
  <fo:rule-graphic/>
  <fo:block space-before="2pt">
    <xsl:text>Chapter </xsl:text>
    <xsl:number/>
    <xsl:text>: </xsl:text>
    <xsl:apply-templates/>
  </fo:block>
  <fo:rule-graphic/>
</xsl:template>

2.7.2 Creating Elements and Attributes

<xsl:stylesheet
  xmlns:xsl="http://www.w3.org/TR/WD-xsl"
  xmlns:fo="http://www.w3.org/TR/WD-xsl/FO"
  xmlns:qxsl="quote:http://www.w3.org/TR/WD-xsl">

<xsl:template match="/">
  <qxsl:stylesheet>
    <xsl:apply-templates/>
  </qxsl:stylesheet>
</xsl:template>

<xsl:template match="block">
  <qxsl:template match="{.}">
     <fo:block><qxsl:apply-templates/></fo:block>
  </qxsl:template>
</xsl:template>

</xsl:stylesheet>

<elements>
<block>p</block>
<block>h1</block>
<block>h2</block>
<block>h3</block>
<block>h4</block>
</elements>

<xsl:attribute-set name="title-style">
  <xsl:attribute name="font-size">12pt</xsl:attribute>
  <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

<xsl:template match="chapter/heading">
  <fo:block quadding="start">
    <xsl:use attribute-set="title-style"/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

2.7.3 Creating Text

A template can also contain text nodes. Each text node in a template remaining after whitespace has been stripped as specified in Section 2.4.8: Whitespace Stripping will create a text node with the same value in the result tree. Adjacent text nodes in the result tree are automatically merged.

Note that text is processed at the tree level. Thus, markup of < in a template will be represented in the stylesheet tree by a text node that includes the character <. This will create a text node in the result tree that contains a < character, which will be represented by the markup < (or an equivalent character reference) when the result tree is externalized as an XML document.

Literal data characters may also be wrapped in an xsl:text element. This wrapping may change what whitespace characters are stripped (see Section 2.4.8: Whitespace Stripping) but does not affect how the characters are handled by the XSL processor thereafter.

2.7.4 Creating Processing Instructions

The xsl:pi element is instantiated to create a processing instruction node. The content of the xsl:pi element is a template for the value of the processing instruction node. The xsl:pi element has a required name attribute that specifies the name of the processing instruction node. The value of the name attribute is interpreted as an attribute value template.

For example, this

<xsl:pi name="xml-stylesheet">href="book.css" type="text/css"</xsl:pi>

would create the processing instruction

<?xml-stylesheet href="book.css" type="text/css"?>

It is an error if instantiating the content of xsl:pi creates anything other than characters. An XSL processor may signal the error; if it does not signal the error, it must recover by ignoring the offending nodes together with their content.

It is an error if the result of instantiating the content of the xsl:pi contains the string ?>. An XSL processor may signal the error; if it does not signal the error, it must recover by inserting a space after any occurrence of ? that is followed by an >.

2.7.5 Creating Comments

The xsl:comment element is instantiated to create a comment node in the result tree. The content of the xsl:comment element is a template for the value of the comment node.

For example, this

<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>

would create the comment

<!--This file is automatically generated. Do not edit!-->

It is an error if instantiating the content of xsl:comment creates anything other than characters. An XSL processor may signal the error; if it does not signal the error, it must recover by ignoring the offending nodes together with their content.

It is an error if if the result of instantiating the content of the xsl:comment contains the string -- or ends with -. An XSL processor may signal the error; if it does not signal the error, it must recover by inserting a space after any occurrence of - that is followed by another -.

2.7.6 Processing with Template Rules

This example creates a block for a chapter element and then processes its immediate children.

<xsl:template match="chapter">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

In the absence of a select attribute, the xsl:apply-templates instruction processes all of the children of the current node, including text nodes. However, text nodes that have been stripped as specified in Section 2.4.8: Whitespace Stripping will not be processed.

A select attribute can be used to process nodes selected by a pattern instead of all children. The value of the select attribute is a select pattern. The following example processes all of the author children of the author-group:

<xsl:template match="author-group">
  <fo:inline-sequence>
    <xsl:apply-templates select="author"/>
  </fo:inline-sequence>
</xsl:template>

The pattern controls the depth at which matches occur. The following example processes all of the first-names of the authors that are direct children of author-group:

<xsl:template match="author-group">
  <fo:inline-sequence>
    <xsl:apply-templates select="author/first-name"/>
  </fo:inline-sequence>
</xsl:template>

// can be used in the pattern to allow the matches to occur at arbitrary depths.

This example processes all of the heading elements contained in the book element.

<xsl:template match="book">
  <fo:block>
    <xsl:apply-templates select=".//heading"/>
  </fo:block>
</xsl:template>

An AncestorExpr in the pattern allows the processing of elements that are not descendants of the current node. This example finds an employee's department and then processes the group children of the department.

<xsl:template match="employee">
  <fo:block>
    Employee <xsl:apply-templates select="name"/> belongs to group
    <xsl:apply-templates select="ancestor(department)/group"/>
  </fo:block>
</xsl:template>

This example assumes that a department element contains group and employee elements (at some level). When processing the employee elements, the AncestorExpr in the pattern allows navigation upward to the department element in order to extract the information about the group to which the employee belongs.

An IdExpr allows processing of elements with a specific ID. For example, this template rule applies to elements with the ID cfo; the second xsl:apply-templates element processes the name child of the element with ID ceo:

<xsl:template match="id(cfo)">
  <xsl:apply-templates select="name"/> reports to <xsl:apply-templates select="id(ceo)/name"/>
</xsl:template>

Multiple xsl:apply-templates elements can be used within a single template to do simple reordering. The following example creates two HTML tables. The first table is filled with domestic sales while the second table is filled with foreign sales.

<xsl:template match="product">
  <TABLE>
    <xsl:apply-templates select="sales/domestic"/>
  </TABLE>
  <TABLE>
    <xsl:apply-templates select="sales/foreign"/>
  </TABLE>
</xsl:template>

Use of select patterns in xsl:apply-templates can lead to infinite loops. It is an error if, during the invocation of a rule for an element, that same rule is invoked again for that element. An XSL processor may signal the error; if it does not signal the error, it must recover by creating an empty result tree structure for the nested invocation.

2.7.7 Direct Processing

When the result has a known regular structure, it is useful to be able to specify directly the template for selected nodes. The xsl:for-each element contains a template which is instantiated for each node selected by the pattern specified by the select attribute. The template is instantiated with the selected node as the current node.

For example, given an XML document with this structure

<customers>
  <customer>
    <name>...</name>
    <order>...</order>
    <order>...</order>
  </customer>
  <customer>
    <name>...</name>
    <order>...</order>
    <order>...</order>
  </customer>
</customers>

the following would create an HTML document containing a table with a row for each customer element

<xsl:template match="/">
  <HTML>
    <HEAD>
      <TITLE>Customers</TITLE>
    </HEAD>
    <BODY>
      <TABLE>
    <TBODY>
      <xsl:for-each select="customers/customer">
        <TR>
          <TH>
        <xsl:apply-templates select="name"/>
          </TH>
          <xsl:for-each select="order">
        <TD>
          <xsl:apply-templates/>
        </TD>
          </xsl:for-each>
        </TR>
      </xsl:for-each>
    </TBODY>
      </TABLE>
    </BODY>
  </HTML>
</xsl:template>

As with xsl:apply-templates the pattern is a select pattern. The select attribute is required.

2.7.8 Processing Modes

Processing modes allow an element to be processed multiple times, each time producing a different result.

Both xsl:template and xsl:apply-templates have an optional mode attribute whose value is a name. If an xsl:apply-templates element has a mode attribute, then it applies only those template rules from xsl:template elements that have a mode attribute with the same value; if an xsl:apply-templates element does not have a mode attribute, then it applies only those template rules from xsl:template elements that do not have a a mode attribute.

If there is no matching template, then the built-in template rules are applied, even if a mode attribute was specified in xsl:apply-templates.

2.7.9 Sorting

Sorting is specified by adding xsl:sort elements as children of xsl:apply-templates or xsl:for-each. The first xsl:sort child specifies the primary sort key, the second xsl:sort child specifies the secondary sort key and so on. When xsl:apply-templates or xsl:for-each has one or more xsl:sort children, then instead of processing the selected elements in document order, it sorts the elements according to the specified sort keys and then processes them in sorted order. When used in xsl:for-each, xsl:sort elements must occur first.

xsl:sort has a select attribute whose value is a select pattern. For each node to be processed, the select pattern is evaluated with that node as the current node. The value of the first selected node is used as the sort key for that node. The default value of the code select attribute is . (which addresses the current node).

This string serves as a sort key for the node. The following optional attributes on xsl:sort control how the list of sort keys are sorted:

• order specifies whether the strings should be sorted in ascending or descending order; ascending specifies ascending order; descending specifies descending order; the default is ascending

• lang specifies the language of the sort keys; it has the same range of values as xml:lang[W3C XML]; if no lang value is specified, the language should be determined from the system environment

• data-type specifies the data type of the strings; the following values are allowed

  • text specifies that the sort keys should be sorted lexicographically in the culturally correct manner for the language specified by lang

  • number specifies that the sort keys should be converted to numbers and then sorted according to the numeric value; the value specified by lang can be used to assist in the conversion to numbers

  The default value is text.

  Ed. Note: We plan to leverage the work on XML schemas to define further values in the future.

• case-order has the value upper-first or lower-first; this applies when data-type="text", and specifies that upper-case characters should sort before lower-case letters or vice-versa respectively. For example, if lang="en" then A a B b are sorted with case-order="upper-first" and a A b B are sorted with case-order="lower-first". The default value is language dependent.

The values of all of the above attributes are interpreted as attribute value templates.

The sort must be stable: in the sorted list of nodes, any sublist that has sort keys that all compare equal must be in document order.

For example, suppose an employee database has the form

<employees>
  <employee>
    <name>
      <first>James</first>
      <last>Clark</last>
    </name>
    ...
  </employee>
</employees>

Then a list of employees sorted by name could be generated using:

<xsl:template match="employees">
 <ul>
  <xsl:apply-templates select="employee">
    <xsl:sort select="name/last"/>
    <xsl:sort select="name/first"/>
  </xsl:apply-templates>
  </ul>
</xsl:template>

<xsl:template match="employee">
 <li>
  <xsl:value-of select="name/first"/>
  <xsl:text> </xsl:text>
  <xsl:value-of select="name/last"/>
 </li>
</xsl:template>

2.7.10 Numbering

<xsl:template match="ol/item">
  <fo:block>
    <xsl:number/><xsl:text>. </xsl:text><xsl:apply-templates/>
  </fo:block>
<xsl:template>

<xsl:template match="title">
  <fo:block>
     <xsl:number level="multi"
                 count="chapter|section|subsection"
                 format="1.1. "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="appendix//title" priority="1">
  <fo:block>
     <xsl:number level="multi"
                 count="appendix|section|subsection"
                 format="A.1. "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="note">
  <fo:block>
     <xsl:number level="any" from="chapter" format="(1) "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="H4">
 <fo:block>
   <xsl:number level="any" from="H1" count="H2"/>
   <xsl:text>.</xsl:text>
   <xsl:number level="any" from="H2" count="H3"/>
   <xsl:text>.</xsl:text>
   <xsl:number level="any" from="H3" count="H4"/>
   <xsl:text> </xsl:text>
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

<xsl:template match="note">
  <xsl:text> (Note </xsl:text>
  <xsl:counter-increment name="note"/>
  <xsl:counter name="note"/>
  <xsl:text>).</xsl:text>
</xsl:template>

<xsl:template match="OL">
  <dl>
    <xsl:counter-reset name="li"/>
    <xsl:apply-templates/>
  </dl>
</xsl:template>

<xsl:template match="LI">
  <xsl:counter-increment name="li"/>
  <dt><xsl:counter name="li"/></dt>
  <dd><xsl:apply-templates/></dd>
</xsl:template>

<xsl:template match="h2">
  <xsl:counter-increment name="h2"/>
  <p>
    <xsl:counter name="h2"/>
    <xsl:text>. </xsl:text>
    <xsl:apply-templates/>
  </p>
  <xsl:counter-reset name="h3"/>
</xsl:template>

<xsl:template match="h3">
  <xsl:counter-increment name="h3"/>
  <p>
    <xsl:counter name="h2"/>
    <xsl:text>.</xsl:text>
    <xsl:counter name="h3"/>
    <xsl:text>. </xsl:text>
    <xsl:apply-templates/>
  </p>
  <xsl:counter-reset name="h4"/>
</xsl:template>

<xsl:template match="h4">
  <xsl:counter-increment name="h4"/>
  <p>
    <xsl:counter name="h2"/>
    <xsl:text>.</xsl:text>
    <xsl:counter name="h3"/>
    <xsl:text>.</xsl:text>
    <xsl:counter name="h4"/>
    <xsl:text>.</xsl:text>
    <xsl:apply-templates/>
  </p>
</xsl:template>

<xsl:template match="div">
  <div>
    <xsl:apply-templates/>
  </div>
</xsl:template>

<xsl:template match="title">
 <p>
  <xsl:counter-increment name="div"/>
  <xsl:counters name="div" format="1.1. "/>
  <xsl:apply-templates/>
 </p>
 <xsl:counter-reset name="div"/>
</xsl:template>

2.7.11 Conditionals within a Template

There are two instructions in XSL which support conditional processing in a template: xsl:if and xsl:choose. The xsl:if instruction provides simple if-then conditionality; the xsl:choose instruction supports selection of one choice when there are several possibilities.

<xsl:template match="namelist/name">
  <xsl:apply-templates/>
  <xsl:if test=".[not(last-of-type())]">, </xsl:if>
</xsl:template>

<xsl:template match="orderedlist/listitem">
  <fo:list-item indent-start='2pi'>
    <fo:list-item-label>
      <xsl:choose>
        <xsl:when test='ancestor(orderedlist/orderedlist)'>
          <xsl:number format="i"/>
        </xsl:when>
        <xsl:when test='ancestor(orderedlist)'>
          <xsl:number format="a"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:number format="1"/>
        </xsl:otherwise>
      </xsl:choose>
      <xsl:text>. </xsl:text>
    </fo:list-item-label>
    <fo:list-item-body>
      <xsl:apply-templates/>
    </fo:list-item-body>
  </fo:list-item>
</xsl:template>

2.7.12 Copying

The xsl:copy element provides an easy way of copying the current node. The xsl:copy element is replaced by a copy of the current node. The namespace nodes of the current node are automatically copied as well, but the attributes and children of the node are not automatically copied. The content of the xsl:copy element is a template for the attributes and children of the created node; the content is not used for nodes of types that do not have attribues or children (attributes, text, comments and processing instructions).

The root node is treated specially because the root node of the result tree is created implicitly. When the current node is the root node, xsl:copy will not create a root node, but will just use the content template.

For example, the identity transformation can be written using xsl:copy as follows:

<xsl:template match="*|@*|comment()|pi()|text()">
  <xsl:copy>
    <xsl:apply-templates select="*|@*|comment()|pi()|text()"/>
  </xsl:copy>
</xsl:template>

2.7.13 Computing Generated Text

Within a template, the xsl:value-of element can be used to compute generated text, for example by extracting text from the source tree or by inserting the value of a string constant. The xsl:value-of element does this with a string expression that is specified as the value of the select attribute. String expressions can also be used inside attribute values of literal result elements by enclosing the string expression in curly brace ({}).

<xsl:template match="person">
  <P>
   <xsl:value-of select="@first-name"/>
   <xsl:text> </xsl:text>
   <xsl:value-of select="@surname"/>
  </P>
</xsl:template>

<xsl:template match="person">
  <P>
   <xsl:value-of select="first-name"/>
   <xsl:text> </xsl:text>
   <xsl:value-of select="surname"/>
  </P>
</xsl:template>

<xsl:template match="procedure">
  <fo:block>
    <xsl:value-of select="ancestor(*[@security])/@security"/>
  </fo:block>
  <xsl:apply-templates/>
</xsl:template>

<xsl:constant name="image-dir" value="/images"/>

<xsl:template match="photograph">
<IMG SRC="{constant(image-dir)}/{href}" WIDTH="{size/@width}"/>
</xsl:template>

<photograph>
  <href>headquarters.jpg</href>
  <size width="300"/>
</photograph>

<IMG SRC="/images/headquarters.jpg" WIDTH="300"/>

<a href="#{id({@ref})/title}">

<a href="#{id(@ref)/title}">

2.7.14 String Constants

Global string constants may be defined using an xsl:constant element. The name attribute specifies the name of the constant, and the value attribute specified the value.

A stylesheet must not contain more than one definition of a constant with the same name and same importance. A definition of a constant will not be used if there is another definition of a constant with the same name and higher importance.

String constants are referenced using a ConstantRef string expression.

<xsl:constant name="para-font-size" value="12pt"/>

<xsl:template match="para">
 <fo:block font-size="{constant(para-font-size)}">
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

The value attribute is interpreted as an attribute value template. If the value of a constant definition x references a constant y, then the value for y must be computed before the value of x. It is an error if it is impossible to do this for all constant definitions because of dependency cycles.

2.7.15 Macros

Parts of templates can also be factored out of similar rules into macros for reuse. Macros allow authors to create aggregate result fragments and refer to the composite as if it were a single object. In this example, a macro is defined for a boxed paragraph with the word "Warning!" preceding the contents. The macro is referenced from a rule for warning elements.

<xsl:macro name="warning-para">
  <fo:block-level-box>
    <fo:block>
      <xsl:text>Warning! </xsl:text>
      <xsl:contents/>
    </fo:block>
  </fo:block-level-box>
</xsl:macro>

<xsl:template match="warning">
  <xsl:invoke macro="warning-para">
    <xsl:apply-templates/>
  </xsl-invoke>
</xsl:template>

Macros are defined using the macro element. The name attribute specifies the name of the macro being defined. The content of the macro element is a template, called the body of the macro. A macro is invoked using the xsl:invoke element; the content of xsl:invoke is a template. The name of the macro to be invoked is given by the macro attribute. Invoking a macro first instantiates the content of xsl:invoke. It then instantiates the body of the invoked macro passing it the result tree fragment created by the instantiation of the content of xsl:invoke; this fragment can be inserted in the body of the macro using the xsl:contents element.

Macros allow named arguments to be declared with the xsl:macro-arg element; the name attribute specifies the argument name, and the optional default attribute specifies the default value for the argument. Within the body of a macro, macro arguments are referenced using a MacroArgRef string expression. It is an error to refer to a macro argument that has not been declared. An XSL processor may signal the error; if it does not signal the error, it must recover by using an empty string. Arguments are supplied to a macro invocation using the code xsl:arg element; the name attribute specifies the argument name, and the value attribute specifies the argument value. It is an error to supply an argument to a macro invocation if the macro did not declare an argument of that name. An XSL processor may signal the error; if it does not signal the error, it must recover by ignoring the argument. The value attribute of xsl:arg and the default attribute of xsl:macro-arg are interpreted as attribute value templates; they can contain string expressions in curly braces as with literal result elements.

This example defines a macro for a numbered-block with an argument to control the format of the number.

<xsl:macro name="numbered-block">
  <xsl:macro-arg name="format" default="1. "/>
  <xsl:number format="{arg(format)}"/>
  <fo:block/>
    <xsl:contents/>
  </fo:block>
</xsl:macro>

<xsl:template match="appendix/title">
  <xsl:invoke macro="numbered-block">
    <xsl:arg name="format" value="A. "/>
    <xsl:apply-templates/>
  </xsl:invoke>
</xsl:template>

It is an error if a stylesheet contains more than one definition of a macro with the same name and same importance. An XSL processor may signal the error; if it does not signal the error, if must recover by choosing from amongst the definitions with highest importance the one that occurs last in the stylesheet.

2.8.1 Stylesheet Import

An XSL stylesheet may contain xsl:import elements. All the xsl:import elements must occur at the beginning of the stylesheet. The xsl:import element has an href attribute whose value is the URI of a stylesheet to be imported. A relative URI is resolved relative to the base URI of the xsl:import element (see Section 2.4.2.2: Base URI).

<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl">
  <xsl:import href="article.xsl"/>
  <xsl:import href="bigfont.xsl"/>
  <xsl:attribute-set name="note-style">
    <xsl:attribute name="font-style">italic</xsl:attribute>
  </xsl:attribute-set>
</xsl:stylesheet>

Rules and definitions in the importing stylesheet are defined to be more important than rules and definitions in any imported stylesheets. Also rules and definitions in one imported stylesheet are defined to be more important than rules and definitions in previous imported stylesheets.

In general a more important rule or definition takes precedence over a less important rule or definition. This is defined in detail for each kind of rule and definition.

xsl:apply-imports processes the current node using only template rules that were imported into the stylesheet containing the current rule; the node is processed in the current rule's mode.

2.8.2 Stylesheet Inclusion

An XSL stylesheet may include another XSL stylesheet using an xsl:include element. The xsl:include element has an href attribute whose value is the URI of a stylesheet to be included. A relative URI is resolved relative to the base URI of the xsl:include element (see Section 2.4.2.2: Base URI). The xsl:include element can occur as the child of the xsl:stylesheet element at any point after all xsl:import elements.

The inclusion works at the XML tree level. The resource located by the href attribute value is parsed as an XML document, and the children of the xsl:stylesheet element in this document replace the xsl:include element in the including document. Also any xsl:import elements in the included document are moved up in the including document to after any existing xsl:import elements in the including document. Unlike with xsl:import, the fact that rules or definitions are included does not affect the way they are processed.

2.8.3 Embedding Stylesheets

Normally an XSL stylesheet is a complete XML document with the xsl:stylesheet element as the document element. However an XSL stylesheet may also be embedded in another resource. Two forms of embedding are possible:

• the XSL stylesheet may be textually embedded in a non-XML resource, or
• the xsl:stylesheet element may occur in an XML document other than as the document element.

In the second case, the possibility arises of documents with inline style, that is documents that specify their own style. XSL does not define a specific mechanism for this. This is because this can be done by means of a general purpose mechanism for associating stylesheets with documents provided that:

• the mechanism allows a part of a resource to be specified as the stylesheet, for example by using a URI with a fragment identifier, and
• the mechanism can itself can be embedded in the document, for example as a processing instruction.

It is not in the scope of XSL to define such a mechanism.

The xsl:stylesheet element may have an ID attribute that specifies a unique identifier.

The following example shows how inline style can be accomplished using the xml-stylesheet processing instruction mechanism for associating a stylesheet with an XML document. The URI uses an XPointer in a fragment identifier to locate the xsl:stylesheet element.

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="#id(style1)"?>
<!DOCTYPE doc SYSTEM "doc.dtd">
<doc>
<head>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/TR/WD-xsl" id="style1">
<xsl:import href="doc.xsl"/>
<xsl:template match="id(foo)">
 <fo:block font-weight="bold"><xsl:apply-templates/></fo:block>
</xsl:template>
</xsl:stylesheet>
</head>
<body>
<para id="foo">
...
</para>
</body>
</doc>

3.2.1 Introduction

The formatting model is defined in terms of rectangular areas and spaces.

• Areas reserve space and hold content.

  Selected rectangular areas may have their own coordinate systems and may contain other rectangular areas.

  Rectangular areas may be filled with other areas; when this happens the contained areas are placed in accordance with the writing-mode, a property of the containing area which controls the direction of placement of successive contained areas.

  [Ednote: Further versions or extensions of the model may take into account non-rectangular areas.]

  A rectangular area is like a CSS box in that it has margins, borders, and padding, which are specified by properties of the formatting object that caused the creation of the area.

  [Ednote: We have not fully resolved technical differences between CSS's use of margins and XSL's use of display-space and inline-space. I have left the references to margins in this section, because I believe that these issues can be resolved and we will eventually need to describe handling of margins at those locations in the document.. However, the descriptions of the handling of inline-space and display-space is more accurate and more complete at this time.]

• Spaces reserve space before, after, or between areas and do not have content. They are used to make adjustments to the layout.

It is the responsibility of the formatter to manage inheritance and to specify the resultant properties when creating any area. This is necessary since this formatting model should be applicable to both XSL and CSS, which have differing inheritance strategies. It is therefore necessary for the formatter to derive certain properties when it creates (synthesizes) an area that has no directly related formatting object (such as the creation of line-areas within a block area).

3.2.2 Rectangular areas

There are four kinds of rectangular areas: area-containers, block-areas, line-areas, and inline-areas.

• Area-containers may contain smaller area-containers. Alternatively, an area-container may be filled with a sequence of block-areas and display-spaces, which are stacked (placed sequentially and adjacent to one another, possibly separated by display-spaces) within the area-container in a direction determined by the writing-mode.

  Area-containers always have a writing-mode and set a coordinate system for all contained areas. The start-indent and end-indent of any block-area is measured from the area-container's corresponding edges, not from the edges of any intervening (nested) block-area.

  Area-containers may be placed at a specific positions within the containing area or may be attached to the inside of any edge of the containing area.

• Block-areas are filled with line-areas, display-spaces, and nested block-areas stacked (placed sequentially and adjacent to one another, possibly separated by display-spaces) in a direction determined by the writing-mode, or alternatively may consist of a graphic element.

  Block-areas should not be thought of as abstract entities which are "broken" across an area-container boundary; rather, at a container boundary a block-level formatting object may generate two (or more) block-areas.

  Block-areas are always stacked in the containing area.

• Line-areas are filled with inline-areas and inline-spaces in a direction determined by the writing-mode.

  Line-areas are always stacked (placed sequentially and adjacent to one another, possibly separated by display-spaces) in the containing block-area.

• An inline-area may contain other inline-areas. The lowest level inline-area commonly contains a single character glyph image (and is then called a glyph-area). An inline-area may have more complex content (e.g. an in-line mathematical expression).

  Inline-areas should not be thought of as abstract entities which are "broken" across a line boundary; rather, at a line boundary an inline formatting object may generate two (or more) inline-areas.

  Inline-areas are always stacked (placed sequentially and adjacent to one another, possibly separated by inline-spaces) in the containing area.

Rectangular areas have a number of common features. Each has a margin, border, and padding, defined as follows.

• A border is an open box surrounding the content of the area. A border is specified in terms of its color and of the thickness of each of its four sides. This thickness may be specified as a range with minimum, optimum, and maximum values.

• Padding is the open space between the inside of the border and the content of the area. It is specified by its thickness in each of the four directions.

• A margin is used to determine the open space reserved between the outside of the border of the rectangular area and those of other rectangular areas. It is specified by its thickness in each of the four directions, though only some of these may apply in determining the allocation-rectangle, described below.

By a rectangle we mean an open rectangle, consisting of four edges. This model identifies a number of specific rectangles:

• The content-rectangle of a rectangular area is the rectangle surrounding the area's content.

• The padding rectangle surrounds the area's padding. If the padding has 0 thickness, the padding rectangle is the same as the content-rectangle.

• The border rectangle surrounds the area's border. If the border has 0 width, the border rectangle is the same as the padding rectangle.

• The margin rectangle surrounds the area's margin. If the margin has 0 width, the margin rectangle is the same as the border rectangle.

All rectangular areas have properties which are either specified (explicitly) or derived. Margin, border and padding specifications are specified properties.

Among the properties of areas are the writing-mode. This determines the way glyphs are aligned (called the glyph-alignment-mode), and several directions used for rectangular area placement:

• block-progression-direction: the direction of progression of sequential block-areas within an area-container.

• line-progression-direction: the direction of progression of sequential line-areas within a block-area. This is usually the same as the block-progression-direction but may sometimes be opposite to the block-progression-direction.

• inline-progression-direction: the direction of progression of sequential inline-areas within a line-area. This is always perpendicular to the line-progression-direction.

• escapement-progression-direction: the direction of progression of sequential glyph-areas within an inline-area. This is usually the same as the inline-progression-direction but may sometimes be opposite to the inline-progression-direction.

Inline-areas have a designated position-point. We will define the descender-depth of a glyph-area to be how far it extends in the line-progression-direction from the position-point, and the ascender-height to be how far it extends in the opposite direction. Similar definitions may be made for more complex inline-areas.

The edges of any rectangle associated with a rectangular area are identified by their relative direction, based on the writing-mode.

• The edge occurring first in the block-progression-direction or the line-progression-direction (as applicable) and perpendicular to it is called the before-edge of the rectangle. The opposite edge is the after-edge.

• The edge occurring first in the inline-progression-direction or the escapement-progression-direction (as applicable) is called the start-edge of the rectangle. The opposite edge is called the end-edge.

In European writing systems, these are the "top" and "bottom" edges, and "left" and "right" edges, respectively, and "ascender-height" and "descender-depth" have their usual meanings.

Two rectangles associated to a rectangular area are of particular significance:

• The content-rectangle bounds the portion of the area in which the allocation-rectangles of smaller areas may appear. It is possible for marks associated with an area to be found outside the content-rectangle, but these are considered decoration and are deemed not to take up area.

• The allocation-rectangle bounds the portion of the area which is used to allocate space when placing the area inside a larger area. When we speak of an area's "size" we are normally referring to the dimensions of its allocation-rectangle.

  For area-containers the allocation-rectangle extends as far as the border rectangle in the block-progression-direction, and as far as the margin rectangle in the perpendicular direction.

  For all other rectangular areas, the allocation-rectangle extends to the margin rectangle in the inline-progression-direction. For block-areas it extends to the border rectangle in the line-progression-direction, and for line-areas and inline-areas, it extends only to the content-rectangle in that direction.

3.2.3 Display-spaces

Display-spaces are blank space assigned preceding and following line-areas and block-areas to control their placement. They are assigned either automatically by the formatter or as otherwise specified.

A display-space between two areas (block or line) is specified by a triple of values (minimum, optimum, maximum) which defines the limits of how the space may be transformed by later processes such as vertical justification. In the absence of further processing, the two areas will be separated by the optimum value, but such processing may reduce it as small as the specified minimum or stretch it as large as the specified maximum.

A display-space is thought of as having a before-edge and after-edge separated in the block-progression-direction or line-progression-direction by the display-space's value. A display-space value may be negative, which can cause areas to overlap.

When two or more display-spaces are adjacent, they shall be resolved into a single display-space whose minimum, optimum and maximum values are derived according to the space-resolution-rules, as described below. These depend on certain specified properties of the display-space, namely conditionality and precedence.

• Conditionality is a Boolean value which specifies whether the space persists at the beginning or end of an area-container. If true, the space is called a conditional-space and is always omitted if it appears at the before-edge or after-edge of the content-rectangle of an area-container; in this case any immediately succeeding conditional-spaces are also omitted.

• Precedence has a value which is either an integer or the special token "force". A space with a precedence value of "force" is called a forcing space.

Space-resolution-rules. When several spaces are assigned to be adjacent, they are resolved into a single space as follows:

1. At the beginning or end of an area-container, any conditional-spaces are omitted if this has not already been done.

2. Then, if any space is forcing, the resolved space is taken to be the sum of all the forcing spaces, and all non-forcing spaces are suppressed.

3. If all spaces are non-forcing, then the eligible spaces shall be those with the maximum precedence, and among these, the space or spaces having the greatest optimum value. All other spaces are suppressed. The resolved space is taken to have the same optimum value as the eligible spaces; its minimum value shall be the greatest of the minimum values of the eligible spaces, and its maximum value shall be the least of the maximum values.

A display-space at the before-edge or after-edge of the content-rectangle of a block-area is combined with the padding of the block-area in that direction according to the space-resolution-rules, except that the resolved display-space is never resolved to be smaller than the padding.

3.2.4 Inline-spaces

Inline-spaces are blank space assigned preceding and following inline-areas. They are assigned either automatically by the formatter (e.g. for word spacing, letterspacing, or kerning) or as otherwise specified.

An inline-space is specified by a triple of values (minimum, optimum, maximum) which defines the limits of how the space may be transformed by later processes such as justification. It separates inline-areas in a direct analogy to the way display-space separates block-areas.

An inline-space is thought of as having a start-edge and end-edge, separated in the inline-progression-direction by the inline-space's value. An inline-space value may be negative, which can cause inline-areas to overlap.

Inline-spaces have conditionality and precedence. Conditional inline-spaces are omitted at the start and end of a line-area. When multiple inline-spaces are assigned to be adjacent, they are resolved in accordance with the space-resolution-rules.

3.2.5 Area containers

An area-container defines a coordinate system for its content, which may be oriented differently from that of its containing area.

The block-progression-direction of an area-container is derived from its coordinate system and its writing-mode, and controls the orientation and placement of block-areas in the area-container.

The allocation-rectangle of an area-container has a fixed size in the direction perpendicular to its block-progression-direction, and may have a fixed size in the block-progression-direction, or may grow to accommodate its content.

Area-containers may directly contain smaller area-containers, or alternatively may be filled with block-areas. Area-containers may be directly contained in larger area-containers, block-areas, or inline-areas, or may be uncontained (e.g. a page area).

3.2.6 Block-areas

A block-area's margins, borders, and padding are specified by the formatter based on the properties of its generating flow object.

A block-area's writing-mode is specified by the formatter (though the formatter may choose to derive the value from its containing area). This determines its line-progression-direction, which controls the orientation and placement of line-areas in its content-rectangle, and its inline-progression-direction, which is used to determine the direction of writing within contained line-areas.

Block-areas also have a specified nominal-font (a fully qualified font name and font size), which is used by the formatter to establish a default font for the block-area's directly contained line-areas and block-areas, but may be overridden. Other properties include line-height (the nominal distance between the before-edges of successive line-areas), minimum-leading (the minimum space allowed between line-areas), and space-before and space-after specifications (which may be identified with the specifications for before- and after-margins).

A derived property of a block-area is its nominal-glyph-height, which is the distance from the maximum ascender-height to the maximum descender depth of the glyph-areas of the nominal-font. This is a property of the nominal-font and is not dependent on which glyphs are actually present in the block-area.

The allocation-rectangle of a block-area has fixed size in the inline-progression-direction, and varies in the line-progression-direction to accommodate its content, though this may not grow outside the content-rectangle of its containing area. (The overflow property does allow the content to exceed the allocation-rectangle under limited circumstances. The overflowing data is considered decoration and is not considered as part of the layout. Overflowing data may be clipped or may overprint content in other areas.) A block-area consisting of a graphic element has fixed size in both directions.

A block-area may directly contain line-areas, display-spaces, and nested block-areas, or may consist of a graphic element. Block-areas may be directly contained in area-containers and higher-level block-areas.

3.2.7 Line-areas

There is no formatting-object that directly corresponds to a line-area. Thus, line-areas are always created by the formatter. A line-area's margins, borders, and padding are derived by the formatter from the settings on the containing area.

A line-area also derives its inline-progression-direction from its containing block-area, and this is used to determine the direction of writing within a line. It also derives its line-height and minimum-leading properties, as well as its nominal-font, which is used to derive its nominal-glyph-height.

The allocation-rectangle of a line is determined by the presence or absence of the minimum-leading property: if absent, the allocation-rectangle is the nominal-requested-line-rectangle; if present, it is the maximum-line-rectangle, as described below.

The nominal-requested-line-rectangle for a line-area is the rectangle bounded in the inline-progression-direction by the content-rectangle of the containing block-area, as modified by typographic properties such as indents, and in the perpendicular direction by its nominal-glyph-height. It has the same height for each line in a block-area.

The maximum-line-rectangle for a line has the same length as the nominal-requested-line-rectangle in the inline-progression-direction. In the perpendicular direction it is bounded by the maximum ascender-height and the maximum descender-depth for the actual fonts and inline-areas placed on the line, as raised and lowered by vertical-align and other adjustments perpendicular to the inline-progression-direction. Its height may vary depending on the contents of the line-area.

The nominal-font is always deemed to occur on a line, and thus the maximum-line-rectangle always contains the nominal-requested-line-rectangle.

Inline-areas are placed within a line-area relative to a placement-point . This varies during the placement process, but initially the placement-point is a point on the start-edge of its content-rectangle, separated from the before-edge of the nominal-requested-line-rectangle by a distance equal to the ascender-height for the nominal-font.

Line-areas may directly contain inline-areas and inline-spaces. They may be directly contained in block-areas.

3.2.8 Inline-areas

The most common inline-area is a glyph-area, which contains the representation for a character in a particular font. Other examples of inline-areas might include portions of inline mathematical expressions.

Inline-areas have margins, borders, and padding, specified by the formatter. (The margins before and after an inline-area are disregarded in determining the size of its allocation-rectangle. However, margins at the start-edge and end-edge are incorporated into the allocation-rectangle.)

The allocation-rectangle for an inline-area has a fixed size in both dimensions, though this may be specified as a range within which the size may be modified by further processes such as justification. An inline-area also has a font, which is derived from the containing area (if not explicitly set on the inline-area).

Each inline-area has a designated position-point on one of the edges of its allocation-rectangle (typically the start-edge). On the opposite edge of the allocation-rectangle there is another point called the escapement-point, and the vector from the position-point to the escapement-point is called the escapement-vector.

The position-point and escapement-point are assigned according to the writing-system in use (e.g. the glyph baseline in European languages) and the current escapement-progression-direction in effect for bidirectional text. These points may be futher adjusted in the case of mixed-language formatting involving different glyph-alignment-modes.

A glyph-area is atomic and may contain no other areas. An inline-area may be atomic and contain no other areas, or may be non-atomic and contain an area-container (such as for an inline-graphic), a block-area or other inline-areas. Inline-areas may be directly contained only in line-areas or in other inline-areas.

3.2.9 Inline-area placement within a line-area

The formatter constructs a series of inline-areas and assigns these to line-areas according to its line-breaking algorithm.

Inline-areas assigned to a line-area are placed in the line-area in their display order (which may be different from the logical order, when writing-systems are mixed).

Before an inline-area is placed, the placement-point of the line-area may be adjusted by shifts perpendicular to the inline-progression-direction (e.g. for subscript and superscript, or to allow for glyphs with a different natural alignment from the line-area's glyph-alignment mode).

Each inline-area is oriented so that the direction of its escapement-vector matches the escapement-progression-direction, and is placed so that its position-point matches the current placement-point of the line-area. The escapement-point of the inline-area then becomes the new placement-point.

Each inline-space is placed so that its start-edge intersects the current placement-point, and the placement-point is translated in the inline-progression-direction, to the end-edge of the inline-space. Adjacent spaces are combined according to the space-resolution-rules. A conditional-space is not placed if it is at the start-edge of the content-rectangle of a line-area, but may be placed if it follows a non-conditional-space there. Similarly a conditional-space is not placed if it is at the end of a line-area, but may be placed if it precedes a non-conditional-space there.

3.2.10 Line-area placement within a block-area

Preceding and following each line-area assigned to a block-area, the formatter assigns display-spaces, whose conditionality and precedence are determined by the generating flow object.

The values of these display-spaces are determined by the presence or absence of the minimum-leading property. If minimum-leading is present then the value of each is equal to half the value of minimum-leading. Otherwise it is equal to half of the difference between the line-height and nominal-glyph-height, as derived from the containing block-area (if not set explicitly on the inline-area).

Each display-space is placed so that its before-edge coincides with the after-edge of the allocation-rectangle of the previous block-area or line-area. Adjacent spaces are combined according to the space-resolution-rules. A conditional-space is not placed if it is at the before-edge of the content-rectangle of an area-container, but may be placed if it follows a non-conditional-space there. Similarly a conditional-space is not placed at the after-edge, but may be placed if it precedes a non-conditional-space there.

Each line-area is placed so that the before-edge of its allocation-rectangle matches the after-edge of the previous display-space, line-area, or block-area, or failing these, the before-edge of the content-rectangle of its containing block-area. The start-edge and end-edges of the allocation-rectangle are placed to coincide with corresponding edges of the content-rectangle of the containing block-area.

3.2.11 Block-area placement

Preceding and following each block-area assigned to an area-container, or nested inside another block-area, the formatter assigns display-spaces, whose height, conditionality and precedence are determined in accordance with its space-before and space-after properties, and by other properties of the generating flow object.

Each display-space is placed so that its before-edge coincides with the after-edge of the allocation-rectangle of the previous block-area or line-area. Adjacent spaces are combined according to the space-resolution-rules. A conditional-space is not placed if it is at the before-edge of the content-rectangle of an area-container, but may be placed if it follows a non-conditional-space there, and similarly for the after-edge.

Each block-area is placed so that the before-edge of its allocation-rectangle matches the after-edge of the previous display-space, line-area, or block-area, or failing that, the before-edge of the content-rectangle of the containing area-container or block-area.

The start-edge and end-edges of its allocation-rectangle are placed to coincide with the corresponding edges of the content-rectangle of the containing block-area or area-container.

In no case is the space between block-areas affected by the display-spaces contained in those block-areas, or in particular by their specified values of line-height.

3.4.1 fo:basic-page-sequence

3.4.2 fo:block

3.4.3 fo:character

3.4.4 fo:display-graphic

3.4.5 fo:display-link

3.4.6 fo:display-rule

3.4.7 fo:display-sequence

3.4.8 fo:inline-graphic

3.4.9 fo:inline-link

3.4.10 fo:inline-rule

3.4.11 fo:inline-sequence

3.4.12 fo:link-end-locator

3.4.13 fo:list-block

3.4.14 fo:list-item

3.4.15 fo:list-item-body

3.4.16 fo:list-item-label

3.4.17 fo:page-number

3.4.18 fo:queue

3.4.19 fo:simple-page-master

3.5.1 asis-truncate-indicator

3.5.2 asis-wrap-indent

3.5.3 asis-wrap-indicator

3.5.4 background-attachment

3.5.5 background-color

3.5.6 background-image

3.5.7 background-position

3.5.8 background-repeat

3.5.9 body-overflow

3.5.10 body-writing-mode

3.5.11 border-color-after

3.5.12 border-color-before

3.5.13 border-color-bottom

3.5.14 border-color-end

3.5.15 border-color-left

3.5.16 border-color-right

3.5.17 border-color-start

3.5.18 border-color-top

3.5.19 border-width-after

3.5.20 border-width-before

3.5.21 border-width-bottom

3.5.22 border-width-end

3.5.23 border-width-left

3.5.24 border-width-right

3.5.25 border-width-start

3.5.26 border-width-top

3.5.27 break-after

3.5.28 break-before

3.5.29 character

3.5.30 color

3.5.31 contents-alignment

3.5.32 contents-rotation

3.5.33 destination

3.5.34 end-indent

3.5.35 end-side-overflow

3.5.36 end-side-separation

3.5.37 end-side-size

3.5.38 end-side-writing-mode

3.5.39 escapement-space-end

3.5.40 escapement-space-start

3.5.41 expand-tabs

3.5.42 first-page-master

3.5.43 font-family

3.5.44 font-size

3.5.45 font-size-adjust

3.5.46 font-stretch

3.5.47 font-style

3.5.48 font-variant

3.5.49 font-weight

3.5.50 footer-overflow

3.5.51 footer-separation

3.5.52 footer-size

3.5.53 footer-writing-mode

3.5.54 glyph-alignment-mode