# Extension:MathLaTeX

This page is a translated version of the page Extension:MathLaTeX and the translation is 100% complete.
Other languages:
MediaWiki manüel uzantıları
MathLaTeX
Sürüm durumu: bakımsız
Uygulama Ayrıştırıcı uzantısı
Açıklama Lateks ifadesini yerel kaynakları kullanarak bir görüntüye dönüştürün.
Yazar(lar) Jesse B. Dooley (jbdooleymesaj)
En son sürüm v1.2 (2016-01-18)
MediaWiki 1.24+
Lisans GNU Genel Kamu Lisansı 3.0
İndir

https://sourceforge.net/projects/mathlatex/README
Örnek <mathlatex width= height= dpi= >E=mc{2}</mathlatex>
mathlatex

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

## Önsöz

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

## Kurulum

• 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

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

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


#### Düğmeler

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 );  #### Hizmet Hesabı 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. ### Deneme 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. ## Kullanıcı Kılavuzu 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]. ### Öznitellikler 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. ### Yapılandırma 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.

#### Yapılandırma Dosyaları

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.

### Dizin Yapısı

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.

### Hata ayıklama

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.

### Hata mesajları

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.

### Bakım Betikleri

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.

### Oluşturma

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.

### Depo

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.

### Özel Sayfalar

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.

#### Galeri

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.

#### Paketler

Required packages are in Green.
Missing required packages are in Red.
Extra packages are in Black.


#### Sarmalayıcı

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.

## Mimari

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.

### Akış şeması

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


### Oluşturma

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.

### Depolama

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.

## Hata Listesi

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

## Gelecek Özellikler

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

## Sürüm

• 1.0 Initial Release
• 1.1 Fixed attribute parser bug.
• 1.2 Cosmetic changes to the documentation.