Up: Table of Contents REC-MathML-19980407; revised 19990707

3. Presentation Markup



3.3 General Layout Schemata

Besides tokens there are several families of MathML presentation elements. One family of elements deals with various "scripting" notations, such as subscript and superscript. Another family is concerned with matrices and tables. The remainder of the elements, discussed in this section, describe other basic notations such as fractions and radicals, or deal with general functions such as setting style properties and error handling.

3.3.1 <mrow> -- horizontally group any number of subexpressions

Description:

An <mrow> element is used to group together any number of subexpressions, usually consisting of one or more <mo> elements acting as "operators" on one or more other expressions which are their "operands".

Several elements automatically treat their arguments as if they were contained in an <mrow> element. See the discussion of inferred <mrow>s in Section 3.1.3. See also <mfenced> (Section 3.3.8), which can effectively form an <mrow> containing its arguments separated by commas.

Attributes of <mrow>:

None (except the attributes allowed for all MathML elements, listed in Section 2.3.4).

<mrow> elements are typically rendered visually as a horizontal row of their arguments, left to right in the order in which the arguments occur, or audibly as a sequence of renderings of the arguments. The description in Section 3.2.4 of suggested rendering rules for <mo> elements assumes that all horizontal spacing between operators and their operands is added by the rendering of <mo> elements (or, more generally, embellished operators), not by the rendering of the <mrow>s they are contained in.

MathML is designed to allow renderers to automatically linebreak expressions (that is, to break excessively long expressions into several lines), without requiring authors to specify explicitly how this should be done. This is because linebreaking positions can't be chosen well without knowing the width of the display device and the current font size, which for many uses of MathML will not be known except by the renderer at the time of each rendering.

Determining good positions for linebreaks is complex, and rules for this are not described here; whether and how it is done is up to each MathML renderer. Typically, linebreaking will involve selection of "good" points for insertion of linebreaks between successive arguments of <mrow> elements.

Although MathML does not require linebreaking or specify a particular linebreaking algorithm, it has several features designed to allow such algorithms to produce good results. These include the use of special entities for certain operators, including invisible operators (see Section 3.2.4), or for providing hints related to linebreaking when necessary (see Section 3.2.5), and the ability to use nested <mrow>s to describe subexpression structure (see below).

<mrow> of one argument

MathML renderers are required to treat an <mrow> element containing exactly one argument as equivalent in all ways to the single argument occurring alone, provided there are no attributes on the <mrow> element's begin tag. If there are attributes on the <mrow> element's begin tag, no requirement of equivalence is imposed. This equivalence condition is intended to simplify the implementation of MathML-generating software such as template-based authoring tools. It directly affects the definitions of embellished operator and spacelike element and the rules for determining the default value of the form attribute of an <mo> element; see Sections 3.2.4 and 3.2.6. See also the discussion of equivalence of MathML expressions in Chapter 7.

Proper grouping of subexpressions using <mrow>

Subexpressions should be grouped by the document author in the same way as they are grouped in the mathematical interpretation of the expression; that is, according to the underlying "syntax tree" of the expression. Specifically, operators and their mathematical arguments should occur in a single <mrow>; more than one operator should occur directly in one <mrow> only when they can be considered (in a syntactic sense) to act together on the interleaved arguments, e.g. for a single parenthesized term and its parentheses, for chains of relational operators, or for sequences of terms separated by + and -. A precise rule is given below.

Proper grouping has several purposes: it improves display by possibly affecting spacing; it allows for more intelligent linebreaking and indentation; and it simplifies possible semantic interpretation of presentation elements by computer algebra systems, and audio renderers.

Although improper grouping will sometimes result in suboptimal renderings, and will often make interpretation other than pure visual rendering difficult or impossible, any grouping of expressions using <mrow> is allowed in MathML syntax; that is, renderers should not assume the rules for proper grouping will be followed.

Precise rule for proper grouping

A precise rule for when and how to nest subexpressions using <mrow> is especially desirable when generating MathML automatically by conversion from other formats for displayed math, such as TeX, which don't always specify how subexpressions nest. When a precise rule for grouping is desired, the following rule should be used:

Two adjacent operators (i.e. <mo> elements, possibly embellished), possibly separated by operands (i.e. anything other than operators), should occur in the same <mrow> only when the left operator has an infix or prefix form (perhaps inferred), the right operator has an infix or postfix form, and the operators are listed in the same group of entries in the operator dictionary provided in Appendix C. In all other cases, nested <mrow>s should be used.

When forming a nested <mrow> (during generation of MathML) which includes just one of two successive operators with the forms mentioned above (which mean that either operator could in principle act on the intervening operand or operands), it is necessary to decide which operator acts on those operands directly (or would do so, if they were present). Ideally, this should be determined from the original expression; for example, in conversion from an operator-precedence-based format, it would be the operator with the higher precedence. If this cannot be determined directly from the original expression, the operator which occurs later in the suggested operator dictionary (Appendix C) can be assumed to have a higher precedence for this purpose.

Note that the above rule has no effect on whether any MathML expression is valid, only on the recommended way of generating MathML from other formats for displayed math or directly from written notation.

(Some of the terminology used in stating the above rule in defined in Section 3.2.4.)

Examples of <mrow>:

As an example, [Graphics:images/3_10.gif] should be written as:
<mrow>
  <mrow>
     <mn> 2 </mn>
     <mo> &InvisibleTimes; </mo>
     <mi> x </mi>
  </mrow>
  <mo> + </mo>
  <mi> y </mi>
  <mo> - </mo>
  <mi> z </mi>
</mrow>

The proper encoding of (x, y) furnishes a less obvious example of nesting <mrow>s:

<mrow>
   <mo> ( </mo>
   <mrow>
      <mi> x </mi>
      <mo> , </mo>
      <mi> y </mi>
   </mrow>
   <mo> ) </mo>
</mrow>

In this case, a nested <mrow> is required inside the parentheses, since parentheses and commas, thought of as fence and separator "operators", do not act together on their arguments.

3.3.2 <mfrac> -- form a fraction from two subexpressions

Description:

The <mfrac> element is used for fractions. It can also be used to mark up fraction-like objects such as binomial coefficients and Legendre symbols. The syntax for <mfrac> is

<mfrac> numerator denominator </mfrac>

Attributes of <mfrac>:

Name  values  default 
linethickness  number [ v-unit ] | thin | medium | thick  1 (rule thickness) 

The linethickness attribute indicates the thickness of the horizontal "fraction bar", or "rule", typically used to render fractions. A fraction with linethickness="0" renders without the bar, and might be used within binomial coefficients. A linethickness greater than one might be used with nested fractions. These cases are shown below:

[Graphics:images/3_9.gif] [Graphics:images/3_11.gif] 

In general, the value of linethickness can be a number, as a multiplier of the default thickness of the fraction bar (the default thickness is not specified by MathML), or a number with a unit of vertical length (see Section 2.3.3), or one of the keywords medium (same as 1), thin (thinner than 1, otherwise up to the renderer), or thick (thicker than 1, otherwise up to the renderer).

The <mfrac> element sets displaystyle to "false", or if it was already false increments scriptlevel by 1, within numerator and denominator. These attributes are inherited by every element from its rendering environment, but can be set explicitly only on the <mstyle> element. (See Section 3.3.4.)

Examples of <mfrac>:

The examples shown above can be represented in MathML as:

<mrow>
   <mo> ( </mo>
   <mfrac linethickness="0">
      <mi> a </mi>
      <mi> b </mi>
   </mfrac>
   <mo> ) </mo>
</mrow>

<mfrac linethickness="2">
   <mfrac>
      <mi> a </mi>
      <mi> b </mi>
   </mfrac>
   <mfrac>
      <mi> c </mi>
      <mi> d </mi>
   </mfrac>
</mfrac>

A more generic example is:

<mfrac>
   <mrow>
      <mn> 1 </mn>
      <mo> + </mo>
      <msqrt>
         <mn> 5 </mn>
      </msqrt>
   </mrow>
   <mn> 2 </mn>
</mfrac>

3.3.3 <msqrt> and <mroot> -- form a radical

Description:

These elements construct radicals. The <msqrt> element is used for square roots, while the <mroot> element is used to draw radicals with indices, e.g. a cube root. The syntax for these elements is

<msqrt> base </msqrt>

<mroot> base index </mroot>

The <mroot> element requires exactly 2 arguments. However, <msqrt> accepts any number of arguments; if this number is not 1, its contents are treated as a single "inferred <mrow>" containing its arguments, as described in Section 3.1.3.

Attributes of <msqrt> and <mroot>:

None (except the attributes allowed for all MathML elements, listed in Section 2.3.4).

The <mroot> element increments scriptlevel by 2, and sets displaystyle to "false", within index, but leaves both attributes unchanged within base. The <msqrt> element leaves both attributes unchanged within all its arguments. These attributes are inherited by every element from its rendering environment, but can be set explicitly only on <mstyle>. (See Section 3.3.4.)

3.3.4 <mstyle> -- style change

Description:

The <mstyle> element is used to make style changes which affect the rendering of its contents. <mstyle> can be given any attribute accepted by any MathML presentation element; it can also be given certain special attributes listed below.

The <mstyle> element accepts any number of arguments. If this number is not 1, its contents are treated as a single "inferred <mrow>" formed from all its arguments, as described in Section 3.1.3.

Loosely speaking, the effect of the <mstyle> element is to change the default value of an attribute for the elements it contains. Style changes work in one of two ways, depending on whether an attribute's default value is documented as inherited. The two cases are:

Note that attribute values inherited from an <mstyle>, in either manner, affect a given element in the <mstyle>'s content only if that attribute is not given a value in that element's begin tag. On any element for which the attribute is set explicitly, the value specified on the begin tag overrides the inherited value. The only exception to this rule is when the value given on the begin tag is documented as specifying an incremental change to the value inherited from that element's context or rendering environment.

Note also that the difference between inherited and non-inherited attributes set by <mstyle>, explained above, only matters when the attribute is set on some element within the <mstyle>'s contents which has children which also set it. Thus it never matters for attributes, such as color, which can only be set on token elements (or on <mstyle> itself).

There is one exceptional element, <mpadded>, whose attributes cannot be set with <mstyle>. When the attributes width, height and depth are specified on an <mstyle> element, they apply only to the <mspace/> element. Similarly, when lspace is set with <mstyle>, it applies only to the <mo> element.

Attributes accepted by <mstyle>:

As stated above, <mstyle> accepts all attributes of all MathML presentation elements. Additionally, <mstyle> can be given the following special attributes which are implicitly inherited by every MathML element as part of its rendering environment:
Name  values  default 
scriptlevel  ['+' | '-'] unsigned-integer   inherited 
displaystyle  true | false   inherited 
scriptsizemultiplier  number   0.71 
scriptminsize  number v-unit  8pt 
color  #rgb | #rrggbb | html-color-name  inherited 
background  #rgb | #rrggbb | transparent | html-color-name  transparent 

scriptlevel and displaystyle

MathML uses two attributes, displaystyle and scriptlevel, to control orthogonal presentation features that TeX encodes into one "style" attribute with values \displaystyle, \textstyle, \scriptstyle, and \scriptscriptstyle. The corresponding values of displaystyle and scriptlevel for those TeX styles would be "true" and "0", "false" and "0", "false" and "1", and "false" and "2", respectively.

The main effect of the displaystyle attribute is that it determines the effect of other attributes such as the largeop and movablescripts attributes of <mo>. The main effect of the scriptlevel attribute is to control the font size. Typically, the higher the scriptlevel, the smaller the font size. (Non-visual renderers can respond to the font size in an analogous way for their medium.) More sophisticated renderers may also choose to use these attributes in other ways, such as rendering expressions with displaystyle="false" in a more vertically compressed manner.

These attributes are given initial values for the outermost expression of an instance of MathML based on its rendering environment. A short list of layout schemata described below modify these values for some of their subexpressions. Otherwise, values are determined by inheritance whenever they are not directly specified on a given element's start tag.

For an instance of MathML embedded in a textual data format (such as HTML) in "display" mode, i.e. in place of a paragraph, displaystyle = "true" and scriptlevel = "0" for the outermost expression of the embedded MathML; if the MathML is embedded in "inline" mode, i.e. in place of a character, displaystyle = "false" and scriptlevel = "0" for the outermost expression. See Chapter 7 for further discussion of the distinction between "display" and "inline" embedding of MathML and how this can be specified in particular instances. In general, a MathML renderer may determine these initial values in whatever manner is appropriate for the location and context of the specific instance of MathML it is rendering, or if it has no way to determine this, based on the way it is most likely to be used; as a last resort it is suggested that it use the most generic values displaystyle = "true" and scriptlevel = "0".

The MathML layout schemata which typically display some of their arguments in smaller type or with less vertical spacing, namely the elements for scripts, fractions, radicals, and tables or matrices, set displaystyle to "false", and in some cases increase scriptlevel, for those arguments. The new values are inherited by all subexpressions within those arguments, unless they are overridden.

The specific rules by which each element modifies displaystyle and/or scriptlevel are given in the specification for each element which does so; the complete list of elements which modify either attribute are: the "scripting" elements <msub>, <msup>, <msubsup>, <munder>, <mover>, <munderover>, and <mmultiscripts>; and the elements <mfrac>, <mroot>, and <mtable>.

When <mstyle> is given a scriptlevel attribute with no sign, it sets the value of scriptlevel within its contents to the value given, which must be a nonnegative integer. When the attribute value consists of a sign followed by an integer, the value of scriptlevel is incremented (for '+') or decremented (for '-') by the amount given. The incremental syntax for this attribute is an exception to the general rules for setting inherited attributes using <mstyle>, and is not allowed by any other attribute on <mstyle>.

Whenever the scriptlevel is changed, either automatically or by being explicitly incremented, decremented, or set, the current font size is multiplied by the value of scriptsizemultiplier to the power of the change in scriptlevel. For example, if scriptlevel is increased by 2, the font size is multiplied by scriptsizemultiplier twice in succession; if scriptlevel is explicitly set to 2 when it had been 3, the font size is divided by scriptsizemultiplier.

The default value of scriptsizemultiplier is less than one (in fact, it is approximately the square root of 1/2), resulting in a smaller font size with increasing scriptlevel. To prevent scripts from becoming unreadably small, the font size is never allowed to go below the value of scriptminsize as a result of a change to scriptlevel, though it can be set to a lower value using the fontsize attribute (Section 3.2.1) on <mstyle> or on token elements. If a change to scriptlevel would cause the font size to become lower than scriptminsize using the above formula, the font size is instead set equal to scriptminsize within the subexpression for which scriptlevel was changed.

In the syntax for scriptminsize, v-unit represents a unit of vertical length (as described in Section 2.3.3). The most common unit for specifying font sizes in typesetting is pt (points).

Explicit changes to the fontsize attribute have no effect on the value of scriptlevel.

Further details on scriptlevel for renderers

For MathML renderers which support CSS1 style sheets, or some other analogous style sheet mechanism, absolute or relative changes to fontsize (or other attributes) may occur implicitly on any element in response to a style sheet. Changes to fontsize of this kind also have no effect on scriptlevel. A style sheet-induced change to fontsize overrides scriptminsize in the same way as for an explicit change to fontsize in the element's begin tag (discussed above), whether it is specified in the style sheet as an absolute or a relative change. (However, any subsequent scriptlevel-induced change to fontsize will still be affected by it.) As is required for inherited attributes in CSS1, the style sheet-modified fontsize is inherited by child elements.

If the same element is subject to both a style sheet-induced and an automatic (scriptlevel-related) change to its own fontsize, the scriptlevel-related change is done first -- in fact, in the simplest implementation of the element-specific rules for scriptlevel, this change would be done by the element's parent as part of producing the rendering properties it passes to the given element, since it is the parent element which knows whether scriptlevel should be changed for each of its child elements.

If the element's own fontsize is changed by a style sheet and it also changes scriptlevel (and thus fontsize) for one of its children, the style sheet-induced change is done first, followed by the change inherited by that child. If more than one child's scriptlevel is changed, the change inherited by each child has no effect on the other children. (As a mnemonic rule which applies to a "parse tree" of elements and their children, style sheet-induced changes to fontsize can be associated to nodes of the tree, i.e. to MathML elements, and scriptlevel-related changes can be associated to the edges between parent and child elements; then the order of the associated changes corresponds to the order of nodes and edges in each path down the tree.) For general information on the relative order of processing of properties set by style sheets vs. by attributes, see the appropriate subsection of CSS-compatible attributes in Section 2.3.3.

If scriptlevel is changed incrementally by an <mstyle> element which also sets certain other attributes, the overall effect of the changes may depend on the order in which they are processed. In such cases, the attributes in the following list should be processed in the following order, regardless of the order in which they occur in the XML-format attribute list of the <mstyle> begin tag: scriptsizemultiplier, scriptminsize, scriptlevel, fontsize.

Note that scriptlevel can, in principle, attain any integral value by being decremented sufficiently, even though it can only be explicitly set to nonnegative values. Negative values of scriptlevel generated in this way are legal and should work as described, generating font sizes larger than those of the surrounding expression. Since scriptlevel is initially 0 and never decreases automatically, it will always be nonnegative unless it is decremented past 0 using <mstyle>.

Explicit decrements of scriptlevel after the font size has been limited by scriptminsize as described above would produce undesirable results. This might occur, for example, in a representation of a continued fraction, in which the scriptlevel was decremented for part of the denominator back to its value for the fraction as a whole, if the continued fraction itself was located in a place which had a high scriptlevel. To prevent this problem, MathML renderers should, when decrementing scriptlevel, use as the initial font size the value the font size would have had if it had never been limited by scriptminsize. They should not, however, ignore the effects of explicit settings of fontsize, even to values below scriptminsize.

Since MathML renderers may be unable to make use of arbitrary font sizes with good results, they may wish to modify the mapping from scriptlevel to fontsize to produce better renderings in their judgement. In particular, if fontsizes have to be rounded to available values, or limited to values within a range, the details of how this is done are up to the renderer. Renderers should, however, ensure that a series of incremental changes to scriptlevel resulting in its return to the same value for some subexpression that it had in a surrounding expression results in the same fontsize for that subexpression as for the surrounding expression.

Color and background attributes

The color attribute controls the color in which the content of tokens is rendered. Additionally, when inherited from <mstyle> or from a MathML expression's rendering environment, it controls the color of all other drawing by MathML elements, including the lines or radical signs that can be drawn by <mfrac>, <mtable>, or <msqrt>.

Note that the background attribute, though not inherited, has the default value "transparent" (as in CSS1), which effectively allows an element's parent to control its background.

The values of color and background can be specified as a string consisting of '#' followed without intervening whitespace by either 1-digit or 2-digit hexadecimal values for the red, green, and blue components, respectively, of the desired color, with the same number of digits used for each component (or as the keyword "transparent" for background). The hexadecimal digits are not case-sensitive. The possible 1-digit values range from 0 (component not present) to F (component fully present), and the possible 2-digit values range from 00 (component not present) to FF (component fully present), with the 1-digit value x being equivalent to the 2-digit value xx (rather than x0).

These attributes can also be specified as an html-color-name, which is defined in the following subsection.

CSS compatibility of color attributes

The color syntax described above is a subset of the syntax of the "color" and "background-color" properties of CSS1. (The "background-color" syntax is in turn a subset of the full CSS1 "background" property syntax, which also permits specification of (for example) background images with optional repeats. The more general attribute name background is used in MathML to facilitate possible extensions to the attribute's scope in future versions of MathML.)

Color values on either attribute can also be specified as an html-color-name, that is, as one of the color-name keywords defined in HTML 4.0. The list of allowed color names includes most of the commonest English color words, though not "orange", "brown", or "pink", and also includes a number of less-common color words; see the reference for the complete list and the equivalent RGB values. Note that the color name keywords are not case-sensitive, unlike most keywords in MathML attribute values. (The same color name keywords are defined for the CSS1 "color" property, but with unspecified RGB values. See also the subsection CSS-compatible attributes within Section 2.3.3.)

Precise background region not specified

The suggested MathML visual rendering rules do not define the precise extent of the region whose background is affected by using the background attribute on <mstyle>, except that, when <mstyle>'s content does not have negative dimensions and its drawing region is not overlapped by other drawing due to surrounding negative spacing, this region should lie behind all the drawing done to render the content of the <mstyle>, but should not lie behind any of the drawing done to render surrounding expressions. The effect of overlap of drawing regions caused by negative spacing on the extent of the region affected by the background attribute is not defined by these rules.

Example of <mstyle>:

The example of limiting the stretchiness of a parenthesis shown in the section on <mo>,

<mrow>
   <mo maxsize="1"> ( </mo>
   <mfrac> <mi> a </mi> <mi> b </mi> </mfrac>
   <mo maxsize="1"> ) </mo>
</mrow>

can be rewritten using <mstyle> as:

<mstyle maxsize="1">
   <mrow>
      <mo> ( </mo>
      <mfrac> <mi> a </mi> <mi> b </mi> </mfrac>
      <mo> ) </mo>
   </mrow>
</mstyle>

3.3.5 <merror> -- enclose an error message from a preprocessor

Description:

The <merror> element displays its contents as an "error message". This might be done, for example, by displaying the contents in red, flashing the contents, or changing the background color. The contents can be any expression or expression sequence.

<merror> accepts any number of arguments; if this number is not 1, its contents are treated as a single "inferred <mrow>" as described in Section 3.1.3.

The intent of this element is to provide a standard way for programs that generate MathML from other input to report syntax errors in their input. Since it is anticipated that preprocessors that parse input syntaxes designed for easy hand entry will be developed to generate MathML, it is important that they have the ability to indicate that a syntax error occurred at a certain point. See Section 7.2.2.

The suggested use of <merror> for reporting syntax errors is for a preprocessor to replace the erroneous part of its input with an <merror> element containing a description of the error, while processing the surrounding expressions normally as far as possible. By this means, the error message will be rendered where the erroneous input would have appeared, had it been correct; this makes it easier for an author to determine from the rendered output what portion of the input was in error.

No specific error message format is suggested here, but as with error messages from any program, the format should be designed to make as clear as possible (to a human viewer of the rendered error message) what was wrong with the input and how it can be fixed. If the erroneous input contains correctly formatted subsections, it may be useful for these to be preprocessed normally and included in the error message (within the contents of the <merror> element), taking advantage of the ability of <merror> to contain arbitrary MathML expressions rather than only text.

Attributes of <merror>:

None (except the attributes allowed for all MathML elements, listed in Section 2.3.4).

Example of <merror>:

If a MathML syntax-checking preprocessor received the input

<mfraction>
   <mrow> <mn> 1 </mn> <mo> + </mo> <msqrt> <mn> 5 </mn> </msqrt> </mrow>
   <mn> 2 </mn>
</mfraction>

which contains the non-MathML element <mfraction> (presumably in place of the MathML element <mfrac>), it might generate the error message

<merror>
   <mtext> Unrecognized element: &lt;mfraction&gt;;
arguments were:&nbsp; </mtext>
   <mrow> <mn> 1 </mn> <mo> + </mo> <msqrt> <mn> 5 </mn> </msqrt> </mrow>
   <mtext> &nbsp;and&nbsp; </mtext>
   <mn> 2 </mn>
</merror>

Note that the preprocessor's input is not, in this case, valid MathML, but the error message it outputs is valid MathML.

3.3.6 <mpadded> -- adjust space around content

Description:

An <mpadded> element renders the same as its content, but with its overall size and other dimensions (such as baseline position) modified according to its attributes. The <mpadded> element does not rescale (stretch or shrink) its content; its only effect is to modify the apparent size and position of the "bounding box" around its content, so as to affect the relative position of the content with respect to the surrounding elements. The name of the element reflects the use of <mpadded> to effectively add "padding", or extra space, around its content. If the "padding" is negative, it is possible for the content of <mpadded> to be rendered outside the <mpadded> element's bounding box; see below for warnings about several potential pitfalls of this effect.

The <mpadded> element accepts any number of arguments; if this number is not 1, its contents are treated as a single "inferred <mrow>" as described in Section 3.1.3.

It is suggested that audio renderers add (or shorten) time delays based on the attributes representing horizontal space (width and lspace).

Attributes of <mpadded>:

Name  values  default 
width  [ + | - ] unsigned-number ( % [ pseudo-unit ] | pseudo-unit | h-unit )   same as content
lspace  [ + | - ] unsigned-number ( % [ pseudo-unit ] | pseudo-unit | h-unit )   0
height  [ + | - ] unsigned-number ( % [ pseudo-unit ] | pseudo-unit | v-unit )   same as content
depth  [ + | - ] unsigned-number ( % [ pseudo-unit ] | pseudo-unit | v-unit )   same as content

(The pseudo-unit syntax symbol is described below.)

These attributes modify the dimensions of the "bounding box" of the <mpadded> element. The dimensions (which have the same names as the attributes) are defined in the next subsection. Depending on the format of the attribute value, a dimension may be set to a new value, or to an incremented or decremented version of the content's corresponding dimension. Values may be specified as multiples or percentages of any of the dimensions of the normal rendering of the element's content (using so-called "pseudo-units"), or as multiples of standard length units.

If an attribute value begins with a + or - sign, it specifies an increment or decrement of the corresponding dimension by the following length value (interpreted as explained below). Otherwise, the corresponding dimension is set directly to the following length value. Note that the + and - do not mean that the following value is positive or negative, even when an explicit length unit (h-unit or v-unit) is given. In particular, these attributes cannot directly set a dimension to a negative value.

Length values (after the optional sign, which is not part of the length value) can be specified in several formats. Each format begins with an unsigned-number, which may be followed by a % sign and an optional "pseudo-unit" (denoted by pseudo-unit in the attribute syntaxes above), by a pseudo-unit alone, or by one of the length units (denoted by h-unit or v-unit) specified in Section 2.3.3, not including %. The possible pseudo-units are the keywords width, lspace, height, and depth; they each represent the length of the same-named dimension of the <mpadded> element's content (not of the <mpadded> element itself). The lengths represented by h-unit or v-unit are described in Section 2.3.3.

In any of these formats, the length value specified is the product of: the specified number; 0.01 if % is given; and the length represented by the unit or pseudo-unit. If no pseudo-unit is given after %, the one with the same name as the attribute being specified is assumed.

Some examples of attribute formats using pseudo-units (explicit or default) are as follows: depth="100% height" and depth="1.0 height" both set the depth of the <mpadded> element to the height of its content. depth="105%" sets the depth to 1.05 times the content's depth, and either depth="+100%" or depth="200%" sets the depth to twice the content's depth.

Dimensions that would be positive if the content was rendered normally cannot be made negative using <mpadded>; a positive dimension is set to 0 if it would otherwise become negative. Dimensions which are initially 0 can be made negative, but this should generally be avoided. See the warnings below on the use of negative spacing for "tweaking" or conveying meaning.

The rules given above imply that all of the following attribute settings have the same effect, which is to leave the content's dimensions unchanged:

<mpadded width="+0em"> ... </mpadded>
<mpadded width="+0%"> ... </mpadded>
<mpadded width="-0em"> ... </mpadded>
<mpadded width="- 0 height"> ... </mpadded>
<mpadded width="100%"> ... </mpadded>
<mpadded width="100% width"> ... </mpadded>
<mpadded width="1 width"> ... </mpadded>
<mpadded width="1.0 width"> ... </mpadded>
<mpadded> ... </mpadded>

Meanings of dimension attributes

See the Glossary given in Appendix B for further information about some of the typesetting terms used here.

The width attribute refers to the overall horizontal width of a bounding box. By default (i.e. when lspace is not modified), the bounding box of the content of an <mpadded> element should be rendered flush with the left edge of the <mpadded> element's bounding box. Thus, increasing width alone effectively adds space on the right edge of the box.

The lspace attribute refers to the amount of space between the left edge of a bounding box and where the rendering of its contents' bounding box actually begins. Unlike the other dimensions, lspace does not correspond to a real property of a bounding box, but exists only transiently during the computations done by each instance of <mpadded>. It is provided so that there is a way to add space on the left edge of a bounding box.

The rationale behind using width and lspace to control horizontal padding instead of more symmetric attributes, such as a hypothetical rspace and lspace, is that it is desirable to have a "width" pseudo unit, in part because "width" is an actual property of a bounding box.

The height attribute refers to the amount of vertical space between the baseline (the line along the bottom of most letter glyphs in normal text rendering) and the top of the bounding box.

The depth attribute refers to the amount of vertical space between the bottom of the bounding box and the baseline.

MathML renderers should ensure that, except for the effects of the attributes, relative spacing between the contents of <mpadded> and surrounding MathML elements is not modified by replacing an <mpadded> element with an <mrow> element with the same content. This holds even if linebreaking occurs within the <mpadded> element. However, if an <mpadded> element with non-default attribute values is subjected to linebreaking, MathML does not define how its attributes or rendering interact with the linebreaking algorithm.

Warning: nonportability of "tweaking"

A likely temptation for the use of the <mpadded> and <mspace/> elements (and perhaps also <mphantom> and <mtext>) will be for an author to improve the spacing generated by a specific renderer by slightly modifying it in specific expressions -- i.e., to "tweak" the rendering.

Authors are strongly warned that different MathML renderers may use different spacing rules for computing the relative positions of rendered symbols in expressions which have no explicit modifications to their spacing; if renderer B improves upon renderer A's spacing rules, explicit spacing added to improve the output quality of renderer A may produce very poor results in renderer B, very likely worse than without any "tweaking" at all.

Even when a specific choice of renderer can be assumed, its spacing rules may be improved in successive versions, so that the effect of tweaking in a given MathML document may grow worse with time. Also, when style sheet mechanisms are extended to MathML, even one version of a renderer may use different spacing rules for users with different style sheets.

Therefore, it is suggested that MathML markup never use <mpadded> or <mspace/> elements to tweak the rendering of specific expressions, unless the MathML is generated solely to be viewed using one specific version of one MathML renderer, using one specific style sheet (if style sheets are available in that renderer).

In cases where the temptation to improve spacing proves too strong, careful use of <mpadded>, <mphantom>, or the alignment elements (Section 3.5.4) may give more portable results than the direct insertion of extra space using <mspace/> or <mtext>. Advice given to the implementors of MathML renderers might be still more productive, in the long run.

Warning: spacing should not be used to convey meaning

MathML elements which permit "negative spacing", namely <mspace/>, <mpadded>, and <mtext>, could in theory be used to simulate new notations or "overstruck" characters by the visual overlap of the renderings of more than one MathML subexpression.

This practice is strongly discouraged in all situations, for the following reasons:

More generally, any construct which uses spacing to convey mathematical meaning, rather than simply as an aid to viewing expression structure, is discouraged. That is, the constructs which are discouraged are those which would be interpreted differently by a human viewer of rendered MathML if all explicit spacing was removed.

If such constructs are used in spite of this warning, they should be enclosed in a <semantics> element which also provides an additional MathML expression which can be interpreted in a standard way.

For example, the MathML expression

<mrow>
   <mpadded width="0"> <mi> C </mi> </mpadded>
   <mspace width="0.3em"/>
   <mtext> | </mtext>
</mrow>

forms an overstruck symbol in violation of the policy stated above; it might be intended to represent the set of complex numbers for a MathML renderer which lacks support for the standard symbol used for this purpose. This kind of construct should always be avoided in MathML, for the reasons stated above; indeed, it should never be necessary for standard symbols, since a MathML renderer with no better method of rendering them is free to use overstriking internally, so that it can still support general MathML input.

However, if for whatever reason such a construct is used in MathML, it should always be enclosed in a <semantics> element such as

<semantics>
   <mrow>
      <mpadded width="0"> <mi> C </mi> </mpadded>
      <mspace width="0.3em"/>
      <mtext> | </mtext>
   </mrow>
   <annotation-xml encoding="mathml">
      <mi> &DoubleStruckCapitalC; </mi>
   </annotation-xml>
</semantics>

which provides an alternative, standard encoding for the desired symbol, which is much more easily interpreted than the construct using negative spacing. (The alternative encoding in this example uses MathML presentation elements; the content elements described in Chapter 4 should also be considered.)

(The above warning also applies to most uses of rendering attributes to alter the meaning conveyed by an expression, with the exception of attributes on <mi> (such as fontweight) used to distinguish one variable from another.)

3.3.7 <mphantom> -- make content invisible but preserve its size

Description:

The <mphantom> element renders invisibly, but with the same size and other dimensions, including baseline position, that its contents would have if they were rendered normally. <mphantom> can be used to align parts of an expression by invisibly duplicating subexpressions.

The <mphantom> element accepts any number of arguments; if this number is not 1, its contents are treated as a single "inferred <mrow>" formed from all its arguments, as described in Section 3.1.3.

It is suggested that audio renderers render <mphantom> elements in an analogous way for their medium, by rendering them as silence of the same duration as the normal rendering of their contents.

Attributes of <mphantom>:

None (except the attributes allowed for all MathML elements, listed in Section 2.3.4).

Note that it is possible to wrap both an <mphantom> and an <mpadded> element around one MathML expression, as in <mphantom><mpadded attribute-settings> ... </mpadded></mphantom>, to change its size and make it invisible at the same time.

MathML renderers should ensure that the relative spacing between the contents of an <mphantom> element and the surrounding MathML elements is the same as it would be if the <mphantom> element were replaced by an <mrow> element with the same content. This holds even if linebreaking occurs within the <mphantom> element.

For the above reason, <mphantom> is not considered spacelike (Section 3.2.6) unless its content is spacelike, since the suggested rendering rules for operators are affected by whether nearby elements are spacelike. Even so, the warning about the legal grouping of spacelike elements may apply to uses of <mphantom>.

There is one situation where the preceding rule for rendering an <mphantom> may not give the desired effect. When an <mphantom> is wrapped around a subsequence of the arguments of an <mrow>, the default determination of the form attribute for an <mo> element within the subsequence can change. (See the default value of the form attribute described in Section 3.2.4.) It may be necessary to add an explicit form attribute to such an <mo> in these cases. This is illustrated in the following example.

Example of <mphantom>:

In this example, <mphantom> is used to ensure alignment of corresponding parts of the numerator and denominator of a fraction:

<mfrac>
   <mrow>
      <mi> x </mi>
      <mo> + </mo>
      <mi> y </mi>
      <mo> + </mo>
      <mi> z </mi>
   </mrow>
   <mrow>
      <mi> x </mi>
      <mphantom>
         <mo form="infix"> + </mo>
         <mi> y </mi>
      </mphantom>
      <mo> + </mo>
      <mi> z </mi>
   </mrow>
</mfrac>

This would render as something like

x + y + z
---------
x     + z

rather than as

x + y + z
---------
  x + z

The explicit attribute setting form="infix" on the <mo> element inside the <mphantom> sets the form attribute to what it would have been in the absence of the surrounding <mphantom>. This is necessary since otherwise, the + sign would be interpreted as a prefix operator, which might have slightly different spacing.

Alternatively, this problem could be avoided without any explicit attribute settings, by wrapping each of the arguments <mo>+</mo> and <mi>y</mi> in its own <mphantom> element, i.e.

<mfrac>
   <mrow>
      <mi> x </mi>
      <mo> + </mo>
      <mi> y </mi>
      <mo> + </mo>
      <mi> z </mi>
   </mrow>
   <mrow>
      <mi> x </mi>
      <mphantom>
         <mo> + </mo>
      </mphantom>
      <mphantom>
         <mi> y </mi>
      </mphantom>
      <mo> + </mo>
      <mi> z </mi>
   </mrow>
</mfrac>

3.3.8 <mfenced> -- surround content with a pair of fences

Description:

The <mfenced> element provides a convenient form in which to express common constructs involving fences (i.e. braces, brackets, and parentheses), possibly including separators (such as comma) between the arguments.

For example, <mfenced> <mi>x</mi> </mfenced> renders as "(x)" and is equivalent to

<mrow> <mo> ( </mo> <mi>x</mi> <mo> ) </mo> </mrow>

and <mfenced> <mi>x</mi> <mi>y</mi> </mfenced> renders as "(x, y)" and is equivalent to

<mrow>
   <mo> ( </mo>
   <mrow> <mi>x</mi> <mo>,</mo> <mi>y</mi> </mrow>
   <mo> ) </mo>
</mrow>

Individual fences or separators are represented using <mo> elements, as described in Section 3.2.4. Thus, any <mfenced> element is completely equivalent to an expanded form described below; either form can be used in MathML, at the convenience of an author or of a MathML-generating program. A MathML renderer is required to render either of these forms in exactly the same way.

In general, an <mfenced> element can contain zero or more arguments, and will enclose them between fences in an <mrow>; if there is more than one argument, it will insert separators between adjacent arguments, using an additional nested <mrow> around the arguments and separators for proper grouping (Section 3.3.1). The general expanded form is shown below. The fences and separators will be parentheses and comma by default, but can be changed using attributes, as shown in the following table.

Attributes of <mfenced>:

Name  values  default 
open  string  
close  string  
separators  character *  

A generic <mfenced> element, with all attributes explicit, looks as follows:

<mfenced open="opening-fence"
         close="closing-fence"
         separators="sep#1 sep#2 ... sep#(n-1)" >
   arg#1
   ...
   arg#n
</mfenced>

The opening-fence and closing-fence are arbitrary strings. (Since they are used as the content of <mo> elements, any whitespace they contain will be trimmed and collapsed as described in Section 2.3.5.)

The value of separators is a sequence of zero or more separator characters (or entity references), optionally separated by whitespace. Each sep#i consists of exactly one character or entity reference. Thus, separators=",;" is equivalent to separators=" , ; ".

The general <mfenced> element shown above is equivalent to the following expanded form:

<mrow>
   <mo fence="true"> opening-fence </mo>
   <mrow>
      arg#1
      <mo separator="true"> sep#1 </mo>
      ...
      <mo separator="true"> sep#(n-1) </mo>
      arg#n
   </mrow>
   <mo fence="true"> closing-fence </mo>
</mrow>

Each argument except the last is followed by a separator. The inner <mrow> is added for proper grouping, as described in Section 3.3.1.

When there is only one argument, the above form has no separators; since <mrow> arg#1 </mrow> is equivalent to arg#1 (as described in Section 3.3.1), this case is also equivalent to:

<mrow>
   <mo fence="true"> opening-fence </mo>
   arg#1
   <mo fence="true"> closing-fence </mo>
</mrow>

If there are too many separator characters, the extra ones are ignored. If separator characters are given, but there are too few, the last one is repeated as necessary. Thus, the default value of separators="," is equivalent to separators=",,", separators=",,,", etc. If there are no separator characters provided but some are needed, for example if separators=" " or "" and there is more than one argument, then no separator elements are inserted at all -- that is, the elements <mo separator="true"> sep#i </mo> are left out entirely. Note that this is different from inserting separators consisting of <mo> elements with empty content.

Finally, for the case with no arguments, i.e.

<mfenced open="opening-fence"
         close="closing-fence"
         separators="anything" >
</mfenced>

the equivalent expanded form is defined to include just the fences within an <mrow>:

<mrow>
   <mo fence="true"> opening-fence </mo>
   <mo fence="true"> closing-fence </mo>
</mrow>

Note that not all "fenced expressions" can be encoded by an <mfenced> element. Such exceptional expressions include those with an "embellished" separator or fence or one enclosed in an <mstyle> element, a missing or extra separator or fence, or a separator with multiple content characters. In these cases, it is necessary to encode the expression using an appropriately modified version of an expanded form. As discussed above, it is always permissible to use the expanded form directly, even when it is not necessary. In particular, authors cannot be guaranteed that MathML preprocessors won't replace occurrences of <mfenced> with equivalent expanded forms.

Note that the equivalent expanded forms shown above include attributes on the <mo> elements which identify them as fences or separators. Since the most common choices of fences and separators already occur in the operator dictionary with those attributes, authors would not normally need to specify those attributes explicitly when using the expanded form directly. Also, the rules for the default form attribute (Section 3.2.4) cause the opening and closing fences to be effectively given the values form="prefix" and form="postfix" respectively, and the separators to be given the value form="infix".

Note that it would be incorrect to use <mfenced> with a separator of, for instance, "+", as an abbreviation for an expression using "+" as an ordinary operator, e.g. <mrow> <mi>x</mi> <mo>+</mo> <mi>y</mi> <mo>+</mo> <mi>z</mi> </mrow>. This is because the + signs would be treated as separators, not infix operators. That is, it would render as if they were marked up as <mo separator="true">+</mo>, which might therefore render inappropriately.

Examples of <mfenced>:

(a+b)

<mfenced>
   <mrow>
      <mi> a </mi>
      <mo> + </mo>
      <mi> b </mi>
   </mrow>
</mfenced>

Note that the above <mrow> is necessary so that the <mfenced> has just one argument. Without it, this would render incorrectly as "(a, +, b)".

[0,1)

<mfenced open="[">
   <mn> 0 </mn>
   <mn> 1 </mn>
</mfenced>

f(x,y)

<mrow>
   <mi> f </mi>
   <mo> &ApplyFunction; </mo>
   <mfenced>
      <mi> x </mi>
      <mi> y </mi>
   </mfenced>
</mrow>


Next: Presentation Markup -- Script and Limit
Up: Table of Contents