#+STARTUP: odd
#+OPTIONS: toc:nil
#+TITLE:How to use jsMath with org-mode

* Why bother
  Here are some advantages and disadvantages about using jsMath instead of images.
- Advantages ::
  - It's really pretty when you have all the fonts installed and you can zoom in
    without any loss of quality.
  - No need to generate images when exporting
    + When you see the generated HTML page the jsMath script is run and replaces
      the latex code appropriately. Because the efficiency of the java-script
      engine in modern browsers are increasing more and more these replacements
      are usually fast even if there are a lot of equations in the generated
      page.
    + On the other hand, creating images when exporting can take considerable
      time when there are many equations.

- Disadvantages ::
  - It is more difficult to setup
    + you have to install jsMath for authors, since you are creating pages with it.
    + you have to install jsMath for users, that is, install the fonts that will
      be used. If this is not done, jsMath will use images for the
      equations. You won't need to generate the images when exporting, since
      jsMath already has all images (it just put the pieces together)
  - It is more inconvenient to send the generated HTML page to a friend, since
    your friend will need to install the fonts used by jsMath.

    
    Because we are going to process the latex code with jsMath, the variable
    org-export-with-LaTeX-fragments must be set to nil and the options
    : #+OPTIONS: ^:nil
    : #+OPTIONS: LaTeX:nil
    must be in the beginning of the org file. These measures are necessary
    assure that the latex code will be left intact by org-mode.

* Download jsMath
  First we need to download jsMath for authors as explained in
  http://www.math.union.edu/~dpvc/jsMath/download/jsMath.html. The necessary
  files are [[http://sourceforge.net/project/showfiles.php?group_id=172663][here]]. Download the latest version of jsMath and also the "jsMath
  Image Fonts"[fn:1] file. Don't bother with the sprite fonts.
  
* Installation and configuration of jsMath
  Unpack the jsMath and jsMath-image-fonts archives, and place the fonts
  folder from the second archive into the jsMath folder from the first
  archive. That is, the fonts folder should be in the same folder as the
  jsMath.js file.
  
  The main configuration file for jsMath is the easy/load.js script. We need
  to tell org-mode to include this script in each generated HTML
  file. Assuming that the jsMath folder is in the same parent folder as the
  folder containing the .org files, we can just add
  : #+STYLE: <SCRIPT SRC="../jsMath/easy/load.js"></SCRIPT>
  to the beginning of each org file. Alternatively, if org-publish is utilized
  we can put
  : :style "<link rel=\"stylesheet\" type=\"text/css\" href=\"../stylesheet.css\" />"
  in the project definition.

  
  With that, when the HTML generated by org-mode is viewed in the browser jsMath
  will replace the equations inside the math delimiters appropriately[fn:2]. By
  default, jsMath recognizes =\(= and =\)= as math delimiters for inline
  equations, and =\[= and =\]= (in addition to =$$=) as math delimiters for
  display equations.
  
  To recognize =$= as math delimiters for inline equations change
  "processSingleDollars:" to 1 in the easy/load.js file.

  You will probably want to load some additional plugins (for instance,
  AMSSymbols). In order to do that search for
    : loadFiles: [],
  in the easy/load.js file and add each plugin name separated by comma. Here I
  use
    : loadFiles: ["extensions/AMSmath.js","extensions/AMSsymbols.js", "extensions/autobold.js", "extensions/eqn-number.js"],
  The plugins AMSmath and AMSSymbols are self-explanatory and you will need them
  if you are using symbols or environments provided by AMS such as the symbol
  =\triangleq=.
  
  The plugin eqn-number is really nice. It will number equations that have a
  label and allow you to reference them later with the ref command. For instance
    : \[
    : \label{a_label}
    : x=2*y
    : \]
    : Bla bla bla from equation \(\ref{a_label}\)
  will create a numbered equation that can be referred as showed in the
  example[fn:3]. The reference is a link to the equation.

  The plugin autobold causes jsMath to use \boldsymbol{...} around
  mathematics that appears within <B>...</B> tags or has font-weight:bold
  applied via CSS rule.

  Look in the extensions folder for other plugins (some of
  them are loaded automatically by jsMath and it is not necessary to include
  them in the loadFiles).

  As last, if the browser freezes when jsMath is being loaded, try disable the
  autoload feature in the easy/load.js file.

* As pretty as it can get
  jsMath should be working with org-mode by now, but it is using the image fonts
  and warns the user with a red frame at the top of the page. That means that
  the "installation for authors" part is done and now we only need to install
  some .ttf fonts available at the jsMath website. Download the file
  [[http://www.math.union.edu/~dpvc/jsMath/download/TeX-fonts-linux.tgz][TeX-fonts-linux.tgz]] in the website. and extract the files to ~/.fonts.

  The package TeX-fonts-linux has the most common ones, but it is also good to
  install the extra fonts (to see, for instance, the "mathcal" symbols).

* Extra fonts
  Some additional fonts available in the [[http://www.math.union.edu/~dpvc/jsMath/download/extra-fonts/welcome.html][extra fonts]] page are useful.  Download
  the zip file for authors (for instance bbold10.zip) and extract it to the
  jsMath/fonts folder. Then download the corresponding .ttf file to the ~/.fonts
  (I prefer the light version because the dark version may be confused with
  bold). You don't need to install all of the extra fonts. The ones I found
  useful are bbold10, cmbsy10, cmmib10, msam10 and msbm10[fn:4].

* Footnotes

[fn:1] The Image Fonts are the images of each symbol that jsMath uses as a
fallback when the user does not have the ttf fonts installed. We will install
these fonts later and it would be possible to avoid installing the image fonts,
but it requires an additional configuration step.

[fn:2] A button "jsMath" should appear at the bottom east of the page.

[fn:3] The Math delimiters are necessary to tell jsMath to process the \ref
command.

[fn:4] Without the extra fonts some symbols won't be showed even if the plugin
is loaded, such as the \triangleq symbol.