MathML

MathML is a W3C markup language for mathematics http://www.w3.org/Math/. The DocBook XSL stylesheets cannot format MathML content, but it will pass the markup through so that a downstream processor can format it. For XSL-FO output, the Antenna House XSL Formatter with the optional MathML module can handle MathML markup.

For HTML output, the W3C describes in their document Putting Mathematics on the Web with MathML how browsers can handle MathML. For example, the document describes how the W3C makes available an XSL stylesheet that you can attach to an XHTML file that will render MathML markup that is embedded in the XHTML file. This method assumes a browser can apply an XSL stylesheet, and not all do so. Browsers are beginning to add native support for MathML. Mozilla Firefox can format MathML embedded in XHTML files. You might need to use a .xhtml filename extension for the output if you are browsing files locally.

Because not all browsers and XSL-FO processors support MathML yet, some people choose to convert their MathML to graphics format for publication. There are several commercial MathML editors that can generate SVG and other graphics formats. The open source SVGMath software, written in Python, can convert a subset of MathML to SVG. You can download it from http://www.grigoriev.ru/svgmath/.

Including MathML in DocBook source files can be tricky because the element names are not in the DocBook DTD. Also, MathML has its own set of character entities such as ⁢ that are defined in the MathML DTD that are not in the DocBook DTD. You can fix these problems by including the MathML DTD into your DocBook DTD. You can use a DTD customization layer for the DocBook DTD to do this, or, as the following example shows, you can do it in the DOCTYPE declaration of each document. Which method you use depends on how much math you use. do not try to do both.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
<!ENTITY % MATHML.prefixed "INCLUDE">
<!ENTITY % MATHML.prefix "mml">
<!ENTITY % equation.content "(alt?, (graphic+|mediaobject+|mml:math))">
<!ENTITY % inlineequation.content 
                "(alt?, (inlinegraphic+|inlinemediaobject+|mml:math))">
<!ENTITY % mathml PUBLIC "-//W3C//DTD MathML 2.0//EN"
        "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd">
%mathml;
]>
<book>
...

The above example also shows how you can add MathML elements to the model for the DocBook equation and inlineequation elements by enhancing the equation.content and inlineequation.content parameter entities, respectively, in the DocBook DTD. It copies the parameter entity declarations from the DocBook DTD and extends them. Then you can put your math in DocBook documents like the following:

<equation>
<title>My MathML example</title>
<mml:math>
  <mml:mrow>
    <mml:mo>&sum;</mml:mo>
    <mml:mn>4</mml:mn>
    <mml:mo>+</mml:mo>
    <mml:mi>x</mml:mi>
  </mml:mrow>
</mml:math>
</equation>

It is important to keep the MathML element names in a separate namespace from the DocBook elements or confusion will reign. When you process a file like this to FO or XHTML, the MathML output elements will still have a namespace prefix on them. If you process to HTML, however, they will not have a namespace prefix. Browsers that do not recognize the MathML elements will ignore the tags and show the characters, but as an unformatted line.

You can also put MathML markup in a separate file. This can help reduce clutter in your DocBook document, since some MathML can be quite long. If you want to be able to validate it, you need to include the MathML DOCTYPE declaration in the separate file:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE mml:math PUBLIC "-//W3C//DTD MathML 2.0//EN"
        "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd" [
<!ENTITY % MATHML.prefixed "INCLUDE">
<!ENTITY % MATHML.prefix "mml">
]>
<mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" id="mymath">
  <mml:mrow>
  ...
  </mml:mrow>
</mml:math>

However, once you add a DOCTYPE declaration, you can no longer use a system entity reference to pull in the math content into your DocBook document. Instead, use XInclude, which is described in the section “Using XInclude”. You put an XInclude element inside your DocBook document where you want the math to appear:

<equation>
  <xi:include href="math.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</equation>

You'll still need to include the MathML DTD in your DocBook DTD or DOCTYPE declaration, or the document will not validate after the content is pulled in.