8 Document Object Model for MathML

8.1 Introduction

This document extends the Core API of the DOM Level 2 to describe objects and methods specific to MathML elements in documents. The functionality needed to manipulate basic hierarchical document structures, elements, and attributes will be found in the core document; functionality that depends on the specific elements defined in MathML will be found in this document.

The actual DOM specification appears in Appendix D Document Object Model for MathML.

The goals of the MathML-specific DOM API are:

• To specialize and add functionality that relates specifically to MathML elements.

• To provide convenience mechanisms, where appropriate, for common and frequent operations on MathML elements.

This document includes the following specializations for MathML:

• A MathMLElement interface derived from the core interface Element. MathMLElement specifies the operations and queries that can be made on any MathML element. Methods on MathMLElement include those for the retrieval and modification of attributes that apply to all MathML elements.

• Various specializations of MathMLElement to encode syntactical restrictions imposed by MathML.

• Specializations of MathMLElement representing all MathML elements with attributes extending beyond those specified in the MathMLElement interface. For all such attributes, the derived interface for the element contains explicit methods for setting and getting the values.

• Special methods for insertion and retrieval of children of MathML elements. While the basic methods inherited from the Node and Element interfaces must clearly remain available, it is felt that in many cases they may be misleading. Thus, for instance, the MathMLFractionElement interface provides for access to numerator and denominator attributes; a call to setDenominator(newNode) is less ambiguous from a calling application's perspective than a call to Node::replaceNode(newNode, Node::childNodes().item(2)).

Where no special convenience methods are provided for retrieving attributes or child Nodes, the basic functionality of the Core DOM should be used to retrieve them.

MathML specifies rules that are invisible to generic XML processors and validators. The fact that MathML DOM objects are required to respect these rules, and to throw exceptions when those rules are violated, is an important reason for providing a MathML-specific DOM extension.

There are basically two kinds of additional MathML grammar and syntax rules. One kind involves placing additional criteria on attribute values. For example, it is not possible in pure XML to require that an attribute value be a positive integer. The second kind of rule specifies more detailed restrictions on the child elements (for example on ordering) than are given in the DTD. For example, it is not possible in XML to specify that the first child be interpreted one way, and the second in another. The MathML DOM objects are required to provide this interpretation.

MathML ignores whitespace occurring outside token elements. Non-whitespace characters are not allowed there. Whitespace occurring within the content of token elements is "trimmed" from the ends (i.e. all whitespace at the beginning and end of the content is removed), and "collapsed" internally (i.e. each sequence of 1 or more whitespace characters is replaced with one blank character). The MathML DOM elements perform this whitespace trimming as necessary. In MathML, as in XML, "whitespace" means blanks, tabs, newlines, or carriage returns, i.e. characters with hexadecimal Unicode codes U+0020, U+0009, U+000a, or U+000d, respectively.