Use Starmath—NOT LaTeX, NOT MathML—when exporting Org mode files to LibreOffice

Overview

Use Starmath—NOT LaTeX, NOT MathML—when exporting Org mode files to LibreOffice or Microsoft Word.

(If you are impatient, you can skip the introductory note, and jump right to  How do I go about using Starmath in Org mode documents.)

How do you typeset Math in your Org mode documents?

According to the Org User Manual(1),

Org mode can contain LaTeX math fragments, and it supports ways to process these for several export back-ends.

• When exporting to LaTeX, the code is left as it is.
• When exporting to HTML, Org can use either MathJax or transcode the math into images.

How do you typeset Math in your Org mode documents when exporting to OpenDocument (LibreOffice / Word) format?

According to the Org Use Manual(1),

LaTeX math snippets can be embedded in the ODT document in one of the following ways

• MathML

LaTeX fragments are first converted into MathML fragments using an external LaTeX-to-MathML converter program. The resulting MathML fragments are then embedded as an OpenDocument Formula in the exported document

• PNG images

LaTeX fragments are processed into PNG or SVG images and the resulting images are embedded in the exported document. This method requires dvipng program, dvisvgm or ImageMagick programs.

The manual further goes on to suggest Mathtoweb(1) or LaTeXML(1).

The Problem with above choices is …

• PNG Images are not editable
• MathML is not “native” to LibreOffice. And this means that even if a LaTeX-to-MathML converter does a good job of converting to LaTeX to MathML, LibreOffice allegedly does NOT do a good job of rendering MathML, … and if you hunt the LibreOffice‘s bug reports for Math-related problems you would frequently run in to statements that more or less expresses the following sentiment.

As ODF requires use of MathML, we strive to support MathML for import and export.(1)

And to corroborate the above “striving to support ” remark, the official LibreOffice Math Help page(1) says

Import MathML from Clipboard

This command transforms MathML clipboard content to StarMath and inserts it at the current cursor position.

If the transformation fails, nothing is inserted.

To access this command…

Choose Tools – Import MathML from Clipboard

If you are naive, you may think that the sole reason an import from MathML might fail is because of an error on your part, and that you copied a malformed MathML. But sooner or later you will realize that the Help page is, in actual fact, tendering you a reluctant apology while admitting so much as “LibreOffice doesn’t do a good job of importing MathML”.

The Bigger Problem is …

There is a much bigger problem.

If you are producing LibreOffice documents in the first place, you most likely don’t want to touch LaTeX even with a 10-foot pole, which is the case with me.

The Solution is …

A way to circumvent above problems, is to skip using LaTeX for typesetting Math, and to instead use the Starmath format.

What is Starmath?

Starmath is how you typeset a equation/formula in LibreOffice. It seems that it is based on Troff‘s(1) Eqn (1) format. You can learn about this dialect for typesetting Math in The LibreOffice Math Guide(1).

How do I go about using Starmath in Org mode documents

Overview

Step 1: Install The Enhanced ODT exporter(1)

This step is crucial. Don’t skip this step.

This feature is available with only the enhanced OpenDocument exporter(1) and not with the OpenDocument exporter that comes with stock Emacs.

• Update package-archives
'("ox-odt" . "https://kjambunathan.github.io/elpa/"))
• Install the ox-odt package with M-x package-refresh-contents RET and M-x package-install RET ox-odt RET
• Re-start Emacs.

In my case, I ended up installing ox-odt-9.3.7.361.

Step 2: Tell the exporter that you are using Starmath as the math dialect

#+options: tex:t
#+odt_math_syntax: starmath

Step 3: Type away and then Export

Start typing your math equations in Starmath much like what you do when embedding LaTeX fragments. In other words, you use the regular LaTeX math-delimiters–$...$, $\(...)\$, \[...]\, $$...$$ and $$...$$–and fill them with Math not in TeX dialect but in Starmath dialect.

Can you give me an example?

Here is a sample document(1) that uses Starmath to typeset Math equations.

#+options: tex:t
#+odt_math_syntax: starmath

#+odt_extra_styles:
#+odt_extra_styles:
#+odt_extra_styles:

#+begin_center
*Finding Roots of a Quadratic Equation*
#+end_center

The process of /"completing the square"/ makes use of the algebraic
identity

#+NAME: step0
$x^2 + 2hx + h^2 = (x+h)^2$

which represents a well-defined algorithm that can be used to solve

Starting with a quadratic equation in standard form, $ax^2 + bx + c = 0$

1. Divide each side by $a$, the coefficient of the squared term.

#+NAME: step1
$x^2+{ b over a }x+{ c over a } = 0$

2. Subtract the constant term $c slash a$ from both sides.

#+NAME: step2
$x^2+{ b over a }x = -{ c over a }$

3. Add the square of one-half of $b slash a$, the coefficient of $x$, to both sides. This /"completes the square"/, converting the left side into a perfect square, as in [[step0]].

$x^2 + 2({ b over { 2a } })x = -{ c over a }$

#+NAME: step3
$x^2 + 2({ b over { 2a } })x + ({ b over { 2a } })^2 = -{ c over a } + ({ b over { 2a } })^2$

4. Write the left side as a square and simplify the right side if necessary.

#+NAME: step4
$$matrix { (x + b over { 2a })^2 # {} = {} # - { c over a } + { b^2 over { 4a^2 } } ## ~ # {} = {} # (-4ac + b^2) over { 4a^2 } }$$

5. Produce two linear equations by equating the square root of the left side with the positive and negative square roots of the right side.

#+NAME: step5
$matrix{ (x + b over { 2a }) # {} = {}# +- sqrt{ { -4ac + b^2 } over { 4a^2 } } ## {} # {} = {} # +- { sqrt{ -4ac + b^2 } over { 2a } } }$

6. Solve each of the two linear equations.

#+NAME: step6
$matrix{ x # {} = {} # -b over { 2a } +- { sqrt{ -4ac + b^2 } over { 2a } } ## {} # {} = {} # { -b +- { sqrt{ -4ac + b^2 } } } over { 2a } }$

How does it look?

An Org mode file using Starmath for typesetting Math equations(1)

How LibreOffice renders above Org file on export to ODT(1)

1. Starmath equations are editable in LibreOffice
2. Math formula editor helps you create/edit the Starmath markup using a visual editor

Conclusion

Starmath option is a boon for Org mode users who routinely produce Math-heavy LibreOffice documents. However, it suffers from the following limitations:

• When editing Starmath fragments in Emacs, there is no immediate feedback on how the Math will be rendered in LibreOffice.
• Also, unlike me, if you have a need to export an Org mode file that contains Starmath fragments to formats like  HTML or LaTeX, then you need to resort to some compicated markup.

If you are keen in exploring the second item above, I invite you to consult the article Mix Starmath and LaTeX / Mix English and Tamil in same Org file (or) How to conditionally export text using Macros and Drawers in Org mode – Emacs Notes.

That said,  experience suggests that  an Org mode user producing a Math-heavy document is unlikely to have a need for  simultaneous export to both LibreOffice and non-LibreOffice formats.  If this weren’t the case, wouldn’t there be already a solution in place …?

That said, I hope in coming days,

• there is a way to preview Starmath fragments in an Emacs buffer, much like how one would preview LaTeX fragments(1)
• there is a way to convert Starmath fragments to MathML,  much like how there are multiple off-the-shelf LaTeX-to-MathMLconverters (1)
gnu