# 5 Mixing Markup Languages for Mathematical Expressions

MathML markup can be combined with other markup languages, and these mixing constructions are realized by the semantic annotation elements. The semantic annotation elements provide an important tool for making associations between alternate representations of an expression, and for associating semantic properties and other attributions with a MathML expression. These elements allow presentation markup and content markup to be combined in several different ways. One method, known as mixed markup, is to intersperse content and presentation elements in what is essentially a single tree. Another method, known as parallel markup, is to provide both explicit presentation markup and content markup in a pair of markup expressions, combined by a single semantics element.

## 5.1 Annotation Framework

An important concern of MathML is to represent associations between presentation and content markup forms for an expression. Representing associations between MathML expressions and data of other kinds is also important in many contexts. For this reason, MathML provides a general framework for annotation. A MathML expression may be decorated with a sequence of pairs made up of a symbol that indicates the kind of annotation, known as the annotation key, and associated data, known as the annotation value.

### 5.1.1 Annotation elements

The semantics, annotation, and annotation-xml elements are used together to represent annotations in MathML. The semantics element provides the container for a expression and its annotations. The annotation element is the container for text annotations, and the annotation-xml element is used for XML annotations. The semantics element contains the expression being annotated as its first child, followed by a sequence of zero or more annotation and/or annotation-xml elements.

<semantics>
<mrow>
<mrow>
<mi>sin</mi>
<mo>&#x2061;<!--FUNCTION APPLICATION--></mo>
<mfenced><mi>x</mi></mfenced>
</mrow>
<mo>+</mo>
<mn>5</mn>
</mrow>
<annotation encoding="application/x-tex">
\sin x + 5
</annotation>
<annotation-xml encoding="application/openmath+xml">
<OMA xmlns="http://www.openmath.org/OpenMath">
<OMS cd="arith1" name="plus"/>
<OMA><OMS cd="transc1" name="sin"/><OMV name="x"/></OMA>
<OMI>5</OMI>
</OMA>
</annotation-xml>
</semantics>

The semantics element is considered to be both a presentation element and a content element, and may be used in either context. All MathML processors should process the semantics element, even if they only process one of these two subsets of MathML.

### 5.1.2 Annotation keys

An annotation key specifies the relationship between an expression and an annotation. Many kinds of relationships are possible. Examples include alternate representations, specification or clarification of semantics, type information, rendering hints, and private data intended for specific processors. The annotation key is the primary means by which a processor determines whether or not to process an annotation.

The logical relationship between an expression and an annotation can have a significant impact on the proper processing of the expression. For example, a particular annotation form, called semantic attributions, cannot be ignored without altering the meaning of the annotated expression, at least in some processing contexts. On the other hand, alternate representations do not alter the meaning of an expression, but may alter the presentation of the expression as they are frequently used to provide rendering hints. Still other annotations carry private data or metadata that are useful in a specific context, but do not alter either the semantics or the presentation of the expression.

In MathML 3, annotation keys are defined as symbols in Content Dictionaries, and are specified using of the cd and name attributes on the annotation and annotation-xml elements. For backward compatibility with MathML 2, an annotation key may also be referenced using the definitionURL attribute as an alternative to the cd and name attributes. Further details on referencing symbols in Content Dictionaries are discussed in Section 4.2.3 Content Symbols <csymbol>. The symbol definition in a Content Dictionary for an annotation key may have a role property. Two particular roles are relevant for annotations: a role of "attribution" identifies a generic annotation that can be ignored without altering the meaning of the annotated term, and a role of "semantic-attribution" indicates that the annotation is a semantic annotation, that is, the annotation cannot be ignored without potentially altering the meaning of the expression.

MathML 3 provides two predefined annotation keys for the most common kinds of annotations: alternate-representation and contentequiv defined in the mathmlkeys content dictionary. The alternate-representation annotation key specifies that the annotation value provides an alternate representation for an expression in some other markup language, and the contentequiv annotation key specifies that the annotation value provides a semantically equivalent alternative for the annotated expression. Further details about the use of these keys is given in the sections below.

The default annotation key is alternate-representation when no annotation key is explicitly specified on an annotation or annotation-xml element.

Typically, annotation keys specify only the logical nature of the relationship between an expression and an annotation. The data format for an annotation is indicated with the encoding attribute. In MathML 2, the encoding attribute was the primary information that a processor could use to determine whether or not it could understand an annotation. For backward compatibility, processors are encouraged to examine both the annotation key and encoding attribute. In particular, MathML 2 specified the predefined encoding values MathML, MathML-Content, and MathML-Presentation. The MathML encoding value is used to indicate an annotation-xml element contains a MathML expression. The use of the other values is more specific, as discussed in following sections.

While the predefined alternate-representation and contentequiv keys cover many common use cases, user communities are encouraged to define and standardize additional content dictionaries as necessary. Annotation keys in user-defined, public Content Dictionaries are preferred over private encoding attribute value conventions, since content dictionaries are more expressive, more open and more maintainable than private encoding values. However, for backward compatibility with MathML 2, the encoding attribute may also be used.

### 5.1.3 Alternate representations

Alternate representation annotations are most often used to provide renderings for an expression, or to provide an equivalent representation in another markup language. In general, alternate representation annotations do not alter the meaning of the annotated expression, but may alter its presentation.

A particularly important case is the use of a presentation MathML expression to indicate a preferred rendering for a content MathML expression. This case may be represented by labeling the annotation with the application/mathml-presentation+xml value for the encoding attribute. For backward compatibility with MathML 2.0, this case can also be represented with the equivalent MathML-Presentation value for the encoding attribute. Note that when a presentation MathML annotation is present in a semantics element, it may be used as the default rendering of the semantics element, instead of the default rendering of the first child.

In the example below, the semantics element binds together various alternate representations for a content MathML expression. The presentation MathML annotation may be used as the default rendering, while the other annotations give representations in other markup languages. Since no attribution keys are explicitly specified, the default annotation key alternate-representation applies to each of the annotations.

<semantics>
<apply>
<plus/>
<apply><sin/><ci>x</ci></apply>
<cn>5</cn>
</apply>
<annotation-xml encoding="MathML-Presentation">
<mrow>
<mrow>
<mi>sin</mi>
<mo>&#x2061;<!--FUNCTION APPLICATION--></mo>
<mfenced open="(" close=")"><mi>x</mi></mfenced>
</mrow>
<mo>+</mo>
<mn>5</mn>
</mrow>
</annotation-xml>
<annotation encoding="application/x-maple">
sin(x) + 5
</annotation>
<annotation encoding="application/vnd.wolfram.mathematica">
Sin[x] + 5
</annotation>
<annotation encoding="application/x-tex">
\sin x + 5
</annotation>
<annotation-xml encoding="application/openmath+xml">
<OMA xmlns="http://www.openmath.org/OpenMath">
<OMA>
<OMS cd="arith1" name="plus"/>
<OMA><OMS cd="transc1" name="sin"/><OMV name="x"/></OMA>
<OMI>5</OMI>
</OMA>
</OMA>
</annotation-xml>
</semantics>

### 5.1.4 Content equivalents

Content equivalent annotations provide additional computational information about an expression. Annotations with the contentequiv key cannot be ignored without potentially changing the behavior of an expression.

An important case arises when a content MathML annotation is used to disambiguate the meaning of a presentation MathML expression. This case may be represented by labeling the annotation with the application/mathml-content+xml value for the encoding attribute. In MathML 2, this type of annotation was represented with the equivalent MathML-Content value for the encoding attribute, so processors are urged to support this usage for backward compatibility. A content MathML annotation, whether in MathML 2 or 3, may be used for other purposes as well, such as for other kinds of semantic assertions. Consequently, in MathML 3, the contentequiv annotation key should be used to make an explicit assertion that the annotation provides a definitive content markup equivalent for an expression.

In the example below, an ambiguous presentation MathML expression is annotated with a MathML-Content annotation clarifying its precise meaning.

<semantics>
<mrow>
<mrow>
<mi>a</mi>
<mfenced open="(" close=")">
<mrow><mi>x</mi><mo>+</mo><mn>5</mn></mrow>
</mfenced>
</mrow>
</mrow>
<annotation-xml cd="mathmlkeys" name="contentequiv"
encoding="MathML-Content">
<apply>
<ci>a</ci>
<apply><plus/><ci>x</ci><cn>5</cn></apply>
</apply>
</annotation-xml>
</semantics>

### 5.1.5 Annotation references

In the usual case, each annotation element includes either character data content (in the case of annotation) or XML markup data (in the case of annotation-xml) that represents the annotation value. There is no restriction on the type of annotation that may appear within a semantics element. For example, an annotation could provide a TEX encoding, a linear input form for a computer algebra system, a rendered image, or detailed mathematical type information.

In some cases the alternative children of a semantics element are not an essential part of the behavior of the annotated expression, but may be useful to specialized processors. To enable the availability of several annotation formats in a more efficient manner, a semantics element may contain empty annotation and annotation-xml elements that provide encoding and src attributes to specify an external location for the annotation value associated with the annotation. This type of annotation is known as an annotation reference.

<semantics>
<mfrac><mi>a</mi><mrow><mi>a</mi><mo>+</mo><mi>b</mi></mrow></mfrac>
<annotation encoding="image/png" src="333/formula56.png"/>
<annotation encoding="application/x-maple" src="333/formula56.ms"/>
</semantics>

Processing agents that anticipate that consumers of exported markup may not be able to retrieve the external entity referenced by such annotations should request the content of the external entity at the indicated location and replace the annotation with its expanded form.

An annotation reference follows the same rules as for other annotations to determine the annotation key that specifies the relationship between the annotated object and the annotation value.

## 5.2 Elements for Semantic Annotations

This section explains the semantic mapping elements semantics, annotation, and annotation-xml. These elements associate alternate representations for a presentation or content expression, or associate semantic or other attributions that may modify the meaning of the annotated expression.

### 5.2.1 The semantics element

#### 5.2.1.1 Description

The semantics element is the container element that associates annotations with a MathML expression. The semantics element has as its first child the expression to be annotated. Any MathML expression may appear as the first child of the semantics element. Subsequent annotation and annotation-xml children enclose the annotations. An annotation represented in XML is enclosed in an annotation-xml element. An annotation represented in character data is enclosed in an annotation element.

As noted above, the semantics element is considered to be both a presentation element and a content element, since it can act as either, depending on its content. Consequently, all MathML processors should process the semantics element, even if they process only presentation markup or only content markup.

The default rendering of a semantics element is the default rendering of its first child. A renderer may use the information contained in the annotations to customize its rendering of the annotated element.

<semantics>
<mrow>
<mrow>
<mi>sin</mi>
<mo>&#x2061;<!--FUNCTION APPLICATION--></mo>
<mfenced><mi>x</mi></mfenced>
</mrow>
<mo>+</mo>
<mn>5</mn>
</mrow>
<annotation-xml cd="mathmlkeys" name="contentequiv" encoding="MathML-Content">
<apply>
<plus/>
<apply><sin/><ci>x</ci></apply>
<cn>5</cn>
</apply>
</annotation-xml>
<annotation encoding="application/x-tex">
\sin x + 5
</annotation>
</semantics>

#### 5.2.1.2 Attributes

Name values default
definitionURL URI none
The location of an external source for semantic information
encoding string none
The encoding of the external semantic information

The semantics element takes the definitionURL and encoding attributes, which reference an external source for some or all of the semantic information for the annotated element, as modified by the annotation. The use of these attributes on the semantics element is deprecated in MathML3.

### 5.2.2 The annotation element

#### 5.2.2.1 Description

The annotation element is the container element for a semantic annotation whose representation is parsed character data in a non-XML format. The annotation element should contain the character data for the annotation, and should not contain XML markup elements. If the annotation contains one of the XML reserved characters &, <, >, ', or ", then these characters must be encoded using an XML entity reference or an XML CDATA section.

#### 5.2.2.2 Attributes

Name values default
definitionURL URI none
The location of the annotation key symbol
encoding string none
The encoding of the semantic information in the annotation
cd string mathmlkeys
The content dictionary that contains the annotation key symbol
name string alternate-representation
The name of the annotation key symbol
src URI none
The location of an external source for semantic information

Taken together, the cd and name attributes specify the annotation key symbol, which identifies the relationship between the annotated element and the annotation, as described in Section 5.1.1 Annotation elements. The definitionURL attribute provides an alternate way to reference the annotation key symbol as a single attribute. If none of these attributes are present, the annotation key symbol is the symbol alternate-representation from the mathmlkeys content dictionary.

The encoding attribute describes the content type of the annotation. The value of the encoding attribute may contain a media type that identifies the data format for the encoding data. For data formats that do not have an associated media type, implementors may choose a self-describing character string to identify their content type.

The src attribute provides a mechanism to attach external entities as annotations on MathML expressions.

<annotation encoding="image/png" src="333/formula56.png"/>

The annotation element is a semantic mapping element that may only be used as a child of the semantics element. While there is no default rendering for the annotation element, a renderer may use the information contained in an annotation to customize its rendering of the annotated element.

### 5.2.3 The annotation-xml element

#### 5.2.3.1 Description

The annotation-xml element is the container element for a semantic annotation whose representation is structured markup in an XML format. The annotation-xml element should contain the markup elements, attributes, and character data for the annotation.

#### 5.2.3.2 Attributes

Name values default
definitionURL URI none
The location of the annotation key symbol
encoding string none
The encoding of the semantic information in the annotation
cd string mathmlkeys
The content dictionary that contains the annotation key symbol
name string alternate-representation
The name of the annotation key symbol
src URI none
The location of an external source for semantic information

Taken together, the cd and name attributes specify the annotation key symbol, which identifies the relationship between the annotated element and the annotation, as described in Section 5.1.1 Annotation elements. The definitionURL attribute provides an alternate way to reference the annotation key symbol as a single attribute. If none of these attributes are present, the annotation key symbol is the symbol alternate-representation from the mathmlkeys content dictionary.

The encoding attribute describes the content type of the annotation. The value of the encoding attribute may contain a media type that identifies the data format for the encoding data. For data formats that do not have an associated media type, implementors may choose a self-describing character string to identify their content type. In particular, as described above and in Section 6.2.3 Names of MathML Encodings, MathML specifies MathML, MathML-Presentation, and MathML-Content as predefined values for the encoding attribute. Finally, The src attribute provides a mechanism to attach external XML entities as annotations on MathML expressions.

<annotation-xml cd="mathmlkeys" name="contentequiv" encoding="MathML-Content">
<apply>
<plus/>
<apply><sin/><ci>x</ci></apply>
<cn>5</cn>
</apply>
</annotation-xml>

<annotation-xml encoding="application/openmath+xml">
<OMA xmlns="http://www.openmath.org/OpenMath">
<OMS cd="arith1" name="plus"/>
<OMA><OMS cd="transc1" name="sin"/><OMV name="x"/></OMA>
<OMI>5</OMI>
</OMA>
</annotation-xml>

When the annotation value is represented in an XML dialect other than MathML, the namespace for the XML markup for the annotation should be identified by means of namespace attributes and/or namespace prefixes on the annotation value. For instance:

<annotation-xml encoding="application/xhtml+xml">
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
<p>The base of the natural logarithms, approximately 2.71828.</p>
</body>
</html>
</annotation-xml>

The annotation-xml element is a semantic mapping element that may only be used as a child of the semantics element. While there is no default rendering for the annotation-xml element, a renderer may use the information contained in an annotation to customize its rendering of the annotated element.

## 5.3 Combining Presentation and Content Markup

Presentation markup encodes the notational structure of an expression. Content markup encodes the functional structure of an expression. In certain cases, a particular application of MathML may require a combination of both presentation and content markup. This section describes specific constraints that govern the use of presentation markup within content markup, and vice versa.

### 5.3.1 Presentation Markup in Content Markup

Presentation markup may be embedded within content markup so long as the resulting expression retains an unambiguous function application structure. Specifically, presentation markup may only appear in content markup in three ways:

1. within ci and cn token elements

2. within the csymbol element

3. within the semantics element

Any other presentation markup occurring within content markup is a MathML error. More detailed discussion of these three cases follows:

Presentation markup within token elements.
The token elements ci and cn are permitted to contain any sequence of MathML characters (defined in Chapter 7 Characters, Entities and Fonts) and/or presentation elements. Contiguous blocks of MathML characters in ci or cn elements are treated as if wrapped in mi or mn elements, as appropriate, and the resulting collection of presentation elements is rendered as if wrapped in an implicit mrow element.
Presentation markup within the csymbol element.
The csymbol element may contain either MathML characters interspersed with presentation markup, or content markup. It is a MathML error for a csymbol element to contain both presentation and content elements. When the csymbol element contains character data and presentation markup, the same rendering rules that apply to the token elements ci and cn should be used.
Presentation markup within the semantics element.
One of the main purposes of the semantics element is to provide a mechanism for incorporating arbitrary MathML expressions into content markup in a semantically meaningful way. In particular, any valid presentation expression can be embedded in a content expression by placing it as the first child of a semantics element. The meaning of this wrapped expression should be indicated by one or more annotation elements also contained in the semantics element.

### 5.3.2 Content Markup in Presentation Markup

Content markup may be embedded within presentation markup so long as the resulting expression has an unambiguous rendering. That is, it must be possible, in principle, to produce a presentation markup fragment for each content markup fragment that appears in the combined expression. The replacement of each content markup fragment by its corresponding presentation markup should produce a well-formed presentation markup expression. A presentation engine should then be able to process this presentation expression without reference to the content markup bits included in the original expression.

In general, this constraint means that each embedded content expression must be well-formed, as a content expression, and must be able to stand alone outside the context of any containing content markup element. As a result, the following content elements may not appear as an immediate child of a presentation element: annotation, annotation-xml, bvar, condition, degree, logbase, lowlimit, uplimit.

In addition, within presentation markup, content markup may not appear within presentation token elements.

## 5.4 Parallel Markup

Some applications are able to use both presentation and content information. Parallel markup is a way to combine two or more markup trees for the same mathematical expression. Parallel markup is achieved with the semantics element. Parallel markup for an expression may appear on its own, or as part of a larger content or presentation tree.

### 5.4.1 Top-level Parallel Markup

In many cases, the goal is to provide presentation markup and content markup for a mathematical expression as a whole. A single semantics element may be used to pair two markup trees, where one child element provides the presentation markup, and the other child element provides the content markup.

The following example encodes the Boolean arithmetic expression (a+b)(c+d) in this way.

<semantics>
<mrow>
<mrow><mo>(</mo><mi>a</mi> <mo>+</mo> <mi>b</mi><mo>)</mo></mrow>
<mo>&#x2062;<!--INVISIBLE TIMES--></mo>
<mrow><mo>(</mo><mi>c</mi> <mo>+</mo> <mi>d</mi><mo>)</mo></mrow>
</mrow>
<annotation-xml encoding="MathML-Content">
<apply><and/>
<apply><xor/><ci>a</ci> <ci>b</ci></apply>
<apply><xor/><ci>c</ci> <ci>d</ci></apply>
</apply>
</annotation-xml>
</semantics>

Note that the above markup annotates the presentation markup as the first child element, with the content markup as part of the annotation-xml element. An equivalent form could be given that annotates the content markup as the first child element, with the presentation markup as part of the annotation-xml element.

### 5.4.2 Parallel Markup via Cross-References

To accommodate applications that must process sub-expressions of large objects, MathML supports cross-references between the branches of a semantics element to identify corresponding sub-structures. These cross-references are established by the use of the id and xref attributes within a semantics element. This application of the id and xref attributes within a semantics element should be viewed as best practice to enable a recipient to select arbitrary sub-expressions in each alternative branch of a semantics element. The id and xref attributes may be placed on MathML elements of any type.

The following example demonstrates cross-references for the Boolean arithmetic expression (a+b)(c+d).

<semantics>
<mrow id="E">
<mrow id="E.1">
<mo id="E.1.1">(</mo>
<mi id="E.1.2">a</mi>
<mo id="E.1.3">+</mo>
<mi id="E.1.4">b</mi>
<mo id="E.1.5">)</mo>
</mrow>
<mo id="E.2">&#x2062;<!--INVISIBLE TIMES--></mo>
<mrow id="E.3">
<mo id="E.3.1">(</mo>
<mi id="E.3.2">c</mi>
<mo id="E.3.3">+</mo>
<mi id="E.3.4">d</mi>
<mo id="E.3.5">)</mo>
</mrow>
</mrow>

<annotation-xml encoding="MathML-Content">
<apply xref="E">
<and xref="E.2"/>
<apply xref="E.1">
<xor xref="E.1.3"/><ci xref="E.1.2">a</ci><ci xref="E.1.4">b</ci>
</apply>
<apply xref="E.3">
<xor xref="E.3.3"/><ci xref="E.3.2">c</ci><ci xref="E.3.4">d</ci>
</apply>
</apply>
</annotation-xml>
</semantics>


An id attribute and associated xref attributes that appear within the same semantics element establish the cross-references between corresponding sub-expressions.

For parallel markup, all of the id attributes referenced by any xref attribute should be in the same branch of an enclosing semantics element. This constraint guarantees that the cross-references do not create unintentional cycles. This restriction does not exclude the use of id attributes within other branches of the enclosing semantics element. It does, however, exclude references to these other id attributes originating from the same semantics element.

There is no restriction on which branch of the semantics element may contain the destination id attributes. It is up to the application to determine which branch to use.

In general, there will not be a one-to-one correspondence between nodes in parallel branches. For example, a presentation tree may contain elements, such as parentheses, that have no correspondents in the content tree. It is therefore often useful to put the id attributes on the branch with the finest-grained node structure. Then all of the other branches will have xref attributes to some subset of the id attributes.

In absence of other criteria, the first branch of the semantics element is a sensible choice to contain the id attributes. Applications that add or remove annotations will then not have to re-assign these attributes as the annotations change.

In general, the use of id and xref attributes allows a full correspondence between sub-expressions to be given in text that is at most a constant factor larger than the original. The direction of the references should not be taken to imply that sub-expression selection is intended to be permitted only on one child of the semantics element. It is equally feasible to select a subtree in any branch and to recover the corresponding subtrees of the other branches.

Parallel markup with cross-references may be used in any XML-encoded branch of the semantic annotations, as shown by the following example where the Boolean expression of the previous section is annotated with OpenMath markup that includes cross-references:

<semantics>
<mrow id="EE">
<mrow id="EE.1">
<mo id="EE.1.1">(</mo>
<mi id="EE.1.2">a</mi>
<mo id="EE.1.3">+</mo>
<mi id="EE.1.4">b</mi>
<mo id="EE.1.5">)</mo>
</mrow>
<mo id="EE.2">&#x2062;<!--INVISIBLE TIMES--></mo>
<mrow id="EE.3">
<mo id="EE.3.1">(</mo>
<mi id="EE.3.2">c</mi>
<mo id="EE.3.3">+</mo>
<mi id="EE.3.4">d</mi>
<mo id="EE.3.5">)</mo>
</mrow>
</mrow>

<annotation-xml encoding="MathML-Content">
<apply xref="EE">
<and xref="EE.2"/>
<apply xref="EE.1">
<xor xref="EE.1.3"/><ci xref="EE.1.2">a</ci><ci xref="EE.1.4">b</ci>
</apply>
<apply xref="EE.3">
<xor xref="EE.3.3"/><ci xref="EE.3.2">c</ci><ci xref="EE.3.4">d</ci>
</apply>
</apply>
</annotation-xml>

<annotation-xml encoding="application/openmath+xml">
<om:OMA xmlns:om="http://www.openmath.org/OpenMath" href="EE">
<om:OMS name="and" cd="logic1" href="EE.2"/>

<om:OMA href="EE.1">
<om:OMS name="xor" cd="logic1" href="EE.1.3"/>
<om:OMV name="a" href="EE.1.2"/>
<om:OMV name="b" href="EE.1.4"/>
</om:OMA>

<om:OMA href="EE.3">
<om:OMS name="xor" cd="logic1" href="EE.3.3"/>
<om:OMV name="c" href="EE.3.2"/>
<om:OMV name="d" href="EE.3.4"/>
</om:OMA>
</om:OMA>
</annotation-xml>
</semantics>


Here OMA, OMS and OMV are elements defined in the OpenMath standard for representing application, symbol, and variable, respectively. The references from the OpenMath annotation are given by the href attributes.

Overview: Mathematical Markup Language (MathML) Version 3.0
Previous: 4 Content Markup
Next: 6 Interactions with the Host Environment