TWiki Web>MathModePlugin (2020-05-19, TWikiAdminUser)

MathModePlugin

Page contents

Add math formulas to TWiki topics using LaTeX markup language

Description

This plugin allows you to include mathematics in a TWiki page, with a format very similar to LaTeX. The external program latex2html is used to generate gif (or png) images from the math markup, and the image is then included in the page. The first time a particular expression is rendered, you will notice a lag as latex2html is being run on the server. Once rendered, the image is saved as an attached file for the page, so subsequent viewings will not require re-renders. When you remove a math expression from a page, its image is deleted.

Note that this plugin is called MathModePlugin, not LaTeXPlugin, because the only piece of LaTeX implemented is rendering of images of mathematics.

Syntax Rules

<latex [attr="value"]* > formula </latex>

generates an image from the contained formula. In addition attribute-value pairs may be specified that are passed to the resulting img html tag. The only exeptions are the following attributes which take effect in the latex rendering pipeline:

size: the latex font size; possible values are tiny, scriptsize, footnotesize, small, normalsize, large, Large, LARGE, huge or Huge; defaults to %LATEXFONTSIZE%
color: the foreground color of the formula; defaults to %LATEXFGCOLOR%
bgcolor: the background color; defaults to %LATEXBGCOLOR%

The formula will be displayed using a math latex environment by default. If the formula contains a latex linebreak (\\) then a multline environment of amsmath is used instead. If the formula contains an alignment sequence (& = &) then an eqnarray environment is used.

Note that the old notation using %$formula$% and %\[formula\]% is still supported but are deprecated.

If you might want to recompute the images cached for the current page then append ?refresh=on to its url, e.g. click here to refresh the formulas in the examples below.

Examples

The following will only display correctly if this plugin is installed and configured correctly.

<latex title="this is an example">
  \int_{-\infty}^\infty e^{-\alpha x^2} dx = \sqrt{\frac{\pi}{\alpha}}
</latex>

<latex>
  {\cal P} & = & \{f_1, f_2, \ldots, f_m\} \\
  {\cal C} & = & \{c_1, c_2, \ldots, c_m\} \\
  {\cal N} & = & \{n_1, n_2, \ldots, n_m\}
</latex>

<latex title="Calligraphics" color="orange">
  \cal
  A, B, C, D, E, F, G, H, I, J, K, L, M, \\
  \cal
  N, O, P, Q, R, S, T, U, V, W, X, Y, Z
</latex>

Calligraphics

<latex>
  \sum_{i_1, i_2, \ldots, i_n} \pi * i + \sigma
</latex>

This is new inline test.

Greek letters
`\alpha`		`\theta`
`\beta`		`\iota`
`\gamma`		`\kappa`
`\delta`		`\lambda`
`\epsilon`		`\mu`
`\zeta`		`\nu`
`\eta`		`\xi`

Plugin Installation Instructions

Download the ZIP file

Unzip MathModePlugin.zip in your twiki installation directory. Content:

File:	Description:
`data/TWiki/MathModePlugin.txt`
`lib/TWiki/Plugins/MathModePlugin/Core.pm`
`lib/TWiki/Plugins/MathModePlugin.pm`
`pub/TWiki/MathModePlugin/latex2img`

This plugin makes use of three additional tools that are used to convert latex formulas to images. These are
- a working LaTeX implementation
- dvipng and
- ImageMagick
Make sure they are installed and check the paths to the programs latex, dvipng and convert in the latex2img shiped with this plugin
Edit the file <path-to-twiki>/pub/TWiki/MathModePlugin/latex2img accordingly and set execute permission for your webserver on it
Visit configure in your TWiki installation, and enable the plugin in the {Plugins} section.

Troubleshooting

If you get error like "fmtutil: [some-dir]/latex.fmt does not exist", run fmtutil-sys --all on your server to recreate all latex formatstyles.
If your generated image of the latex formula does not show up, then you probably have encoding issues. Look into the source of the <img>-tag in your page's source code. Non-ASCII characters in file names might cause troubles. Check the localization in the TWiki configure page.

Configuration

There are a set of configuration variables that an be set in different places. All of the below variables can be set in your LocalSite.cfg file like this:

$TWiki::cfg{MathModePlugin}{<Name>} = <value>;

Some of the below variables can only be set this way, some of the may be overridden by defining the respective prefrence variable.

Name	Preference Variable	Default
`HashCodeLength`		32
	length of the hash code. If you switch to a different hash function, you will likely have to change this
`ImagePrefix`		'_MathModePlugin_'
	string to be prepended to any auto-generated image
`ImageType`	%LATEXIMAGETYPE%	'png'
	extension of the image type; possible values are 'gif' and 'png'
`Latex2Img`		'.../TWiki/MathModePlugin/latex2img'
	the script to convert a latex formula to an image
`LatexPreamble`	%LATEXPREAMBLE%	'\usepackage{latexsym}'
	latex preamble to include additional packages (e.g. \usepackage{mathptmx} to change the math font) ; note, that the packages `amsmath` and `color` are loaded too as they are obligatory
`ScaleFactor`	%LATEXSCALEFACTOR%	1.2
	factor to scale images
`LatexFGColor`	%LATEXFGCOLOR%	black
	default text color
`LatexBGColor`	%LATEXBGCOLOR%	white
	default background color
`LatexFontSize`	%LATEXFONTSIZE%	normalsize
	default font size

Plugin Info

Plugin Author:	TWiki:Main.GraemeLufkin, TWiki:Main.MichaelDaum
Copyright:	© 2002 Graeme Lufkin gwl@u.washington.edu; © 2006-2007 Michael Daum http://wikiring.de; © 2007-2011 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2.98
Change History:
2012-12-10	TWikibug:Item7071: MathModePlugin doesn't support multiple disks.
2011-10-17	TWikibug:Item6799: Add troubleshoot info -- TWiki:Main.MatthiasRella
2010-04-25	TWikibug:Item6433: Doc improvements -- TWiki:Main.PeterThoeny
07 Dec 2007:	replaced `templfile` with `mktemp` in the latex2img helper script
13 Nov 2007:	fixed plugin on 4.2
18 Dec 2006:	only use one bgcolor
02 Oct 2006:	don't fail on hierarchical webs; backwards compatible tempfile cleanup
31 Aug 2006:	added NO_PREFS_IN_TOPIC; using `xcolor` instead of `color` latex package now to be able to specify colors in html typical codes; default preamble uses latexsym now
07 Aug 2006:	switched from latex2html to latex+dvipng+convert; added `size`, `color`, `bgcolor` to <latex> tag; rendering pngs by default now; reworked plugin settings; added a latex2img shell script; returning full latex error report
04 Aug 2006:	major rewrite; fixed security issues by using TWiki's sandbox feature and creating tempfiles properly; added new <latex>...</latex> tag to support multiline formulas; better configurability; better error reporting; fixed issues where images have not been cleaned up regularly; speedup don't clean orphaned images during `view` but during `save`; speedup by adding lazy compilation and initialization; implemented a `postRenderingHandler` for TWiki V4; prevent auto-generated images stored in pub from being auto-attached using TWiki V4
03 Apr 2002:	Initial version
CPAN Dependencies:	none
Other Dependencies:	LaTeX, dvipng, ImageMagick
Perl Version:	5.8
TWiki:Plugins/Benchmark:	GoodStyle nn%, FormattedSearch nn%, MathModePlugin nn%
Plugin Home:	TWiki:Plugins/MathModePlugin
Feedback:	TWiki:Plugins/MathModePluginDev
Appraisal:	TWiki:Plugins/MathModePluginAppraisal

Error during latex2img:

ERROR: problems during latex
INPUT:
\documentclass[fleqn,12pt]{article}
\usepackage{amsmath}
\usepackage[normal]{xcolor}
\setlength{\mathindent}{0cm}
\definecolor{teal}{rgb}{0,0.5,0.5}
\definecolor{navy}{rgb}{0,0,0.5}
\definecolor{aqua}{rgb}{0,1,1}
\definecolor{lime}{rgb}{0,1,0}
\definecolor{maroon}{rgb}{0.5,0,0}
\definecolor{silver}{gray}{0.75}
\usepackage{latexsym}
\begin{document}
\pagestyle{empty}
\pagecolor{white}
{
\color{black}
\begin{math}\displaystyle \eta\end{math}
}
\clearpage
{
\color{orange}
\Large
\begin{multline*}\displaystyle \cal
  A, B, C, D, E, F, G, H, I, J, K, L, M, \\
  \cal
  N, O, P, Q, R, S, T, U, V, W, X, Y, Z\end{multline*}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \delta\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \epsilon\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \int_{-\infty}^\infty e^{-\alpha x^2} dx = \sqrt{\frac{\pi}{\alpha}}\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \mu\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \nu\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \lambda\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \xi\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \theta\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \gamma\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \beta\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \iota\end{math}
}
\clearpage
{
\color{black}
\begin{eqnarray*}\displaystyle {\cal P} & = & \{f_1, f_2, \ldots, f_m\} \\
  {\cal C} & = & \{c_1, c_2, \ldots, c_m\} \\
  {\cal N} & = & \{n_1, n_2, \ldots, n_m\}\end{eqnarray*}
}
\clearpage
{
\color{red}
\large
\begin{math}\displaystyle \cal A\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \zeta\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \sum_{i_1, i_2, \ldots, i_n} \pi * i + \sigma\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \kappa\end{math}
}
\clearpage
{
\color{black}
\begin{math}\displaystyle \alpha\end{math}
}
\clearpage
\end{document}
STDERR:
This is pdfTeX, Version 3.1415926-2.5-1.40.14 (TeX Live 2013)
 restricted \write18 enabled.
entering extended mode
(/tmp/3XprJHY4yH/dSHzjJML0c
LaTeX2e <2011/06/27>
Babel  and hyphenation patterns for english, dumylang, nohyphenation, lo
aded.
(/usr/share/texlive/texmf-dist/tex/latex/base/article.cls
Document Class: article 2007/10/19 v1.4h Standard LaTeX document class
(/usr/share/texlive/texmf-dist/tex/latex/base/fleqn.clo)
(/usr/share/texlive/texmf-dist/tex/latex/base/size12.clo
kpathsea: Running mktextfm cmr12
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmr12.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.
kpathsea: Appending font creation commands to missfont.log.

! Font OT1/cmr/m/n/12=cmr12 at 12.0pt not loadable: Metric (TFM) file not found
.
 
                   relax 
l.64 \normalsize
                
)) (/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsmath.sty
For additional information on amsmath, use the `?' option.
(/usr/share/texlive/texmf-dist/tex/latex/amsmath/amstext.sty
(/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsgen.sty))
(/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsbsy.sty)
(/usr/share/texlive/texmf-dist/tex/latex/amsmath/amsopn.sty))
(/usr/share/texlive/texmf-dist/tex/latex/xcolor/xcolor.sty
(/usr/share/texlive/texmf-dist/tex/latex/latexconfig/color.cfg)
(/usr/share/texlive/texmf-dist/tex/latex/graphics/dvips.def))
(/usr/share/texlive/texmf-dist/tex/latex/base/latexsym.sty)
kpathsea: Running mktextfm cmr8
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmr8.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmr6
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmr6.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmmi12
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmmi12.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmmi8
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmmi8.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmmi6
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmmi6.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmsy10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmsy10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmsy8
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmsy8.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmsy6
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmsy6.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmex10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmex10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

No file dSHzjJML0c.aux.
! Font OT1/cmr/m/n/8=cmr8 at 8.0pt not loadable: Metric (TFM) file not found.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OT1/cmr/m/n/6=cmr6 at 6.0pt not loadable: Metric (TFM) file not found.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OML/cmm/m/it/12=cmmi12 at 12.0pt not loadable: Metric (TFM) file not fou
nd.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OML/cmm/m/it/8=cmmi8 at 8.0pt not loadable: Metric (TFM) file not found.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OML/cmm/m/it/6=cmmi6 at 6.0pt not loadable: Metric (TFM) file not found.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OMS/cmsy/m/n/12=cmsy10 at 12.0pt not loadable: Metric (TFM) file not fou
nd.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OMS/cmsy/m/n/8=cmsy8 at 8.0pt not loadable: Metric (TFM) file not found.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OMS/cmsy/m/n/6=cmsy6 at 6.0pt not loadable: Metric (TFM) file not found.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
! Font OMX/cmex/m/n/12=cmex10 at 12.0pt not loadable: Metric (TFM) file not fou
nd.
 
                   relax 
l.17 \begin{math}
                 \displaystyle \eta\end{math}
(/usr/share/texlive/texmf-dist/tex/latex/base/ulasy.fd)
! Math formula deleted: Insufficient symbol fonts.
\endmath ->\relax \ifmmode \ifinner $
                                     \else \@badmath \fi \else \@badmath \fi 
l.17 \begin{math}\displaystyle \eta\end{math}
                                             
[1]
kpathsea: Running mktextfm cmr17
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmr17.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmr10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmr10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmmi12
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmmi12.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmmi10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmmi10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmsy10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmsy10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmsy10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmsy10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmex10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmex10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

kpathsea: Running mktextfm cmex10
/usr/share/texlive/texmf/web2c/mktexnam: Could not map source abbreviation  for cmex10.
/usr/share/texlive/texmf/web2c/mktexnam: Need to update ?
mktextfm: mktexdir ./.texlive2012/texmf-var/fonts/tfm/unknown/unknown failed.

! Font OT1/cmr/m/n/17.28=cmr17 at 17.28pt not loadable: Metric (TFM) file not f
ound.
 
                   relax 
l.22 \Large
           
! Font OT1/cmr/m/n/10=cmr10 at 10.0pt not loadable: Metric (TFM) file not found
.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Font OML/cmm/m/it/17.28=cmmi12 at 17.28pt not loadable: Metric (TFM) file not
 found.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Font OML/cmm/m/it/10=cmmi10 at 10.0pt not loadable: Metric (TFM) file not fou
nd.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Font OMS/cmsy/m/n/17.28=cmsy10 at 17.28pt not loadable: Metric (TFM) file not
 found.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Font OMS/cmsy/m/n/10=cmsy10 at 10.0pt not loadable: Metric (TFM) file not fou
nd.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Font OMX/cmex/m/n/17.28=cmex10 at 17.28pt not loadable: Metric (TFM) file not
 found.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Font OMX/cmex/m/n/10=cmex10 at 10.0pt not loadable: Metric (TFM) file not fou
nd.
 
                   relax 
l.23 \begin{multline*}
                      \displaystyle \cal
! Math formula deleted: Insufficient symbol fonts.