Structure Editor: best practices and tips

Simple alignment: 2 lines aligned at =

Basic equation-lines alignment can be achieved by placing the lines in a table and adjusting the column and row alignment of the mtable element. For more sophisticated equation alignment, you need to edit the MathML directly in a MathFlow Editor source-view panel, and use either a table with alignment markers (http://www.w3.org/TR/MathML3/chapter3.html#presm.malign) or the linebreaking indentation attributes (http://www.w3.org/TR/MathML3/chapter3.html#presm.lbindent.attrs).

However, for the most simple 2-line examples (or even more than 2), the process described below is easier than a table, and is more friendly to screen reading software.

MathML 3 linebreaking

MathML 3.0 introduced new linebreaking features which have been incorporated into MathFlow. To align equations, highlight the linebreak <mspace>, either using the MathML ancestry bar or the Source view, and go to the Linebreak Attributes dialog (in the Properties menu) to set the linebreaking alignment properties.

For example, to align by the equals sign, highlight the first equals sign in your equation, go to Properties > Common Attributes, and set a value for @id, such as "equals". Then open the Linebreak Attributes dialog as described in the previous paragraph (remembering to highlight the linebreak <mspace>). Set the indentalign property to "id" and set indenttarget to the value for the id attribute on the first equals sign:

Simple alignment

For more information on the MathML 3.0 linebreaking features, please see the overview of MathML 3's features on our MathML 3 page.

More complex alignment at =

The previous topic showed how to align simple equations at relational symbols, such as the = sign. Quite often though, the situation is more complex than that, requiring a more detailed technique to align the equations.

MathML also has the concept of "alignment markers". These are space-like elements that one can use to vertically align specific points within a column of MathML expressions. To effect this degree of alignment control, MathML offers the elements <malignmark/> and <maligngroup/>, and two attributes, edge and groupalign. For more detailed explanation of these elements and attributes, see chapter 3 of the MathML spec. The example below uses both of these elements, but neither of the attributes.

Let's start with this code (copy and paste it into the editor):

<math><mrow><mtable><mtr><mtd><maligngroup/><template/><mo>=</mo><malignmark/><template/></mtd></mtr><mtr><mtd><maligngroup/><mo>=</mo><malignmark/><template/></mtd></mtr></mtable></mrow></math>
Note: <template/> isn't a MathML element; it's used by MathFlow as a placeholder, an empty box where you will insert content. When you do so, <template/> will be replaced with the content.

Although more complex than the previous example, this is still a fairly simple example. Once you understand the concepts covered here, you should be able to handle much more complex examples.

If we align the code somewhat more visually, it might look like this:

<math><mrow><mtable>
<mtr><mtd>
<maligngroup/>
   <template/><mo>=</mo><malignmark/><template/>
</mtd></mtr>
<mtr><mtd>
<maligngroup/>
              <mo>=</mo><malignmark/><template/>
</mtd></mtr>
</mtable></mrow></math>

If you need the expressions to align in more than one place vertically (all the variables, all the operators, all the =, etc.), don't add more alignment marks; add a groupalign attribute. You should have either alignment marks OR groupalign attribute(s), but not both. Notice in our example, each maligngroup has only one malignmark.

In MathFlow, it looks like this, after the code is pasted, and before any content is added:

expression is an empty template, equal sign, another empty template, and on the next line an equal sign aligned with the preceding equal sign, and an empty template to its right

Let's see what it would look like with "real" content. Click inside the first template box and type something. Press Tab to move to the next template box and type something, and repeat for the last box. The size of the box contents doesn't have to be the same size. Here's a somewhat complex implementation of what started out as a fairly simple example:

expression: first line 60 miles per hour equals 60 miles per hour times 1 hour over 3600 seconds times 5,280 feet over 1 mile. next line equals fraction 60 times 5,280 over 3,600 end fraction feet over second. next line equals 88 feet over second

Note 1: To add subsequent lines beneath the 2 in the example code above, copy one of the rows — <mtr>…</mtr> — and paste it above the </mtable> tag. You can work either in a text editor or in MathFlow's Source view. If you do the work in a text editor, copy & paste the entire ‹math› block into MathFlow (either Source or Design view).

Note 2: You can have content to the left of the = sign on second and subsequent lines if you want. Just add whatever you need over there, but make sure the maligngroup precedes the entire contents of the mtd, and keep the alignment marks in the same place.

This code may also be used to add a button to a custom toolbar. See our description of the toolbar configuration language in Programmer documentation.

Long equations wrapped to multiple lines

It's fairly common in technical publishing to have an equation too long to fit on one line. That becomes even more common if the publication is formatted in two columns. Such situations are most often handled by breaking the equation up into multiple lines. Both MathML and MathFlow provide the means to do that.

For our example, let's consider this equation:

long equation

This is likely too wide for most 2-column publications, so we need to decide where to have it wrap (break) to the next line. MathML provides at least 2 means of doing that (other than tables). One way is to explicitly tell the MathML renderer where to break the equation. The other method is to tell it "where it's OK" to break the equation, but if there's room, "you don't have to break it here". (Conversely we can also specify "don't break here".)

You may copy this code and paste it into the editor if you want to follow along with this tip:

<math><mrow><msup><mrow><mo>(</mo><mn>1</mn><mo>+</mo><mi>x</mi><mo>)</mo>
</mrow><mrow><mi>n</mi></mrow></msup><mo>=</mo><mn>1</mn><mo>+</mo>
<mi>n</mi><mi>x</mi><mo>+</mo><mfrac><mrow><mi>n</mi><mrow><mo>(</mo>
<mi>n</mi><mo>&minus;</mo><mn>1</mn><mo>)</mo></mrow></mrow><mrow><mn>2</mn>
<mo>!</mo></mrow></mfrac><msup><mrow><mi>x</mi></mrow><mrow><mn>2</mn>
</mrow></msup><mo>+</mo><mfrac><mrow><mi>n</mi><mrow><mo>(</mo><mi>n</mi>
<mo>&minus;</mo><mn>1</mn><mo>)</mo></mrow><mrow><mo>(</mo><mi>n</mi>
<mo>&minus;</mo><mn>2</mn><mo>)</mo></mrow></mrow><mrow><mn>3</mn><mo>!</mo>
</mrow></mfrac><msup><mrow><mi>x</mi></mrow><mrow><mn>3</mn></mrow></msup>
<mo>+</mo><mfrac><mrow><mi>n</mi><mrow><mo>(</mo><mi>n</mi><mo>&minus;</mo>
<mn>1</mn><mo>)</mo></mrow><mrow><mo>(</mo><mi>n</mi><mo>&minus;</mo>
<mn>2</mn><mo>)</mo></mrow><mrow><mo>(</mo><mi>n</mi><mo>&minus;</mo>
<mn>3</mn><mo>)</mo></mrow></mrow><mrow><mn>4</mn><mo>!</mo></mrow></mfrac>
<msup><mrow><mi>x</mi></mrow><mrow><mn>4</mn></mrow></msup><mo>+</mo>
<mi>&mldr;</mi></mrow></math>

First, it's important to note MathFlow supports its own linebreaking when no explicit linebreaking is present, and independent of any linebreaking the renderer provides (IOW, if you don't specify linebreaking, it may look different in the document than it does in MathFlow).

Here's how our equation looks in MathFlow before any linebreaking is applied:

same equation as above, but with MathFlow's automatic linebreaking applied

Let's apply linebreaking after each "x" term beginning with x squared, and force the + operator to the new line. To do so, we'll add a linebreak='newline' attribute to the <mo> tag for each operator we want to begin a new line.

To do that, select the + operator where you want to apply the break, then choose Linebreak Attributes from the Properties menu. The attribute listed first in the dialog is linebreak. From the dropdown list on linebreak, choose newline. Click Done, and repeat the process for the next + (the one before the ellipsis).

Here's how our equation looks now:

same equation as above, but with our explicit linebreaking applied

More complex alignment is possible, but we leave that for you to investigate.

See also:

Multiple identifiers into one

To group several individual identifiers into a single identifier, select (highlight) the identifiers and navigate to the Edit > Characters > Group menu item. You can also split a single token item into individual token items using the Ungroup feature.

Example

Change: <mrow><mi>I</mi><mi>D</mi><mi>T</mi></mrow>
To: <mrow><mi>IDT</mi></mrow>

Select the characters, then choose "Group" from the Edit menu.

Series of variables converted into one text token

To group a series of variables into a single text token, select the characters and choose the Edit > Characters > Group menu item. Select the characters again (an easy way to do that is to select the <mi> token in the MathML ancestry). Choose the Text template, which is in the Layout Template Palette of the standard toolbar (see screen shot). Alternatively, you can apply the text mode with the Ctrl+T shortcut.

Example

Change: <mi>y</mi><mo>=</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi>
To: <mi>y</mi><mo>=</mo><mtext>return</mtext>

Select the characters and group as above, then select again and apply the Text template.