Jump to content

Extension:MathLaTeX

From mediawiki.org
Translate this page
Languages:
MediaWiki extensions manual
MathLaTeX
Release status: unmaintained
px
Implementation Parser extension
Description Convert latex statement into an image using local resources.
Author(s) Jesse B. Dooley (jbdooleytalk)
Latest version v1.2 (2016-01-18)
MediaWiki 1.24+
License GNU General Public License 3.0
Download

SourceForge:

Note:
No localisation updates are
provided by translatewiki.net .



https://sourceforge.net/projects/mathlatex/README
Example <mathlatex width= height= dpi= >E=mc{2}</mathlatex>
Tags
mathlatex
Hooks used

The MathLaTeX extension renders mathematical equations on wiki pages using a local LaTeX[1] installed with Cygwin[2].

Preamble

[edit]

The problem is how to render a mathematical equation in a MediaWiki article in as efficient and effective a manner as possible with the least aggravation.

The solution is simple. Render the equation as an image and place it in the article inside a image tag. The complexity comes from how many different ways there are to render an equation into an image multiplied by how many ways each solution can be implemented.

There are five possible rendering solutions, HTML, LaTeX, MathJax, MathML, and Mathoid. Each can be implemented in two ways, render locally or with a remote server. Consider four popular OSs; Linux, MacOS, OpenBSD, and Windows. This gives 20 different solutions. Cramming all possible solutions into one extension violates the maxim One size never fits all and is a quick way to a hot mess. A better architecture choice is to publish a framework solution and let the MediaWiki community implement solutions.

The MathLaTeX extension is my effort at implementing the solution for LaTeX rendering under Windows 7 Ultimate x64 SP1 with Cygwin x64.

Tested Configuration:

  • Cygwin64
  • MediaWiki 1.24.2
  • XAMPP 5.5.24
  • Windows 7 Ultimate x64 SP1

Installation

[edit]
  • Note: This installation works for me. Your performance will vary.
  • Note: This assumes only the C drive. Change your installation as needed.
  • Note: Do not install the documentation for TeX Live[3]. This can add hours to the installation time and yields nothing useful.

Cygwin

[edit]

Install Cygwin 64bit along with ghostscript, ImageMagick and latex/texlive.

Install the following Cygwin packages. 

ImageMagick
ghostscript
ghostscript-fonts-other
ghostscript-fonts-std
poppler-data
popt
popt-devel
texlive
texlive-collection-basic
texlive-collection-bibtexextra
texlive-collection-binextra
texlive-collection-context
texlive-collection-fontsextra
texlive-collection-fontsrecommended
texlive-collection-fontutils
texlive-collection-formatsextra
texlive-collection-genericrecommended
texlive-collection-langenglish
texlive-collection-langfrench
texlive-collection-langgerman
texlive-collection-langgreek
texlive-collection-langspanish
texlive-collection-latex
texlive-collection-latexextra
texlive-collection-latexrecommended
texlive-collection-mathextra
texlive-collection-metapost
texlive-collection-music
texlive-collection-omega
texlive-collection-pictures
texlive-collection-plainextra
texlive-collection-pstricks
texlive-collection-publishers
texlive-collection-science
texlive-collection-xetex

Add these to the Windows System Path in this order: 

C:\cygwin64\usr\local\bin;
C:\cygwin64\usr\bin;
C:\cygwin64\bin;
C:\cygwin64\lib;

Create these Windows System Variables: 

CYGWIN	=	nodosfilewarning
HOME	=	/cygdrive/c/cygwin64/home/<User Name>

MathLaTeX

[edit]

Make these changes to LocalSettings.php 

// ImageMagick Settings - using C:/cygwin64 64bit
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "C:/cygwin64/bin/convert.exe";

// Path to the GNU diff3 utility. Used for conflict resolution.
$wgDiff  = "C:/cygwin64/bin/diff.exe";
$wgDiff3 = "C:/cygwin64/bin/diff3.exe";

// MathLaTeX
require_once "{$IP}/extensions/MathLaTeX/MathLaTeX.php";
require_once "{$IP}/extensions/MathLaTeX/SpecialMathLaTeX.php";

Buttons

[edit]
Fig. 1 MathLaTeX Button

The edit button looks like pi-in-a-circle and loads into the Classic Edit Toolbar with MathLaTeX.

The edit button for WikiEditor looks like pi-in-a-circle .

To load the WikiEditor button put the following code into your MediaWiki:Common.js article and add $wgUseSiteJs = true; to LocalSettings.php. 

var customizeToolbar = function() {
	$('#wpTextbox1').wikiEditor('addToToolbar', {
	section: 'main',
	group: 'format',
	tools: {
		"mathlatex": {
			label: 'MathLaTeX',
			type: 'button',
			icon: 'http://localhost/<wiki name>/extensions/MathLaTeX/images/button_mathlatex_wikieditor.png',
			action: {
				type: 'encapsulate',
				options: {
					pre:"&lt;mathlatex width= height= dpi= &gt;",
					post:"&lt;/mathlatex&gt;"
				}
			}
		}
	}
});

};

/* Check if view is in edit mode and that the required modules are available. Then, customize the toolbar … */
if ( $.inArray( mw.config.get( 'wgAction' ), [ 'edit', 'submit' ] ) !== -1 ) {
	mw.loader.using( 'user.options', function () {
		// This can be the string "0" if the user disabled the preference ([[phab:T54542#555387]])
		if ( mw.user.options.get( 'usebetatoolbar' ) == 1 ) {
			$.when(
				mw.loader.using( 'ext.wikiEditor.toolbar' ), $.ready
			).then( customizeToolbar );
		}
	} );
}
// Add the customizations to LiquidThreads' edit toolbar, if available
mw.hook( 'ext.lqt.textareaCreated' ).add( customizeToolbar );

Service Account

[edit]

The service account 'MW_MATH' is used for all the files and pages produced by MathLaTeX. On a public wiki grant MW_MATH administrative rights so the Special Pages can be updated.

Testing

[edit]

The README contains this article in wiki text. Create a new article in your wiki, copy and paste the README into it and save. If no error messages are produced the installation was successful.

User Manual

[edit]

MathLaTeX renders LaTeX statements as Portable Network Graphics (PNG) files, then replaces the LaTeX statement in the wikitext with an Image Tag for that PNG file. Expressing an equation as a LaTeX statement is beyond this article's scope but two places to start are, MediaWiki's Help:Displaying a formula and Online LaTeX Editor[4].

Place the LaTeX statement between the MathLaTeX tags. For example, E=mc^{2} would be <mathlatex>E=mc^{2}</mathlatex> and is rendered as, . MathLaTeX displays error messages in the wiki article starting where the MathLaTeX tag was.

LaTeX documentation is at the LaTeX Project[5].

Attributes

[edit]

The opening tag takes three optional attributes, width, height, and dpi. Each takes an integer argument. Width and height are expressed in pixels and control how the image is displayed inside the Image tag. DPI, Dots-Per-Inch, controls the rendered image size.

Table 1 illustrates different DPI settings. A large DPI produces a larger image. A smaller DPI produces a smaller image. The default DPI is 120 because it produces an image easily embedded in text.

Table 1. Equation at different DPI
TeX Image DPI
<mathlatex >E=mc{2}</mathlatex> 120
<mathlatex dpi=200 >E=mc{2}</mathlatex> 200
<mathlatex dpi=300>E=mc{2}</mathlatex> 300

Different Width and Height are applied in Table 2 below using the same 120 DPI image.

Table 2. Width and Height. 120 DPI
TeX Image Width/Height
<mathlatex width=100 height=200>E=mc{2}</mathlatex> 100/200
<mathlatex width=200 height=100>E=mc{2}</mathlatex> 200/100
<mathlatex width=100>E=mc{2}</mathlatex> 100/
<mathlatex height=100>E=mc{2}</mathlatex> /100

Attributes are entered in the opening tag. For example. Write E=mc^{2} in an article. Highlight it. Then click the edit button to produce this: <mathlatex width= height= dpi= >E=mc^{2}</mathlatex>. An unset attribute is ignored. A set one is processed.

Configuration

[edit]

The variable $NamespaceWhiteList lists Namespaces, by id, that MathLaTeX will not operate in. By default MathLaTeX only operates in Main.

The constant DEFAULT_DPI defines the default Dots-Per-Inch used. The default is 120.

Configuration Files

[edit]

The configuration files are stored in MathLaTeX/config/.

  • latexpackages.php holds two arrays, $requiredlibs and $seachlibs. The $requiredlibs holds Cygwin packages required by Render::wrapper. The $seachlibs array holds Cygwin packages required by MathLaTeX.

Directory Structure

[edit]

Under the MathLaTeX directory there are:

  • config - holds the configuration files
  • i18n - holds the localisation files.
  • images - holds the images
  • maintenance - holds the maintenance scripts
  • modules - holds the button javascript file.

Debugging

[edit]

On a failure a stack-trace is written into the article starting at the equation position.

The wfDebugLog function is used throughout MathLaTeX so enable $wgDebugLogFile for more detailed debugging.

The variable $MathDebug controls whether the temporary folder used for rendering is deleted. Set to TRUE and it is not deleted. Set to FALSE and it is deleted. The default setting is FALSE.

Error Messages

[edit]

When an error occurs the MathLaTeX statement is replaced with an error message that does a stack trace. In the Error Message below dvipng.exe is inaccessible. Note that the original equation is reproduced in line 4.

MathLaTeX Error begin
MathLaTeX::body::onPageContentSave createImage failed
Equation begin
e=mc3
Equation end
MathLaTeX::body::createImage render failed
Render:DviPNGrender failed
Render::DviPNGrender png creation failed
cmd dvipng.exe -bg Transparent --gamma 1.5 -D 120 -T tight --strict MW_MATH_5c59dc24ade841a750bd5849dec7ea12_120.dvi -o MW_MATH_5c59dc24ade841a750bd5849dec7ea12_120.png
retval 1
dvipng result
MathLaTeX Error end

The Special Pages throws an MWException upon error.

Maintenance Scripts

[edit]

In the maintenance subdirectory the equationCensus.php will list all the MW_MATH images and how many pages each image is linked to. An image with one link is only displayed in the Gallery and is a candidate for deletion.

Render

[edit]

The MathLaTeXRender process wraps the author's equation statement to produce a valid LaTeX statement for processing. The default wrapper is shown in Table 3.

Table 3. Default LaTeX Wrapper

\nonstopmode
\documentclass[12pt]{article}
\usepackage{mathtools}
\usepackage{lmodern}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{pst-plot}
\usepackage{color}
\pagestyle{empty}
\begin{document}
$$
Equation Text Here.
$$
\end{document}

To specify a custom wrapper begin the statement with a "%" as the first character. LaTeX uses the "%" character to start comment lines. MathLaTeXRender will then bypass the default wrapper and send the LaTeX statement on to texlive.

Repository

[edit]

The MatLaTeXRepository process saves files using "MATH_MW" as the owner in the MediaWiki File Repository. All file operations act only on files with "MATH_MW" as the owner. The LaTeX statement for an image is saved in the Summary section. The Summary is limited to 200 characters, so only the first 200 characters are saved.

Special Pages

[edit]

Visibility into MathLaTeX on a private wiki is trivial. Visibility into MathLaTeX on a public wiki is gets a bit more complex. Did the Sysop modify the default wrapper? Were changes made to the default texlive packages? Is the equation I want already made?

Three Special pages, Gallery, Packages, and Wrapper, answer these questions.

Open the MathLaTeX button on Special pages displays the menu for the three Special pages as seen below:

Fig. 2 MathLaTeX Special Menu

Each button updates the associated page. The link to the right displays that page. Only a WikiSysOp can update the Special pages. Each page should be posted as read-only on the site's MathLaTeX page.

[edit]
Fig. 3 MathLaTeX Gallery Sample

Each equation is listed in descending file-name alphabetical order. Each file-name is enclosed inside an image tag for and easy cut-and-paste.

Packages

[edit]
Fig. 4 MathLaTeX Packages Sample 
Required packages are in Green.
Missing required packages are in Red.
Extra packages are in Black.


Wrapper

[edit]
Fig. 5 MathLaTeX Wrapper Sample

The default latex wrapper is displayed at left. The user's latex statement replaces Equation Text Here. If the user's latex statement starts with a '%' then the entire default latex statement is replaces with the user's.

Architecture

[edit]

Rendering a TeX statement as an image in MediaWiki presents three major problems: Rendering in LaTeX, here implemented as Tex Live, is a CPU hog that inhales cycles. An equation image can be displayed using a separate image server or using the Images tag. Error Messages can be displayed to the user as an image, a popup window, or text.

Maximizing an efficient and simple solution resulted in the following design choices:

  1. Maximize image reuse
    1. Standardize the image naming scheme for efficient image lookup and reuse.
    2. Provide an image gallery that is automatically updated.
  2. Use the Image tag because it is more efficient than building a separate image server.
  3. Use a standardized error message in text format to replace the MathLaTeX statement in the wiki page.

Flowchart

[edit]
Fig. 6 MathLaTeX Flowchart


-- Flowchart in text format
Start -> onPageContentSave -> 
if namespace is allowed continue, else return true
->
if text has mathlatex label, continue, else return true
->
if >0 valid equations, continue, else return true
->
foreach equations
  -> trimplaintext
     -> if length == 0 skip else continue
  -> create equation filename
  -> search repository for filename
     -> if not found 
      createImage
        -> if success return true, add to repository, else return error message
        -> if createImage fails replace equation in wiki page with error message, continue
  -> replace equation in wiki page with equation filename
End

Rendering

[edit]

The MathLaTeXRender class performs the following operations on the latex statement:

  1. Wraps the latex statement in the default latex wrapper.
    1. Do not wrap the latex statement if the first character is '%'.
  2. Run 'pdftex.exe --fmt=latex --interaction=nonstopmode <latex statement>' to produce a DVI file.
  3. Run 'dvipng.exe -bg Transparent --gamma 1.5 -T tight --strict <DVI file>' to produce the PNG file.

This process produces the sharpest image over a wide size range.

Storage

[edit]

Why not add tables to the wikidb and fix the Summary Bug? Because adding random tables to a database design is egregiously bad engineering that could corrupt the database now or sometime in the future. Another possibility is that a future wikidb design will eliminate user added tables.

For future consideration. A separate MySQL database to store equation data.

Bug List

[edit]
  • 001 Summary Bug - Two hundred character limit for the saved latex statement.

Future Features

[edit]
  • Write a hook to combine needed features from onPageContentSave and ParserFirstCallInit. Maybe call it ParseFirstCallPageSave.
  • Link images into a group.

Version

[edit]
  • 1.0 Initial Release
  • 1.1 Fixed attribute parser bug.
  • 1.2 Cosmetic changes to the documentation.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:MathLaTeX&oldid=6727149"