Equation Editor Features and Capabilities

The WebEQ Equation Editor is based on the idea of an equation template. For example, there are templates for fractions, subscripts, superscripts, and matrices, among others. An author builds up an equation by inserting templates, and then filling in the blanks.

Filling in the blanks consists of entering letters and numbers from the keyboard, selecting symbols from a palette, or replacing a blank with another template. By nesting equation templates inside one another, it is possible to build up almost any equation. One can navigate around an equation using the mouse and arrow keys, and cut and paste subexpressions to edit even very complex expressions.

All of the Equation Editor templates and symbols are directly based on MathML. MathML is a new markup language for math on the Web from W3C, the World Wide Web Consortium. You can certainly use the Editor without knowing much MathML. However, if you want to understand all the subtleties, you will probably want to read A Gentle Introduction to MathML.

The Editor allows you to change several dozen MathML equation layout attributes to fine-tune visual appearances. Although the effect of most attributes is self-explanatory, descriptions of these attributes are given in the MathML Reference Section. A fuller discussion of attributes is also given in the Gentle Introduction. (Complete information is also available in the lengthy and technical W3C MathML specification, though of course, the specification contains no WebEQ-specific information.)

Templates, Characters, and Cursor Movement

The first thing you need to know about using the WebEQ Editor is how cursor movement works. When you start a new equation, the cursor automatically starts as a vertical line in an empty <mrow> template. An <mrow> is probably the most basic Editor template, and consists of a horizontal row that stretches to contain any number of characters, symbols or other templates. As you type, the editor will begin inserting the characters into the <mrow>.

Normally, the editor will automatically put each individual character in a special "token" box. There are tokens boxes for variables (called an <mi> box in MathML), numbers (<mn>), operators (<mo>), and so on.

Once you have a few tokens or templates in your <mrow>, the right and left arrow keys generally move the cursor between the "child boxes" in the row. When you move the cursor over a template that groups several expressions together, it will take an L-shape to show the extent of the grouped items. You can also move the cursor with the mouse, as you would expect.

The editor tries to do a good job of judging when to ignore all the layers of MathML nesting and jump ahead to the next reasonable place to begin inserting characters again. If you find yourself having a hard time getting the cursor where you want it with the arrow keys, just use the mouse, which generally does a better job of tunneling in.

If you need something besides numbers and characters in your equation, such as a fraction or a superscript, you will need to insert the appropriate template, and then fill it out. To do this, you can either click on the appropriate button on the template toolbar across the top of the editor, or use the Insert Menu which lists the templates along with their MathML names. Whether you use the toolbar or the nemu, a blank template will appear at the insertion point, with small squares indicating the position where data should be inserted.

In MathML, there are rules governing what templates can be nested inside each other. For example, only table rows may appear inside a table template. The only templates which will be enabled on the Insert Menu are those which may be legitimately inserted at the current cursor location.

When you insert a template, the cursor will automatically jump to the first template blank. However, if for some reason, you want to move the cursor away, and fill in the template blanks later, you will first have to select the template blank again with the cursor. You can verify that the cursor is on a template blank by looking at the editor status line in the lower right corner. The current cursor selection and the parent template are indicated there in the form <parent> : <cursor>.

When the cursor is on a template, ready to inset, the status line will typically display as <mrow> : <template>. This is an important aid in avoiding a common confusion: a template blank typically appears in an <mrow> that will later stretch to contain whatever sequence of character and symbols you enter. However, when the template blank is the only thing in the <mrow> they will both be the same size, so check the status line to make sure the cursor is on the template, and not the row.

The up and down arrows keys generally move the cursor into and out of templates. The left and right arrows move the cursor between the children in a given template. What this means in practice is probably best understood by experimenting a little, but a simple example conveys the main idea.

Suppose you want to put an x² in your <mrow>. To do this, move the cursor to the place where the x² should be inserted. The insertion point is immediately to the left of the cursor. That is, whatever you type or insert from a menu appears to the left of the cursor.

Now select the msup template from the toolbar, and a template with two blanks will appear, with the cursor highlighting the first one. Hitting the up arrow will select the <mrow> containing the blank. Hitting it again will select the entire <msup> template. Hitting the down arrow will move the cursor back inside the template, since that is the natural place to begin inserting characters.

When you are inside the superscript template the right and left arrows will move the cursor between the base and superscript templates. However, if you go up to the top level, the right and left arrows will step you over the whole superscript template. To get back inside it, use the down arrow.

As noted above, the template blanks are usually nested inside several other constructs, it can be difficult to tell just what is selected. Even with the <msup>, there are three different "levels" since the template blank is inside an <mrow> which is itself inside the <msup>. Thus it is good to get in the habit of checking the status line in the lower right corner of the Editor window, where it displays the currently selected element and its parent.

Because selecting a template blank is such a common task, there are two kinds of shortcuts. Hitting the TAB key will cycle between all open template blanks. You can also move the cursor to a template blank by clicking on it with the mouse.

   
Illustration: Moving into a template with the down arrow.

Entering Symbols

For simple equations, you may only need the letters, symbols and digits available on the keyboard. However, in many situations, you will want to enter special mathematical symbol characters. Entering symbols is accomplished by picking symbols from the Symbol Palette window.

The Symbol Palette window displays the WebEQ symbol characters, and lets you enter one into an equation by clicking on it. You can open the Symbol Palette window from the Windows Menu in the main editor window, or by clicking the large button with Greek letters on it in the toolbar.

The Symbol Palette contains the most commonly used MathML symbols characters. However, there are a very large number of MathML symbols (nearly 1300) and although WebEQ doesn't support all 1300, it supports more than appear in the Symbol Palette. If you need to use these characters, you will have to insert them by hand using a text editor, and use the Wizard to produce your images or applets. A comprehensive list of the symbol characters supported by WebEQ is given in the WebTeX documentation.

The Attribute Window

Almost all Equation Editor templates have some layout parameters or "attributes" which control things like colors, fonts, alignment, spacing and styles. These attributes correspond to the MathML attributes for that particular layout template.

In order to change the attributes for a given template, open the Attribute Window from the Windows Menu in the main editor window. Then change the appropriate value. The MathML attributes for all templates are visible in the Attribute Window, but you can only change those that apply to the currently selected template.

Ordinarily, changes only apply to the currently selected template, and are not "inherited" by the templates nested inside it. However, the <mstyle> template is designed precisely to propagate attribute changes to its children, in case you want to change an attribute for an entire subexpression.

Attribute inheritance, and the meaning of all the MathML attributes are discussed in detail in the Gentle Introduction to MathML.

Saving Your Work

Once you are satisfied with your equation, you can save it in several formats. You can save it as an image, write out the MathML encoding to a file, or write out WebEQ Math Viewer applet code. When you save an applet or image, you can import it into an HTML page using your favorite HTML editing tools as you normally would.

All of these functions are available on the File Menu of the Editor. When you choose "Save" or "Save As", the Editor will just save the MathML markup for your equation. Since most current browsers can't directly read MathML source, you will probably need to further process the MathML for it to be useful. For example, if you directly import the MathML source into an HTML file, you can use the Wizard to later generate images or applet tags.

One advantage to saving the MathML source is that you can open equations saved in this format again, and edit them further. To open an equation, select "Open" from the File Menu.

The "Compactify MathML" option on the File Menu is closely related to saving MathML source. By default, the Equation Editor introduces some extra levels of nesting in grouping templates so that editing functions more naturally while you are working on your equation. However, once you are finished editing, there is no reason for these extra <mrow>'s in the MathML source, and selecting "Compactify MathML" before saving will remove them.

You can also cut and paste MathML markup directly from the editor into HTML files in a text editor, like Notepad under Windows or SimpleEdit under MacOS. There are two ways of selecting MathML code to copy onto the clipboard. First, you can open a MathML source window from the Editor Windows menu. This window will display the full MathML source for the equation currently in the main editor window. You can now highlight, copy and paste MathML markup as you normally do under your operating system.

You can also copy and paste from the main editor window. Use the mouse to highlight your equation (or part of your equation if you don't want it all), and select "Copy Selection to Clipboard" from the File menu. You can now paste into your HTML file in your text editor. It is important to note that it is the cursor selection which determines what MathML code will be placed on the clipboard.

It is also important to avoid confusing the usual "Cut", "Copy", and "Paste" functions under the Edit menu from "Copy MathML to Clipboard". The usual editing functions are used to move around parts of equations, as part of the editing process. When you select a subexpression, and use Edit | Cut, it will disappear from the current equation. Similarly, moving the cursor and using Edit | Paste will insert the cut expression at the new location. By contrast, "Copy Selection to Clipboard" leaves the current equation unchanged, while copying the MathML markup for the selected expression to the clipboard.

The other options for saving an equation are "Save as PNG", "Save as JPEG" and "Save as Applet". In the first two cases, the editor directly saves an image file, which you can import into an HTML page in the normal way. In the second case, the Editor generates a complete WebEQ Applet tag, which you can cut-and-paste into an HTML page.

If you choose Save as Applet, the editor will generate generic applet code suitable for local viewing, or viewing in a browser that has the WebEQ Math Viewer applet installed, but not for general distribution from a server. In particular, the applet tags specify no CODEBASE paramater, which is equivalent to assuming that the WebEQ class file tree is in the same directory as the HTML file containing the applet.

To customize applet parameters, you will need to either edit the applet code directly with a text editor, or use the WebEQ Wizard to process the MathML source directly. If you are creating a document with several applets, the second method will probably be more satisfactory. Just save the raw MathML code using Save or Save As, import it as text into your HTML file, and then use the Wizard. You will need to remember to set the Wizard delimiters option to "MathML" since your equations will be delimited by <math> tags, and not the WebTeX dollar signs and escaped brackets.