Note to Firefox users: If you are seeing numerous square boxes (they look like this:
) in the guide below, it means your MathML fonts are not up to date.
They can be updated here: Firefox MathML fonts. If you are using an up-to-date version of Firefix (3.0+), see the Mozilla 1.9, STIX (BETA) FONTS at the above link.
Using MathToWeb
MathToWeb will convert any text file containing mathematical expressions written
in AMS-Latex to MathML. In this respect, the file extension is of no importance, it could
be: *.txt, *.xml, *.htm, etc., MathToWeb
will convert them all in the same way. The file extension does become important when it comes to displaying
your documents in a browser however, and the *.xml extension, along with the mandatory declarations found in the template below
are recommended for this purpose.
MathToWeb can be downloaded as a graphics-based program (a picture of which can be seen on the
home page) or a command-line program. The former is very simple to use: simply select a file (one that contains
AMS-Latex math expressions that you would like converted to MathML) and press the 'Convert' button. For information on the using the command-line
version, click here.
Regardless of which version you use (graphics or command-line), MathToWeb will create a separate file into which it
will place your converted text. It will put this file in the same directory as the source file and name it by
tacking '_MathToWeb_###' to the original file name.
MathToWeb can be used in one of two general ways:
Place just your Latex math expressions in one or more text files. Convert these (one at a time) to
MathML using MathToWeb (it will create separate files containing your converted MathML for each) and move
this text to your main document as it develops. The main document must be built from the template below or
at least, have the same declarations. This web site was constructed in such a way.
Embed your Latex math expressions within the final document (based on the template below) and
have MathToWeb convert this to MathML. MathToWeb will identify the Latex math environments within the
document and insert MathML in their place. Again, a separate file will be created containing your final,
converted text.
There are a few things to be aware of before writing documents containing MathML.
MathML is an XML application and web pages that use it must comply with strict XML syntax rules.
This can be achieved by writing your web pages in a form of HTML called XHTML (see the Wiki page on XHTML).
It is not difficult to conform to the XHTML standard. Four essential rules follow:
All tags must be written in lower-case letters. For example, one would write <h1>, not <H1>.
Tags must be closed. For example, <p>...</p> and <br />.
Tags must be nested correctly. Don't do this: <u><b>x</u></b>; instead, write: <u><b>x</b></u> or <b><u>x</u></b>
Attributes must be enclosed in quotation marks (either single or double). For example: style="font-size: 11px;".
Below is a template that contains all the necessary XHTML declarations etc. that
are required to have MathML display properly in a browser. It should be copied and saved to a text file
with an .xml extension (for example, my_web_page_template.xml).
Within the body of this template you'll find a couple of example equations written in Latex. These can be deleted and
replaced with your own work; however, before doing this, it is instructive to convert the template, as is, to MathML.
This simple procedure is explained below.
Testing the template
Copy the template to a text file and save it in a directory of your choice as test.xml.
(You can name it anything you like, but be sure it has an .xml extension.)
It has been pointed out in the Support Forum recently (Feb. 2008), that
[Windows-Vista + MathPlayer plug-in + IE7] may object to the .xml file extension, but .xhtml can be used
successfully in its place. All other browsers are fine with the .xml extension.
Use the 'Browse' button of MathToWeb to locate and open the above file (an image of MathToWeb is on the home page).
Press the 'Convert' button. MathToWeb will identify all AMS-Latex math environments in the present document
and convert them to MathML.
* A separate file will be created containing your converted text. In this instance, it will be named:
test_MathToWeb_000.xml.
View this file using the 'Open File...' command on your browser's 'File' menu; or just press the
'View in Firefox' button (you must have Firefox installed if running Windows - the button uses
the default browser in other operating systems).
To convert the template using the command-line version, click here.
Template for web pages that will contain MathML
Math environments
MathToWeb parses only on AMS-Latex math environments,
either inline formulae such as $...$, or display environments such as \begin{equation}...\end{equation},
with only a few exceptions (such as cross-references to equations), it generally ignores everything else.
A complete list of math environments that MathToWeb recognizes follows, and there is more information on
each of them individually below.
Inline environments
$...$
\(...\)
Display environments
equation
multline
gather
align
flalign
alignat
equation*
multline*
gather*
align*
flalign*
alignat*
Specialized environments
subequations
Subordinate environments
split
cases
gathered
aligned
alignedat
An 'inline environment' places the equation in question within the text in which it is declared, so that it reads as part of the sentence.
A 'display environment' places the equation on a separate line of its own, so that it stands out from other text.
The starred forms (e.g. equation*) of the above display environments are unnumbered and they are used when no cross-references to a particular equation will be made.
MathToWeb does not support flalign and alignat (or their starred forms) at this time.
Actually, flalign and flalign* can be used, but they are treated in a similar fashion to align and align*.
There are two environments available to break up single long equations into multiple lines or
rows: multline and split.
Both use \\ to specify the start of new rows; however, they differ in that split
allows for alignment points to be specified using &.
A subordinate environment must be used inside a display environment.
split must be used inside: equation, gather or align (or their * forms).
Do not use it inside multline or multline*.
cases, gathered and aligned, must be used inside equation or equation*.
MathToWeb requires a \tag{<your-tag>} declaration to be made on all un-starred display
environments: equation, multline, gather and align, as well as on subequations.
This tells MathToWeb what equation number is to be displayed for the math environment in question, and it displays
it in parentheses. For example,
The command \tag*{...} is also supported, for example, \tag*{iv}, and
it causes the text that you supply to be typeset literally, with no parentheses being added.
These two commands, \tag, and \tag*, while being supported by AMS-Latex, are not generally
used except to override an automatically generated number. For this reason, we will
colour these commands light blue (\tag) in the examples below, to mean that
their usage is MathToWeb specific (supported, but not required in Latex).
In addition, the command \notag can be used to suppress particular numbers on the multi-number
display environments: align and gather.
The command must be placed to the immediate left of the row
separator \\, as follows, ...(a+b+c) \notag\\, on the line
in which the number is to be suppressed.
\label{<your-label>} declarations are required in both Latex and MathToWeb if a
particular equation is to be cross-referenced (see Cross-referencing your equations). There are several
examples in the list below. Note that it is customary to use hyphens '-' to break up multi-word label names
rather than underscores '_', because the latter is the Latex command for 'subscript'. It is also common to see
colons used in label names to separate an initial short word describing what is being labelled
from the desired label name itself. For example,
\label{eq:hamiltonian-for-system} uses 'eq:' in the label name to specify that this is an 'equation'.
Other short prefixes used in this manner are: 'eq:' (equation), 'fig:' (figure), 'sec:' (section).
MathToWeb's implementation of multline left-aligns the first row, centre-aligns the middle row (or rows), and right-aligns the last row, as
can be seen in the above example.
This behaviour can be modified by applying the commands
\shoveleft and \shoveright, which take as their argument the entire row
in question, excluding the row separator \\. These commands are used only on the
middle rows and have the effect of forcing them left or right. An example using \shoveright is below.
align permits alignment points to be specified using & and rows by
\\, and is commonly
used to vertically align two or more equations, usually on binary operators such as equal signs (the
example above illustrates this).
Alignment for this environment is actually as follows: right & left & right & left & right & left ... .
To have numbering suspended on a particular row, place a \notag command instead of \tag{...}\label{...}.
The subordinate environment split can be used within the align environment (see the section on split below).
The spacing around the equal sign in the above example is not optimal. This problem is being addressed and it
is hoped that a solution will be at hand in the near future.
\text{...} can be used inside any of the math environments, but in case of align, it
is often used to annotate a multi-line equation line-by-line
(the example below illustrates this).
There a couple of things to note regarding this example:
\notag is used to suspend numbering on the second line (the first row is numbered 1.9, the second has no tag, the last is 2.0).
References to other equations using the command \ref{...} (or \eqref{...}) are made
from inside \text{...} calls.
MathToWeb treats references (which are, in fact, just links) that are inside MathML differently that those that are outside.
Looking at the MathML for the example below,
we see that the hyperlinks representing cross-references (which are inside MathML code) are actually XML xlink calls made from <mrow> tags, for example, <mrow xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:href="#align-eq1">1.6</mrow>, rather
than normal HTML hyperlinks <a href="#align-eq1">1.6</a>. The former is necessary for
links inside MathML, which is an XML application. Although not illustrated here, MathToWeb
does use the latter mentioned HTML links for cross-references outside of
MathML code (see Cross-referencing your equations for more on this topic).
numbered by parent environment as a single equation
split must be used inside: equation, gather or align (or their * forms).
Do not use it inside multline or multline*.
The subordinate environment split allows a single equation to be
broken into multiple lines in such a way that rows are marked by \\ and alignment points by &.
Each split has associated with it just one equation number (see 2.1 in example below, and
1.4 in the example below that).
splitinsideequation
In this instance, split must constitute the entire body of the equation.
numbered by parent environment as a single equation
gathered and aligned must be used inside: equation or equation*.
These environments exist primarily to allow delimiters to be placed around multi-lined equation structures, as
a whole, something that can not done using gather or align because these expand to the full
width of the line, allowing nothing else.
For example, one might try the following in order to place curly braces
around an align structure; however, such a construct will produce an error, both in Latex and MathToWeb.
There are a couple of points to note regarding the above example:
\left. is used in place of \left\{, to insert a
'phantom delimiter' that does not appear, but which makes the necessary match
with the automatically sized right pairing delimiter \right\}. Recall that the \left and \right
commands cause the pairing delimiters \{ and \} to be automatically sized. (MathToWeb also supports \right.). Looking at the MathML for this example, we see
that <mphantom>...</mphantom> tags are used to accomplish this effect.
On the second-last line we have \text{$Y_0$ equations}. A \text{...} call, in which there exists a nested inline math
environment, $Y_0$. This is allowed in Latex and MathToWeb.
\begin{cases}
...
\end{cases}
subordinate
numbered by parent environment as a single equation
numbered subordinately using lower-case Latin letters (a, b, c,...) relative to the parent number.
With subequations you get a reference to the entire equation group (see "\label{eq:group}" below which is numbered 2.7).
The multi-equation display environments that can be used within subequations are: gather, align and flalign.
(The * forms of these are permissible also, however, there is not much point in this.)
MathToWeb supports the command \intertext{...} which is used to insert short interjectional
remarks in the middle of multi-line display environments, while at the same time preserving alignment.
\intertext can be used only within: gather, gather*, align, align*, flalign, flalign* and split.
Do not use it inside: multline, multline*, gathered, aligned and cases.
The command must be placed right after a \\ (see the example below).
Any single word or short phrase can be used in an \intertext statement. For example: "and" or "it follows that".
The following example was borrowed from section 3.10 of AMS User's Guide for the amsmath Package (Version 2.0)
(\tag{...} and \label{...} commands have been added).
The position of the word "and" is significant here. Notice that it is aligned on the page margin, rather than the equation margin.
The commands \cdots and \ldots are also supported by MathToWeb, although
the AMS literature
encourages the use of the more
semantically oriented commands: \dotsb, \dotsc, \dotsi, \dotsm and \dotso .
Care must be taken when using the following characters which are
used internally by Latex and MathToWeb.
Each must be preceded by a \ character (a backslash) in order to have it interpreted
properly, as the list below illustrates.
Note particularly, that curly braces are in this list.
\# \$ \% \& \~ \_ \^ \\ \{ \}
Note: MathToWeb processes only the contents of Latex math environments, one of which
is delimited by dollar symbols, $...$ (see AMS math environments).
If a dollar symbol is present anywhere else in a given document, either inside or outside of a math environment,
it must be escaped using \$.
MathToWeb recognizes standard HTML/XML comments:
<!-- --> .
It will skip-over any text between these delimiters, so if it is desirable to temporarily comment out certain LaTeX
equations contained in your document, it can be done in this way.
(Note: The ' used above for both single and double primes is the single quotation mark from the keyboard.)
• Single or multiple characters can be underlined using code such as \underline{A} which
is rendered as
A‾. A practical example is below.
• Any symbol can be typeset below or above a particular base character using the commands
\underset and \overset. \underset{*}{A}→A*\overset{*}{Z}→Z*
The \frac command takes two arguments, the numerator being the first and the denominator the second.
(At present, MathToWeb has limited support \dfrac and \tfrac (d=display-style, t=text-style), in that
it will display them in the same way it does \frac.)
(At present, MathToWeb has limited support \dbinom and \tbinom (d=display-style, t=text-style), in that
it will display them in the same way it does \binom.)
(ab)$\binom{a}{b}$
Top and bottom embellishments
abcde˜
\widetilde{abcde}
abcde^
\widehat{abcde}
abcde‾
\overline{abcde}
abcde‾
\underline{abcde}
abcde⏞
\overbrace{abcde}
abcde⏟
\underbrace{abcde}
abcde⟵
\overleftarrow{abcde}
abcde⟵
\underleftarrow{abcde}
abcde⟶
\overrightarrow{abcde}
abcde⟶
\underrightarrow{abcde}
abcde⟷
\overleftrightarrow{abcde}
abcde⟷
\underleftrightarrow{abcde}
In addition, \overbrace can take a superscript and \underbrace a subscript:
\xleftarrow and \xrightarrow will widen automatically to accommodate the width
of their superscripts and subscripts. These commands allow one optional argument (in square brackets)
that represents the subscript, and have one mandatory argument (in curly braces) that represents the
superscript.
Pairing delimiters (see the next section) will not adjust their height to enclose their contents unless you specifically request
it. This can be achieved using a pair of \big... prefixes (see the list below), which set
the delimiters to a particular fixed size, or by using \left and \right, which
causes auto-sizing.
The second example illustrates the use of the commands \left \right which auto-size the
parentheses on which they act (these are absent in the first example, for comparison).
In the last example above, we have matched a \lvert
delimiter (on the left), to a \rangle delimiter (on the right) and vise versa,
demonstrating the point that any left pairing delimiter can, in fact, be matched to any right pairing
delimiter.
Note: MathToWeb pre-defines the function \abs{x}→|x| so that it can be used directly.
In Latex, recommended practice is to place the following command in the preamble: \providecommand{\abs}[1]{\lvert#1\rvert}
(see section 6.2, Short Math Guide for Latex, version 1.09).
The light-blue coloured operator names such as \arcsinh are
supported by MathToWeb, but not by Latex where they would be handled using the command \DeclareMathOperator
or \operatorname, see below (MathToWeb supports the latter).
Limits
lim
\lim
lim inf
\liminf
lim sup
\limsup
lim⟵
\varprojlim
lim⟶
\varinjlim
lim‾
\varliminf
lim‾
\varlimsup
inj lim
\injlim
proj lim
\projlim
The command \textstyle can be applied to: \lim , \liminf and
\limsup . See the first two limit examples below.
Other
arg
\arg
deg
\deg
det
\det
dim
\dim
exp
\exp
gcd
\gcd
hom
\hom
inf
\inf
ker
\ker
lg
\lg
ln
\ln
log
\log
max
\max
min
\min
Pr
\Pr
sup
\sup
Defining your own named operator using \operatorname{..}
Below we have defined a named operator which we call "skew": \operatorname{skew}(x)→skew(x)
Note: The most common Latex command for declaring new named operators is
\DeclareMathOperator. This command is not yet supported by MathToWeb.
Examples:
cos2t=1+cos2t2$\cos^2 t = \frac{ 1 + \cos{2t} }{ 2 }$MathML
logax=lnxlna$\log_a x = \frac{\ln x}{\ln a}$MathML
The above two examples are identical, with the exception that in the second, we have applied \textstyle
to the \lim operator.
Forcing \textstyle on an operator such as \lim has the effect of shifting
underscripts to subscripts and overscripts to superscripts, making the equation compact (in the vertical direction)
and more suitable for inline display.
MathToWeb makes this command available
for: \lim, \liminf and \limsup.
Text can be inserted into the LaTeX of any equation environment using
\text{...}.
It is important to note that, if required, inline LaTeX enviroments (i.e. $...$)
can be nested within text,
e.g. \text{this inline equation, $A_i$ is nested within the text} (see the third example below).
The examples below should be adequate to demonstate the use of this command.
AmeansB$A \; \text{means} \; B$(Recall that \; is a thick space. Below we use \qquad, a double quad space.)
Using \newcommand{..}[..]{..} and \renewcommand{..}[..]{..}
Use \newcommand to create your own Latex commands which you name and define using known Latex.
The command \renewcommand differs slightly from \newcommand, in that it is used
to over-write an existing Latex command. (Note: Use only lower- or upper-case letters when defining command-names, e.g. \mycommand{..}[..]{..}.)
These are good commands to use when the same Latex occurs at multiple locations in a particular document.
Instead of typing it over and over, simply define a new command to represent it, and place that in your document
at all the locations where it is required.
To use these commands with MathToWeb, place the \newcommand and \renewcommand
declarations in HTML comments - anywhere in the document (see the example below).
The syntax of these commands is as follows: ('number of arguments', the optional argument in square brackets, must be an integer between 0 and 9 inclusive.)
\newcommand{\command-name}[number of arguments]{command text, using #1, #2 etc. to denote arguments}
As of version 2.0.3 (command-line variant only, at the moment), \newcommand declarations can be
declared in an external text file and 'brought in' to a particular document using the -ncf option. An
example of a command-line call using this option follows (the external \newcommand declarations
are in myncf.txt):
>java -jar mathtoweb.jar -ncf myncf1.txt test.xml
If it is desirable to include more than one new-command file, separate them using commas, as follows:
The following math font switches are supported by MathToWeb: \mathbf, \mathbb,
\mathcal, \mathfrak, \mathit and \mathsf.
There use is described in more detail below.
Most math symbols can be rendered in bold type using the command
\boldsymbol or \pmb ("poor man's bold").
These are meant to be applied to only one symbol at a time.
The \textstyle command can be applied to any of the above operators. It must be placed
so that it immediately precedes the operator on which it acts, for example $\textstyle\int xdx$ (several
examples are below).
∑0≤i≤m0≤j≤nAij$\sum_{\substack{0 \le i \le m \\ 0 \le j \le n}} A_{ij}$
limx→x∘∈Bx∈DI(x,t)$\lim_{\substack{x \to x^\circ \in B \\ x \in D}} \; I(x,t)$
The \nolimits command
The \nolimits command can be used to force limits from an over/under configuration
to that of superscript/subscript. It must be placed immediately to the right of the base to which it applies (see the examples below).
∫abf(x)dx$\int_a^b f(x)\,dx$⟶ compare to ∫abf(x)dx$\int\nolimits_a^b f(x)\,dx$
Note: When requiring "textstyle", MathToWeb will sometimes give more satisfactory results if
\nolimits is used in addition to \textstyle (see the examples below).
Note: Although it hasn't been shown, the matrix structures below must be placed inside some sort of math environment
to have them display properly in a browser.
The unnumbered display environment, \begin{equation*} ... \end{equation*} works well for
the purpose of testing.
\begin{matrix}
a&b\\
c&d
\end{matrix}
abcd
\begin{smallmatrix}
a&b\\
c&d
\end{smallmatrix}
abcd
To place pairing delimiters such as parentheses around this:
This example was borrowed from section 3.4 of AMS User's Guide for the amsmath Package (Version 2.0).
(One addition to this code was made, the \tag{1} command on the second line, which is required by MathToWeb, but optional in Latex.)