Tutorial on previewing LaTeX fragments
authorNick Dokos <nicholas.dokos@hp.com>
Wed, 3 Jul 2013 20:18:14 +0000 (16:18 -0400)
committerNick Dokos <nicholas.dokos@hp.com>
Wed, 3 Jul 2013 20:18:14 +0000 (16:18 -0400)
org-tutorials/index.org
org-tutorials/org-latex-preview.org [new file with mode: 0644]

index a1519da..cd9c9fd 100644 (file)
   Jovana Milutinovich.
 - [[file:org-latex-export.org][Using the OLD LaTeX exporter]] introduces configuration topics for
   users of Org Mode < 8.0.
+- [[file:org-latex-preview.org][Some notes on previewing LaTeX fragments]].
 - [[file:org-google-sync.org][Syncing with Google Calendar]]
 
 ** Import
diff --git a/org-tutorials/org-latex-preview.org b/org-tutorials/org-latex-preview.org
new file mode 100644 (file)
index 0000000..764208e
--- /dev/null
@@ -0,0 +1,327 @@
+
+* 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 setup, 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
+* Euler
+
+\[
+e^{i\pi} = -1
+\]
+
+\[
+\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
+\]
+#+END_EXAMPLE
+
+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 in a LaTeX fragment, create the image and overlay
+it over the source code.  If there is no fragment at point, display
+all fragments in the current text, from one headline to the next.  With
+prefix SUBTREE, display all fragments in the current subtree.  With a
+double prefix arg C-u C-u, or when the cursor is before the first headline,
+display all fragments in the buffer.
+The images can be removed again with C-c C-c.
+#+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_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
+
+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 :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-05-25 Sat]) 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{soul}
+\usepackage{textcomp}
+\usepackage{marvosym}
+\usepackage{wasysym}
+\usepackage{latexsym}
+\usepackage{amssymb}
+
+#+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.
+
+\[
+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.
+
+** 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-06-10 Mon 00:00]), 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.
+
+
+