Update some changed export keybindings

[worg.git] / org-tutorials / org-latex-preview.org

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

* 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.

* 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:

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

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

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:

#+BEGIN_QUOTE
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.
#+END_QUOTE

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

* 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.

* dvipng setup
** 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_EXAMPLE
#+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
#+END_EXAMPLE

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.

#+BEGIN_SRC sh :exports code :results silent
cd /tmp
latex /tmp/example.tex
dvipng -o /tmp/example.png /tmp/example.dvi
display /tmp/example.png
#+END_SRC

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.

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

#+BEGIN_SRC elisp
(setq org-latex-create-formula-image-program 'dvipng)
#+END_SRC

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:

#+BEGIN_EXAMPLE
\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

#+END_EXAMPLE

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.

* 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:

#+BEGIN_SRC sh :results silent
cd /tmp
pdflatex /tmp/example.tex
convert /tmp/example.pdf /tmp/example.png
display /tmp/example.png
#+END_SRC

The necessary org setup is now

#+BEGIN_SRC elisp
(setq org-latex-create-formula-image-program 'imagemagick)
#+END_SRC

The package stuff is identical.

* Comparing and contrasting the two methods

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

#+BEGIN_EXAMPLE
\[
e^{i\pi} = -1
\]
#+END_EXAMPLE

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.

** 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.

** 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:

#+BEGIN_SRC elisp
  (setq org-latex-listings 'minted)
  (require 'ox-latex)
  (add-to-list 'org-latex-packages-alist '("" "minted"))
#+END_SRC

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]), 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=:

#+BEGIN_QUOTE
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.
#+END_QUOTE

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=:

#+BEGIN_SRC elisp
  (add-to-list 'org-latex-packages-alist '("" "minted" nil))
#+END_SRC

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.