View source for Testwiki:Rendering math

{{About||the help page|Help:Displaying a formula|the WikiProject|Wikipedia:WikiProject Mathematics|Wikipedia's mathematics style manual|Wikipedia:Manual of Style/Mathematics}}
{{essay}}
{{nutshell|There exist at least three different forms of math formulae on Wikipedia pages, with at least seven ways to present them. None is completely satisfactory.}}
This essay offers a comparison of different encodings and presentation of mathematical formulae. The three principal ones are the {{tag|math|o}} tag, raw wiki (or HTML) code, and "texhtml" templates. The {{tag|math|o}} and "texhtml" encoding may have different presentations for registered users, depending on user preferences and personal styles.

== Comparison of markup encodings ==
{| class="wikitable"
! Encoding
! Advantages
! Disadvantages
|-
! scope=row | {{tag|math|o}}LaTeX{{tag|math|c}}
|
* Well-known and standardized.
* Portable to/from scientific papers.
* Clearly distinguishes semantics from appearance.
* Flexible and can handle all formulae.
* Easy for other software to process.
|
* Requires knowledge of [[LaTeX]] markup language.
* Lacks Unicode support — cannot use Unicode for mathematical operators, [https://phabricator.wikimedia.org/T165751] or for [[Cyrillic script|Cyrillic]] and other scripts. [https://phabricator.wikimedia.org/T50032]
* Unable to place wikilinks on parts of formulae.
|-
! scope=row | Raw [[wikicode|wiki]] or [[HTML]] code
|
* Built into [[MediaWiki]].
|
* Encodes appearance rather than its semantics.
* Difficult to process in software.
* Unable to handle square roots, vertical fractions, and other common formula types.
* Proper use (italic variables, protected spaces around operators) requires care and is a frequent source of mistakes.
|-
! scope=row | "texhtml" templates, such as {{tl|math}}
|
* Encourages standardized notation.
* Distinguishes semantics from appearance.
* More polished appearance than wiki/HTML code.
* Recognizable (although not easily processed) by software.
|
* Proliferation of templates
* Vulnerable to changes and edit wars.
* Produces html nesting errors when the surrounding text is italicized (e.g. hatnotes, reference titles, or the {{tl|unsolved}} template), making some other solution necessary in those contexts.
* Not able to handle some complex formulas.
* The equal ([[=]]) and [[Vertical bar|pipe]] ({{!}}) symbols require special care (the {{tl|{{=}}}} and {<nowiki />{[[Template:!|!]]}<nowiki />} templates or other workarounds must be used).
|}

== Comparison of presentations ==
{| class=wikitable
|- 
!Encoding
!Presentation
!Advantages
!Disadvantages
|-
! rowspan="5" scope="row" | {{tag|math|o}}
! scope=row | [[SVG]] with hidden [[MathML]]<br />(Wikipedia's default)
|
* More polished than the PNG below.
| rowspan = 2| 
* Images do not match article text in font size.
* Images do not usually have proper baseline alignment for inline math.
* Images do not change color when part of a link.
* Copy-paste as text duplicates the formula's source code, copy-paste as image is not supported in many programs e.g. Word.
|-
! scope=row | [[Portable Network Graphics|PNG]]
|
* Robust.
* Little overhead in a browser.
|-
! scope=row | Native [[MathML]]
|
* Robust and standard-compliant.
* Little overhead in Firefox.
* Supported by screen readers.
|
* Requires [[mw:Extension:Math#Viewing_math|special user CSS and/or plugins]] for full functionality like copy-paste.
* Only works well in Firefox.
* Not well-documented.
|-
! scope=row | [[MathJax]]
|
* Works in all browsers.
* Pretty fonts.
* Working copy-paste.
|
* High server load for font assets.
* Slow rendering.[https://phabricator.wikimedia.org/T99369#1478321]
* No longer available as a reader preference. See [[phab:T99369#1484437|T99369#1484437]] for how to manually inject a script (without using WMF servers).
|-
![[KaTeX]]
|
* Faster than MathJax.
* Same advantages as above.
* Has \operatorname*.
|
* Support for commands still incomplete.
* Has never been available as a user preference. See [[phab:T99369#6970581|T99369#6970581]] for how to use it anyways.
|- style="border-top: 2px solid;"
!scope=row colspan=2 |{{anchor|raw presentation}}Raw wiki or HTML code
|
* Avoids switching font families in running text.
* Minimal overhead.
* Appearance does not depend on user (account) preferences.
|
* Does not distinguish a formula from the running text.
* The default sans-serif may render certain characters indistinguishable, such as 1, I and l.
* In articles mixing raw wiki with {{tag|math|o}} formulae, the appearance of the same variable in the two types of formula does not match (serif vs sans-serif).
|- style="border-top: 2px solid;"
!scope=row colspan=2 | {{anchor|texhtml presentation}}{{tl|math}} ('texhtml' class)
|
* Distinguishes a formula from the running text.
* Close match to the appearance of inline {{tag|math|o}}.
|
* Mixing of font families (sans-serif for English, serif for math), in running text, can be jarring.
* Reverts to the appearance of raw wiki code on systems that don't support font changes (e.g. the Wikipedia Android app)
* Not an exact match to {{tag|math|o}} formulas in the same article
** uses ''Times'' font, not ''Computer Modern'' as in TeX; text generally look thinner.
** occasional kerning problems due to mixture of italics and roman: {{math|''f''(''x'')}}; {{math|1=(λ''x''.''M'')}}. See {{tlx|italics correction}}.
* Cannot be used within most citation templates
|-
! colspan=4 | Specific {{visible anchor|templates}}
|-
!scope=row colspan=2 | {{tl|mvar}}: {{mvar|x}}
|
* A shorthand for variables like <code><nowiki>{{math|''x''}}</nowiki></code>.
* Clean semantics.
|
* Cannot be used for vectors. (Must use <code><nowiki>{{math|'''v'''}}</nowiki></code> to get {{math|'''v'''}}, <code><nowiki>{{math|{{vec|''v''}}}}</nowiki></code> to get {{math|{{vec|''v''}}}}.)   
|-
!scope=row colspan=2 | {{tl|sqrt}}: {{sqrt|2}}
|
* Clean semantics.
|
* The vinculum is slightly interrupted.
* Does not look well under {{tl|math}} or so, itself. (<code><nowiki>{{math|{{sqrt|2}}}}</nowiki></code> yields: {{math|{{sqrt|2}}}}.)
* Discouraged by [[MOS:RADICAL]].
|-
!scope=row colspan=2 | {{tl|radic}}: {{radic|2|3}}
|
* Clean semantics.
|
* Same as above. (<code><nowiki>{{math|{{radic|2|3}}}}</nowiki></code> yields: {{math|{{radic|2|3}}}}.)
* Discouraged by [[MOS:RADICAL]].
|-
!scope=row colspan=2 | {{tl|sfrac}}: {{sfrac|1|2}}
|
* Clean semantics.
* Encouraged by [[MOS:FRAC]] for math and science articles only. 
|
* Occupies too much vertical space in a running text. Embedded sub- and superscript causes vertical misalignment. (<code><nowiki>yadda {{math|{{sfrac|1|2}}}} yadda</nowiki></code> yields: yadda {{math|{{sfrac|1|2}}}} yadda.)
|-
!scope=row colspan=2 | {{tl|frac}}: {{frac|1|2}}
|
* Clean semantics.
|
* [[MOS:FRAC]] discourages this for math and science articles only; for other topics this is often preferred.
|-
!scope=row colspan=2 | {{plainlist|
* {{tl|open-open}}: {{open-open|−∞, +∞}}
* {{tl|open-closed}}: {{open-closed|−∞, 0}}
* {{tl|closed-open}}: {{closed-open|0, +∞}}
* {{tl|closed-closed}}: {{closed-closed|0,1}}
}}
|
* Semantically distinguishes [[interval (mathematics)|intervals]] from other types of formulae.
|
* Because the interval endpoints are coded as a single parameter, the semantics is a bit obscure.
|-
!scope=row colspan=2 | [[Bra–ket notation]]:
* {{tl|ket}} {{ket|''ψ''}}
* {{tl|bra}} {{bra|''ψ''}}
* {{tl|bra-ket}} {{bra-ket|''ψ''|''ξ''}}
|
* Semantically distinguishes [[bra–ket notation]] from other types of formula.
* Avoids complex html coding for angular bracket characters ⟨ <code>&amp;#x27E8;</code> or {{tl|langle}}, ⟩ <code>&amp;#x27E9;</code> or {{tl|rangle}}, and vertical bar &#124; <code>&amp;#124;</code> and prevents incorrect usage of less-than/greater-than signs for these characters.
|
* Angular brackets may not render on all browsers. <!---yes: at root this is a problem the template has--->
|-
!scope=row colspan=2 | {{tl|vec}}: {{vec|''A''}}
|
* Clean semantics.
|
* The arrow is not centered over italicized letters.
* The arrow is too high over x-height letters. (<code><nowiki>{{math|{{vec|''v''}}}}</nowiki></code> yields: {{math|{{vec|''v''}}}}.)
|-
!scope=row colspan=2 | {{tl|intmath}}: {{intmath|int|0|+∞}}
|
* Clean semantics.
|
* Name differs from math/LaTeX coding conventions.
|-
!scope=row colspan=2 | {{plainlist|
* {{tl|overset}}: {{overset|→|''A''}}, {{overset|~|''A''}}
* {{tl|underset}}: {{underset|→|''A''}}, {{underset|~|''A''}}
}}
|
* Clean semantics.
|
* Produces bad spacing when combined with fraction templates.
|}

===Pros of HTML===

# Formulas in HTML behave more like regular text. In-line HTML formulae always align properly with the rest of the HTML text and, to some degree, can be copied-and-pasted (this is not a problem if TeX is rendered using [[w:MathJax|MathJax]], and the alignment should not be a problem for PNG rendering now that [[phab:T34694|bug 32694]] is fixed).
# The formula's background and font size match the rest of HTML contents (this can be fixed on TeX formulas by using the commands [[#Color|<syntaxhighlight lang="latex" inline>\pagecolor</syntaxhighlight> and <syntaxhighlight lang="latex" inline>\definecolor</syntaxhighlight>]]) and the appearance respects CSS and browser settings while the typeface is conveniently altered to help you identify formulae.
# Pages using HTML code for formulae will load faster and they will create less clutter on your hard disk.
# Formulae typeset with HTML code will be accessible to client-side script links (a.k.a. scriptlets).
# The display of a formula entered using mathematical templates can be conveniently altered by modifying the templates involved; this modification will affect all relevant formulae without any manual intervention.
# The HTML code, if entered diligently, will contain all semantic information to transform the equation back to TeX or any other code as needed. It can even contain differences TeX does not normally catch, e.g. <syntaxhighlight lang="wikitext" inline>{{math|''i''}}</syntaxhighlight> for the [[w:imaginary unit|imaginary unit]] and <syntaxhighlight lang="wikitext" inline>{{math|<var>i</var>}}</syntaxhighlight> for an arbitrary index variable.
# Unlike generated bitmaps, HTML is not sensitive to [[w:Dots per inch|dots per inch]] variances between viewing platforms.

===Pros of TeX===

# TeX is semantically more precise than HTML.
## In TeX, "<syntaxhighlight lang="latex" inline>x</syntaxhighlight>" means mathematical variable "<math>x</math>", whereas in HTML "<syntaxhighlight lang="latex" inline>x</syntaxhighlight>" is generic and somewhat ambiguous.
## On the other hand, if you encode the same formula as "<syntaxhighlight lang="wikitext" inline>{{math|<var>x</var>}}</syntaxhighlight>", adding the var tag doesn't affect the visual result {{math|''x''}} and provides the additional semantic description that x is a variable. This requires diligence and more typing that could make the formula harder to understand as you type it, and provides no help to most readers, but could be worth considering if no other rendering options are available.
# One consequence of point&nbsp;1 is that TeX code can be transformed into HTML, but not vice versa.{{Ref |dilHTML}} This means that on the server side we can always transform a formula, based on its complexity and location within the text, user preferences, type of browser, etc. Therefore, where possible, all the benefits of HTML can be retained, together with the benefits of TeX. It is true that the current situation is not ideal, but that is not a good reason to drop information or contents. It is more a reason to [[WP:Bug reports and feature requests|help improve the situation]].
# Another consequence of point&nbsp;1 is that TeX can be converted to [[w:MathML|MathML]] (e.g. by MathJax) for browsers which support it, thus keeping its semantics and allowing the rendering to be better suited for the reader’s graphic device.
# TeX is the preferred text formatting language of most professional mathematicians, scientists, and engineers. It is easier to persuade them to contribute if they can write in TeX.
# TeX has been specifically designed for typesetting formulae, so input is easier and more natural if you are accustomed to it, and output is more aesthetically pleasing if you focus on a single formula rather than on the whole containing page.
# Once a formula is done correctly in TeX, it will render reliably, whereas the success of HTML formulae is somewhat dependent on browsers or versions of browsers. Another aspect of this dependency is fonts: the serif font used for rendering formulae is browser-dependent and it may be missing some important glyphs. While the browser is generally capable to substitute a matching glyph from a different font family, it need not be the case for combined glyphs (compare "''{{IPA|a&#773;}}''" and " ''a̅''").
# When writing in TeX, editors need not worry about whether this or that version of this or that browser supports this or that HTML entity. The burden of these decisions is put on the software. This does not hold for HTML formulae, which can easily end up being rendered wrongly or differently from the editor’s intentions on a different browser.{{Ref |browsupp}}
# TeX formulae, by default, render larger and are usually more readable than HTML formulae and are not dependent on client-side browser resources, such as fonts, and so the results are more reliably WYSIWYG.
# While TeX does not assist you in finding HTML codes or Unicode values (which you can obtain by viewing the HTML source in your browser), copying and pasting from a TeX PNG image in Wikipedia into simple text will return the LaTeX source.

: <small>{{Note |dilHTML | |Unless your wikitext follows the style of point&nbsp;1.2}}</small>
: <small>{{Note |browsupp | |The entity support problem is not limited to mathematical formulae though; it can be easily solved by using the corresponding characters instead of entities, as the character repertoire links do, except for cases where the corresponding glyphs are visually indiscernible (e.g. &amp;ndash; for &lsquo;&ndash;&rsquo; and &amp;minus; for &lsquo;&minus;&rsquo;).}}</small>

In some cases it may be the best choice to use neither TeX nor the HTML substitutes, but instead Unicode or the simple ASCII symbols of a standard keyboard.

== Discussions ==
* [[Help:Displaying a formula]]
* [[Wikipedia talk:MOSPHYS]]
* [[Wikipedia talk:WikiProject Mathematics/Archive/2013/Jan #Destruction of .7B.7Bmath.7D.7D and similar templates]]
* [[Phabricator:T99369|Discussion about MathJax vs MathML and the future of math formatting on Wikipedia]]

== See also ==
* [[Wikipedia:WikiProject Mathematics/Typography]]
* [[Wikipedia:texvc]], a {{tag|math|o}} to HTML converter; not used for HTML anymore
* [[:Category:Mathematical formatting templates]]

{{Wikipedia technical help|collapsed}}
[[Category:Mathematics Wikipedia administration]]