== Overview ==

Fonts with appropriate Unicode coverage and Open Font Format features are required for good math rendering. Maintainers of WebKit ports and operating systems should ensure that such fonts are available to get more reliable results on MathML tests and to maximize user experience. WebKit users encountering troubles with the rendering of MathML are encouraged to check that such a font is installed on their system. They are also invited to configure the default math font to match their preference.

== Recommended Math Fonts ==

Here is a list of known math fonts that can be used to render MathML formulas in WebKit:

* [http://www.ctan.org/tex-archive/fonts/Asana-Math/ Asana Math]
* [http://www.microsoft.com/typography/fonts/family.aspx?FID=360 Cambria Math]
* [http://www.gust.org.pl/projects/e-foundry/lm-math Latin Modern Math]
* [https://github.com/khaledhosny/libertinus Libertinus Math]
* [http://tug.org/store/lucida/opentype.html Lucida Bright Math]
* [http://www.typoma.com/en/fonts.html Minion Math]
* [http://sourceforge.net/projects/stixfonts/files/Current%20Release/STIXv1.1.1-word.zip/download STIX Math]
* [http://www.gust.org.pl/projects/e-foundry/tg-math/download/index_html#Bonum_Math TeX Gyre Bonum Math]
* [http://www.gust.org.pl/projects/e-foundry/tg-math/download/index_html#Pagella_Math TeX Gyre Pagella Math]
* [http://www.gust.org.pl/projects/e-foundry/tg-math/download/index_html#Schola_Math TeX Gyre Schola Math]
* [http://www.gust.org.pl/projects/e-foundry/tg-math/download/index_html#Termes_Math TeX Gyre Termes Math]
* [https://github.com/khaledhosny/xits-math/releases XITS Math]

This list essentially corresponds to known fonts that have an Open Font Format MATH table (for a complete list of required features and unicode coverage see the sections below). Latin Modern Math is recommended for users who are familiar with [https://en.wikipedia.org/wiki/Computer_Modern TeX's Computer Modern style]. The STIX family provides the best unicode coverage but it has many bugs that will only be fixed in version 2. These two fonts form the recommended minimal set to consider for maintainers and the default option to try for users. XITS Math also has many features for Arabic and right-to-left math.

== Customizing Math Font ==

The default font-family on the `<math>` tag is not inherited but set to a list of known math fonts. Authors or readers of MathML equations can easily customize it by adding the following CSS rule to the author/user style sheet:

{{{
  math {
     font-family: "My Fancy Math Font";
  }
}}}

For best rendering, it is recommended to use text font and math font that have consistent style. For example, authors can use the following stylesheet to display their page with the "Latin Modern" style:

{{{
  body {
     font-family: "Latin Modern Roman";
  }
  math {
     font-family: "Latin Modern Math";
  }
}}}

For more information, see this [https://github.com/fred-wang/MathFonts/  page with Web fonts, sample CSS style sheets and online demos].

== Unicode Coverage ==

In order to display various scientific and technical symbols, math fonts should cover the largest possible subset of [https://www.w3.org/TR/xml-entity-names/#blocks Unicode Character Ranges for Scientific Documents] and more specifically:

* [https://www.w3.org/TR/xml-entity-names/#alphabets Mathematical Alphanumeric Characters]

* [https://www.w3.org/TR/MathML3/appendixc.html#oper-dict.entries-table Operators from the MathML dictionary].

Mathematical Alphanumeric Characters are required to display variables with their default mathematical italic style and to support the `mathvariant` attribute. However, the former is currently done with CSS ([https://bugs.webkit.org/show_bug.cgi?id=155018 bug 155018]) and the latter is not implemented yet ([https://bugs.webkit.org/show_bug.cgi?id=108778 bug 108778]).

== Open Font Format features ==

Development is in progress to [http://www.mathml-association.org/MathMLinHTML5/ make our MathML support rely on TeX rules and Open Font Format features features]. These Open Font Format features are available in the recommended math fonts listed above.

=== MathConstants table ===

These are layout constants for example the default thickness of fraction bar. Here is the implementation status:

 * ScriptPercentScaleDown: no
 * ScriptScriptPercentScaleDown: no
 * DelimitedSubFormulaMinHeight: no
 * DisplayOperatorMinHeight: yes
 * MathLeading: no
 * AxisHeight: partial ([https://bugs.webkit.org/show_bug.cgi?id=133567 bug 133567])
 * AccentBaseHeight: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * FlattenedAccentBaseHeight: no
 * SubscriptShiftDown: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SubscriptTopMax: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SubscriptBaselineDropMin: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SuperscriptShiftUp: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SuperscriptShiftUpCramped: no ([https://bugs.webkit.org/show_bug.cgi?id=156401 bug 156401])
 * SuperscriptBottomMin: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SuperscriptBaselineDropMax: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SubSuperscriptGapMin: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SuperscriptBottomMaxWith: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * SpaceAfterScript: yes ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918])
 * UpperLimitGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * UpperLimitBaselineRiseMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * LowerLimitGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * LowerLimitBaselineDropMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * StackTopShiftUp: no ([https://bugs.webkit.org/show_bug.cgi?id=155714 bug 155714])
 * StackTopDisplayStyleShiftUp: no ([https://bugs.webkit.org/show_bug.cgi?id=155714 bug 155714])
 * StackBottomShiftDown: no ([https://bugs.webkit.org/show_bug.cgi?id=155714 bug 155714])
 * StackBottomDisplayStyleShiftDown: no ([https://bugs.webkit.org/show_bug.cgi?id=155714 bug 155714])
 * StackGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155714 bug 155714])
 * StackDisplayStyleGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155714 bug 155714])
 * StretchStackTopShiftUp: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * StretchStackTopShiftUp: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * StretchStackBottomShiftDown: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * StretchStackGapAboveMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * StretchStackGapBelowMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * FractionNumeratorShiftUp: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionNumeratorDisplayStyleShiftUp: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionDenominatorShiftDown: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionDenominatorDisplayStyleShiftDown: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionNumeratorGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionNumDisplayStyleGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionRuleThickness: yes
 * FractionDenominatorGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * FractionDenomDisplayStyleGapMin: no ([https://bugs.webkit.org/show_bug.cgi?id=155639 bug 155639])
 * SkewedFractionHorizontalGap: no
 * SkewedFractionVerticalGap: no
 * OverbarVerticalGap: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * OverbarRuleThickness: no
 * OverbarExtraAscender: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * UnderbarVerticalGap: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * UnderbarRuleThickness: no
 * UnderbarExtraDescender: no ([https://bugs.webkit.org/show_bug.cgi?id=155756 bug 155756])
 * RadicalVerticalGap: yes
 * RadicalDisplayStyleVerticalGap: no ([https://bugs.webkit.org/show_bug.cgi?id=155638 bug 155638])
 * RadicalRuleThickness: yes
 * RadicalExtraAscender: yes
 * RadicalKernBeforeDegree: yes
 * RadicalKernAfterDegree: yes
 * RadicalDegreeBottomRaise: yes

=== MathGlyphInfo table ===

Currently, we only use italic correction to position subscripts of large operators ([https://bugs.webkit.org/show_bug.cgi?id=153918 bug 153918]).

=== MathVariants table ===

This table is very important for displaying larger variants of operators (via the MathGlyphVariantRecord table) as well as stretching to an arbitrary size (via a GlyphAssembly table). Note that our support for glyph assemblies is limited to a restricted syntax with at most 3 pieces and a same extender connecting them. Some examples of why it is needed:

* operator in display style like big integrals, summation symbols, etc
* vertical stretching of radicals, fences, arrows etc
* horizontal stretching of accents, braces, arrows, etc

=== Tags ===

Nothing has been implemented yet. The following tags should be considered: `math`, `ssty`, `flac`, `dtls` and `rtlm`.

== Obsolete Fonts and Fallback Mechanisms ==

Some old fonts with good math Unicode coverage that do not have the Open Font Format features mentioned above can still be used to provide minimal support with the help of some fallback mechanisms included in WebKit. So for example:

* Everything that relies exclusively on Unicode coverage will work for these fonts too.
* stretched vertical parenthesis, brackets, braces, ceilings, floors, bars and integral sign can be drawn via the characters U+007C, U+2016, U+2225, U+2320, U+2321, U+239B, U+239C, U+239D, U+239E, U+239F, U+23A0, U+23A1, U+23A2, U+23A3, U+23A4, U+23A5, U+23A6, U+23A7, U+23A8, U+23A9, U+23AA, U+23AB, U+23AC, U+23AD, U+23AE instead of using the MathVariants table.
* stretched radical symbols are drawn with hardcoded drawing paths instead of reading the MathVariants table.

However, all of this should be considered a way to workaround the lack of proper math fonts. In particular, note that:

* Any larger variants or glyph assembly not listed above can not be done without the MathVariants table (e.g. stretched arrows, horizontal braces, big operators in display style etc).
* Layout constants from the MathConstants table are set to some arbitrary values based on x-height or font size (hence alignment, positions, shifts, gaps and so on may be bad or totally wrong).
* Italic correction from the MathGlyphInfo table is considered to be zero (so e.g. placement of subscript attached to integrals may be wrong).