3. Using the MathML tool

Figure 1. The MathML tool

Using the MathML tool does not require you to learn MathML presentation markup. However there are three points you must learn, understand and remember before using this tool:

Clicking on a tool in a palette always replaces the implicitly or explicitly selected element^[2] by the MathML template clicked upon.
Figure 2. Clicking on the "xⁿ Scripts" button in the MathML tool displays the Scripts palette
A section in a palette^[3] always starts with a completely empty template followed by one or more samples of this template.
These samples show you how, once filled, the empty template looks like. They are also useful by themselves: you may prefer clicking on them rather than the empty template and then, use the normal text selection to replace some of the text they contain.
As always with XMLmind XML Editor, you need to type text in the placeholders contained in the newly inserted math template. MathML has three main text containers:
mi
represents identifiers: variable names, function names, constants, etc.
mn
represents numbers.
mo
represents operators (e.g. "+"), fences (e.g. "("), separators (e.g. ",").
Most placeholders are mi elements^[4]. Make sure not to type a number inside an mi element, not to type a variable name in an mn element, etc. If you need to specify a number,
- click inside the mi placeholder and use the "Variables & Numbers" palette to replace it by a number,
- or, more simply, type the number then press Ctrl+Shift+SPACE to let XMLmind XML Editor replace the mi element by an mn element. More information about this facility in Section 3.1, “Parsing simple math expressions as MathML”.
Why all this trouble? After all, we are talking about presentation markup and not about content, semantic, markup. The reason is that using the right presentation element also means using the right typesetting rules.
Example 1: typing a single letter in an mi element renders this element using an italic font, while typing a longer identifier renders this mi element using an upright font.
Example 2: typing a curly brace "{" inside an mo element placed before a ``tall element'' (e.g. a fraction) will cause the curly brace to stretch vertically. Note that there is no way to force a curly brace to stretch vertically if you type this character in an mn or mi element.
Example 3: typing a "+" sign inside an mo element placed between two elements automatically adds the right amount of space before and after the "+" sign.

3.1. Parsing simple math expressions as MathML

XMLmind XML Editor can parse as MathML simple math expressions typed inside mi and mn elements^[5]. For simple equations, using this facility is much more productive than using the MathML tool.

For example, let's suppose you want to insert the famous equation in your document.

Use the "Add MathML equation" button found in the DocBook toolbar and select inlineequation.
The newly inserted element mainly contains an empty mi placeholder. Type "E=m*c^2" in this placeholder.
Press Ctrl+Shift+SPACE to invoke menu item DocBook → Parse Text As MathML. Doing this displays a popup:
Click in the popup (or press Down then Enter, like for any popup menu) in order to accept what's suggested. Et voilà, your mi element incorrectly containing "E=m*c^2" is replaced by proper MathML markup.

Of course, as we'll see it in Section 3.2, “Sample editing session”, this facility is also very handy when used in conjunction with MathML tool.

Supported expressions

The simple math expressions which can be successfully parsed by Parse Text As MathML can be quickly described as follows:

Numbers are parsed as mn.
Identifiers starting with a letter, optionally followed by letters and/or digits are parsed as mi. However, the following special, case-sensitive, identifiers are translated to a single math character:
- Lower-case Greek letters: alpha, beta, gamma, delta, epsilon, zeta, eta, theta, iota, kappa, lambda, mu, nu, xi, omicron, pi, rho, sigma, tau, upsilon, phi, chi, psi, omega.
- Upper-case Greek letters: Alpha, Beta, Gamma, Delta, Epsilon, Zeta, Eta, Theta, Iota, Kappa, Lambda, Mu, Nu, Xi, Omicron, Pi, Rho, Sigma, Tau, Upsilon, Phi, Chi, Psi, Omega.
- Miscellaneous symbols: NN (), ZZ (), QQ (), RR (), CC (), emptyset (), infty ().
The only operators which are supported are: =, != (not equal), <, <=, >, >=, + (unary or binary), - (unary or binary), * (translated to ⁢), / (means "division", not "fraction"), ^ (exponent) and _ (here underscore means "indice"); all with their usual precedence.
You can use parentheses for grouping. However if you do so, these parentheses will show up as mo elements in the MathML. If you do not want to see the parentheses in the MathML, use {} instead of ().
Functions such as "f(x, y, z)" are also supported.
Whitespace is ignored.

Examples:

Text	MathML
`2*x <= -y/0.5 <= z^i <= v_j <= w^i_j`
`z = x^(2i) + y^{2i}`
`cos(pi/2)`
`sin(-x) = -sin(x)`

3.2. Sample editing session


	First write down on a paper the equation you want to author using the MathML tool. By constantly referring to your paper while using the MathML tool, you'll clearly see all the top to bottom steps needed to perform your task.

Suppose that you need to insert the following equation in a DocBook 5 document: .

Use the "Add MathML equation" button found in the DocBook toolbar and select inlineequation.
Click inside the newly inserted element and select the Equations palette in the MathML tool. Click on the Equation template:
This gives you:
Type "F" in the left placeholder:
Click in the right placeholder then click on the first template of the "Fractions" palette.
This gives you:
Type "G*m_1*m_2" in the top placeholder.
Press Ctrl+Shift+SPACE to invoke menu item DocBook → Parse Text As MathML.
Press Down then Enter to accept what's suggested in the popup.
Type "d^2" in the bottom placeholder.
Press Ctrl+Shift+SPACE to invoke menu item DocBook → Parse Text As MathML.
Press Down then Enter to accept what's suggested in the popup.

3.3. Modifying existing equations

Let's suppose you have entered the following equation: . After doing that, you realize that the correct equation is in fact: . One way to correct the equation is to:

to explicitly select ,
press Ctrl+C to copy the fraction to the clipboard,
click the template from the "Operations & Functions" palette to replace the selection,
explicitly select the left mi placeholder,
press Ctrl+V to paste the fraction,
Finally, replace the right mi placeholder by an mn element containing 1.

Fortunately there is a much quicker way to do this: using the text selection rather than the implicit or explicit element selection.

When you use the text selection:

In fact, you select the MathML element which is the common ancestor of all the elements involved in the text selection. Note that this text selection is not used per se, therefore there is no need to be precise to the character.
The MathML tool wraps the selected MathML element in the template clicked upon, rather than replace the selection by the template clicked upon. That is, you'll not loose what you have already typed.

Therefore the most efficient way to correct the above equation is to proceed as follows:

select "2 x 3" normally, by dragging your mouse over this text,
click the template in order to wrap the fraction (which is “common ancestor of the text selection”),
Finally, replace the right mi placeholder by an mn element containing 1.

This worked fine, but what if the correct equation was ?

Well, if you select the text by dragging your mouse from the right to the left, the MathML tool will use the last placeholder of the template clicked upon. Normally (mouse dragged from the left to the right), the MathML tool uses the first placeholder of the template clicked upon.

Wrapping the implicitly or explicitly selected element

In some cases, you'll find that the text selection does not allow you to select the MathML element you want. For example, let's suppose you have entered and the correct equation is . There is no way to select the square root using the text selection.

When this is the case, you'll have to explicitly select the MathML element (for example, by clicking on m:msqrt in the Node Path Bar) you want to wrap and then Ctrl+click ^[6] or Shift+click on a template of a palette.

Ctrl+click: Wraps implicitly or explicitly selected element in the template clicked upon. Within this template, the first placeholder is substituted with the selected element.
Shift+click: Wraps implicitly or explicitly selected element in the template clicked upon. Within this template, the last placeholder is substituted with the selected element.

3.4. Useful tips

When you don't understand a template, move your mouse over it and you'll see a useful ``balloon help''.
Figure 3. Tool tip for the ``Invisible Times'' binary operation
The editing operations performed using a MathML palette are repeatable. That is, suffice to click elsewhere and press Ctrl+A (Cmd+A on the mac) to repeat the same replacement operation.
The editing operations performed using a MathML palette can be recorded using the macro recorder (Tools → Record Macro → Start).
The MathML tool has a "Text & Space" palette. Use it if you want to insert text which is not mi, mn or mo.
If you want to edit an mtable, for example add a column to a matrix or add an equation to a set of equations, use the table editing commands found in the DocBook menu (e.g. DocBook → Column → Insert Before) and in the MathML menu (e.g. MathML → Row → Copy).
If you want to insert special characters, use the Characters tool or use the "Insert MathML Character by Name" found in the DocBook menu and in the MathML menu.
It is fairly easy to tweak the look of an equation created using the MathML tool. For this, you'll generally insert mspace elements (Edit → Insert After), wrap one or more elements into a mphantom or mpadded element (Edit → Wrap) or specify attribute values using the Attributes tool. Of course, doing this requires you to learn MathML presentation markup.

^[2]The explicitly selected nodes have a red box drawn around them. In absence of explicitly selected nodes, the implicitly selected element is the element having a text node child containing the caret.

^[3]In the above screenshot, the first section of the Scripts palette is Subscript, the second one is Superscript, etc

^[4]The samples found after the empty template give you a hint on the nature of the placeholders.

^[5]Parse Text As MathML is disabled (grayed) when the caret is found in the other elements which may contain text, namely: mo, mtext and ms.

^[6]Or Cmd+click on the Mac.


2. How to add equations to your XML documents		4. MathML preferences