7 MathML interactions with the Wide World

7.1.1 Recognizing MathML in an XML Model

Within an XML document supporting namespaces (TODO: cite xmlns and xml specs), the preferred method to recognize MathML markup is by the identification of the math element in the appropriate namespace, i.e. that of URI http://www.w3.org/1998/Math/MathML.

This is the recommended method to embed MathML within [XHTML] documents. Some user-agents' setup may require supplementary information to be available, such as the MicroSoft behaviour specification (TODO: quote) used in the MathType browser-extension (TODO:quote).

Markup-language specifications that wish to embed MathML may provide special conditions independent of this recommendation. The conditions should be equivalent and the elements' local-names should remain the same.

7.1.2 Resource Types for MathML Documents

Although rendering MathML expressions often occurs in place in a Web browser, other MathML processing functions take place more naturally in other applications. Particularly common tasks include opening a MathML expression in an equation editor or computer algebra system. It is important therefore to specify the encoding-names that MathML fragments should be called with:

MIME types [RFC2045], [RFC2046] offer a strategy that can be used in current user agents to invoke a MathML processor. This is primarily useful when referencing separate files containing MathML markup from an embed or object element, or within a desktop environment. (TODO: check that this still applies)

[RFC3023] assigns MathML the MIME type application/mathml+xml which is the official mime-type. The W3C Math Working Group recommends the standard file extension .mml within a registry associating file formats to file-extension. In MathML 1.0, text/mathml was given as the suggested MIME type. This has been superceded by RFC3023. In the next section, alternate encoding names are provided for the purposes of desktop transfers.

7.2.1 Basic Flavors' Names and Contents

MathML contains two distinct vocabularies: one for encoding mathematical semantics called Chapter 4 Content Markup and one for encoding visual presentation called Chapter 3 Presentation Markup. Some MathML-aware applications import and export only one of these vocabularies, while other may be capable of producing and consuming both. Consequently, we propose three distinct MathML flavors:

Note that Content MathML, Presentation MathML and MathML are the exact strings that should be used to describe the flavors described above. On operating systems that allow such, applications should register such names (e.g. Windows' RegisterClipboardFormat).

When transferring MathML, for example when placing it within a clipboard, an application MUST ensure the content is a well-formed XML instance of a MathML schema. Specifically:

1. The instance MUST begin with a XML processing instruction, e.g. <?xml version="1.0">

2. The instance MUST contain exactly one root math element.

3. Since MathML is frequently embedded within other XML document types, the instance MUST declare the MathML namespace on the root math element. In addition, the instance SHOULD use a schemaLocation attribute on the math element to indicate the location of MathML schema documents against which the instance is valid. Note that the presence of the schemaLocation attribute does not require a consumer of the MathML instance to obtain or use the cited schema documents.

4. The instance MUST use numeric character references (e.g. &#x03b1;) rather than character entity names (e.g. &alpha;) for greater interoperability.

5. The character encoding for the instance MUST be either specified in the XML header, UTF-16, or UTF-8. UTF-16-encoded data MUST begin with a byte-order mark (BOM). If no BOM or encoding is given, the character encoding will be assumed to be UTF-8.

7.2.2 Recommended Behaviours when Transferring

Applications that transfer MathML SHOULD adhere to the following conventions:

1. Applications that have pure presentation markup and/or pure content markup versions of an expression SHOULD offer as many of these two flavors as are available.

2. When both presentation and content are exported, recipients should consider it equivalent to a single MathML instance in which presentation and content are combined at the top level using MathML's semantics element (see Section 5.5.1 Top-level Parallel Markup). (TODO: issue: in DnD you can't read several, at least in java) The order between flavors determines whether presentation wraps content, or vice-versa. Usually, Presentation MathML should be offered first so that it wraps the Content MathML.

3. When an application has a mixed presentation and content version in addition to pure presentation and/or content versions, it should export the mixed versionafter the pure presentation and/or content markup versions, and mark it as the generic MathML flavor.

4. When an application cannot produce pure presentation and/or content markup versions, or cannot determine whether MathML data is pure presentation or content markup (e.g. data being passed through from a third application,) it should export only one version marked as the generic MathML flavor.

5. An application that only has pure presentation and/or content markup versions of an expression available SHOULD NOT export a second copy of the data marked as the generic MathML flavor.

6. When an application exports a MathML fragment whose root element is a semantics element, it SHOULD offer, after the flavors above, a flavor for each annotation or annotation-xml element: the flavor should be given by the encoding attribute value, and the content should be the child text in UTF-8 (if the annotation element contains only textual data), a valid XML fragment (if the annotation-xml element contains children), or the data resulting of requesting the URL given by the href attribute.

7. As a final fallback applications SHOULD export a version of the data in plain-text flavor (such as CF_UNICODETEXT, UnicodeText, NSStringPboardType, text/plain, ...). When an application has multiple versions of an expression available, it may choose the version to export as text at its discretion. Since some older MathML-aware programs expect MathML instances transferred as text to begin with a math element, the text version should generally omit the XML processing instruction, DOCTYPE declaration and other XML prolog material before the math element. Similarly, the BOM should be omitted for Unicode text encoded as UTF-16. Note, the Unicode text version of the data should always be the last flavor exported, following the principle that exported flavors should be ordered with the most specific flavor first and the least specific flavor last.

7.2.3 Discussion

For purposes of determining whether a MathML instance is pure content markup or pure presentation markup, the math element and the semantics, annotation and annotation-xml elements should be regarded as belonging to both the presentation and content markup vocabularies. This is obvious for the root math element which is required for all MathML expressions. However, the semantics element and its child annotation elements comprise an arbitrary annotation mechanism within MathML, and are not tied to either presentation or content markup. Consequently, applications consuming MathML should always process these four elements even if the application only implements one of the two vocabularies.

It is worth noting that the above recommendations allow agents producing MathML to provide binary data for the clipboard, for example as an image or an application-specific format. The sole method to do so is to reference the binary data by the href attribute since XML child-text does not allow arbitrary byte-streams.

While the above recommendations are intended to improve interoperability between MathML-aware applications utilizing the transfer flavors, it should be noted that they do not guarantee interoperablility. For example, references to external resources (e.g. stylesheets, etc.) in MathML data can also cause interoperability problems if the consumer of the data is unable to locate them, just as can happen when cutting and pasting HTML or many other data types. Applications that make use of references to external resources are encouraged to make users aware of potential problems and provide alternate ways for obtaining the referenced resources. In general, consumers of MathML data containing references they cannot resolve or do not understand should ignore them.

7.2.4 Examples

<?xml version="1.0"?>
<math xmlns="http://www.w3.org/1998/Math/MathML">...</math>

<math xmlns="http://www.w3.org/1998/Math/MathML">...</math>

<?xml version="1.0"?>
<math xmlns="http://www.w3.org/1998/Math/MathML">...</math>

<math xmlns="http://www.w3.org/1998/Math/MathML">...</math>

<?xml version="1.0"?>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:mrow>
  ...
  <mml:mrow>
</mml:math>

<?xml version="1.0"?>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:apply>
  ...
  <mml:apply>
</mml:math>

<?xml version="1.0"?>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:mrow>
    <mml:apply> ... content markup within presentation markup ... </mml:apply>
    ...
  </mml:mrow>
</mml:math> 

{x \over x-1}

<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:mrow>
  ...
  <mml:mrow>
</mml:math>

<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML">
  <mml:semantics>
    <mml:mrow>...</mml:mrow>
    <mml:annotation-xml encoding="MathML content">...</mml:annotation-xml>
    <mml:annotation encoding="TeX">{1 \over x}</mml:annotation>
    <mml:annotation encoding="image/png" href="formula3848.png"/>
  </mml:semantics>
</mml:math>

<?xml version="1.0"?>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:mrow>
  ...
  <mml:mrow>
</mml:math>

<?xml version="1.0"?>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:apply>
  ...
  <mml:apply>
</mml:math>

<?xml version="1.0"?>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:mrow>
    <mml:apply> ... content markup within presentation markup ... </mml:apply>
    ...
  </mml:mrow>
</mml:math> 

{x \over x-1}

<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/Math/XMLSchema/mathml2/mathml2.xsd">
  <mml:mrow>
  ...
  <mml:mrow>
</mml:math>

7.3.1 Mixing MathML and HTML

In order to fully integrate MathML into XHTML, it should be possible not only to embed MathML in XHTML, as described in Section 7.1.1 Recognizing MathML in an XML Model, but also to embed XHTML in MathML. However, the problem of supporting XHTML in MathML presents many difficulties. Therefore, at present, the MathML specification does not permit any XHTML elements within a MathML expression, although this may be subject to change in a future revision of MathML.

In most cases, XHTML elements (headings, paragraphs, lists, etc.) either do not apply in mathematical contexts, or MathML already provides equivalent or better functionality specifically tailored to mathematical content (tables, mathematics style changes, etc.). However, there are two notable exceptions, the XHTML anchor and image elements. For this functionality, MathML relies on the general XML linking and graphics mechanisms being developed by other W3C Activities.

7.3.2 Linking

MathML has no element that corresponds to the XHTML anchor element a. In XHTML, anchors are used both to make links, and to provide locations to which a link can be made. MathML, as an XML application, defines links by the use of the mechanism described in the W3C Recommendation "XML Linking Language" [XLink].

A MathML element is designated as a link by the presence of the attribute xlink:href. To use the attribute xlink:href, it is also necessary to declare the appropriate namespace. Thus, a typical MathML link might look like:

<mrow xmlns:xlink="http://www.w3.org/1999/xlink"
      xlink:href="sample.xml">
  ...
</mrow>

MathML designates that almost all elements can be used as XML linking elements. The only elements that cannot serve as linking elements are those which exist primarily to disambiguate other MathML constructs and in general do not correspond to any part of a typical visual rendering. The full list of exceptional elements that cannot be used as linking elements is given in the table below.

Note that the XML Linking [XLink] and XML Pointer Language [XPointer] specifications also define how to link into a MathML expressions. Be aware, however, that such links may or may not be properly interpreted in current software.

7.3.3 Images

The img element has no MathML equivalent. The decision to omit a general mechanism for image inclusion from MathML was based on several factors. However, the main reason for not providing an image facility is that MathML takes great pains to make the notational structure and mathematical content it encodes easily available to processors, whereas information contained in images is only available to a human reader looking at a visual representation. Thus, for example, in the MathML paradigm, it would be preferable to introduce new glyphs via the mglyph element which at a minimum identifies them as glyphs, rather than simply including them as images.

7.3.4 MathML and Graphical Markup

Apart from the introduction of new glyphs, many of the situations where one might be inclined to use an image amount to displaying labeled diagrams. For example, knot diagrams, Venn diagrams, Dynkin diagrams, Feynman diagrams and commutative diagrams all fall into this category. As such, their content would be better encoded via some combination of structured graphics and MathML markup. However, at the time of this writing, it is beyond the scope of the W3C Math Activity to define a markup language to encode such a general concept as "labeled diagrams." (See http://www.w3.org/Math for current W3C activity in mathematics and http://www.w3.org/Graphics for the W3C graphics activity.)

One mechanism for embedding additional graphical content is via the semantics element, as in the following example:

<semantics>
  <apply>
    <intersect/>
    <ci>A</ci>
    <ci>B</ci>
  </apply>
  <annotation-xml encoding="SVG1.1">
    <svg xmlns="http://www.w3.org/2000/svg"  viewBox="0 0 290 180">
      <clipPath id="a">
      <circle cy="90" cx="100" r="60"/>
      </clipPath>
      <circle fill="#AAAAAA" cy="90" cx="190"
              r="60" style="clip-path:url(#a)"/>
      <circle stroke="black" fill="none" cy="90" cx="100" r="60"/>
      <circle stroke="black" fill="none" cy="90" cx="190" r="60"/>
    </svg>
  </annotation-xml>
  <annotation-xml encoding="application/xhtml+xml">
    <img xmlns="http://www.w3.org/1999/xhtml" src="intersect.gif" alt="A intersect B"/>
  </annotation-xml>
</semantics>

Here, the annotation-xml elements are used to indicate alternative representations of the Content MathML depiction of the intersection of two sets. The first one is in the "Scalable Vector Graphics" format [SVG1.1] (see [XHTML-MathML-SVG] for the definition of an XHTML profile integrating MathML and SVG), the second one uses the XHTML img element embedded as an XHTML fragment. In this situation, a MathML processor can use any of these representations for display, perhaps producing a graphical format such as the image below.

Note that the semantics representation of this example is given in the Content MathML markup, as the first child of the semantics element. In this regard, it is the representation most analogous to the alt attribute of the img element in XHTML, and would likely be the best choice for non-visual rendering.