LaTeX plugin

This plugin uses LaTeX+ImageMagick to render mathematical formulae embedded within a DokuWiki page. This gives a professional look to equations, and the syntax allows almost copy-paste conversion between DokuWiki and LaTeX manuscripts. For example, you may simply type $ a + b = c $ into your wiki code and it will automatically be shown as .¹⁾

Follow the usual plugin installation instructions to download and install the plugin.

External requirements: This plugin requires the following software to be installed on the server hosting your wiki. If you do not have root access, contact your administrator.²⁾

• A copy of LaTeX (preferably a recent version of TeXlive), which inclues both latex and dvips binaries.
• ImageMagick, which in turn requires…
• Ghostscript

This plugin will not work in PHP safe mode. - unless your server administrator has specifically allowed access to the software this plugin needs.

Variously out-dated but quite in-depth installation instructions can be found on E-razor's wiki. You might also consult the similar instructions for math in MediaWiki (but note that DokuWiki's plugin does not need texvc, OCaml, etc.). Here is a summary

• Ubuntu/Debian (works: March 2011)

  apt-get install texlive-latex-base imagemagick ghostscript

• CentOS 5³⁾⁴⁾

  yum install tetex tetex-fonts tetex-dvips tetex-latex ghostscript ImageMagick
  fmtutil-sys --all

• Fedora Core 3

  yum install tetex-latex ImageMagick

• Archlinux

  pacman -S texlive-most texlive-lang

  to install latex, read the latex article in the archwiki for more options

• Windows (confirmed to work on Windows 7 with DokuWiki on a Stick –Mark April 29 2011)
  • Download and install the plugin. For some reason, plugin manager has troubles doing automatic installation on my machine. No mattery, just unpack it manually.
  • You will need to download a LaTeX installation (MikTex works), and ImageMagick. You will also need ghostscript, but this may already be provided by MikTex or some other software you have (some feedback here, anybody?).
  • Make sure that the LaTeX and ImageMagick binaries are in the PATH variable (and restart your webserver to absorb the change), or use the plugin's configuration to set the full paths – note that you will need quotes around filenames with spaces, such as “C:\Program Files (x86)\MiKTeX 2.9\miktex\bin\latex”.
    • The ImageMagick path must be at the beginning of the PATH variable, since the convert binary has the same name as a Microsoft-supplied program.
  • Should be good to go; give it a try!

The following syntax is recognized by the LaTeX plugin at the moment. For the most part, the recognized syntax is inserted as-is into a small LaTeX template (which can be changed in the Configuration Manager), then compiled:

• $…$ syntax is rendered in-line, just as in LaTeX
• $$…$$ syntax is rendered on its own line, just as in LaTeX
• \begin{displaymath}…\end{displaymath} syntax
• \begin{eqnarray}…\end{eqnarray} syntax
• \begin{eqnarray*}…\end{eqnarray*} syntax
• \begin{equation}…\end{equation} syntax
• \begin{equation*}…\end{equation*} syntax
• Special: <latex>…</latex> syntax is rendered in-line in non-math-mode. This is useful to enter environments such as picture, etc.

• Although the numbered-equation styles are available, the numbers do not carry over between equations. You can hard code them by including a LaTeX command like \setcounter{equation}{5}, which will reset the equation counter to start at 5.
• The symbol $ can no longer be used for currency, so use %%$%% instead in wiki text.
• Certain words are blacklisted from being included in LaTeX code – for example $ L_{\rm name} $ will show as because “name” is blacklisted (I am not sure why, but I'm keeping the old blacklist just in case –Mark). The image title tag (tooltip) will indicate that this is the case, emulated here: .

From the Configuration Manager, you can modify the following settings:

• Media namespace in which to store images (default is :wiki:latex).
• Image type: default is png.
• Maximum allowed image size.
• Maximum allowed length of LaTeX code (sort of a security filter).
• Paths to latex, dvips, convert, and identify programs.
• Options to convert program, to control image size, transparency.
• The LaTeX template used for each rendered block: add \usepackage{} statements here, change color, etc.

There is an admin plugin included for ease in managing the LaTeX image cache, which can easily grow to thousands of equations in size. This can be accessed through the administration actions panel.

The admin plugin also allows you to troubleshoot problems in the rendering process.

• If the plugin settings are incorrect (or you are missing some external software), you will see instead of the image. The image will have a tooltip (html title tag) indicating the particular error.
• Try a test run of your LaTeX installation from the admin panel of the LaTeX plugin. Besides a tooltip, you will see information on:
  • Existence and versions of latex, dvips, convert, and identify binaries.
  • The LaTeX file to be compiled.
  • The ouput (stdout/stderr) of all the commands used.
  • The .log file from LaTeX compilation.
• This LaTeX plugin is similar in operation to the LaTeX plugins of other wiki software. Check the MediaWiki LaTeX troubleshooting guide for possible solutions, though note for example that the DokuWiki plugin does not use texvc.
• In php.ini “exec” should not appear in the disable_functions list

• Some ancient LaTeX installations may work better (i.e., work, period) if you remove the inputenc package from the preamble, but this is not the preferred method since Dokuwiki uses UTF-8.
• Missing latex.fmt. This is a bug found in CentOS 5, due to the packages failing to update the proper files. Quite confusingly, normal users are able to use LaTeX with no problems but all web-invoked LaTeX will fail (the apache user cannot write to its home directory /var/www/.). You can either:
  • Run the following command as root⁵⁾

    fmtutil-sys --all

    or, if that does not work,

  • Run LaTeX as a normal user allowing LaTeX to generate its own latex.fmt in your home directory, then copy that latex.fmt into your temporary directory where the DokuWiki LaTeX plugin can find it.⁶⁾ You can find the file at $HOME/.texmf-var/web2c/latex.fmt. You may want to relocate the temporary folder to be inside your Dokuwiki installation, so that latex.fmt is not wiped out by a temporary files cleaner.
• Invalid drive specification. This error appears in the troubleshooter's program versions test in Windows. The plugin attempts to call convert but it gets Microsoft's program rather than the ImageMagick one. Adjust your PATH environment variable or configure the plugin to use an absolute path.

This plugin was originally written by Alexander 'E-razor' Krause based on class.latexrender.php by Benjamin Zeiss then extended by Michael Boyle, and is now maintained on github by Mark Lundeberg.

• March 4 2011 - Mark Lundeberg
  • starting with Michael Boyle version (which enabled $…$, <latex></latex>, \begin{displaymath}, \begin{eqnarray}, \begin{eqnarray*})
  • changed inlines to have vertical-alignment:middle; (not perfect, but close)
  • changed big equations to have nicer CSS margins.
  • added DokuTexit render mode, following suggestion on E-Razor's page
  • restructured files to share a common class
  • added several config options to config manager (paths of binaries, colour, formula size, image format)
  • added support for $$ … $$ as in LaTeX, for displayed equations.
  • added support for \begin{equation} and \begin{equation*}.
  • uploaded the plugin here where other people can find it.

• March 6 2011
  • added admin page for cache wiping/cleaning.
  • binary paths now include options, as applicable.
  • added config options for preamble/postamble.
  • added config options for max formula sizes
  • added a minimal ODT render mode.
  • added informative tooltip text on images of failed renders.

• March 9 2011
  • added troubleshooter to admin panel

• April 24 2011
  • Changed image namespace to :wiki:latex (avoids polluting root namespace)
  • Changed temporaries to a media namespace: :wiki:latex:tmp (allows access to temporary files, through the wiki itself!)

• April 28/29 2011
  • Removed keep_tmp option and removed program options from configuration (only paths specified now).
  • Made compatible with Windows – works with DokuWiki on a Stick, MikTex, and ImageMagick official binaries, essentially out-of-the-box.

• Great! It works! Thanks for supporting me in installation. — thuanlethuanle
  
  2011/03/11 16:26

If the embedded imgages aren't perfectly aligned, you can gain more controll bei adding 'media_latex' zu the class in syntax.php lines 91 and 96. After that create an style.css with 'img.media_latex{ … }'.

I'm not sure if that applies for the current plugin (there's no syntax.php), and anyway there are already two CSS styles declared in plugins/latex/all.css : The first style img.latex_displayed is for equations on their own line such as $$ G(x) = 2 $$, which have a slight indent. The second style img.latex_inline sets vertical alignment to middle for in-line latex such as $a + b = c$. -Mark

Why does the new latex plugin display formulas in red color ?

Ok I just found the answer myself Nice work !

Maybe a stupid question but how can I display the Dollars symbol ($) on the page ? The plugin replace all my $ by the message “Latex render failed” It's not very easy to use %%$%% !

Yes, that's an unfortunate side effect of the plugin. If you don't mind losing the $ a+b $ syntax entirely, you can delete plugins/latex/syntax/dollar.php. Another way you could consider is to add a space to dollar.php line 14, changing the trigger pattern from

$this->Lexer->addEntryPattern('\$(?=.*\$)',$mode,'plugin_latex_dollar');

to

$this->Lexer->addEntryPattern('\$ (?=.*\$)',$mode,'plugin_latex_dollar');

That way, the plugin would only activate on text like ”the sum $ a+b $” where the $ is followed by a space, and would not activate on text like ”projected total cost of $2000”. -Mark

Well, why don't you try <nowiki>? -Di

If i give the group @ALL an “Read”-Permission to read the page, they can access and read the normal Text…but the Latex-Image are not there! What to do?

Solved! Need to give “Read”-Permission to “wiki:latex:*”