Note: You are currently viewing documentation for Moodle 3.0. Up-to-date documentation for the latest stable version of Moodle may be available here: TeX notation filter.

TeX notation filter: Difference between revisions

From MoodleDocs
m (removing new features template)
 
(38 intermediate revisions by 9 users not shown)
Line 1: Line 1:
Location: TeX Notation settings link in ''Administration > Modules > Filters > Manage filters''
{{Filters}}
The TeX Filter is a core Moodle filter intended to allow one to convert tex expressions into GIF, PNG or SVG images. The filter relies on some additional binaries to accomplish this for expressions contained between appropriate tokens.  Where these binaries are not available,  Moodle provides for a fallback through the use of  Mimetex. Versions of MimeTex for Linux (glib2.3 32bit), Windows, Mac OS X and FreeBSD are included in the Moodle distribution. There are other technologies available for displaying Tex (see the section on [[Mathematics]] tools for a discussion.) 


'''Note''': being based on binaries it requires the availability of three PHP program execution functions: <code><nowiki>exec</nowiki></code>, <code><nowiki>shell_exec</nowiki></code> and <code><nowiki>system</nowiki></code>.


The TeX Filter converts TeX code into GIF images. Versions of MimeTex for Linux (glib2.3), Windows, Mac OS X and FreeBSD are included in the Moodle distribution and are easily activated. Moodle also uses any one of a number of programs to render the TeX Notation into images. Since Moodle 1.6, Moodle allows the installation and implementation of full Latex binaries such as AsciiMathML or DragMath or many other maths markup packages.
== Methods and Usage ==


To avoid confusion you should note that the TeX filter has two separate methods for converting the TeX notation to images. The preferred method is a collection of three binaries that you are responsible for installing (if they are not already present,  though many webhosts make these available) and configuring on your server. The filter settings page relates entirely to this method. If this fails for any reason the filter will fall back to a single binary - MimeTeX.  A number of different builds are included in the Moodle distribution for popular operating systems,  though Mimetex and its bigger brother, MathTex are easy enough to compile and install if you have systems administration experience.


=== Introduction - A Tale of Two Filters ===
Before doing anything else, you need to go to ''Settings > Site administration > Plugins > Filters'' and activate the TeX Notation Filter. If you want to use the Algebra filter (another core filter) since the Algebra Filter is really only a "front end" to the Tex filter,  you should also turn on the Algebra filter.  For more information on the Algebra Filter see the [[Algebra filter]].


To avoid confusion you should note that the TeX filter has two separate methods for converting the TeX notation to images. The preferred method is a collection of three binaries that you are responsible for installing and configuring on your server. The filter settings page relates entirely to this method. If this fails for any reason the filter will fall back to a single binary - MimeTeX - that is included with Moodle. A number of different builds are included for popular operating systems.  
Once the filter is turned on and properly configured you can make use of it by
 
including a TeX expression delimited by double-dollar signs. Example:
=== Turn the Filters On ===
    $$ \sqrt{x + y} $$


Before doing anything else, you need to go to '''Administration > Filters > Manage Filters''' and activate the Algebra and TeX Notation Filters, the default Filters. If you install other TeX filters, they too will need to be activated.  
If this does not display properly, see the information on debugging.


=== Usage ===
== MimeTeX ==


To use the default MimeTeX filter the resource should include a TeX expression delimited by double-dollar signs. Example:
Moodle may use a pre-built MimeTeX binary (located in the filters/tex directory) as a fallback if it can't properly access dvips, convert and latex binaries. There are a number of different versions for different operating systems. The TeX filter picks the appropriate binary for the detected host operating system (you will need to hack the script if your operating system is not included). Note that your web server needs to be set up with appropriate permissions for running binaries in that location.  
    $$ \sqrt{x + y} $$


If this does not display properly, then there are two possible reasons, turn the filters on and check the paths to the latex, dvips and conversion binaries. You can find those in the Tex Notation Settings page.
The [http://www.forkosh.com/mimetexmanual.html MimeTeX manual] is available but is arguably intended for persons with systems administration experience and does not specifically address the Moodle environment.


=== MimeTeX ===
You should only use MimeTeX if installing the full LaTeX system fails or the binaries are not available on your system. The results are not nearly as good.


Moodle uses a number of MimeTeX pre-built binaries in the Moodle standard distribution and are located in the filters/tex directory. These are "fallback" binaries that will operate if you have no other TeX filter in place or it the one you have does not function properly. There are a number of different versions for different operating systems. The TeX filter picks the appropriate binary for the detected host operating system (you will need to hack the script if your operating system is not included). Note that your web server needs to be set up with appropriate permissions for running binaries in that location.
== Compatability with MathJax ==


Windows Users need to download and install at least two other programs, a TeX editing program, MikTeX is one, and a image generating program, either GhostScript or Image Magick, to use a TeX filter, but the fallback of MimeTeX appears to be sufficient to at least get started.  
In Moodle 2.8 onwards, the TeX Notation and MathJaxloader filter may be used in combination.  If both filters are enabled on the page, images will be displayed first by the TeX notation filter, and the MathJax version of the TeX expression will replace a little while later when MathJax has finished loading and processing.  If both filters are available, a teacher may decide which to use in an activity by enabling one and disabling the other.


If you use TeX in a GIFT question import file you must escape { } and = (even # and ~) with a \ before each symbol.
== Site administration settings ==


More information on [[Using TeX Notation]]. The [http://www.forkosh.com/mimetexmanual.html MimeTeX manual] is available and, potentially, it could be useful, but maybe not - too confusing if you have little experience with TeX and has no relationship with the Moodle environment.
Location: TeX Notation settings link in ''Settings > Site administration > Plugins > Filters > Manage filters''
 
=== Settings Page ===


The TeX filter settings page are primarily intended to adjust the operation of the LaTeX renderer. The defaults for the three path settings are selected according to the detection of the operating system on which Moodle is running. These are simply suggested common values - Moodle does not check that the binaries actually exist at these locations. More recent versions of Moodle show a green tick or a red cross next to the path setting - this shows that the binary exists at that location (only). The settings have no effect on the operation of the MimeTex binary (used if any of these binaries are not found).
The TeX filter settings page are primarily intended to adjust the operation of the LaTeX renderer. The defaults for the three path settings are selected according to the detection of the operating system on which Moodle is running. These are simply suggested common values - Moodle does not check that the binaries actually exist at these locations. More recent versions of Moodle show a green tick or a red cross next to the path setting - this shows that the binary exists at that location (only). The settings have no effect on the operation of the MimeTex binary (used if any of these binaries are not found).
Line 37: Line 37:
==== Installing the binaries ====
==== Installing the binaries ====


This depends on your platform, but for a typical Linux install you are going to need a latex implementation (e.g. tetex) and the convert binary (e.g, from ImageMagick). A typical command - in this case for Ubuntu - that installs everything you need would look something like:
This depends on your platform, but for a typical install you are going to need a LaTeX implementation. On modern Linux implementations you should look for the 'texlive' package (e.g. ''apt-get install texlive'') although a Windows version is available (see [http://www.tug.org/texlive/doc/texlive-en/texlive-en.html Tex Live]). It is highly unlikely that you will have all these binaries as part of a standard install. If you cannot find texlive you may have to install LaTeX, Ghostscript and ImageMagick separately. While not endorsed by Moodle.org, a simple installation binary for Windows is [http://miktex.org/| MikTeX]. 


    apt-get install tetex-base tetex-bin tetex-extra imagemagick ghostscript
The filter settings page will try to guess the most likely location for the binary files depending on the detected platform. If correct, green ticks will appear against each setting. If red crosses appear you will need to check and modify the settings as required. A simple check is made to establish if the binaries exist at the given paths. A tick or a cross is displayed alongside each as a result. Note that this does not check that the application actually works, just that it is there.


On newer versions of Ubuntu, tetex has been replaced by '''texlive'''. You may need to experiment a bit (for example, ImageMagick doesn't seem to work properly on Solaris but Ghostscript does). If you find the combination that works for your system kindly add the info to this page! On Windows however, ImageMagic seems to work as it should with '''teXLive'''.
Some systems supply the fonts as separate packages. If you are having problems make sure you have all the fonts you need installed. You may need to track down an 'extra' fonts package to get the required maths fonts.


==== LaTeX preamble ====
==== LaTeX preamble ====
Line 53: Line 53:
==== Density ====
==== Density ====


This setting effects the size of the resulting image. The default setting is 120 pixels, and it produces a reasonable image but for some complicated equations, this still may not be enough. It may be that anything less is not going to produce an image of sufficient quality but the image size can be controlled by the TeX encoding when the page is rendered.
This setting effects the size of the resulting image. The default setting is 120 pixels, and it produces an image of  reasonable quality, but for some complicated equations, this still may not be enough. It may be that anything less is not going to produce an image of sufficient quality but the image size can be controlled by the TeX encoding when the page is rendered.


==== Path of ''latex'' binary ====
==== Path of ''latex'' binary ====
Line 59: Line 59:
Path to standard latex binary.
Path to standard latex binary.


On a MacOS X, the path is "/usr/texbin/".
On Unix based systems it is normally "/usr/bin/latex". On a MacOS X, the path is "/usr/texbin/".


In Windows, using MiKTeX, it is usually something like C:\texmf\miktex\bin\latex.exe
In Windows, using MiKTeX, it is usually something like C:\texmf\miktex\bin\latex.exe
Line 67: Line 67:
Path to standard dvips binary - generally distributed as part of a LaTeX system.
Path to standard dvips binary - generally distributed as part of a LaTeX system.


On a MacOS X, the path is "/usr/texbin/".
On Unix based systems it is normally "/usr/bin/dvips". On a MacOS X, the path is "/usr/texbin/".


On Windows using MikTeX is is usually something like C:\texmf\miktex\bin\dvips.exe
On Windows using MikTeX is is usually something like C:\texmf\miktex\bin\dvips.exe
Line 73: Line 73:
==== Path of ''convert'' binary ====
==== Path of ''convert'' binary ====


Path to standard convert binary. This is distributed as part of the Ghostscript system, or ImageMagick in Linux.
Path to standard convert binary. It is necessary to produce GIF or PNG images from using the latex and dvips binaries. This is distributed as part of the Ghostscript system, or ImageMagick in Linux.


A simple check is made to establish if the binaries exist at the given paths. A tick or a cross is displayed alongside each as a result. Note that this does not check that the application actually works, just that it is there.
On Unix based systems it is normally "/usr/bin/convert". On a MacOS X, the path is "/usr/local/bin/".
 
On a MacOS X, the path is "/usr/local/bin/".


On a Windows based PC the path is something like C:\Program Files\ImageMagick\convert.exe (for ImageMagick, but something else for GhostScript.)
On a Windows based PC the path is something like C:\Program Files\ImageMagick\convert.exe (for ImageMagick, but something else for GhostScript.)


=== Debugging TeX filter ===
==== Path of ''dvisvgm'' binary ====


The TeX filter has a debugging script (which will be much more helpful if you turn moodle debugging on) included that should help if you are having problems. The URL will be as follows...
This binary is used instead of convert to produce SVG images. This is distributed as part of TeXlive on Linux although it may be require the full or extra packages to be installed.


  http://your.moodle.path/filter/tex/texdebug.php
On Unix based systems it is normally "/usr/bin/dvisvgm".


You can either enter this path explicitly or with appropriate role permissions the TeX images (or more likely incorrectly rendered text, if you need debugging) will link to this. There are a number of options and suggestions to facilitate debugging the filter. Note that options for the latex/ghostscript versions are only provided from Moodle version 1.8.3.
On a Windows based PC  a compiled binary is available from [http://dvisvgm.sourceforge.net/Downloads sourceforge] and can placed in the same directory with the latex binary.


=== Mimetex on Debian based systems ===
==== Path of ''mimetex'' binary ====


For some reason, the mimetex file that comes with Moodle doesn't work on Debian based systems (like Debian, Ubuntu, ...).
If this is blank and the binaries above are missing or fail, the TeX filter will attempt to use a mimetex binary distributed with Moodle. If you have installed mimetex on the server and would rather use it include the path here.
What works is installing Mimetex and Ghostscript on your server as Debian package (needs to be executed as root):


apt-get install tetex-extra mimetex gs
== Debugging TeX filter ==


Move your old mimetex file away
The TeX filter has a debugging script (which will be much more helpful if you turn moodle debugging on) included that should help if you are having problems. The URL will be as follows...


mv /var/www/moodle/filter/tex/mimetex.linux /var/www/moodle/filter/tex/mimetex.linux.old
  <nowiki>http://your.moodle.path/filter/tex/texdebug.php</nowiki>


Make a symbolic link to the mimetex file, installed by the debian installer
You can either enter this path explicitly or with appropriate role permissions the TeX images (or more likely incorrectly rendered text, if you need debugging) will link to this. On more recent versions of Moodle you are ''required'' to be logged in as an Administrator to access this facility.
 
ln -s /usr/bin/mimetex /var/www/moodle/filter/tex/mimetex.linux


== See also ==
== See also ==


* [[Filters]]
* [http://moodle.org/mod/glossary/view.php?id=2739&mode=letter&hook=M&sortkey=CREATION&sortorder=asc  TeX Filter Glossary] - a [[Glossary|glossary]] you can add to your course which details usage of the supported [[TeX notation]].
* [http://moodle.org/mod/glossary/view.php?id=2739&mode=letter&hook=M&sortkey=CREATION&sortorder=asc  TeX Filter Glossary] - a [[Glossary|glossary]] you can add to your course which details usage of the supported [[TeX notation]].
* [http://www.latex-project.org/ LaTeX] - the LaTeX document preparation system.
* [http://www.latex-project.org/ LaTeX] - the LaTeX document preparation system.
Line 114: Line 108:
* [http://www.imagemagick.org/script/index.php ImageMagick] - required to render images for Windows
* [http://www.imagemagick.org/script/index.php ImageMagick] - required to render images for Windows
* [[Using TeX Notation]]
* [[Using TeX Notation]]
* [[Advanced Maths Tools]] for Moodle 2.x - SEE - The Next Generation of TeX Tools
* [https://moodle.org/mod/forum/view.php?id=752 Mathematics tools forum] on moodle.org


[[Category:Filter]]
[[Category:Site administration]]
[[Category:Mathematics]]
[[Category:Mathematics]]
[[de:TeX-Notation]]
[[es:Filtro de notación TeX]]

Latest revision as of 14:43, 20 April 2015

The TeX Filter is a core Moodle filter intended to allow one to convert tex expressions into GIF, PNG or SVG images. The filter relies on some additional binaries to accomplish this for expressions contained between appropriate tokens. Where these binaries are not available, Moodle provides for a fallback through the use of Mimetex. Versions of MimeTex for Linux (glib2.3 32bit), Windows, Mac OS X and FreeBSD are included in the Moodle distribution. There are other technologies available for displaying Tex (see the section on Mathematics tools for a discussion.)

Note: being based on binaries it requires the availability of three PHP program execution functions: exec, shell_exec and system.

Methods and Usage

To avoid confusion you should note that the TeX filter has two separate methods for converting the TeX notation to images. The preferred method is a collection of three binaries that you are responsible for installing (if they are not already present, though many webhosts make these available) and configuring on your server. The filter settings page relates entirely to this method. If this fails for any reason the filter will fall back to a single binary - MimeTeX. A number of different builds are included in the Moodle distribution for popular operating systems, though Mimetex and its bigger brother, MathTex are easy enough to compile and install if you have systems administration experience.

Before doing anything else, you need to go to Settings > Site administration > Plugins > Filters and activate the TeX Notation Filter. If you want to use the Algebra filter (another core filter) since the Algebra Filter is really only a "front end" to the Tex filter, you should also turn on the Algebra filter. For more information on the Algebra Filter see the Algebra filter.

Once the filter is turned on and properly configured you can make use of it by including a TeX expression delimited by double-dollar signs. Example:

   $$ \sqrt{x + y} $$

If this does not display properly, see the information on debugging.

MimeTeX

Moodle may use a pre-built MimeTeX binary (located in the filters/tex directory) as a fallback if it can't properly access dvips, convert and latex binaries. There are a number of different versions for different operating systems. The TeX filter picks the appropriate binary for the detected host operating system (you will need to hack the script if your operating system is not included). Note that your web server needs to be set up with appropriate permissions for running binaries in that location.

The MimeTeX manual is available but is arguably intended for persons with systems administration experience and does not specifically address the Moodle environment.

You should only use MimeTeX if installing the full LaTeX system fails or the binaries are not available on your system. The results are not nearly as good.

Compatability with MathJax

In Moodle 2.8 onwards, the TeX Notation and MathJaxloader filter may be used in combination. If both filters are enabled on the page, images will be displayed first by the TeX notation filter, and the MathJax version of the TeX expression will replace a little while later when MathJax has finished loading and processing. If both filters are available, a teacher may decide which to use in an activity by enabling one and disabling the other.

Site administration settings

Location: TeX Notation settings link in Settings > Site administration > Plugins > Filters > Manage filters

The TeX filter settings page are primarily intended to adjust the operation of the LaTeX renderer. The defaults for the three path settings are selected according to the detection of the operating system on which Moodle is running. These are simply suggested common values - Moodle does not check that the binaries actually exist at these locations. More recent versions of Moodle show a green tick or a red cross next to the path setting - this shows that the binary exists at that location (only). The settings have no effect on the operation of the MimeTex binary (used if any of these binaries are not found).

Installing the binaries

This depends on your platform, but for a typical install you are going to need a LaTeX implementation. On modern Linux implementations you should look for the 'texlive' package (e.g. apt-get install texlive) although a Windows version is available (see Tex Live). It is highly unlikely that you will have all these binaries as part of a standard install. If you cannot find texlive you may have to install LaTeX, Ghostscript and ImageMagick separately. While not endorsed by Moodle.org, a simple installation binary for Windows is MikTeX.

The filter settings page will try to guess the most likely location for the binary files depending on the detected platform. If correct, green ticks will appear against each setting. If red crosses appear you will need to check and modify the settings as required. A simple check is made to establish if the binaries exist at the given paths. A tick or a cross is displayed alongside each as a result. Note that this does not check that the application actually works, just that it is there.

Some systems supply the fonts as separate packages. If you are having problems make sure you have all the fonts you need installed. You may need to track down an 'extra' fonts package to get the required maths fonts.

LaTeX preamble

Enables the LaTeX preamble to be specified. The default should work for most users, but you may need to change it to support non-latin character sets etc. Please see the LaTeX documentation for further details.

Transparent colour

This should be set to your normal text background colour. The default setting is #FFFFFF (i.e., white).

Density

This setting effects the size of the resulting image. The default setting is 120 pixels, and it produces an image of reasonable quality, but for some complicated equations, this still may not be enough. It may be that anything less is not going to produce an image of sufficient quality but the image size can be controlled by the TeX encoding when the page is rendered.

Path of latex binary

Path to standard latex binary.

On Unix based systems it is normally "/usr/bin/latex". On a MacOS X, the path is "/usr/texbin/".

In Windows, using MiKTeX, it is usually something like C:\texmf\miktex\bin\latex.exe

Path of dvips binary

Path to standard dvips binary - generally distributed as part of a LaTeX system.

On Unix based systems it is normally "/usr/bin/dvips". On a MacOS X, the path is "/usr/texbin/".

On Windows using MikTeX is is usually something like C:\texmf\miktex\bin\dvips.exe

Path of convert binary

Path to standard convert binary. It is necessary to produce GIF or PNG images from using the latex and dvips binaries. This is distributed as part of the Ghostscript system, or ImageMagick in Linux.

On Unix based systems it is normally "/usr/bin/convert". On a MacOS X, the path is "/usr/local/bin/".

On a Windows based PC the path is something like C:\Program Files\ImageMagick\convert.exe (for ImageMagick, but something else for GhostScript.)

Path of dvisvgm binary

This binary is used instead of convert to produce SVG images. This is distributed as part of TeXlive on Linux although it may be require the full or extra packages to be installed.

On Unix based systems it is normally "/usr/bin/dvisvgm".

On a Windows based PC a compiled binary is available from sourceforge and can placed in the same directory with the latex binary.

Path of mimetex binary

If this is blank and the binaries above are missing or fail, the TeX filter will attempt to use a mimetex binary distributed with Moodle. If you have installed mimetex on the server and would rather use it include the path here.

Debugging TeX filter

The TeX filter has a debugging script (which will be much more helpful if you turn moodle debugging on) included that should help if you are having problems. The URL will be as follows...

  http://your.moodle.path/filter/tex/texdebug.php

You can either enter this path explicitly or with appropriate role permissions the TeX images (or more likely incorrectly rendered text, if you need debugging) will link to this. On more recent versions of Moodle you are required to be logged in as an Administrator to access this facility.

See also