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