Editing mathematics in Amaya

Amaya

## Editing mathematics

Amaya proposes a Wysiwyg interface where MathML mathematical expressions are handled as structured components, in the same way as (X)HTML elements. Therefore, you can manipulate math expressions in the same way you manipulate other parts of (X)HTML documents. All editing commands provided by Amaya for handling text are also available for math, but there are some additional controls for entering mathematical constructs. Note that the different browsers don't behave in the same way with MathML: see the browsers compatibility section for more informations.

### Creating mathematical formulae

#### New formula

Generally, mathematical formulae are not alone but included in a document with text, table, images... to do this, you have to create a XHTML document. Otherwise, you can create a MathML document (mml) for instance to use the formulae in other software tools. To do so, use command File / New / New formula or type `Ctrl-n Ctrl-m`.

To create a new mathematical expression in a document, move the insertion point to the position where you want to insert an expression, and then click the Math button (the first) from the Math palette, or choose Insert a formula from the Insert/Math submenu. Here are examples with a formula inserted directly in the XHTML document or inside an SVG image :

Γ ⁡ ( x ) = ∫ 0 + ∞ t x − 1 ⅇ − t ⅆ t

Γ ⁡ ( x ) = ∫ 0 + ∞ t x − 1 ⅇ − t ⅆ t

#### The Math submenu

The Insert/Math submenu includes presentation MathML elements.

- The first items create new elements of a given type in a mathematical expression : Plain text (mtext), Identifier (mi), Number (mn), Operator (mo). These commands can also change the type of a single element or a sequence of elements.
- The next command, Space (mspace), allows you to add space in a formula. To change its size, you have to modify its `width` attribute. See spacing.
- The next item, Character (&xxx;), enables you to enter a character that is not available on the keyboard. It displays a dialog where you have to enter the character name (for instance `alpha` for the Greek character α).
  Note that you can also use the Special characters tool (command Views / Show/hide toolbars / Special characters).
- The two next commands InvisibleTimes and ApplyFunction are used to enter the corresponding invisible characters. See the special characters section.

Following entries of the Insert/Math submenu enable you to create new constructs within a formula. If the insertion point is not in a formula, Amaya first creates a `math` element to accept the new construct. The available constructs are:

- Root with index, `mroot` in MathML: x + 1 3
- Square root, `msqrt`: x + 1
- Enclose, `menclose`: 1234
- Fraction, `mfrac`: 1 x + 1
- Expression with subscript and superscript, `msubsup`: x i + 1 n or ∫ 0 ∞
- Expression with a subscript, `msub`: x i
- Expression with a superscript, `msup`: x n
- Expression with under- and overscript, `munderover`: ∑ i = 1 n
- Expression with underscript, `munder`: x -
- Expression with overscript, `mover`: x → maps to y
- Expression within parentheses, `mrow`: ( a + b )
- Expression with prescripts and tensor indices, `mmultiscripts`: X i j k l
- Finally, the New matrice (mtable) entry allows you to create and edit MathML tables: a b c d

  You must then choose the number of lines and columns in the new table through a dialog that pops up. You can manipulate it like a HTML table through the commands available from the Tools/Edit table submenu.

#### The Math palette

Clicking on a button in the Math palette inserts the mathematical construct represented on its icon. Parts in black are really inserted, parts in red represent placeholder, parts in blue are asked through to a specific dialog. Green parts are simply additional information that are not inserted.

The palette contains all constructs described in Content MathML (but the produced code is an equivalent in Presentation MathML, see the known issues section) and even more. You can also save your own constructs in a mml file in order to use them latter. The 6 tabs are :

1. - Various constructs
     - new formula
     - `mrow`: used to group elements. See the section about the row construct
     - `mphantom`: used to hide a piece of formula, can be used for alignment. The hidden parts can be viewed if you select the formula :

       { − 5 x + 3 y − 0 z = − 11 − 2 x + 0 y − 7 z = − 11 − 3 x + 2 y − 6 z = − 7 0

     - parenthesis: ( x )
     - interval: The open, separator and close symbols are asked. [ a ; b ]
     - fence: Same, but the number of element is asked. [ 1 , c , Y , ⅇ , ∏ }
     - `mtable`: a b c d
     - `menclose`: a or b
     - selector: The number of coordonnates is asked. a i ⁣ j
     - piecewise or vertical brace : ∣ x ∣ = { x if x ≥ 0 − x otherwise
   - Presentation MathML constructs: msup, msub, msubsup, mover, munder, munderover, multiscripts.
   - Sets of numbers: naturals, integers, rationals, reals, complexes, quaternions, primes.
   - Accents and underscript
2. - relations of equivalence and orders
     - equalities, approx, congru, isomorphic
     - inequalities
     - inf, sup, max and min
   - logic
     - True and False
     - equivalence
     - universal and existential quantifiers
     - not, and, or, xor, implies, equivalent to
3. - set theory
     - set/list built by extension/separation, nuple
     - element, subset
     - empty set, powerset
     - complement, difference, symetric difference
     - intersection, union, cartesian product
     - cardinal, omega, aleph, diagonal intersection
   - functions and maps
     - lambda construct
     - map definition, arrows
     - domain, image (range), codomain
     - identity, compose, inverse
4. - arithmetic
     - sum, prod
     - factorial, combination, cardinal
     - factor of
     - lcm, gcd
     - reminder, quotient
   - operations
     - elementary operations: plus, minus, times, divide, fraction
     - power, root
     - floor, ceiling
   - complexes
     - abs, arg, conjugate
     - cartesian, polar
     - real and imaginary part
   - constants: ⅇ , ⅈ , π , γ , NaN (not a number)
5. - analysis
     - differential, partial differential
     - integrals: simple/double/triple, normal/contour, msub/msupsub
     - equivalence
     - limit, tends to
     - supminus ( 1 - ) or supplus ( 0 + )
     - infinity
     - o and O
   - linear algebra
     - direct sum
     - vectorrow, vectorcolumn, matrix
     - transpose, determinant
     - curl, div, grad, laplacian
     - vector product, scalar product, outerproduct
     - orthogonal, parallel, orthogonal complement, norm
   - statistic : mean, sdev, variance, median, mode, moment
6. classical elementary functions (trigonometric, inverse...)

#### Entering Math constructs using the keyboard

You are not required to use the Math submenu or the Math palette to create and edit mathematical expressions. You can enter mathematical constructs directly from the keyboard because each entry of the Math submenu has a keyboard equivalent. These shortcuts are listed on the menu. See the list of current Linux, Mac OS X, and Windows shortcuts.

You can also use the keyboard arrow keys to move the insertion point from one math construct to another. The right and left arrows move the insertion point according to the structure of the mathematical expression. For example, in a fraction when the insertion point is at the end of a numerator, the right arrow key moves the insertion point to the beginning of the denominator. Moreover if you use the right arrow to a construct that is not already completed, the insertion point is directly moved to the nearest placeholder.

### Advanced editing features

#### Entering Math characters

When you type a character string in a MathML element, Amaya parses the string and automatically generates the elements `mo` (operator), `mn` (number), `mi` (identifier), and `mtext`.

For example, to enter the formula x = 2 a + b

1. If you are not in a mathematical expression, choose Insert a formula from the Insert/Math submenu.
2. Type this sequence of 6 characters: `x=2a+b`

Use the Structure or Source view to display the following structure generated by Amaya:

`<mi>x</mi><mo>=</mo><mn>2</mn><mi>a</mi><mo>+</mo><mi>b</mi>`

If the result is not exactly what you want, select the characters that were misinterpreted and change their type with one of the commands such as Plain text (mtext), Identifier (mi), Number (mn), Operator (mo) or Space (mspace).

#### The row construct

The `row` construct from the palette is the equivalent of the braces in LaTeX: it allows you to give informations about how the different part of a formula are grouped together. It does not appear on the screen but have an indirect effect on the rendering.

For instance, when entering brackets as in the following expression:

f ⁡ ( x ) = 1 x

typing the sequence `f(x)= ...` would lead to:

f ⁡ ( x ) = 1 x

Here, the `(x)` must be contained in a `mrow` element. You can correct the problem by selecting this part of the formula and then clicking on the row construct. You can also directly get the expected `mrow` if you choose Parentheses from the Insert/Math submenu or select the button in the Math palette.

#### Spacing

Amaya takes care of spacing within math expressions, but in some cases you may need to add some additional space. Move the cursor to the position where you want to insert space and choose Space (mspace) from the Insert/Math submenu. This creates a default horizontal space. You can then change its `width` attribute to adjust its size or you can add other attributes (`height`, `depth`, `linebreak`) to change vertical spacing. Refer to the MathML specification for more details.

#### Special characters

You can use the Character command from the Insert/Math submenu to enter mathematical characters and symbols that are not available on the keyboard. Type in the name of the character, as defined in the MathML specification. You may choose to type the Unicode value of the character instead. For entering this value in decimal, start with a '#'. For entering the value in hexadecimal, start with '#x'. To type faster, you can also enter the hexadecimal value without any leading '#x', but note that this may be ambiguous (like 'af', for instance). In case of ambiguity, the string is interpreted as a character name.

You can also use the Special characters tool. In this tool, the pull-down menu allows you to choose a group of characters, which are then available in the table below. Click a character in this table to insert it in the formula or anywhere else in the document.

Also, the MathML specification recommends to add invisible characters in order to make it easier for a speech synthesizer to read a formula. These characters are automatically inserted from the palette, but sometimes you have to do it by yourself. You can then use the Insert/Math submenu or shortcuts. The three invisible characters are:

1. invisible times: a ⁢ b
2. apply function: f ⁡ ( x )
3. invisible comma: a i ⁣ j

#### Changing the structure

You may want to change the structure of an existing expression, such as appending a superscript, putting parentheses around an expression, or turning an expression into the numerator of a fraction. To do that, select the expression and enter the new construct with the Math palette, the Insert/Math submenu or the keyboard.

You can also use Transform from the Tools menu. Select the expression you want to transform and Transform will display a menu with all possible changes. For constructs that are not part of the Presentation MathML markup - i.e. only available from the palette - clicking on the button will put the selected expression in the most natural placeholder.

Changing an expression is useful to keep a recursive structure even when you enter a formula linearly. For instance to enter x 2 ≤ 9 25 ⇒ x ≤ 3 5 you can,

- either enter "recursively" (faster but less natural for long expression) :
  - ⇒
  - ≤ ⇒
  - ≤ ⇒
  - x ≤ ⇒
  - x 2 ≤ ⇒
  - x 2 ≤ ⇒
  - x 2 ≤ 9 ⇒
  - ...
- or enter "linearly" (you write as you read, but you need to select several times) :
  - x
  - x
  - x 2
  - x 2 ≤
  - x 2 ≤ 9
  - x 2 ≤ 9
  - ...

Generally, you will use both methods.

#### Viewing structure in MathML

A MathML structure in a document can be viewed by choosing Show Structure from the Views menu. Choosing this option opens up the Structure view, which reveals the main structure of the document, the math elements, and their contents.

Math expressions can be edited in the main view or in the structure view.

The structure view is especially helpful to avoid ambiguity. For example, in the equation below, placing the cursor after character b , it is not clear whether you wish to add something within the square root or after it.

x = a + b + 1

Selecting (or checking) in the Structure view avoids any misselections. You can also check the status line at the bottom of the window.

#### Linking in MathML

You can create and use links in mathematical expressions. These links are represented using the XML Linking Language (XLink). Only simple unidirectional hyperlinks are available in Amaya, but you can associate a link with any part of a formula. For example, the fraction in the formula below is a link to the W3C home page:

y = 1 x 2 + 1

Double-clicking or right-clicking any character within the fraction loads the W3C home page.

To create such a link, select a math expression (the fraction in the above example, for instance by clicking on the fraction bar), click the button from the Elements tool, or choose Create or change link from the Links menu, and click the desired target.

If the target is an expression in a formula, you must first turn the expression into a target. Select the expression and choose Create target from the Links menu to create an `id` attribute for the target expression.

### More about MathML

#### Browsers compatibility

Several browsers support MathML:

- Internet Explorer with the MathPlayer plugin
- Firefox and other Gecko-based browsers
- Opera since version 9.5

It is necessary to use the `.xml` suffix to be sure that XHTML documents are managed as XML. Without this suffix some browsers do not display correctly documents that include mathematical expressions. It is also recommended to use the utf-8 charset for all XML documents.

By default Amaya adds the XHTML 1.1 plus MathML 2.0 doctype at the beginning of the document. This doctype is not mandatory but it is useful:

- to validate the document,
- to generate alphanumerical entities (like &int;) for mathematical symbols in the source code. Otherwise mathematical symbols are coded like any other unicode character.

Unfortunately, this doctype is not supported by many browsers. So it could be necessary to remove this doctype with the Amaya command: Tools/Change doctype/Remove the doctype.

IE uses the `pmathml.xsl` transformation style sheet and a plugin to display the MathML code included in XHTML documents. Amaya adds automatically a link to that transformation style sheet, but the author must store a copy of this style sheet (pmathml.xsl) in the local directory of the document.

#### Known issues

- Amaya implements only the Presentation part of MathML 2.0, not the Content Markup part.
- A few Presentation tags are not entirely available: `mglyph`, `maction`
- All presentation elements and attributes are available, but only the following attributes are rendered on the screen: `display, alttext, mathvariant, mathsize, mathcolor, mathbackground, fontsize, fontweight, fontstyle, fontfamily, color, linethickness, numalign, denomalign, bevelled, notation, lquote, rquote, lspace, rspace, largeop, movablelimits, subscriptshift, superscriptshift, form, width` (mspace only), `height` (mspace only), `depth` (mspace only), `align, rowalign, columnalign, frame, framespacing, displaystyle, side, rowspan, columnspan, rowspacing, columnspacing, rowlines, columnlines`.
- The `class`, `id`, and `style` attributes are available, with the same semantics as in (X)HTML: you can associate CSS styles with MathML elements (`class` and `style` attributes) and a MathML element can be the target of a link (`id` attribute).
- Amaya uses the STIX fonts to render mathematical symbols, but currently not all symbols are supported.