Extension:MathLaTeX

This article describes the MathLaTeX Mediawiki Extension that renders mathematical equations on wiki pages using a local LaTeX installed with Cygwin.

This article was written on January 8, 2016 and is best viewed at 100%.

Document version 1.00

Software version 1.20

Copyright (C) 2015 Jesse B. Dooley under GNU v.3

=Preamble= 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=
 * 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. This can add hours to the installation time and yields nothing useful.

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

MathLaTeX
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


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/ /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 (T54542)		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
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
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= 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.

Place the LaTeX statement between the MathLaTeX tags. For example, E=mc^{2} would be &lt;mathlatex&gt;E=mc^{2}&lt;/mathlatex&gt; 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.

Attributes
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. Different Width and Height are applied in Table 2 below using the same 120 DPI image. 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: &lt;mathlatex width= height= dpi= &gt;E=mc^{2}&lt;/mathlatex&gt;. An unset attribute is ignored. A set one is processed.

Configuration
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
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
Under the MathLaTeX directory there are:
 * config - holds the configuration files
 * i18n - holds the localisation files.
 * images - holds the images
 * maintenance</tt> - holds the maintenance scripts
 * modules</tt> - holds the button javascript file.

Debugging
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
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
In the maintenance</tt> subdirectory the equationCensus.php</tt> 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
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. 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
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
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: 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.

Gallery
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
<pre style="color: green">Required packages are in Green. <pre style="color: red">Missing required packages are in Red. Extra packages are in Black.

Wrapper
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= 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
 * 2) Standardize the image naming scheme for efficient image lookup and reuse.
 * 3) Provide an image gallery that is automatically updated.
 * 4) Use the Image tag because it is more efficient than building a separate image server.
 * 5) Use a standardized error message in text format to replace the MathLaTex statement in the wiki page.

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
The MathLaTeXRender class performs the following operations on the latex statement: This process produces the sharpest image over a wide size range.
 * 1) Wraps the latex statement in the default latex wrapper.
 * 2) Do not wrap the latex statement if the first character is '%'.
 * 3) Run 'pdftex.exe --fmt=latex --interaction=nonstopmode ' to produce a DVI file.
 * 4) Run 'dvipng.exe -bg Transparent --gamma 1.5 -T tight --strict <DVI file>' to produce the PNG file.

Storage
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=
 * 001 Summary Bug - Two hundred character limit for the saved latex statement.

=Future Features= =Version= 1.0 Initial Release
 * Write a hook to combine needed features from onPageContentSave and ParserFirstCallInit. Maybe call it ParseFirstCallPageSave.
 * Link images into a group.

1.1 Fixed attribute parser bug.

1.2 Cosmetic changes to the documentation.