org-tutorials/org-jsmath.org

   1 #+TITLE:      How to use jsMath with org-mode
   2 #+AUTHOR:     Darlan Cavalcante Moreira
   3 #+EMAIL:      darcamo at @gmail dot com
   4 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
   5 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate odd
   6 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   7 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 # This file is released by its authors and contributors under the GNU
  13 # Free Documentation license v1.3 or later, code examples are released
  14 # under the GNU General Public License v3 or later.
  15
  16 [[file:index.org][{Back to Worg's index}]]
  17
  18 * Why bother
  19   Here are some advantages and disadvantages about using jsMath instead of images.
  20 - Advantages ::
  21   - It's really pretty when you have all the fonts installed and you can zoom in
  22     without any loss of quality.
  23   - No need to generate images when exporting
  24     + When you see the generated HTML page the jsMath script is run and replaces
  25       the latex code appropriately. Because the efficiency of the java-script
  26       engine in modern browsers are increasing more and more these replacements
  27       are usually fast even if there are a lot of equations in the generated
  28       page.
  29     + On the other hand, creating images when exporting can take considerable
  30       time when there are many equations.
  31
  32 - Disadvantages ::
  33   - It is more difficult to setup
  34     + you have to install jsMath for authors, since you are creating pages with it.
  35     + you have to install jsMath for users, that is, install the fonts that will
  36       be used. If this is not done, jsMath will use images for the
  37       equations. You won't need to generate the images when exporting, since
  38       jsMath already has all images (it just put the pieces together)
  39   - It is more inconvenient to send the generated HTML page to a friend, since
  40     your friend will need to install the fonts used by jsMath.
  41
  42 * Download jsMath
  43   First we need to download jsMath for authors as explained in
  44   http://www.math.union.edu/~dpvc/jsMath/download/jsMath.html. The necessary
  45   files are [[http://sourceforge.net/project/showfiles.php?group_id=172663][here]]. Download the latest version of jsMath and also the "jsMath
  46   Image Fonts"[fn:1] file. Don't bother with the sprite fonts.
  47
  48 * Installation and configuration of jsMath
  49   Unpack the jsMath and jsMath-image-fonts archives, and place the fonts
  50   folder from the second archive into the jsMath folder from the first
  51   archive. That is, the fonts folder should be in the same folder as the
  52   jsMath.js file.
  53
  54   The main configuration file for jsMath is the easy/load.js script. We need
  55   to tell org-mode to include this script in each generated HTML
  56   file. Assuming that the jsMath folder is in the same parent folder as the
  57   folder containing the .org files, we can just add
  58   : #+STYLE: <SCRIPT SRC="../jsMath/easy/load.js"></SCRIPT>
  59   to the beginning of each org file. Alternatively, if org-publish is utilized
  60   we can put
  61   : :style "<link rel=\"stylesheet\" type=\"text/css\" href=\"../stylesheet.css\" />"
  62   in the project definition.
  63
  64
  65   With that, when the HTML generated by org-mode is viewed in the browser jsMath
  66   will replace the equations inside the math delimiters appropriately[fn:2]. By
  67   default, jsMath recognizes =\(= and =\)= as math delimiters for inline
  68   equations, and =\[= and =\]= (in addition to =$$=) as math delimiters for
  69   display equations.
  70
  71   To recognize =$= as math delimiters for inline equations change
  72   "processSingleDollars:" to 1 in the easy/load.js file.
  73
  74   You will probably want to load some additional plugins (for instance,
  75   AMSSymbols). In order to do that search for
  76     : loadFiles: [],
  77   in the easy/load.js file and add each plugin name separated by comma. Here I
  78   use
  79     : loadFiles: ["extensions/AMSmath.js","extensions/AMSsymbols.js", "extensions/autobold.js", "extensions/eqn-number.js"],
  80   The plugins AMSmath and AMSSymbols are self-explanatory and you will need them
  81   if you are using symbols or environments provided by AMS such as the symbol
  82   =\triangleq=.
  83
  84   The plugin eqn-number is really nice. It will number equations that have a
  85   label and allow you to reference them later with the ref command. For instance
  86     : \[
  87     : \label{a_label}
  88     : x=2*y
  89     : \]
  90     : Bla bla bla from equation \(\ref{a_label}\)
  91   will create a numbered equation that can be referred as showed in the
  92   example[fn:3]. The reference is a link to the equation.
  93
  94   The plugin autobold causes jsMath to use \boldsymbol{...} around
  95   mathematics that appears within <B>...</B> tags or has font-weight:bold
  96   applied via CSS rule.
  97
  98   Look in the extensions folder for other plugins (some of
  99   them are loaded automatically by jsMath and it is not necessary to include
 100   them in the loadFiles).
 101
 102   As last, if the browser freezes when jsMath is being loaded, try disable the
 103   autoload feature in the easy/load.js file.
 104
 105 * Org setup to keep LaTeX intact for jsMath
 106
 107   /(Updated 2010-01-07 by CM)/
 108
 109   Because we are going to process the latex code with jsMath, we
 110   must ensure that Org-mode leaves the latex code intact. This can
 111   now be done by setting the variable
 112   org-export-with-LaTeX-fragments to =verbatim=, e.g. by including
 113   this line at the beginning of the Org file:
 114   : #+OPTIONS: LaTeX:verbatim
 115   (Previously, the same effect was achieved with the lines
 116   : #+OPTIONS: ^:nil
 117   : #+OPTIONS: LaTeX:nil
 118   but this had the side effect of turning off sub- and superscripts
 119   in all non-latex text. The new =verbatim= option can be used with
 120   =^:t=.)
 121
 122 * As pretty as it can get
 123   jsMath should be working with org-mode by now, but it is using the image fonts
 124   and warns the user with a red frame at the top of the page. That means that
 125   the "installation for authors" part is done and now we only need to install
 126   some .ttf fonts available at the jsMath website. Download the file
 127   [[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.
 128
 129   The package TeX-fonts-linux has the most common ones, but it is also good to
 130   install the extra fonts (to see, for instance, the "mathcal" symbols).
 131
 132 * Extra fonts
 133   Some additional fonts available in the [[http://www.math.union.edu/~dpvc/jsMath/download/extra-fonts/welcome.html][extra fonts]] page are useful.  Download
 134   the zip file for authors (for instance bbold10.zip) and extract it to the
 135   jsMath/fonts folder. Then download the corresponding .ttf file to the ~/.fonts
 136   (I prefer the light version because the dark version may be confused with
 137   bold). You don't need to install all of the extra fonts. The ones I found
 138   useful are bbold10, cmbsy10, cmmib10, msam10 and msbm10[fn:4].
 139
 140 * Footnotes
 141
 142 [fn:1] The Image Fonts are the images of each symbol that jsMath uses as a
 143 fallback when the user does not have the ttf fonts installed. We will install
 144 these fonts later and it would be possible to avoid installing the image fonts,
 145 but it requires an additional configuration step.
 146
 147 [fn:2] A button "jsMath" should appear at the bottom east of the page.
 148
 149 [fn:3] The Math delimiters are necessary to tell jsMath to process the \ref
 150 command.
 151
 152 [fn:4] Without the extra fonts some symbols won't be showed even if the plugin
 153 is loaded, such as the \triangleq symbol.