5 Mixing Markup Languages for Mathematical Expressions

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 T_EX 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.1 The semantics 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.2 The annotation element

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

5.2.3 The annotation-xml element

<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>

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

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.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.