jsMath filter for Moodle
========================

by Davide P. Cervone <dpvc at union dot edu>

_________________________________________________________________

OVERVIEW:

This is a Moodle filter that uses the jsMath package to display
mathematics within a web browser rather than a program (like
mimeTeX) that runs on the server to create images.  JsMath uses
JavaScript, CSS and native fonts to generate the mathematics from
TeX code that you enter in your Moodle documents.

You indicate what is mathematics within your messages by enclosing
it either within \(...\) for in-line mathematics, or \[...\] for
displayed equations.  It is possible to customize the delimiters to
better suit your needs, e.g., to make $...$ and $$...$$ be the
markers for mathematics, and the jsMath filter can also interpret
the <tex>...</tex> tags used by the tex filter.

_________________________________________________________________

INSTALLATION:

1. Get the latest jsMath from 

      http://sourceforge.net/project/showfiles.php?group_id=172663

   or use the copy included here (which may not be so up-to-date). 
   Be sure to get both the jsMath zip file and the jsMath-image-fonts
   zip file.  You must use jsMath v3.0 or higher.

2. Unpack both of these zip files, and put the fonts folder that you
   get from the image-fonts archive into the jsMath folder.  You should
   now have jsMath and jsMath/fonts (and the latter folder should contain
   folders named after TeX fonts).

3. Create a filter folder called moodle/filter/jsmath on your server,
   and put the jsMath folder into it. You should have folders called
   moodle/filter/jsmath/jsMath and moodle/filter/jsmath/jsMath/fonts.
   Note the nested jsMath inside another folder called jsmath.  The
   capitalization is important, as is the level of nesting.

4. Put the filter.php and javascript.php files from the directory
   containing this README file into moodle/filter/jsmath.

5. Edit the configuration array at the top of
   moodle/filter/jsmath/javascript.php to suit your needs.
   Similarly, edit the array at the top of filter.php if needed.

6. Activate the jsMath filter using the moodle administration
   account.  If you have the older jstex filter active, you should turn
   it off.  If you have the mimeTeX-based filter installed, you should
   deactivate it as well.

7. With the default settings in the jsMath filter, you should now see
   your mathematics being processed by jsMath rather than mimeTeX. On
   any page containing mathematics, there will be a small jsMath button
   in the lower right-hand corner, and it will let your viewers adjust the
   preferences for jsMath, including the scaling factor and the rendering
   method that they want to use.  There are four rendering methods: one
   that uses the native Tex fonts (if they have them), two that use image
   fonts (the second zip file you downloaded above), and one that uses
   native Unicode fonts.  The native TeX fonts will work best, and the
   Unicode fonts will work least well.  At this point you will probably
   be using the image fonts.

8. To get the native TeX fonts, go to the jsMath font download page
   (http://www.math.union.edu/locate/jsMath/download/jsMath-fonts.html)
   and download one of the tex-fonts archives, depending on how dark
   you want your font to be -- read the instructions on that page.
   (The TeX-fonts-10.zip and TeX-fonts-25.zip included here are
   versions appropriate for the Mac and PC, respectively.)  Unpack
   this and install it in the fonts folder on your browser's computer
   (not on the server).  Any user who wants to use the native TeX fonts
   will have to do the same (there are instructions on the fonts
   download page).  If a user doesn't do this, it will still be OK,
   since jsMath will then use the image fonts, which work fine for
   most situations.
   
__________________________________________________________

CUSTOMIZATION

This filter is similar to the jstex filter that Zbigniew Fiedorowicz wrote
sometime in 2004, but his was less sophisticated in terms of its pattern
matching, and also required a change to weblib.php.  This version works
without modifications to the system.  It includes more features and is
easier to customize.  There are comments at the top of the javascript.php
file that tell you how it works, and below that is an array that
enables/disables the various features.  For example, if you want jsMath to
process $...$ for in-line math, set the processSingleDollars to 1 instead
of 0.  (This is off by default, since single dollar signs are used in
normal text too frequently, and this could cause unwanted side effects.
Users can use \$ to prevent jsMath from using them as math delimiters, but
they would have to be told about that.)

There are other settings that control whether to process $$...$$ (in
addition to the \(...\) and \[...\] that the jsMath filter always
uses), whether to process <tex>...</tex> tags, whether to use mimeTeX
compatibility mode, what default scaling factor to use for the
mathematics, and whether to show the warning message for missing
fonts.
__________________________________________________________

ADDITIONAL FONTS

JsMath includes only 6 fonts by default, but you may need to use additional
symbols that are not available in these fonts, for example, the AMS symbols
that are part of the AmSTeX file formats.  JsMath is capable of using
additional fonts, but you will need to obtain them from the jsMath extra-
font download page (http://www.math.union.edu/locate/jsMath/download/extra-fonts/),
and install them on your server.

JsMath includes extensions for defining the control sequences needed for
some of these fonts.  For example, the AMSsymbols extension makes accessing
the AMS symbol fonts easy, and the boldsymbol extension activates the
bold math fonts (cmmib10 and cmbsy10).

To use one of these extensions, first obtain the needed fonts (for both the
server and the browser), and then modify the javascript.php file to include
the appropriate extension in the loadFiles parameter of the configuration array
at the top of that file.  For example, you could change it to

    loadFiles: ['extensions/AMSsymbols.js','extensions/boldsymbol.js'],

to activate both of these extensions.

If you want to use a font that doesn't include an extension to activate it,
you can either add it to the loadFonts parameter in the javascript.php file,
or use jsMath's autoloading feature to load the font by accessing one of its
characters with the \char command within your mathematics.  E.g.,
\char{msam10}{65} would load the msam10 font automatically and insert the
character at position 65 within that font.  See the jsMath extra-font symbol
charts for details, and the jsMath author documentation for additional details.
