LatexModePlugin

This LaTeX Mode TWiki Plugin allows you to include LaTeX mark up commands within a TWiki page. It uses external programs (specifically latex, dvipng or dvips-and-convert, or mimetex) to generate png or gif images from the mark up. These images are then included in the rendered TWiki page. The first time a particular image is generated, there may be a significant lag in page rendering as the images are generated 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.

This plugin expands the functionality provided by the TWiki:Plugins.MathModePlugin.

Syntax Rules

The plugin interprets a number of delimiters to declare LaTeX markup strings. For example, if the LatexModePlugin is successfully installed, the string \int_{-\infty}^\infty e^{-\alpha x^2} dx = \sqrt{\frac{\pi}{\alpha}} will render as an image $\int_{-\infty}^\infty e^{ -\alpha x^2 } dx = \sqrt{ \frac{\pi}{\alpha} }$, when enclosed within the defined delimiters.

Standard Syntax

This plugin has two standard modes:

  • in-line, declared by %$ $%. Similar to LaTeX's inline math mode, the math markup is rendered on the same line as other text in the string.
  • own-line, declared by %\[ \]% or %MATHMODE{ ... }%. These equations will be rendered with center justification on their own line.

For the majority of users, these commands should be sufficient

Example

This is an example of the \LaTeX rendering possibilities using the LatexModePlugin.

The singular value decomposition of a matrix $A$ is defined as
  \begin{displaymath} A = U \Sigma V^H \end{displaymath} (1)

where $U$ and $V$ are both matrices with orthonormal columns, $\{\cdot\}^H$ indicates a complex-conjugate transpose, and $\Sigma$ is a diagonal matrix with singular values

\[ \sigma_1 > \sigma_2 > \cdots > \sigma_n \geq 0 \]
along the main diagonal. Eq. (1) is just one of the many matrix decompositions that exists for matrix $A$.

After the plugin has been succesfully installed and configured, this example should render like this:

expl-v1.4.png

Extended Syntax

For those that are well familiar with LaTeX, a multi-line syntax allowing more complicated markup commands can be declared using

%BEGINLATEX%
  \begin{<environment>}
	 _latex markup_ 
  \end{<environment>}
%ENDLATEX%
Typically, the declared <environment> will be displaymath, although there is no limitation.

Additional options can be included to modify the rendered result. These include

option possible values default description
inline 0 or 1 0 controls inline vs ownline rendering
label alpha-numeric --- produces a linkable equation number for ownline markup
density positive integer 116 (set below) controls rendered font size
scale positive number 1.0 (set below) sets post-rendered image scaling
gamma positive number 0.6 (set below) controls rendered font darkness
bgcolor --- 'white' sets background color (details below)
color --- 'black' sets foreground font color (details below)
attachment alpha-numeric --- allows one to couple the latex command with an attached file. Useful for latex graphics commands.
engine {"", "dvipng", "ps", "pdf", "mimetex"} "" dynamically switch the rendering engine between the installation default (""), dvipng, dvips+convert, pdflatex+convert, or mimetex for LaTeX packages than need it, e.g. tikz. (details below)

For example, to declare an equation to be numbered by TWiki (not in the LaTeX image) with a larger font size and in red, use the following syntax:

%BEGINLATEX{label="eq1" density="175" color="red"}%

latex markup

%ENDLATEX%

HTML references to LaTeX equations with a defined <label> can be generated using %REFLATEX{<label>}%.

Rendering options

Both DENSITY and SCALE alter the rendered image size and quality. For example, if one doubles the DENSITY and halves the SCALE, the rendered image resolution will improve but keep the same image size on the rendered page. (Note: DENSITY * SCALE is the same in both cases)

density = 116, scale = 2.0 :
 \[ \mathcal{A } \]
density = 232, scale = 1.0 :
 \[\mathcal{A}\]

For regular browser viewing, the SCALE parameter sould be set to 1.0. However, one can use these parameters to improve print quality when printing a topic. To do this, increase the DENSITY setting (a value of 300 will give roughly 300dpi) and then set the SCALE setting below 1.0.

Font Color

As of v1.3, one can now directly control the foreground font color in the rendered mathematics. This is achieved through use of the color.sty package in the intermediate latex file.

Latex is able to render colors defined in 3 color spaces: gray, rgb, and cmyk. A limited number of colors are predefined in Latex. These include:

color color space color space value
black gray 0
white gray 1
red rgb 1,0,0
green rgb 0,1,0
blue rgb 0,0,1
cyan cmyk 1,0,0,0
magenta cmyk 0,1,0,0
yellow cmyk 0,0,1,0

For convenience, the following TWiki colors are pre-defined in the LatexModePlugin

   \definecolor{Red}{rgb}{1,0,0}
   \definecolor{Blue}{rgb}{0,0,1}
   \definecolor{Yellow}{rgb}{1,1,0}
   \definecolor{Orange}{rgb}{1,0.4,0}
   \definecolor{Pink}{rgb}{1,0,1}
   \definecolor{Purple}{rgb}{0.5,0,0.5}
   \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{Green}{rgb}{0,0.5,0}
   \definecolor{Olive}{rgb}{0.5,0.5,0}
   \definecolor{Maroon}{rgb}{0.5,0,0}
   \definecolor{Brown}{rgb}{0.6,0.4,0.2}
   \definecolor{Black}{gray}{0}
   \definecolor{Gray}{gray}{0.5}
   \definecolor{Silver}{gray}{0.75}
   \definecolor{White}{gray}{1}

To use additional colors, they need to be defined in the Latex preamble, as described in the next section.

Including images in LaTeX markup

v3.0 introduced the ability to include attachments in the latex markup processing. This is most useful for graphics, e.g.

%BEGINLATEX{attachment="fig1.eps"}%

  \includegraphics{fig1.eps}

%ENDLATEX%

It is common practice in LaTeX, however, to not specify the filename extension. This is implemented in the Plugin as well, so one could type:

%BEGINLATEX{attachment="fig1"}%

  \includegraphics{fig1}

%ENDLATEX%

and the plugin will search for an attachment with extension '.eps', '.eps.gz', '.pdf', '.png', or '.jpg'. The first extension match will be used, and the rendering engine that can recognize the attachment will also be automatically determined. So for the example above, if a file 'fig1.eps' is attached to the topic, it will be used as the attachment and dvips+convert will be automatically chosen as the rendering engine.

Switching the rendering on the fly

v3.3 introduced the ability to switch rendering dynamically between dvipng, dvips+convert, and pdflatex+convert. Some latex packages are not supported by the preferred method dvipng, for example TikZ and PGF. Rather than force all rendering to use a slower background rendering engine, this switch allows one to use dvipng rendering as the default, but fall back to 'ps' or 'pdf' intermediate files in certain cases.

If you type:
%BEGINLATEX{ engine="ps"}%

\fbox{ 
  \begin{tikzpicture}[auto,bend right] 
    \node (a) at (0:1) {$0^\circ$}; 
    \node (b) at (120:1) {$120^\circ$}; 
    \node (c) at (240:1) {$240^\circ$}; 
    \draw (a) to node {1} node [swap] {1'} (b) 
          (b) to node {2} node [swap] {2'} (c) 
          (c) to node {3} node [swap] {3'} (a); 
  \end{tikzpicture} 
} 

%ENDLATEX%
    It will render as:

TiKZ example

This enables a wide variety of LaTeX packages to be used within TWiki. For example: simple image manipulations using the graphicx package. Note that the package must be declared in the LaTeX preamble.

If you type:
%BEGINLATEX{attachment="fig2.png" engine="pdf"}%

  \includegraphics[angle=30,scale=0.25]{fig2.png}

%ENDLATEX%
    It will render as:

rotation example

Tables, Figures, and cross-references

To round out the functionality available in standard LaTeX, the automatic generation of Figure and Table reference links is also available. These are declared using

  • %BEGINFIGURE{label="fig:label" caption="this is a figure" span="twocolumn"}% ... %ENDFIGURE%, and
  • %BEGINTABLE{label="tbl:label" caption="this is a table" span="twocolumn"}% ... %ENDTABLE%.

These commands will create an HTML table with a numbered caption either above (TABLE) or below (FIGURE) the included text. Cross-references to these declared environments can be accessed through %REFLATEX{<label>}%. To keep the counters/cross-references seperate for each of the three types of references, use eq: or eqn:, fig:, and tbl: as the first characters in any declared label.

The span option is used only by TWiki:Plugins.GenPDFLatex, giving the ability to designate the width of a table or figure in two-column styles. (e.g. for Figures, it expands to \begin{figure*} ... \end{figure*}.) The default span is one-column.

Sections can be numbered and labeled, for easy cross-referencing. To label a section, add a %SECLABEL{_label_}% tag after the TWiki section command. E.g.,

   ---++ %SECLABEL{sec:intro}% Introduction
Cross-references to the label can be generated using %REFLATEX{sec:intro}%.

To add automatic numbering to the sections, set the following parameter to a non-zero number. Sections up to this depth will be numbered.

  • Set MAXSECDEPTH = 3
The default setting is '0', which disables the numbering and section labels.

Defining the LaTeX preamble

In LaTeX, the preamble is used to customize the latex processing, allowing one to add custom styles and declare new commands.

In TWiki, the preamble can be set as either a web or topic preference variable

   * #Set PREAMBLE = \usepackage{color} \definecolor{Aqua}{rgb}{0,1,1}
or as a multi-line declaration, using the tags:
   %BEGINLATEXPREAMBLE% ... %ENDLATEXPREAMBLE%

One critical difference between the two exists. With the exception of the color declarations above, the TWiki preference setting will override the default settings, and is intended to provide site administrators a central point to set preamble settings globally. In contrast, the tag declaration will add to the preamble defined by either the default settings or the preference setting, allowing TWiki users to amend the preamble.

Common Symbols

Since the LatexModePlugin is not installed on TWiki.org the above external html reference is given so that you can see what the symbols are. For those who do use Latex in your TWiki install, you can copy the tables formatted for TWiki from the following topics (the symbols won't actually display without the plugin).

What to type to get a variety of symbols using Latex. Due to page loading constraints, the symbols tables are split up into 5 different topics.

Plugin Settings

Plugin settings are stored as preferences variables. To reference these plugin settings write %<plugin>_<setting>%, i.e. %LATEXMODEPLUGIN_SHORTDESCRIPTION%

  • One line description, as shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Enables LaTeX markup (mathematics and more) in TWiki topics

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

  • Set the dots-per-inch default density level for the rendered images (116 is suggested for 11pt browser fonts.)
    • Set DENSITY = 116

  • Set the gamma correction for the rendered images. This controls how dark the rendered text appears
    • Set GAMMA = 0.6

  • Set the scaling for the image size. Typically, set to '1'.
    • Set SCALE = 1.0

  • Uncomment the following to define a site-wide custom color, DarkBlue.
    • #Set PREAMBLE = \usepackage{color} \definecolor{DarkBlue}{rgb}{0,0.1,0.43}

  • In addition, the following parameters are available at the topic level, EQN, FIG, TBL, to override the counter reset. (i.e. if    * Set EQN = 3 is declared in a topic, the first labeled equation will be given the number 4).

Note: It is recommended to declare these settings in the WikiPreferences or WebPreferences topics, so that they aren't lost when the plugin is upgraded. In this case, the macro declarations should be preceded by LATEXMODEPLUGIN_. E.g. to the set the font density default for a specific web, WEB, use:

  • Set LATEXMODEPLUGIN_DENSITY = 200
in the topic WEB.WebPreferences.

Plugin Installation Instructions

First, confirm that the external software needed by the plugin is installed on the TWiki server. This includes:

Rendering can be performed by (latex and dvipng) or (latex and dvips and convert) or (pdflatex and convert) or (mimetex). The first three options allow one to include almost any LaTeX markup in a TWiki topic, whereas mimetex has very limited functionality. Among the first three options, dvipng is the fastest by a significant margin. The tweakinline processing (v2.5 and above) to align the baseline of LaTeX expressions with HTML text uses convert.

mimetex can be used in server environments where a full LaTeX installation is impractical (e.g. TWiki:Codev.TWikiOnMemoryStick). mimetex provides rendering of equations independently of external font files. This provides a very lightweight and fast mechanism to show equations. However, the number of colors is limited to 4 (black, red, blue, green) and only the mathmode and picture LaTeX environments are supported. Also, the preamble, density, and gamma settings are ignored.

Second,

  • Download the LatexModePlugin.zip file from the Plugin web
    warning Note: versions 3.0 and above are compatible only with TWiki 4.x.x. If you are running an earlier version of TWiki, (i.e. Cairo) download v2.62 (25 Sep 2006) instead. warning

  • Unzip ZIP file in your twiki installation directory. Content:
    File: Description:
    lib/TWiki/Plugins/LatexModePlugin.pm Plugin Perl module
    lib/TWiki/Plugins/LatexModePlugin/Init.pm The initialization module
    lib/TWiki/Plugins/LatexModePlugin/Render.pm The rendering module