<mathmlref>

The <mathmlref> element references a non-DITA XML document that contains MathML markup.

Usage information

The <mathmlref> element enables the use MathML markup by reference. The reference must be to a MathML <math> element. The reference can be one of the following:

  • A URI that addresses an XML document. The XML document has a MathML <math> element as the root element.
  • A URI that addresses an XML document and contains a fragment identifier that is the XML ID of a <math> element within the document.

The reference can be direct, using the @href attribute, or indirect, using the @keyref attribute. For indirect referencing, only the key name should be specified. The ID of the <math> element must be specified as part of the value for the @href attribute on the key definition.

For example, to refer to the <math> element with the @id of math-fragment-02 within a larger document using a key reference, you would define the key in the following way:

<keydef keys="math-fragment-0002" href="mathml/mathml-library.xml#math-fragment-02"/>

You reference this key by using just the key name:

<mathref keyref="math-fragment-0002"/>

Processing expectations

Processors SHOULD process the MathML as though the <m:math> element occurs directly in the content of the containing <mathml> element.

Specialization hierarchy

The <mathmlref> element is specialized from <include>. It is defined in the MathML domain module.

Attributes

The following attributes are available on this element: inclusion attributes, universal attributes, @format, @href, @keyref, and @scope.

For this element:
  • The @format attribute has a default value of mml.
  • The @href attribute is a reference to a MathML document or <mathml> element. If the <mathml> element is the root element of the referenced resource, then no fragment identifier is required. Otherwise, a fragment identifier must be specified, where the fragment identifier is the XML ID of the <mathml> element.
  • The @parse attribute has a default value of xml.

The following attributes are available on this element: universal attributes and the attributes defined below.

@encoding (inclusion attributes)
Specifies the character encoding to use when translating the character data from the referenced content. The value should be a valid encoding name. If not specified, processors may make attempts to automatically determine the correct encoding, for example using HTTP headers, through analysis of the binary structure of the referenced data, or the <?xml?> processing instruction when including XML as text. The resource should be treated as UTF-8 if no other encoding information can be determined.

When parse="xml", standard XML parsing rules apply for the detection of character encoding. The necessity and uses of @encoding for non-standard values of @parse are implementation-dependent.

@format (link-relationship attributes)
Specifies the format of the resource that is referenced. See STUB CONTENT for detailed information on supported values and processing implications.
The @format attribute has a default value of mml.
@href (link-relationship attributes)
Specifies a reference to a resource. See STUB CONTENT for detailed information on supported values and processing implications.
The @href attribute is a reference to a MathML document or <mathml> element. If the <mathml> element is the root element of the referenced resource, then no fragment identifier is required. Otherwise, a fragment identifier must be specified, where the fragment identifier is the XML ID of the <mathml> element.
@keyref
Specifies a key name that acts as a redirectable reference based on a key definition within a map. See STUB CONTENT for information on using this attribute.

For HDITA, the equivalent of @keyref is @data-keyref

@parse (inclusion attributes)
Specifies the processing expectations for the referenced resource. Processors must support the following values:
text

The contents should be treated as plain text. Reserved XML characters should be displayed, and not interpreted as XML markup.

xml

The contents of the referenced resource should be treated as an XML document, and the referenced element should be inserted at the location of the <include> element. If a fragment identifier is included in the address of the content, processors must select the element with the specified ID. If no fragment identifier is included, the root element of the referenced XML document is selected. Any grammar processing should be performed during resolution, such that default attribute values are explicitly populated. Prolog content must be discarded.

It is an error to use parse="xml" anywhere other than within <foreign> or a specialization thereof.

Processors may support other values for the @parse attribute with proprietary processing semantics. Processors should issue warnings and use <fallback> when they encounter unsupported @parse values. Non-standard @parse instructions should be expressed as URIs.

Note (non-normative):
Proprietary @parse values will likely limit the portability and interoperability of DITA content, so should be used with care.
The @parse attribute has a default value of xml.
@scope (link-relationship attributes)
Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See STUB CONTENT for detailed information on supported values and processing implications.

Examples

This section is non-normative.

This section contains examples of how the <mathmlref> element can be used.

Example 1. Referencing a MathML <math> root element

The following code sample shows how a <mathmlref> element can be used to reference a MathML <math> element that is the root element of its containing document:

<equation-block>
  <mathml>
    <mathmlref href="../mathml-source/mathml-root-mathml.mml"/>
  </mathml>
</equation-block>

The mathml-root-mathml.mml file contains the following content. Note that the <math> element sets the MathML namespace as the default namespace, so there are no namespace prefixes on the MathML markup.

<?xml version="1.0" encoding="UTF-8"?>
<math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink">
  <mstyle displaystyle="false" scriptlevel="0">
    <mrow>
      <mfrac>
        <mrow>
          <mi mathcolor="gray">sin</mi>
          <mo rspace="verythinmathspace"/>                    
          <mi>θ</mi>
        </mrow>
        <mi>π</mi>
      </mfrac>
    </mrow>
  </mstyle>
</math>
Example 2. Referencing a specific <math> element within a document

The following code sample shows how a <mathmlref> element can reference a specific <math> element in a containing XML file:

<equation-block>
  <mathml>
    <mathmlref href="../mathml-source/mathml-equation-library.xml#mathfrag-02"/>
  </mathml>
</equation-block>

The mathml-equation-library.xml file contains the following content:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <part>
    <math id="timeinday" xmlns="http://www.w3.org/1998/Math/MathML">
      <mi>x</mi>
    </math>
    <math id="mathfrag-02" xmlns="http://www.w3.org/1998/Math/MathML">
      <math>
        <mrow>
          <mi>y</mi>
          <mo>=</mo>
          <mn>5</mn>
          <mi>x</mi>
          <mo>+</mo>
          <mn>2</mn>
        </mrow>
      </math>
    </math>
  </part>
  <!-- ... -->
</root>