Main ideas

The editor is based on the idea of an equation template. There are templates for fractions, subscripts, superscripts, matrices, etc. To build an equation, you insert templates and fill in the blanks.

To fill in the blanks, enter letters and numbers from the keyboard, select symbols from a palette, or replace a blank with another template. If you select something before inserting a template from the toolbar, the symbol or expression you've selected will automatically be inserted into the first blank in the template. Some people describe this as "wrapping" a template around a selection.

By nesting equation templates inside one another, you can build up almost any equation. Navigate around an equation using the mouse and arrow keys. You can also cut and paste sub-expressions to build up more complex expressions.

The editor templates and symbols are directly based on MathML. MathML is the markup language for encoding math on the Web standardized by the World Wide Web Consortium (W3C). You can certainly use the editor without knowing much (if anything) about MathML.

Example: MathML source code for a very simple expression x + 4.

<math><mi>x</mi><mo>+</mo><mn>4</mn></math>
                                                        

MathFlow Editor allows you to customize many typesetting and style properties to fine-tune visual appearances. You edit properties by selecting an expression and opening a property dialog box from the editor menu bar. Typesetting and style properties mostly correspond directly to MathML concepts. That is, changing properties corresponds to setting MathML attributes. In most cases, MathFlow can process the full range of valid MathML attribute values.

The possible values for each style property are discussed in MathFlow Editor: Controlling style properties, and in the Editor online help.

Most of the time, cursor movement in MathFlow Editor works as you would expect, and you don't need to think too hard about it. However, as the cursor moves through your equation, its shape changes to give you extra information about the equation structure. Spending a few minutes learning about the subtleties of cursor movement will have a big payoff in the long run.

MathFlow Editor tries to make cursor movement as natural and intuitive as possible. In general, the left, right, up and down arrows move the cursor to the next valid insertion point in the corresponding direction. Similarly, clicking the mouse anywhere in an equation moves the cursor to the closest valid location to the click.

Behind the scenes, the MathFlow Editor is negotiating a potentially complicated nested structure of MathML templates. Moving the cursor to the right on the screen can involve jumping in and out of MathML structures behind the scenes.

The cursor may occasionally not move exactly as you would expect on account of the nesting of the MathML structure. In these cases, the cursor movement is giving you additional information about the structure of your equation.

To help you follow where the cursor is in the MathML structure of the equation, the MathFlow Editor gives two visual cues. The cursor position is represented by a blinking red vertical bar. However, note that there is a faint gray rectangle as well. This gray rectangle is outlining the equation template containing the cursor location and is the first cue about the MathML structure near the cursor.

To illustrate, consider stepping through the following equation with the right arrow.

As the cursor moves to the right, note that when it moves into the fraction, the gray rectangle shifts to the fraction, instead of the entire equation.

The second visual cue about the location of the cursor in the nested MathML template structure is the MathML Ancestry panel. As you move the cursor, you can see the nesting of MathML templates, with the innermost template or symbol that the cursor is on at the far right of the Ancestry panel, and the outermost ‹math› template on the left.

In more complicated situations, one might have several nested rows, where the right edges all align. When this happens, hitting the right arrow will move the cursor from an inner template to an outer template in the nesting. Although you will see the gray rectangle outlining the parent template and MathML Ancestry panel change, the actual cursor position stays the same.

By spending a few minutes playing with cursor movement and nested templates, you will rapidly get the hang of navigating around in a structured MathML equation.

When you start a new equation, the cursor automatically starts as a blinking vertical red line. When the Editor window loses focus, the cursor changes to gray and stops blinking. The vertical line is the normal cursor in MathFlow editor.

As you type, the editor will begin inserting the characters into the equation, and the cursor will move to show the insertion point. Also, a faint gray box will appear, outlining the template in which the cursor is currently located. As you move around in an equation, the gray outline shifts, giving you a visual cue about the nesting structure of the underlying MathML, as illustrated here:

In the first two illustrations, the cursor is located in the numerator and denominator of a fraction, and the outlined parent is the row template containing the entire numerator and denominator respectively. In the third illustration, the cursor is on the left edge of the fraction itself, and the outlined parent is a "wrapper" row containing the fraction itself.

The Editor will automatically put characters into special MathML templates called tokens. There are tokens for variables (called an <mi> template in MathML, for math identifier), numbers (<mn>), operators (<mo>), and so on.

The right and left arrow keys generally move the cursor between the tokens in the row. However, when you move the cursor over a token that contains several characters together, the cursor will take an upside-down T-shape to show the extent of the grouped items by underlining them, as shown here.

This triangle is used to indicate the presence of non-MathML markup somewhere within a given element. The example image above was created with the following MathML:

<math>
   <mrow>
      <mfrac>
         <mrow>
            <mi>a</mi>
         </mrow>
         <?foo?>
         <!-- comment --!>
         <atag/>
         <mrow>
            <mi>b</mi>
         </mrow>
      </mfrac>
   </mrow>
</math>

Notice the non-MathML elements between the numerator and denominator elements of the mfrac. Technically, these non-MathML elements should be displayed in Design view in the same location as the fraction bar, which would be very confusing. Since there are many situations where this kind of problem can occur, all such situations will be displayed with the upward facing triangle below the text cursor, whenever the text cursor is "on" an element with non-MathML elements inside. If you place your mouse cursor over the triangle, the status bar will show you the name of the element that contains the non-MathML markup.

Thus it is a good habit to check the ancestry to make sure the cursor is really on the template. The gray rectangle will confirm what you see in the ancestry.

MathFlow Editor includes an option called safe mode that prevents the user from accidentally changing non-MathML elements contained within an equation. When safe mode is engaged for a given type of non-MathML, the Design view within the editor will display non-MathML as a downward pointing triangle within token elements (such as mi, mn, mtext) and container elements (such as mrow and mstyle). The editor will also prevent certain actions from occurring, such as deleting portions of an equation that contain non-MathML elements. Depending on the circumstances, you will either be warned of the presence of non-MathML elements in the status line or prompted for permission to delete the non-MathML elements. When you disable safe mode for any type of non-MathML element, you will not see the non-MathML element in Design view, nor will you be prompted or warned when deleting the non-MathML element. Disabling safe mode will be useful for experienced users who are aware of the presence of non-MathML elements and do not need the additional safety provided by this mode.

To illustrate what non-MathML looks like in Design view, consider the following MathML:

<math>
   <mrow>
      <!--comment 1--!>
      <mi><?pi1?>a<?pi2?>b<?pi3?>c<?pi4?></mi>
      <!--comment 2--!>
   </mrow>
</math>

Notice that there are four processing instructions surrounding the letters "abc", plus the two comments that are to the far left and right of the letters. Viewing this equation in Design view will show red markers above the content at the location of the non-MathML elements as seen here.

Since the comments were placed inside the container element mrow, these triangles are slightly lower than the processing instructions that are contained within the mi. This may be helpful in determining where the non-MathML elements reside. You can also determine what the contents of the non-MathML element are by moving your cursor over the triangle, which will cause the status line to display as much of the non-MathML element as possible.

Non-MathML that is not within a token or container element is displayed as an upward facing triangle just below the current cursor position. Examples of this are shown under "Cursor Embellishment for Non-MathML Elements" in Cursor shapes.

While it is useful to enable safe mode to display non-MathML in token and container elements, it is possible to turn off portions of safe mode or to turn it off entirely. For full details, see Customizing editing behavior.

By default, MathFlow will warn you when the equation contains non-MathML by displaying a dialog box. This is done whenever there are major changes to the equation such as doing the following:

Since this warning can become tedious, you have the option to disable it. This can be done from within the warning dialog box by checking the "Don't show this dialog again" checkbox:

It is also possible to disable the warning through General Editing Preferences. See Customizing editing behavior.