MathModePlugin < TWiki

---+!! <nop>%TOPIC%
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/MathModePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/MathModePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Description

This plugin allows you to include mathematics in a TWiki page, with a format very similar to <nop>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 <nop>LaTeXPlugin, because the only piece of <nop>LaTeX implemented is rendering of images of mathematics.

---++ Syntax Rules

<b>&lt;latex [attr="value"]* &gt; =formula= &lt;/latex&gt;</b>

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 %<nop>LATEXFONTSIZE%
   * =color=: the foreground color of the formula; defaults to
      %<nop>LATEXFGCOLOR%
   * =bgcolor=: the background color; defaults to
      %<nop>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 =%<nop>$formula$%= and =%<nop>\[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 *[[%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%?refresh=on][here]]* to refresh the formulas in the examples below.

---++ Examples

The following will only display correctly if this plugin is installed and configured correctly.
<verbatim>
<latex title="this is an example">
  \int_{-\infty}^\infty e^{-\alpha x^2} dx = \sqrt{\frac{\pi}{\alpha}}
</latex>
</verbatim>
<latex title="this is an example">
  \int_{-\infty}^\infty e^{-\alpha x^2} dx = \sqrt{\frac{\pi}{\alpha}}
</latex>

<verbatim>
<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>
</verbatim>

<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>

<verbatim>
<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>
</verbatim>

<latex title="Calligraphics" color="orange" size="Large">
  \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>

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

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

This is <latex color="red" size="large">\cal A</latex> new inline test.

| *Greek letters* ||||
| =\alpha= | <latex>\alpha</latex> | =\theta= | <latex>\theta</latex> |
| =\beta= | <latex>\beta</latex> | =\iota= | <latex>\iota</latex> |
| =\gamma= | <latex>\gamma</latex> | =\kappa= | <latex>\kappa</latex> |
| =\delta= | <latex>\delta</latex> | =\lambda= | <latex>\lambda</latex> |
| =\epsilon= | <latex>\epsilon</latex> | =\mu= | <latex>\mu</latex> |
| =\zeta= | <latex>\zeta</latex> | =\nu= | <latex>\nu</latex> |
| =\eta= | <latex>\eta</latex> | =\xi= | <latex>\xi</latex> |

---++ Plugin Installation Instructions

   * [[http://twiki.org/p/pub/Plugins/%TOPIC%/%TOPIC%.zip][Download]] the ZIP file
   * Unzip ==%TOPIC%.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 <nop>LaTeX implementation 
      * [[http://sourceforge.net/projects/dvipng/][dvipng]] and
      * [[http://www.imagemagick.org/][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 =&lt;path-to-twiki>/pub/%SYSTEMWEB%/%TOPIC%/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 &lt;img&gt;-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:
<verbatim>
$TWiki::cfg{MathModePlugin}{<Name>} = <value>;
</verbatim>
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 |
| &nbsp; | length of the hash code. If you switch to a different \
           hash function, you will likely have to change this ||
| =ImagePrefix= | | '_MathModePlugin_' |
| &nbsp; | string to be prepended to any auto-generated image ||
| =ImageType= | %<nop>LATEXIMAGETYPE% | 'png' |
| &nbsp; | extension of the image type; \
           possible values are 'gif' and 'png' ||
| =Latex2Img= | | '.../%SYSTEMWEB%/%TOPIC%/latex2img' |
| &nbsp; | the script to convert a latex formula to an image ||
| =LatexPreamble= | %<nop>LATEXPREAMBLE% | '\usepackage{latexsym}' |
| &nbsp; | 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= | %<nop>LATEXSCALEFACTOR% | 1.2 |
| &nbsp; | factor to scale images  ||
| =LatexFGColor= | %<nop>LATEXFGCOLOR% | black |
| &nbsp; | default text color ||
| =LatexBGColor= | %<nop>LATEXBGCOLOR% | white |
| &nbsp; | default background color ||
| =LatexFontSize= | %<nop>LATEXFONTSIZE% | normalsize |
| &nbsp; | default font size ||

---++ Plugin Info
<!-- provided for compatibility only
   * Set SHORTDESCRIPTION = Add math formulas to TWiki topics using <nop>LaTeX markup language
-->
|  Plugin Author: | TWiki:Main.GraemeLufkin, TWiki:Main.MichaelDaum |
|  Copyright: | &copy; 2002 Graeme Lufkin gwl@u.washington.edu; <br /> &copy; 2006-2007 Michael Daum http://wikiring.de; <br /> &copy; 2007-2011 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2.98 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  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 &lt;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 &lt;latex>...&lt;/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: | <nop>LaTeX, dvipng, <nop>ImageMagick |
|  Perl Version: | 5.8 |
|  TWiki:Plugins/Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | TWiki:Plugins/%TOPIC% |
|  Feedback: | TWiki:Plugins/%TOPIC%Dev |
|  Appraisal: | TWiki:Plugins/%TOPIC%Appraisal |
Attachments
Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
ext	latex2img	r1	manage	1.1 K	2013-05-07 - 03:25	TWikiAdminUser	Saved by install script
This topic: TWiki > MathModePlugin
Topic revision: r3 - 2016-07-04 - TWikiAdminUser
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.MathModePlugin.