From 183851b06bd6c52f3cae5375f433da720d410447 Mon Sep 17 00:00:00 2001 From: Pierre Schmitz Date: Wed, 11 Oct 2006 18:12:39 +0000 Subject: MediaWiki 1.7.1 wiederhergestellt --- math/README | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 math/README (limited to 'math/README') diff --git a/math/README b/math/README new file mode 100644 index 00000000..e58cbf04 --- /dev/null +++ b/math/README @@ -0,0 +1,107 @@ +== About texvc == + +texvc takes LaTeX-compatible equations and produces formatted output in +HTML, MathML, and (via LaTeX/dvips/ImageMagick) rasterized PNG images. +Input data is parsed and scrutinized for safety, and the output includes +an estimate of whether the code is simple enough that HTML rendering will +look acceptable. + +The program was written by Tomasz Wegrzanowski for use with MediaWiki; +it's included as part of the MediaWiki package (http://wikipedia.sf.net) +and is under the GPL license. + +Please report bugs at: http://bugzilla.wikimedia.org/ (under "MediaWiki") + +== Setup == + +=== Requirements === + +OCaml 3.06 or later is required to compile texvc; this can be acquired +from http://caml.inria.fr/ if your system doesn't have it available. + +The makefile requires GNU make. + +Rasterization is done via LaTeX, dvips, and ImageMagick. These need +to be installed and in the PATH: latex, dvips, convert + +To work properly with rendering non-ASCII Unicode characters, a +supplemental TeX package is needed (cjk-latex in Debian) + +=== Installation === + +Run 'make' (or 'gmake' if GNU make is not your default make). This should +produce the texvc executable. + +If you're using MediaWiki's install.php and have enabled $wgUseTeX in your +LocalSettings.php, the installer will try to copy texvc into place, in the +'math' subdirectory under where wiki.phtml is installed. + + +== Usage == + +Normally texvc is called from MediaWiki's Math.php modules and everything +Just Works. It can be run manually for testing or for use in another app. + +=== Command-line parameters === + + texvc + +Be sure to properly quote the TeX code! + +Example: + + texvc /home/wiki/tmp /home/wiki/math "y=x+2" iso-8859-1 + +=== Output format === + +Status codes and HTML/MathML transformations are returned on stdout. +A rasterized PNG file will be written to the output directory, named +for the MD5 hash code. + +texvc output format is like this: + +%5 ok, but not html or mathml + c%5%h ok, conservative html, no mathml + m%5%h ok, moderate html, no mathml + l%5%h ok, liberal html, no mathml + C%5%h\0%m ok, conservative html, with mathml + M%5%h\0%m ok, moderate html, with mathml + L%5%h\0%m ok, liberal html, with mathml + X%5%m ok, no html, with mathml + S syntax error + E lexing error + F%s unknown function %s + - other error + + \0 - null character + %5 - md5, 32 hex characters + %h - html code, without \0 characters + %m - mathml code, without \0 characters + + +== Troubleshooting == + +Unforunately, many error conditions with rasterization are not well reported. +texvc will return as though everything is successful, and the only obvious +sign of problems for the user is a big X on a wiki page where an equation +should be. + +Try running texvc from the command line to ensure that the software it relies +upon is all set up. + +Ensure that the temporary and math directories exist and can be written to by +the user account the web server runs under; if you don't control the server, +you may have to make them world-writable. + +== Hacking == + +Before you start hacking on the math package its good to know the workflow, +which is basically: + +1. texvc gets called by includes/Math.php (check out the line begining with "$cmd") +2. texvc does its magic, which is basically to check for invalid latex code. +3. texvc takes the user input if valid and creates a latex file containing it, see + get_preface in texutil.ml +4. latex(1) gets called to create a .dvi file, then a .ps file is created from the + .dvi file using dvips(1), and finally convert(1) creates a .png file from + the .ps file. See render.ml for this process (commenting out the removal of + the temporary file is useful for debugging). -- cgit v1.2.3-54-g00ecf