Math support in Maruku

This document describes Maruku’s support of inline LaTeX-style math.

At the moment, these features are experimental, are probably buggy and the syntax and implementation are bound to change in the near future.

Also, there are many subtleties of which one must care for correctly serving the XHTML+MathML document to browsers. In fact, this documentation is not enough to get you started, unless you feel very adventurous.

1. Syntax

1.1. Inline math

Inline math is contained inside couples of $.

Everything inside will be passed as-is to LaTeX: no Markdown interpretation will take place.

Example: $x^{n}+y^{n} \neq z^{n}$ for $n \geq 3$

Example: $x^n+y^n\ne z^n$ for $n\ge 3$

1.2. Equations

Equations are specified using either the $$ ... $$ or \[ ... \] LaTeX notation. Equations can span multiple lines.

\[ 
\sum_{n=1}^\infty \frac{1}{n} 
\text{ is divergent, but } 
\lim_{n \to \infty} \sum_{i=1}^n \frac{1}{i} - \ln n \text{exists.} 
\]

$$\sum _{n=1}^{\mathrm{\infty }}\frac{1}{n}\text{is divergent, but}\underset{n\to \mathrm{\infty }}{\lim }\sum _{i=1}^n\frac{1}{i}-\ln n\text{exists.}$$

\sum_{n=1}^\infty \frac{1}{n} \text{ is divergent, but } \lim_{n \to \infty} \sum_{i=1}^n \frac{1}{i} - \ln n \quad \text{exists.}

Some random AMSTeX symbols:

$$ \beth \Subset \bigtriangleup \bumpeq \ggg \pitchfork $$ 

2. Cross references

Create a label for an equation in two ways:

• LaTeX style:

  Consider \eqref{a}:
  
  $$ \alpha = \beta  \label{a} $$

• More readable style:

  Consider (eq:a):
  
  $$ \alpha = \beta $$        (a)

You can mix the two.

Labels will work as expected also in the PDF output, whatever style you use: Maruku will insert the necessary \label commands.

The following are 4 equations, labeled A,B,C,D:

You can now refer to (1), (2), (3), (4).

3. Enabling the extension

3.1. On the command line

Use the -m option to choose the kind of output. Possible choices are:

--math-engine itex2mml : Outputs MathML using itex2mml.
--math-engine ritex : Outputs MathML using ritex.
--math-engine blahtex : Outputs MathML using blahtex.
--math-images blahtex : Outputs PNGs using blahtex.

3.2. With embedded Maruku

You have to enable the math extension like this:

require 'maruku'          # loads maruku
require 'maruku/ext/math' # loads the math extension

Use the following to choose the engine:

MaRuKu::Globals[:html_math_engine] = 'ritex'
MaRuKu::Globals[:html_png_engine] =  'blahtex'

Available MathML engines are ‘none’, ‘itex2mml’, ‘blahtex’. ‘blahtex’ is the only PNG engine available.

4. External libraries needed

To output MathML or PNGs, it is needed to install one of the following libraries

4.1. Using ritex

Install with

$ gem install ritex

ritex’s abilities are very limited, but it is the easiest to install.

4.2. Using itex2mml

itex2mml supports much more LaTeX commands/environments than ritex.

Install itex2mml using the instructions at:

http://golem.ph.utexas.edu/~distler/blog/itex2MML.html

This is a summary of the available LaTeX commands:

http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html

Moreover, Jacques Distler is integrating Maruku+itex2mml+Instiki. You can find more information here:

http://golem.ph.utexas.edu/~distler/blog/archives/001111.html

4.3. Using blahtex

Download from http://www.blahtex.org. Make sure you have the command-line blahtex in your path.

5. Subtleties

5.1. Serving the right content/type

• Mozilla wants files to have the .xhtml extension.

…

5.2. Where PNGS are put

• Globals[:math_png_dir]

• Globals[:math_png_dir_url]

5.3. Styling equations

…

5.4. Aligning PNGs

• using ex

• IE7 bug

…