Configuring MathFlow for oXygen

Overview, MathFlow configuration

Behind the scenes, MathFlow consists of executable components integrated with the oXygen Editor via JavaScript code. The executable components and most of the script code do not depend on the specific document type with which MathFlow is being used. However, some of the script code must deal with the particular way in which MathML elements have been incorporated into a document-level markup language. This script code must be customized to work with specific document types.

Setting up a document type for use with MathFlow consists of the following general tasks:

Integrating the MathML DTD into your DTD for the document-level markup. The sample document types (doctype for short) included with oXygen have already integrated the MathML DTD into the doctype, assuming you have chosen an appropriate one for math.
Adding the ‹math› element to your customization file
Defining DTD-specific macros to call the corresponding MathFlow macros
Setting the MathML namespace prefix for the custom doctype
Adding an entry for the ‹math› element to the cascading stylesheet
Adding an entry for the ‹math› element to the HTML stylesheet

Not all of this is covered in this documentation.

Setting up a custom doctype

This information is on a separate page.

Font style management

Overview, font style management

MathFlow allows users to style characters and expressions by requesting particular font faces, weights and slants. While users can specify any font, weight or slant in the underlying MathML markup, what MathFlow actually renders is limited by the availability of fonts on the system. On Windows systems, MathFlow uses two rendering engines, a Java-based engine for the Editor, and a Win32-based engine for preview images and PDF composition. The font and style behavior of both engines is similar, but there are some differences in details as described below.

There are three cases that must be distinguished to understand how MathFlow selects fonts:

Default Rendering

When no explicit style information is specified, the MathFlow rendering engines apply internal algorithms to select fonts. The Java engine firsts attempts to locate characters in a set of preferred system fonts: Times New Roman for alphanumeric characters, Euclid Symbol for common symbol characters, and Code 2000 for rarer symbol characters. Note that Euclid Symbol is included with MathFlow but Code 2000 must be obtained separately. The choice of preferred system fonts is configurable. See Configuring preferred fonts.

When characters cannot be located in MathFlow preferred system fonts, the Java engine also contains built-in fonts containing around 500 symbol characters and will use these fonts instead. Characters that cannot be located either in preferred system fonts or internal fonts render as missing glyphs, generally represented by an empty box. In these cases, explicitly specifying a system font known to contain the character is generally the best solution.

The Win32 rendering engine employs a similar, but more complex model. Characters are first sought in a collection of preferred system fonts, primarily Times New Roman, Symbol and MT Extra. For certain classes of characters, Mathematica fonts, Euclid fonts, and/or Adobe's Mathematical Pi fonts may also be utilized. When characters cannot be located in preferred fonts, the rendering engine searches all available system fonts. At this point, there is no control over the order in which fonts are searched, which can lead to unpredictable results. As in the Java case, explicitly specifying a system font known to contain the character is generally the best solution.

Pre-defined MathML Styles

MathML contains twelve pre-defined logical styles, such as "sans-serif" and "script." When one of these styles is selected, both the Java and Win32 engines reformulate these requests in terms of specific fonts. As above, the renderers first look for characters in preferred fonts, and then fall back to either internal fonts or other system fonts, depending on the rendering engine.

User-defined Custom Styles

For user-defined custom styles, both engines will attempt to literally honor the request. If the specified font is not available, an attempt is made to render the character in some font containing the character. If no font can be found, the character is rendered with a missing glyph indicator.

Styles in MathML markup

MathFlow enables the use of user-defined custom styles definitions as described in Customizing font styles. Custom styles are represented in the MathML markup by attributes specifying style names. Here we give more details about how the association between the style name and the actual font being used is managed.

All character data in a MathML expression must be contained in a token element (MI, MO, MN, MTEXT, etc.) The font used to render the character data is determined by the values of the "mathvariant", "class", "fontfamily", "fontweight" and "fontslant" attributes. The last three attributes are deprecated by MathML 3.0 and are not generated by MathFlow (though they are still honored by the MathFlow rendering engine.) The values for any of these attributes may either be set explicitly on token elements, or inherited from a parent element, usually an MSTYLE element.

When several of these attributes are used, MathFlow uses the following precedences in determining which of them controls the font:

Explicit "mathvariant" values
Inherited "mathvariant" values
Explicit "class" values
Inherited "class" values
Explicit "fontfamily" "fontweight" and "fontslant" values
Inherited "fontfamily" "fontweight" and "fontslant" values

Both the "mathvariant" and "class" values are interpreted as specifying all three components of the fonts specification -- family, weight and slant. Thus, the "mathvariant" value "bold" actually specifies a serif font face, in bold weight, with normal (upright) slant.

To illustrate the above precedence rules, consider and example. If we define the style "myArial" to have family="Arial", weight="normal" and slant="automatic", then the following will display the x in an Arial, normal, upright font, and the y in serif, bold, upright (since mathvariant="bold" takes precedence over fontstyle="italic"):

<math>
  <mstyle mathvariant="bold" fontstyle="italic">
    <mi class="myArial">x</mi><mo>+</mo><mi>y</mi>
  </mstyle>
</math>

Whereas this will display the x in a serif, bold, upright font, and the y in Arial, normal, italic:

<math>
  <mstyle class="myArial" fontstyle="italic">
    <mi mathvariant="bold" >x</mi><mo>+</mo><mi>y</mi>
  </mstyle>
</math>

Custom Font Styles

MathFlow stores the custom font styles you have defined in a file, so that it can be reused from session to session. This file can also be edited directly as a more convenient way of defining a large number of styles, to be shared among many users.

The file in question is named .mfstyles and is stored in the same directory as your MathFlow preferences file, usually the following on Windows systems: C:\Users\<username>.

Font style language

The font style definition file has an XML syntax with seven elements:

<styles>

The root element that can contain any number of <style> elements.

<style>

Each <style> element must contain one <label> element and one <fontspec> element. It is an error if either of these is missing or appears more than once.

<label>

The name of the style.

If the inner text of this element matches the value of the class attribute in a MathML element, then that MathML element will be stylized according to the <fontspec> element that is a sibling of this <label>.

<fontspec>

This can contain 0-3 of the following three elements which describe the font characteristics of the style. If any of these elements are omitted, the corresponding font characteristic adopts a default value listed below.

<fontfamily> - Accepted values are any legal font family name, or "inherited". Default is "inherited".
<fontweight> - Accepted values are "normal", "bold" or "automatic". Default is "automatic".
<fontslant> - Accepted values are normal, italic or automatic. Default is "automatic".

For example, the following code defines two font styles named my Arial, my Arial2, and myEmphasis:

<styles>
  <style>
    <label>myArial</label>
    <fontspec>
      <fontfamily>Arial</fontfamily>
      <fontweight>normal</fontweight>
      <fontslant>automatic</fontslant>
    </fontspec>
  </style>
  <style>
    <label>myArial2</label>
    <fontspec>
      <fontfamily>Arial</fontfamily>
      <fontweight>bold</fontweight>
      <fontslant>normal</fontslant>
    </fontspec>
  </style>
  <style>
    <label>myEmphasis</label>
    <fontspec>
      <fontfamily>inherited</fontfamily>
      <fontweight>bold</fontweight>
      <fontslant>italic</fontslant>
    </fontspec>
  </style>
</styles>

Configuring preferred fonts

The MathFlow Java rendering engine first attempts to render characters using a collection of four preferred system fonts. The specific system fonts to be used may be identified through the use of a configuration file as described below. Internally, MathFlow considers all characters as belonging in one of the following four broad classes:

ALPHA_NUMERIC
GREEK
SYMBOL
EXTRA SYMBOL

The SYMBOL class corresponds to characters found in the standard Adobe Symbol encoding. EXTRA SYMBOL is a catch-all for everything else. MathFlow associates the following numerical values with the following four classes of characters:

ALPHA_NUMERIC = 100
SYMBOL = 101
EXTRA_SYMBOL = 102
GREEK = 103

The default font associations are as follows:

100=Times New Roman
101=Euclid Symbol
102=Code2000
103=Euclid Symbol

To modify the font associations that will be used by MathFlow Editor, create a file named "FontMapping.opt" and place it in this folder:

Windows: C:\Users\<username>

Write four lines in the file, one for each character class of the form NNN=<font name>, as shown above. Once you restart MathFlow these fonts will become the preferred system fonts for character display.

Example

In this example, you need all of the characters that are alpha-numeric to use the system font "Arial." To do this, you will need to change the ALPHA_NUMERIC value (ID is 100 in the FontMapping.opt file) to Arial, rather than Times New Roman as shown above. To accomplish this, use the following FontMapping.opt file:

100=Arial
101=Euclid Symbol
102=Code2000
103=Euclid Symbol

This mapping will cause every character MathFlow identifies as an "alpha numeric" character to be displayed in the specified font. Be aware that if you use the wrong font name in FontMapping.opt, you will not see the correct font. It will use MathFlow internal font if it can't find the system font listed in the file. It is possible to pick any system font, but be aware that most system fonts do not contain glyphs for non-alphanumeric characters. Euclid Symbol is a high quality font for common symbol characters, and you will generally not need to change it. However, Code 2000 is a lower-quality, shareware font whose main appeal is that it has exceptionally comprehensive coverage of Unicode, and depending on what symbols you need, you may wish to replace it with a higher quality font. The "GREEK" font defaults to Euclid symbol, since it has high-quality Greek characters, but high-quality fonts with Greek characters in other styles are not uncommon. In general, you may need to experiment to make sure that the system fonts that you pick contain the proper glyph for the Unicode characters you plan to use.

Configuring the operator dictionary

Operators have certain properties that are set in an Operator Dictionary, such as the size of the space to the left or right of the operator, how it changes when in display or inline style, how it stretches, etc.

MathFlow sets these properties to sensible values, but in some instances you may want to fine-tune them by editing the file containing the definitions of those properties, mfopdict.txt. We've included a sample mfopdict.txt file located in the <path-to-mathflow>\2.1\auxiliary directory. We recommend making a backup copy of this file before you edit it.

Format of the configurable operator dictionary

The properties (e.g., spacing) may be different according to the position of the operator in the formula; whether it is in the middle (infix), at the beginning (prefix), or the end (postfix) of an expression. To reflect this, mfopdict.txt should have three tables, each one started by a line with its name: INFIX, PREFIX, or POSTFIX. It is also possible to change the default spacing for all operators (only the spacing, not other properties), by writing a line with an operator name of "default". Values that are not explicitly set for an operator, or not in a "default" line for spacing use MathFlow's internal values.

In brief:

Empty lines are ignored.
Lines starting with // are considered comments and are ignored.
Operators can be more than a single character.
There are three keywords: INFIX, PREFIX, and POSTFIX to indicate the beginning of each table. Each one should appear in a line by itself.
Each meaningful line is a comma-separated list, in the form opname, lspace, rspace [, largeop=true|false, stretchy=true|false, accent=true|false, moveablelimits=true|false, dsi:linebreakop=true|false, dsi:stretchby=segments|scaling, dsi:scaleratiopct=integer].
- opname is a character, a MathML entity name, or a numerical reference (#xNNNN for hexadecimal, #NNNN for decimal). For example, comma could be represented by the name "comma", the character ",", or the numerical references #x02C or #44.
- lspace and rspace are numbers+unit, where the optional unit could be 'u' (1/100 em) or 'em'. The default is 'u'.
- The other properties should come at the end of the line, and are optional. See the table below for further description of each property.
Default spacings for each table can be given by using opname='default'
Numerical references start with #, e.g. #x3b1 (hexadecimal reference) or #2271 (decimal reference).
Do not include spaces at the ends of the lines.

Example:

////////////////////////////////////////////////
INFIX
////////////////////////////////////////////////
default, 17, 17
minus, 33, 33
plus, 33, 33
sum, 33, 33, moveablelimits=false
////////////////////////////////////////////////
PREFIX
////////////////////////////////////////////////
default, 17, 17
plus, 3em, 5
sum, 33, 33, moveablelimits=false
////////////////////////////////////////////////
POSTFIX
////////////////////////////////////////////////
plus, 5u, 3em
sum, 33, 33, moveablelimits=true

This mfopdict.txt file changes the default spacing of all INFIX and PREFIX operators to 0.17em on both sides, but uses MathFlow default values for postfix operators. The INFIX minus operator has different spacing (0.33em on both sides), and the same is true for the INFIX plus and sum operators. The INFIX sum operator also has the moveablelimits property set to false. In the prefix table, the PREFIX plus gets a larger left space (3em) and a smaller right space (0.05em). Lastly, the sum operator will have moveablelimits when used as a POSTFIX operator.

In this section: