Tutorial on previewing LaTeX fragments
[worg.git] / org-tutorials / org-latex-preview.org
1
2 * LaTeX preview in org
3
4 Org mode is used (among many other uses) by scientists taking
5 notes. Sometimes these notes include mathematics and scientists almost
6 universally use LaTeX in order to write mathematics, but since LaTeX
7 is not WYSIWYG, it is often useful to provide a preview of what
8 something will look like when typeset.
9
10 Most scientists use AUCTeX to write their LaTeX papers and there is a
11 LaTeX preview add-on that provides a preview facility in AUCTeX.
12
13 Org mode provides a similar facility, whose essentials I try to
14 summarize in this note.
15
16 * Basic usage
17
18 Once the facility has been setup, it can be used very simply.  One
19 writes LaTeX code and invokes the command =org-preview-latex-fragment=
20 (bound to C-c C-x C-l). The command processes the latex code and
21 produces a PNG image that is overlaid on the LaTeX code that was used
22 to produce the image, thereby providing the required preview. Pressing
23 C-c C-c gets rid of the overlay.
24
25 Here's an example:
26
27 #+BEGIN_EXAMPLE
28 * Euler
29
30 \[
31 e^{i\pi} = -1
32 \]
33
34 \[
35 \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
36 \]
37 #+END_EXAMPLE
38
39 Generally speaking, the preview mechanism looks for LaTeX environments
40 in the current region of applicability and processes one or more of
41 them. Prefix arguments and position in the buffer affect the region of
42 applicability of the preview mechanism --- the docstring of the
43 function says it better than I possibly could:
44
45 #+BEGIN_QUOTE
46 Preview the LaTeX fragment at point, or all locally or globally.
47 If the cursor is in a LaTeX fragment, create the image and overlay
48 it over the source code.  If there is no fragment at point, display
49 all fragments in the current text, from one headline to the next.  With
50 prefix SUBTREE, display all fragments in the current subtree.  With a
51 double prefix arg C-u C-u, or when the cursor is before the first headline,
52 display all fragments in the buffer.
53 The images can be removed again with C-c C-c.
54 #+END_QUOTE
55
56 Mathematics is the most common application, but other environments (e.g.
57 a listing environment for some code fragment) also work.
58
59 * Under the hood
60
61 There are two methods that can be used for LaTeX preview: dvipng and
62 imagemagick.
63
64 In the dvipng method, the latex fragment is embedded in a complete LaTeX
65 file, which is then processed by the LaTeX program (``latex'') to
66 produce a DVI file. The ``dvipng'' program is then invoked on the DVI
67 file to produce the final PNG-format image.
68
69 In the imagemagick method, the same LaTeX file is run through whatever
70 LaTeX processor you have configured in the =org-latex-pdf-process=
71 variable (the default is three runs of pdflatex). The output is a PDF
72 file, which is then processed by the ``convert'' program (a member of
73 the imagemagick family, hence the name of the method) to produce the
74 PNG-format image.
75
76 The two methods produce slightly different output: the foreground and
77 background colors may differ.
78
79 * dvipng setup
80 ** Obtaining and testing the =dvipng= program
81 You need the dvipng program. On Linux, it's generally in its own package,
82 not part of the larger TeX packages. For example, on Ubuntu, it can be
83 installed with the command =apt-get install dvipng=.
84
85 To test the installation, create a small TeX file:
86
87 #+BEGIN_SRC latex :tangle /tmp/example.tex
88 \documentclass{article}
89
90 \begin{document}
91
92 \[
93 e^{i\pi} = -1
94 \]
95
96 \[
97 \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
98 \]
99
100 \end{document}
101
102 #+END_SRC
103
104 You can tangle the above code block with C-u C-c C-v C-t into the file
105 /tmp/example.tex and process that through latex and dvipng. The following
106 code uses the ``display'' program (part of the imagemagick family) to show
107 the PNG file, but there are many such programs. Use what you have or can
108 get easily.
109
110 #+BEGIN_SRC sh :results silent
111 cd /tmp
112 latex /tmp/example.tex
113 dvipng -o /tmp/example.png /tmp/example.dvi
114 display /tmp/example.png
115 #+END_SRC
116
117 Don't worry about how it looks: if there are no errors, everything is
118 fine.  In actual use, the Org-mode LaTeX previewer will call =dvipng= with
119 appropriate arguments for its nefarious purposes.
120
121 ** Setting up org
122 There is one variable in org that needs to be set up:
123
124 #+BEGIN_SRC elisp
125 (setq org-latex-create-formula-image-program 'dvipng)
126 #+END_SRC
127
128 In addition, you might want to customize the set of latex
129 packages that will be needed in order to produce the preview.
130 Most of these are probably already included. Here is the current
131 (as of [2013-05-25 Sat]) list. You might have more than this
132 because of customizations in your setup. You also might have
133 less than this but that's not likely:
134
135 #+BEGIN_EXAMPLE
136 \usepackage[usenames]{color}
137 \usepackage{amsmath}
138 \usepackage[mathscr]{eucal}
139 \usepackage[utf8]{inputenc}
140 \usepackage[T1]{fontenc}
141 % Package fixltx2e omitted
142 \usepackage{graphicx}
143 % Package longtable omitted
144 % Package float omitted
145 % Package wrapfig omitted
146 \usepackage{soul}
147 \usepackage{textcomp}
148 \usepackage{marvosym}
149 \usepackage{wasysym}
150 \usepackage{latexsym}
151 \usepackage{amssymb}
152
153 #+END_EXAMPLE
154
155 The set of packages is specified using the variables
156 org-latex-default-packages-alist and org-latex-packages-alist. The
157 documentation strongly recommends that you leave the first one as is
158 (unless you really know what you are doing - and even then, it's easy
159 to shoot yourself in the foot). The second one is normally empty, but
160 you can use it to add whatever packages are necessary for your line of
161 work: Feynman diagrams anybody? 
162
163 N.B. With the exception of the setting for
164 =org-latex-create-formula-image-program=, everything else applies to
165 the imagemagick case as well. In fact, it applies not only to latex
166 preview but to latex export in general. Because of this generality,
167 you might find yourself adding packages for latex export that lead
168 to trouble with latex preview. An example is shown below.
169
170 Normally, all of the packages above are included for latex export,
171 but as you can see, some are omitted for latex preview. The mechanism
172 for that is explained below as well.
173
174 * imagemagick setup
175
176 The imagemagick setup mirrors the dvipng setup almost exactly. You
177 have to install the imagemagick package on your system somehow.
178
179 The test file above can be used to test this setup as well. The
180 commands needed are different though:
181
182 #+BEGIN_SRC sh :results silent
183 cd /tmp
184 pdflatex /tmp/example.tex
185 convert /tmp/example.pdf /tmp/example.png
186 display /tmp/example.png
187 #+END_SRC
188
189 The necessary org setup is now
190
191 #+BEGIN_SRC elisp
192 (setq org-latex-create-formula-image-program 'imagemagick)
193 #+END_SRC
194
195 The package stuff is identical.
196
197 * Comparing and contrasting the two methods
198
199 So choose a method, add a LaTeX fragment of your favorite
200 mathematics, e.g.
201
202 \[
203 e^{i\pi} = -1
204 \]
205
206 and press C-c C-x C-l in the fragment. Does the preview show
207 properly? If so, congratulations. Press C-c C-c to make it go away.
208
209 If you are so inclined, switch to the other method by changing the
210 value of =org-latex-create-formula-image-program= and try the preview
211 again. You will have to delete the PNG file produced by the first
212 method, in order to force the new method to create it again. The image
213 files are created in the directory specified by the variable
214 =org-latex-preview-ltxpng-directory= --- by default, that directory is
215 a subdirectory, named ``ltxpng'', of the directory where the org file
216 resides.
217
218 ** Background and foreground colors
219 One difference in the two methods is that the foreground and background
220 colors may come out different. In my case, I don't do anything special
221 to specify them and I'm using a (mostly) green-foreground-on-black-background
222 emacs. The dvipng preview comes out as black-on-white and the imagemagick
223 preview comes out as green-on-white in my case. Depending on your "theme"
224 and other magic, YMMV. I don't have much insight into these aspects however,
225 so feel free to modify this paragraph for the sake of better accuracy.
226
227 ** Minted
228 Programmers often find themselves in the position of having to include
229 code fragments (or perhaps complete programs) in documentation. LaTeX
230 makes that fairly easy. There are two packages contending for the
231 championship: listings and minted. Many people prefer the latter
232 because they think the output looks better, but there is a price to be
233 paid: minted depends on a separate python program, whereas listings is
234 a pure LaTeX package.
235
236 The problem is that, by default, latex (as well as its siblings tex,
237 pdflatex, etc.)  refuses to process a file that uses the minted
238 package because of the necessity of running this separate program. It
239 is considered a security risk.  There are various ways to convince
240 latex to abandon its scruples in this regard.  The most convenient
241 (and therefore most commonly used) is to run it with the
242 =--shell-escape= option.
243
244 So, let's assume that you like minted over listings and have decided
245 to use it for latex export. You read the documentation for the relevant
246 variable, =org-latex-listings=, and set up things as the documentation
247 suggests:
248
249 #+BEGIN_SRC elisp
250   (setq org-latex-listings 'minted)
251   (require 'ox-latex)
252   (add-to-list 'org-latex-packages-alist '("" "minted"))
253 #+END_SRC
254
255 You also have to make sure that =org-latex-pdf-process= calls
256 latex (or pdflatex or xelatex or ...) with the =--shell-escape=
257 option.
258
259 You *export* your articles to LaTeX and produce output that includes
260 very nicely typeset program code fragments. Months later, you try to
261 *preview* some mathematics and the preview does not work. What
262 happened?
263
264 Adding the minted package to =org-latex-packages-alist= as above, adds
265 the =\usepackage{minted}= line to latex files produced by either latex
266 export *or* latex preview. If you've set up preview to use the
267 imagemagick method, then everything should work, because it uses
268 =org-latex-pdf-process= and that has been set up already to use the
269 =--shell-escape= option (otherwise export would not work), so using
270 minted is not a problem.
271
272 But if you have set up preview to use the dvipng method, you are in
273 trouble: that method calls latex directly, the call is hardwired
274 and it does *not* use the =--shell-escape= option. LaTeX refuses to
275 run the external program that minted used, no DVI file is produced
276 and dvipng cannot produce a PNG file.
277
278 One way out of this predicament is to change the latex call. That
279 requires modifying the org mode code and that's not really a good
280 idea. Adding an option that can be set by the user (so that one can
281 pass the =--shell-escape= option to the latex call) is under
282 consideration at this time ([2013-06-10 Mon 00:00]), but it's not there yet.
283
284 Probably the best solution currently is to include minted for latex export
285 but exclude it for latex preview. Remember the list of packages
286 above, where some packages were omitted? Those packages are
287 included by default for latex export, but excluded for latex preview.
288 The magic that allows that is explained in the documentation
289 for =org-latex-packages-alist=:
290
291 #+BEGIN_QUOTE
292 Each cell is of the format:
293
294     ("options" "package" snippet-flag)
295
296 SNIPPET-FLAG, when t, indicates that this package is also needed
297 when turning LaTeX snippets into images for inclusion into
298 non-LaTeX output.
299 #+END_QUOTE
300
301 Note that, counter-intuitively, if the snippet-flag is omitted
302 altogether, then it's as if it were set to t, not nil as one would
303 normally expect. Presumably that's for backward compatibility: the
304 snippet-flag was added later and many people might have settings that
305 don't include it. If its absence were to be interpreted as nil, the
306 packages would not be included for latex preview, leading to
307 surprises.
308
309 To exclude minted from latex preview then, all we have to do is change
310 what we add to =org-latex-packages-alist=:
311
312 #+BEGIN_SRC elisp
313   (add-to-list 'org-latex-packages-alist '("" "minted" nil))
314 #+END_SRC
315
316 There still remains one problem: what does one do in order to include
317 a code fragment into a preview, but wants that code fragment to be
318 processed by minted? The best suggestion currently is: if you have to
319 do that, use the imagemagick method, not the dvipng method.
320
321 The dvipng method predates the imagemagick method, but maybe the
322 problem with minted above, esoteric as it may be, provides motivation
323 to use the imagemagick method instead for latex preview --- it is a
324 bit less brittle than the dvipng method.
325
326
327