This is an old revision of the document!
Table of Contents
Maths Publisher Plugin
Compatible with DokuWiki
2005-09-22 and later
The missing download url means that this extension cannot be installed via the Extension Manager. Please see Publishing a Plugin on dokuwiki.org. Recommended are public repository hosts like GitHub, GitLab or Bitbucket.
This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.
Similar to asciimath, asciimathml, jsmath, latex, latexwas, masciimath, math, mimetex, svgedit
This plugin makes use of phpmathpublisher by Pascal Brachet to allow inclusion of properly rendered mathematical formulae in DokuWiki pages.
This is a completely self-contained PHP solution. It requires no third party packages. It makes use of php's GD library and freely available fonts1) to create an images for each formula. The plugin script, phpmathpublisher and the required fonts are all included in the download package.
There is an alternative math plugin.
PHP Installation Requirements
To run this plugin your PHP installation needs to have:
- tokenizer library
- gd library
- png capabilities, ie. libpng, which also requires the zlib library
- freetype font library
For full details refer to the php documentation.
Syntax
DokuWiki Syntax:
<m size>...mathematical formulae...</m>
size (optional) the base glyph size in pixels - default value: 12.
alignment can be controlled in the same way as DokuWiki images, one space to the left to right align, one to the right to left align, one on each side to centre.
Original formulae syntax page; DokuWiki-compatible formulae syntax (maybe install as wiki:mathsyntax?)
Example:
<m>S(f)(t)=a_{0}+sum{n=1}{+infty}{a_{n} cos(n omega t)+b_{n} sin(n omega t)}</m> <m 8>delim{lbrace}{matrix{3}{1}{{3x-5y+z=0} {sqrt{2}x-7y+8z=0} {x-8y+9z=0}}}{ }</m> <m 32>delim{|}{{1/N} sum{n=1}{N}{gamma(u_n)} - 1/{2 pi} int{0}{2 pi}{gamma(t) dt}}{|} <= epsilon/3</m>
Result:
note: the plugin is not installed at this site, these images are the actual images generated by the plugin taken from a site where the plugin is installed.
You can see the plugin in action here.
Installation
Plugin sources: zip format (460k), tar.gz format (454k), rar format (424k) | darcs repository
The zip & tar.gz format packages maybe installed using the plugin manager. The darcs repository can be used with the darcs plugin.
To install manually, download the source to your plugin folder, lib/plugins
and extract its contents. That will create a new plugin folder, lib/plugins/math
, and install the plugin.
The folder will contain:
syntax.php the plugin script phpmathpublisher/ phpmathpublisher folder phpmathpublisher/mathpublisher.php the main phpmathpublisher script phpmathpublisher/COPYING GPL2 licence phpmathpublisher/CHANGELOG phpmathpublisher changelog phpmathpublisher/fonts/ font folder phpmathpublisher/fonts/COPYING font copyright information phpmathpublisher/fonts/FreeSerif.ttf truetype font phpmathpublisher/fonts/FreeSerifItalic.ttf truetype font phpmathpublisher/fonts/cmex10.ttf truetype font phpmathpublisher/fonts/cmmi10.ttf truetype font phpmathpublisher/fonts/cmr10.ttf truetype font phpmathpublisher/fonts/msam10.ttf truetype font
Phpmathpublisher needs GD to render the images so please check if the GD library is installed on your system. (package php4-gd for debian users)
The plugin is now installed.
ACL & Math Plugin
This plugin stores its images in DokuWiki's media area, in a folder “cache_mathplugin”. To ensure no access problems when users retrieve the formulae images that folder needs to be configured with ACL to give appropriate wiki visitors read access. For completely public wikis this should not be a problem. Wikis which restrict access to the root namespace will need to add the following to their ACL.
cache_mathplugin:* @ALL 1
Details
Configuration
The plugin will work successfully with no changes to its configuration. However there are three settings you may alter:
$mathplugin_size
— the size value to be used if none is provided.$dirimg
— the folder to be used as an image cache$mathplugin_urlimg
— the url required to access images stored in the image cache.
The full details of these settings are given in the plugin source code.
Plugin Source
<?php /** * Math Plugin: incorporate mathematical formulae using MathPublisher into DokuWiki * * Syntax: <m size>...mathematical formula..</m> * size (optional) base glyph size in pixels, * if not present will use the value of $mathplugin_size global, the value * of which can be set below (default: 12) * * Formulae syntax: refer http://www.xm1math.net/phpmathpublisher/doc/help.html * * @license GPL 2 (http://www.gnu.org/licenses/gpl.html) * @author Christopher Smith <chris@jalakai.co.uk> * @date 2005-12-17 * * phpmathpublisher * @link http://www.xm1math.net/phpmathpublisher/ * @author Pascal Brachet */ if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/'); if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/'); require_once(DOKU_PLUGIN.'syntax.php'); require_once(DOKU_INC.'inc/io.php'); global $conf; // -----------------------[ math plugin globals ]--------------------------------------- global $mathplugin_size, $mathplugin_urlimg; // default base size (pixels) of glyphs in the formulae $mathplugin_size = 12; // base url to access images, should correspond to $dirimg below. // if left at default, it will be modified to add a subfolder to avoid filling // the root media folder with clutter, refer _cacheExists() $mathplugin_urlimg = DOKU_URL.'lib/exe/fetch.php?w=&h=&cache=cache&media='; // -----------------------[ mathpublisher settings ]------------------------------------ global $dirfonts,$dirimg; // absolute path to the fonts directory (must not have '/' at end) $dirfonts=dirname(__FILE__)."/phpmathpublisher/fonts"; // absolute path to the img directory (must not have '/' at end) // if left at default, it will be modified to add a subfolder to avoid filling // the root media folder with clutter, refer _cacheExists() $dirimg=$conf['mediadir']; // ------------------------------------------------------------------------------------ /** * All DokuWiki plugins to extend the parser/rendering mechanism * need to inherit from this class */ class syntax_plugin_math extends DokuWiki_Syntax_Plugin { // FIXME localise var $str_nopng = "PHP's gd library is missing or unable to create PNG images"; var $str_noft = "PHP installation missing access to freetype library"; var $enable = false; var $msg_disable = "math plugin disabled: "; var $msg_sent = false; function syntax_plugin_math() { $this->enable = $this->_requirements_ok(); } /** * return some info */ function getInfo(){ return array( 'author' => 'Christopher Smith', 'email' => 'chris@jalakai.co.uk', 'date' => '2008-08-13', 'name' => 'Math Plugin'.(!$this->enable ? ' (disabled)' : ''), 'desc' => 'Add mathematical formulae to DokuWiki Syntax: <m size>math formulae</m> For formulae syntax visit http://www.xm1math.net/phpmathpublisher/doc/help.html'. (!$this->enable ? "\n(".$this->msg_disable.")" : ''), 'url' => 'http://www.dokuwiki.org/plugin:math2', ); } function getType(){ return 'protected'; } function getPType(){ return 'normal'; } function getSort(){ return 208; } /** * Connect pattern to lexer */ function connectTo($mode) { $this->Lexer->addEntryPattern('<m(?=[^\r\n]*?>.*?</m>)',$mode,'plugin_math'); } function postConnect() { $this->Lexer->addExitPattern('</m>','plugin_math'); } /** * Handle the match */ function handle($match, $state, $pos, &$handler){ global $mathplugin_size; if ( $state == DOKU_LEXER_UNMATCHED ) { list($size, $math) = preg_split('/>/u', $match, 2); // will split into size & math formulae if (!is_numeric($size)) $size = $mathplugin_size; if (strlen($math) > 1) { $c_first = $math{0}; $c_last = $math{strlen($math)-1}; $align = ($c_first == ' ') ? ($c_last == ' ' ? 'center' : 'right') : ($c_last == ' ' ? 'left' : 'normal'); } else { $align = 'normal'; } return (array($size, trim($math), $align)); } return false; } /** * Create output */ function render($mode, &$renderer, $data) { global $mathplugin_urlimg; if (!$data) return; // skip rendering for the enter and exit patterns list($size, $math, $align) = $data; if($mode == 'xhtml'){ // phpmathpublisher generates many E_NOTICE errors, ensure error_reporting doesn't include E_NOTICE. $error_level = error_reporting(); error_reporting($error_level & ~E_NOTICE); // check we have ability to create png images if ($this->enable) { // check we have somewhere to create our images & make them if ($this->_cacheExists()) { require_once(dirname(__FILE__).'/phpmathpublisher/mathpublisher.php'); $math_html = mathimage($math, $size, $mathplugin_urlimg); if ($align != 'normal') { $math_html = preg_replace('/<img /i','\0 class="media'.$align.'" ',$math_html); } $renderer->doc .= $math_html; } else { $this->_msg("math plugin img folder is not writable", -1); } } else { $this->_msg($this->msg_disable, -1); } // return to previous error reporting level error_reporting($error_level); return true; } return false; } function _cacheExists() { global $dirimg, $mathplugin_urlimg, $conf; // check for default setting if (!isset($dirimg) || !$dirimg) { $dirimg = $conf['mediadir']; } if ($dirimg == $conf['mediadir']) { // we don't want to clutter the root media dir, so create our own subfolder $dirimg .= "/cache_mathplugin"; $mathplugin_urlimg .= "cache_mathplugin%3a"; if (!@is_dir($dirimg)) { $this->_mkdir($dirimg); } } return @is_writable($dirimg); } // return true if php installation has required libraries/functions for mathpublisher function _requirements_ok() { if (!function_exists('imagepng')) { $this->msg_disable .= $this->str_nopng; return false; } if (!function_exists('imagettftext')) { $this->msg_disable .= $this->str_noft; return false; } return true; } // used to avoid multiple messages function _msg($str, $lvl=0) { if ($this->msg_sent) return; msg($str, $lvl); $this->msg_sent = true; } // would like to see this function in io.php :) function _mkdir($d) { global $conf; umask($conf['dmask']); $ok = io_mkdir_p($d); umask($conf['umask']); return $ok; } } //Setup VIM: ex: et ts=4 enc=utf-8 :
php math publisher
The plugin uses slightly modified version of the phpmathpublisher version 0.3 script. Only the script and fonts (and appropriate copyright files) are included in the download. The full phpmathpublisher package complete with demonstration pages is available at the phpmathpublisher home page.
Revision History
- 2008-08-13 — Update plugin URL, include earlier darcs only updates
- 2006-12-19 — (darcs version only) Fix for bug in images containing root expressions longer than one character (description)
- 2005-12-17 — Add checking for required PHP capabilities, gd library, PNG capability and free type library.
- 2005-11-21 — Font files updated for improved support for non-standard characters (thanks again to Matthias).
- 2005-11-14 — Updated to support DokuWiki style alignment syntax, correction to PType (thanks Matthias Grimm).
- 2005-09-05 — Updated to correct problem with using “/” in image URL (thanks Diego Caro).
- 2005-08-19 — Updated to phpmathpublisher v0.3, size parameter added, will create and use its own image cache, report error if image cache not writable. Single file download released.
- 2005-07-27 — Released.
Bugs
- Cannot download your plugin from china : the IP of the machine hosting http://www.cdsmith.plus.com/dokuwiki/plugin-math.zip is probably censored by the great firewall. Here is a mirror to this file, as 2006.07.26 : link
- $conf['mediaweb'] is not defined out of the box.
- direct access to media-dir is denied out of the box
⇒ replace
$renderer->doc .= mathimage($data[0], 10, $conf['mediaweb']."/"
with something like that
$renderer->doc .= mathimage($data[0], 10, DOKU_URL.'lib/exe/fetch.php?w=&h=&cache=cache&media=');
$conf['mediaweb'] code replaced as indicated. I am not sure about $conf['mediadir'], its a subfolder of data/ and the installation instructions include making that folder and all its subfolders writable by the webserver. — ChrisS 2005-07-29
Center alignment of images does not work due to a CSS issue. Try this patch (— jmiller 2009-01-27):
if ($align != 'normal') { $math_html = preg_replace('/<img /i','\0 class="media'.$align.'" ',$math_html); //INSERT FOLLOWING CODE: if ($align == 'center') $math_html = preg_replace('/ display: inline-block ;/','',$math_html); //END OF INSERTED CODE. }
Todo
Review image caching to better follow DokuWiki's own methods.- [Completed]Review phpmathpublishers decision making to use cached image. It seems to do all but generate the PNG image in order to access some dimensions. Version 0.3 corrects this problem.- [Completed]- Implement ability to change the background and foreground color of rendered images.
- I have used the [box] plugin to help contrast the black text (if you are using a dark background). This seems to work fine, however it would be great to change he text colour.
Discussion
Thanks for the great plugin. The only issue is that it doesn't seem to work with the OpenOffice (ODT) export plugin. (Would this be an issue for this plugin or the ODT plugin? I'm not sure.) That functionality would be much appreciated, even if it just includes the image and not an editable OpenOffice formula object. -jmiller
That sounds pretty sensible, I'll look into adding the image. — Christopher Smith 2008/08/26 19:00
I propose a solution: the code is in this page. Mirco Nisi 2008-08-29 12:05
Thanks for the code… users should remember to clear the cache when using for the first time. I have also noticed that the equation syntax of PhpMathPublisher appears to be quite similar to the syntax used by OpenOffice's formula editor. It may be possible for a set of simple regexps to convert one to the other! (Just a heads up if anyone has some extra time on their hands… ) UPDATE: regexps would not do any good since ODT internally uses MathML. -jmiller
A simple trick to increase the resolution of the image in ODT format ONLY: triple the formula size, then scale down the display size by one-third. In the ODT rendering code, replace
$math_html = namemathimage($math, $size, $mathplugin_urlimg); $renderer->_odtAddImage($math_html);
with this:
$size *= 3; $math_html = namemathimage($math, $size, $mathplugin_urlimg); $aImgInfo = getimagesize($math_html); $renderer->_odtAddImage($math_html, $aImgInfo[0]/3);
I hope this helps somebody who's looking for print quality in their OpenOffice files. -jmiller
Hello, the plugin has been working for me perfectly, but at some point it started hanging, i.e. pages with formulae start loading but never load completely, and DokuWiki doesn't display any errors, etc. I also checked the logs, nothing in there… I have all the required components installed with PHP (otherwise, I guess, the plugin would just show an error). Do you have any idea why this could be and what I can do to fix this? Andrey
Looks like the font-size for some symbols is ignored. In my installation, e.g. the sqrt()
-function is really big in opposite to the text. Is it a misconfiguration or the new DokuWiki version? Kewenig, 20060708
I don't think its DokuWiki. I have copied the raw wiki text from your page to here and it produces a smallersqrt()
sign. I don't know what the problem could be, however the first thing I would try is:
- find the math plugin image directory (normally
pages/media/cache_mathplugin
)and delete all the images. This will force the plugin to generate fresh images, or - change the forumlae slightly, again this will force the plugin to generate a new image
— Christopher Smith 2006-08-08 15:19
Thanks for your answer. It seems the problem is with the handling of the “cmex10.ttf” file. All symbols saved in this file look strange in my output. I also tried an other phpmathpblisher version, but there are also some strange drawings with the symbols in the “cmex10.ttf”. Kewenig 20060809
Incompatible with ACL when group ALL has no right in root namespace (20060717) …
Hi, “cache_mathplugin” directory is in data/media/ which may be not readable by all users depending on ACL conf.
If possible it should be located in data/cache dir ?
ugly fix : add a line withcache_mathplugin:* @ALL 16
in conf/acl.auth.php
HI! I've just installed the plugin and the PHP 4-gd library but when I try to use<m>...</m>tags in the page i get the following error:
Fatal error: Call to undefined function: imagettfbbox() in home/mind/public_html/dokuwiki/lib/plugins/math/phpmathpublisher/mathpublisher.php on line 661
I use apache 1.3 & php4 on a Debian Sid system Thanks
It sounds you don't have the free type library. For details on installing php with the freetype library, refer to php documentation. — Christopher Smith 2005-12-17 07:39
- Pb with plug-in - 20060117
Hello, I have installes this plugin with the currrent version of DokuWiki (Septembre 2005) by the provider FREE.FR. When I make a preview, all is good → but when I save the page → after, I see <m>…</m> . Could you said me where is the problem ?
That is very odd. Do you have a link to your wiki/page? The fact you are seeing <m> … </m> means the plugin hasn't been involved - if it is involved but can't do its stuff it'll replace the <m> … </m> with a message that explains what the problem could be. Its possible you have another (old) plugin which doesn't have the fix to allow plugins to work together. Try using <m> … </m> on a blank page by itself and see what happens. — Christopher Smith 2006-01-17 19:05
I have test your solution !!! And this is very strange. I my first page, the problem exist. In the page, we have not problem !!!! I don't understand. Junior76I took a copy of the content of the page that didn't work, and it works fine for me. What plugins do you have installed? — Christopher Smith 2006-01-18 13:51
- How to question
Hello, love the plugin and I have a suggestion/question on how to make it even better using the toolbar. Does anyone know what the code to insert into DokuWiki's toolbar.php (or elsewhere) to make a button that when pressed would insert (or bracket selected text) with the <m> and </m> tags? I tried doing it myself by inserting the following into toolbar.php and making the appropriate entry into the lang file.
array( 'type' => 'format', 'title' => $lang['qb_math'], 'icon' => 'bold.png', 'key' => 'm', 'open' => '<m>', 'close' => '</m>', ),
I used the 'bold.png' to test it before making a math button but it isn't working. Does anyone know how to do this? to make math entry a bit faster?
toolbar — Christopher Smith 2006-10-21 20:18
Bug in display of root expressions
When a root expression is longer than one character it may overwrite the root symbol and its contained expression. e.g.
<m 32>delim{|}{{1/N} sum{n=1}{N}{gamma(u_n)} - 1/{2 pi} int{0}{2 pi}{gamma(t) dt}}{|} <= epsilon/3</m>
It does render it, but some symbols like “=” or “+inf” are missing. Specifically, for example, the first example is missing “=”, both “+” and “+inf”. In fact, in all three examples what is missing is 1) all numbers 0..9, 2) all sings like “=”, “+”, “-”, 3) infinity. So, for example, row 1 of example 2 shows as “x y z”, nothing else, all numbers, “=”, “+”, “-” are missing…
What could be the reason for that?
P.S. As a suggestion: does it use different methods to render standard symbols (numbers, “=” etc.) and math symbols?