Support via Liberapay

1. LaTeX preview in org

Org mode is used (among many other uses) by scientists taking notes. Sometimes these notes include mathematics and scientists almost universally use LaTeX in order to write mathematics, but since LaTeX is not WYSIWYG, it is often useful to provide a preview of what something will look like when typeset.

Most scientists use AUCTeX to write their LaTeX papers and there is a LaTeX preview add-on that provides a preview facility in AUCTeX.

Org mode provides a similar facility, whose essentials I try to summarize in this note.

2. Basic usage

Once the facility has been set up, it can be used very simply. One writes LaTeX code and invokes the command org-preview-latex-fragment (bound to C-c C-x C-l). The command processes the latex code and produces a PNG image that is overlaid on the LaTeX code that was used to produce the image, thereby providing the required preview. Pressing C-c C-c gets rid of the overlay.

Here's an example:

\[
e^{i\pi} = -1
\]

\[
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
\]

If you press C-c C-x C-l here (or C-u C-c C-x C-l to preview everything in the subtree, or C-u C-u C-c C-x C-l to preview everything in the buffer), you should see something like this (the placement on the page and the size of the equations are probably going to be different, but the formulas should be recognizably the same):

\[ e^{i\pi} = -1 \]

\[ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} \]

Generally speaking, the preview mechanism looks for LaTeX environments in the current region of applicability and processes one or more of them. Prefix arguments and position in the buffer affect the region of applicability of the preview mechanism — the docstring of the function says it better than I possibly could:

Preview the LaTeX fragment at point, or all locally or globally.

If the cursor is on a LaTeX fragment, create the image and overlay it over the source code, if there is none. Remove it otherwise. If there is no fragment at point, display all fragments in the current section.

With prefix ARG, preview or clear image for all fragments in the current subtree or in the whole buffer when used before the first headline. With a double prefix ARG C-u C-u preview or clear images for all fragments in the buffer.

Mathematics is the most common application, but other environments (e.g. a listing environment for some code fragment) also work.

3. Under the hood

There are two methods that can be used for LaTeX preview: dvipng and imagemagick.

In the dvipng method, the latex fragment is embedded in a complete LaTeX file, which is then processed by the LaTeX program (``latex'') to produce a DVI file. The ``dvipng'' program is then invoked on the DVI file to produce the final PNG-format image.

In the imagemagick method, the same LaTeX file is run through whatever LaTeX processor you have configured in the org-latex-pdf-process variable (the default is three runs of pdflatex). The output is a PDF file, which is then processed by the ``convert'' program (a member of the imagemagick family, hence the name of the method) to produce the PNG-format image.

The two methods produce slightly different output: the foreground and background colors may differ.

4. dvipng setup

4.1. Obtaining and testing the dvipng program

You need the dvipng program. On Linux, it's generally in its own package, not part of the larger TeX packages. For example, on Ubuntu, it can be installed with the command apt-get install dvipng.

To test the installation, create a small TeX file:

#+BEGIN_SRC latex :tangle /tmp/example.tex
\documentclass{article}

\begin{document}

\[
e^{i\pi} = -1
\]

\[
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
\]

\end{document}

#+END_SRC

If you are looking at this on the web, you can cut and paste the latex program to /tmp/example.tex and process it through latex and dvipng, as shown below. If you are looking at the org file of this tutorial, you can tangle the above code block with C-u C-c C-v C-t into the file /tmp/example.tex and process that through latex and dvipng. The following code uses the ``display'' program (part of the imagemagick family) to show the PNG file, but there are many such programs. Use what you have or can get easily.

cd /tmp
latex /tmp/example.tex
dvipng -o /tmp/example.png /tmp/example.dvi
display /tmp/example.png

Don't worry about how it looks: if there are no errors, everything is fine. In actual use, the Org-mode LaTeX previewer will call dvipng with appropriate arguments for its nefarious purposes.

4.2. Setting up org

There is one variable in org that needs to be set up:

(setq org-latex-create-formula-image-program 'dvipng)

In addition, you might want to customize the set of latex packages that will be needed in order to produce the preview. Most of these are probably already included. Here is the current (as of [2013-07-05 Fri]) list. You might have more than this because of customizations in your setup. You also might have less than this but that's not likely:

\usepackage[usenames]{color}
\usepackage{amsmath}
\usepackage[mathscr]{eucal}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
% Package fixltx2e omitted
\usepackage{graphicx}
% Package longtable omitted
% Package float omitted
% Package wrapfig omitted
\usepackage[normalem]{ulem}
\usepackage{textcomp}
\usepackage{marvosym}
\usepackage{wasysym}
\usepackage{latexsym}
\usepackage{amssymb}
% Package amstext omitted
% Package hyperref omitted

The set of packages is specified using the variables org-latex-default-packages-alist and org-latex-packages-alist. The documentation strongly recommends that you leave the first one as is (unless you really know what you are doing - and even then, it's easy to shoot yourself in the foot). The second one is normally empty, but you can use it to add whatever packages are necessary for your line of work: Feynman diagrams anybody?

N.B. With the exception of the setting for org-latex-create-formula-image-program, everything else applies to the imagemagick case as well. In fact, it applies not only to latex preview but to latex export in general. Because of this generality, you might find yourself adding packages for latex export that lead to trouble with latex preview. An example is shown below.

Normally, all of the packages above are included for latex export, but as you can see, some are omitted for latex preview. The mechanism for that is explained below as well.

5. imagemagick setup

The imagemagick setup mirrors the dvipng setup almost exactly. You have to install the imagemagick package on your system somehow.

The test file above can be used to test this setup as well. The commands needed are different though:

cd /tmp
pdflatex /tmp/example.tex
convert /tmp/example.pdf /tmp/example.png
display /tmp/example.png

The necessary org setup is now

(setq org-latex-create-formula-image-program 'imagemagick)

The package stuff is identical.

6. Comparing and contrasting the two methods

So choose a method, add a LaTeX fragment of your favorite mathematics, e.g.

\[
e^{i\pi} = -1
\]

and press C-c C-x C-l in the fragment. Does the preview show properly? If so, congratulations. Press C-c C-c to make it go away.

If you are so inclined, switch to the other method by changing the value of org-latex-create-formula-image-program and try the preview again. You will have to delete the PNG file produced by the first method, in order to force the new method to create it again. The image files are created in the directory specified by the variable org-latex-preview-ltxpng-directory — by default, that directory is a subdirectory, named ``ltxpng'', of the directory where the org file resides.

6.1. Background and foreground colors

One difference in the two methods is that the foreground and background colors may come out different. In my case, I don't do anything special to specify them and I'm using a (mostly) green-foreground-on-black-background emacs. The dvipng preview comes out as black-on-white and the imagemagick preview comes out as green-on-white in my case. Depending on your "theme" and other magic, YMMV. I don't have much insight into these aspects however, so feel free to modify this paragraph for the sake of better accuracy.

6.2. Minted

Programmers often find themselves in the position of having to include code fragments (or perhaps complete programs) in documentation. LaTeX makes that fairly easy. There are two packages contending for the championship: listings and minted. Many people prefer the latter because they think the output looks better, but there is a price to be paid: minted depends on a separate python program, whereas listings is a pure LaTeX package.

The problem is that, by default, latex (as well as its siblings tex, pdflatex, etc.) refuses to process a file that uses the minted package because of the necessity of running this separate program. It is considered a security risk. There are various ways to convince latex to abandon its scruples in this regard. The most convenient (and therefore most commonly used) is to run it with the -shell-escape option.

So, let's assume that you like minted over listings and have decided to use it for latex export. You read the documentation for the relevant variable, org-latex-listings, and set up things as the documentation suggests:

(setq org-latex-listings 'minted)
(require 'ox-latex)
(add-to-list 'org-latex-packages-alist '("" "minted"))

You also have to make sure that org-latex-pdf-process calls latex (or pdflatex or xelatex or …) with the -shell-escape option.

You export your articles to LaTeX and produce output that includes very nicely typeset program code fragments. Months later, you try to preview some mathematics and the preview does not work. What happened?

Adding the minted package to org-latex-packages-alist as above, adds the \usepackage{minted} line to latex files produced by either latex export or latex preview. If you've set up preview to use the imagemagick method, then everything should work, because it uses org-latex-pdf-process and that has been set up already to use the -shell-escape option (otherwise export would not work), so using minted is not a problem.

But if you have set up preview to use the dvipng method, you are in trouble: that method calls latex directly, the call is hardwired and it does not use the -shell-escape option. LaTeX refuses to run the external program that minted used, no DVI file is produced and dvipng cannot produce a PNG file.

One way out of this predicament is to change the latex call. That requires modifying the org mode code and that's not really a good idea. Adding an option that can be set by the user (so that one can pass the -shell-escape option to the latex call) is under consideration at this time ([2013-07-05 Fri]), but it's not there yet.

Probably the best solution currently is to include minted for latex export but exclude it for latex preview. Remember the list of packages above, where some packages were omitted? Those packages are included by default for latex export, but excluded for latex preview. The magic that allows that is explained in the documentation for org-latex-packages-alist:

Each cell is of the format:

("options" "package" snippet-flag)

SNIPPET-FLAG, when t, indicates that this package is also needed when turning LaTeX snippets into images for inclusion into non-LaTeX output.

Note that, counter-intuitively, if the snippet-flag is omitted altogether, then it's as if it were set to t, not nil as one would normally expect. Presumably that's for backward compatibility: the snippet-flag was added later and many people might have settings that don't include it. If its absence were to be interpreted as nil, the packages would not be included for latex preview, leading to surprises.

To exclude minted from latex preview then, all we have to do is change what we add to org-latex-packages-alist:

(add-to-list 'org-latex-packages-alist '("" "minted" nil))

There still remains one problem: what does one do in order to include a code fragment into a preview, but wants that code fragment to be processed by minted? The best suggestion currently is: if you have to do that, use the imagemagick method, not the dvipng method.

The dvipng method predates the imagemagick method, but maybe the problem with minted above, esoteric as it may be, provides motivation to use the imagemagick method instead for latex preview — it is a bit less brittle than the dvipng method.

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.