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