Backend dependent execution -- conditionally export tikz to SVG on HTML export
[worg.git] / org-contrib / babel / languages / ob-doc-LaTeX.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE:      LaTeX Source Code Blocks in Org Mode
6 #+AUTHOR:     Tom Dye
7 #+EMAIL:      tsd [at] tsdye [dot] com
8 #+LANGUAGE:   en
9 #+HTML_HEAD:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+LINK_UP:    ../languages.html
11 #+LINK_HOME:  http://orgmode.org/worg/
12 #+EXCLUDE_TAGS: noexport
13
14 #+name: banner
15 #+begin_html
16   <div id="subtitle" style="float: center; text-align: center;">
17   <p>
18   Org Mode support for <a href="http://www.tug.org/">LaTeX</a>
19   Source Code Blocks
20   </p>
21   <p>
22   <a href="http://www.tug.org/">
23   <img src="images/latex-logo-for-banner.png"/>
24   </a>
25   </p>
26   </div>
27 #+end_html
28
29 #+BEGIN_SRC latex :file latex-logo.png :buffer yes
30 \LaTeX
31 #+END_SRC
32
33 #+RESULTS[32c48c151ab8d684ca94cdac40ada3df69e5057e]:
34 #+BEGIN_LaTeX
35 [[file:latex-logo.png]]
36 #+END_LaTeX
37
38
39
40 * Template Checklist [13/13]                                       :noexport:
41   - [X] Revise #+TITLE:
42   - [X] Indicate #+AUTHOR:
43   - [X] Add #+EMAIL:
44   - [X] Revise banner source block [3/3]
45     - [X] Add link to a useful language web site
46     - [X] Replace "Language" with language name
47     - [X] Find a suitable graphic and use it to link to the language
48       web site
49   - [X] Write an [[Introduction]]
50   - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
51   - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
52   - [X] Specify [[Org%20Mode%20Configuration][Org Mode Configuration]]
53   - [X] Describe [[Header%20Arguments][Header Arguments]]
54   - [X] Describe support for [[Sessions]]
55   - [X] Describe [[Result%20Types][Result Types]]
56   - [X] Describe [[Other]] differences from supported languages
57   - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
58 * Introduction
59 LaTeX is a document markup language and a document preparation system
60 for the TeX typesetting program.  The TeX program was developed by
61 Donald Knuth at Stanford University to typeset complex mathematics.
62 LaTeX is an extensible set of TeX macros designed to ease preparation
63 of documents such as letters, articles, reports, and books.  The
64 current version is LaTeX2e.  An ambitious update, LaTeX3, has been in
65 the works for some time.
66
67 Org Mode is able to export LaTeX directly.[fn:1]  LaTeX code
68 embedded in an Org Mode file (not within source code blocks) is
69 exported correctly to a number of the export backends.[fn:2] 
70
71 LaTeX source code blocks can be used to tangle a LaTeX source file, or
72 to create bitmap images or pdf snippets of arbitrary LaTeX code.
73 Typically, this latter use involves mathematics, but it conceivably
74 extends to any TeX output.[fn:3] The LaTeX logo at the top of this
75 page is a bitmap image generated from a simple LaTeX source code
76 block.  The complex example provided by [[Andreas%20Leha][Andreas
77 Leha]], below, uses the TikZ package to create a graphics image.
78
79 * Requirements and Setup
80 In order to use LaTeX source code blocks to their full capacity, a
81 working LaTeX installation is required.[fn:4] LaTeX systems are
82 distributed widely through various channels and one should be
83 available for your computer system.  A good place to find one is the
84 [[http://www.tug.org][TeX Users Group]].
85
86 Once LaTeX is installed and is working correctly, you will need to tell
87 Emacs where to find the various LaTeX executable files.  The location
88 of these files is likely distribution dependent: my MacTeX
89 distribution places them in the =/usr/texbin= subdirectory.
90 Accordingly, I have this in =.emacs=:
91
92 #+begin_src emacs-lisp :exports code
93     (setq exec-path (append exec-path '("/usr/texbin")))
94 #+end_src
95
96 Org Mode can generate
97 [[http://www.w3.org/Press/PNG-fact.html][Portable Network Graphics]]
98 (png) bitmaps from LaTeX source code blocks, which it does with the
99 =dvipng= program that comes with most LaTeX distributions.  If you
100 want to generate bitmaps in other file formats, then you will need to
101 install [[http://www.imagemagick.org/script/index.php][ImageMagick]],
102 a software suite to create, edit, compose or convert bitmap images.
103 Ensure that the ImageMagick executables are installed somewhere on the
104 Emacs =exec-path=.
105
106 If you plan to edit LaTeX source code blocks separately, with =C-c= ',
107 or want to control the size of pdf snippets, then it is highly
108 recommended that [[http://www.gnu.org/software/auctex/][AucTeX]] be
109 installed, as well.  AucTeX is an extensible package for writing and
110 formatting TeX files.  Assuming that AucTeX is installed properly, the
111 following line in =.emacs= will ensure that AucTeX is loaded.
112
113 #+begin_src emacs-lisp 
114 (load "auctex.el" nil t t)
115 #+end_src
116
117 Also highly recommended is
118 [[http://www.gnu.org/software/auctex/reftex.html][RefTeX]], a
119 cross-reference, bibliography, glossary, and index manager initially
120 written by the creator of Org Mode, Carsten Dominik.  Add the
121 following line to =.emacs=:
122
123 #+begin_src emacs-lisp 
124 (add-hook 'LaTeX-mode-hook 'turn-on-reftex) 
125 #+end_src
126
127 Finally, you'll need to ensure that =org-babel-load-languages=
128 includes an entry for LaTeX.  Typically, =org-babel-load-languages=
129 will contain many entries.  The example below omits other languages.
130
131 #+begin_src emacs-lisp :tangle yes
132   (org-babel-do-load-languages
133    'org-babel-load-languages
134    '((latex . t)))
135 #+end_src
136
137 * Org Mode Features for LaTeX Source Code Blocks
138 ** Header Arguments
139 LaTeX source code blocks set default values for two standard header
140 arguments.  In addition, several LaTeX-specific header arguments are
141 defined to control creation of bitmap images and pdf snippets.
142  
143 *** LaTeX-specific Default Values
144 The LaTeX-specific default value of the
145 [[http://orgmode.org/manual/results.html#results][=:results= header
146 argument]] is "latex", which wraps the results in a =#+BEGIN_LaTeX
147 ... #+END_LaTeX= block.
148
149 The LaTeX-specific default value of the
150 [[http://orgmode.org/manual/exports.html#exports][=:exports= header
151 argument]] is "results".
152
153 *** LaTeX-specific Header Arguments
154
155 The standard [[http://orgmode.org/manual/file.html#file][=:file= header
156 argument]] associated with a LaTeX source code block by itself can
157 take the name of either a Portable Network Graphics (png) or a
158 Portable Document Format (pdf) file.  File names for other bitmap file
159 types can be supplied in conjunction with the =:imagemagick= header
160 argument, described below.
161
162 The =:buffer= header argument is a LaTeX-specific header argument that
163 takes the values =yes= or =no=.  It is consulted when a bitmap image
164 has been requested using the =:file= header argument.  If =:buffer
165 yes=, the default, then Org Mode consults the values of
166 =org-format-latex-options= and passes these to the =dvipng= program.
167 If =:buffer no=, then Org Mode takes background and foreground colors
168 from the Emacs buffer.
169
170 Several LaTeX-specfic header arguments control production of pdf
171 snippets.  The LaTeX-specific =:headers= header argument takes a Lisp
172 list that specifies entries for the LaTeX preamble,
173 e.g., '("\\usepackage{tikz}").  The =:fit= header argument invokes the
174 [[http://www.ctan.org/tex-archive/macros/latex/contrib/preview][LaTeX
175 preview package]], which is developed and distributed along with
176 AucTeX.  The =:border= header argument takes a
177 [[http://en.wikibooks.org/wiki/LaTeX/Useful_Measurement_Macros#Length_.27macros.27][LaTeX
178 length]], which should be greater than =0.50001bp=, or half a usual
179 PostScript point.  This can be used to make pdf pages larger than they
180 are by default.  The header arguments =:pdfheight= and =:pdfwidth= set
181 the dimensions of the pdf page.  They can be passed a valid LaTeX length.
182
183 Andreas Leha added the ability to produce bitmaps in formats other
184 than png, using the LaTeX-specific =:imagemagick= header argument.
185 Quoting Andreas' notice sent to the Org Mode list[fn:5]
186
187
188 LaTeX source blocks now have three new options:
189 - =:imagemagick= ::
190   When not nil the source block is processed to pdf and the pdf is
191   converted with ImageMagick to whatever is given as =:file=.
192   Thus, the format is not limited to png.
193 - =:iminoptions= ::
194   This is passed to ImageMagick before the pdf file.
195 - =:imoutoptions= ::
196   This is passed to ImageMagick before the output file.
197
198      
199 ** Sessions
200 LaTeX does not support sessions.
201
202 ** Result Types
203  The default result type is =latex=, which wraps the results in a
204 =#+BEGIN_LaTeX ... #+END_LaTeX= block.
205 ** Other
206 LaTeX source code blocks are a special case because their
207 functionality largely overlaps with the export facilities in Org
208 Mode.  
209
210 * Examples of Use
211 ** "Hello World"
212
213 At its simplest, Org Mode evaluation of LaTeX source code blocks with
214 =C-c C-c= wraps the results in a =#+BEGIN_LaTeX ... #+END_LaTeX=
215 block.
216
217 : #+name: hello-world
218 : #+BEGIN_SRC latex
219 : \LaTeX
220 : #+END_SRC
221
222 : #+RESULTS: hello-world
223 : #+BEGIN_LaTeX
224 : \LaTeX
225 : #+END_LaTeX
226
227 ** Andreas Leha
228 This complex example was posted to the Org Mode list by Andreas Leha.
229 It depends on a working installation of the R statistical
230 software.[fn:6] The code makes use of R sessions to preserve state
231 between R source code blocks.
232
233 The first source code block loads the
234 [[http://www.texample.net/tikz/resources/][TikZ package]], which
235 defines a language to produce vector graphics from a
236 geometric/algebraic description.
237
238 #+begin_src R :session :exports code :results silent
239   library("tikzDevice")
240 #+end_src
241
242 A simple plot is generated and output as LaTeX code by the TikZ
243 device in R.
244
245 #+name: test_plot
246 #+begin_src R :session :exports code :results output latex
247   tikz(console=TRUE, width=4, height=4)
248   plot(rnorm(100), rnorm(100))
249   dummy <- dev.off()
250 #+end_src
251
252 The LaTeX output of this R code is processed by a LaTeX source code
253 block, using Org Mode's noweb syntax.  Note the various =#+header:=
254 lines and their settings, which serve to configure ImageMagick.  In
255 this case, a png file is being produced outside the usual Org Mode
256 path through =dvipng=.  Note that the header presented here has been
257 simplified somewhat.  Interested readers might want to review Andreas'
258 original post.
259
260 : #+name: test_plot_png
261 : #+header: :exports results :file test.png 
262 : #+header: :imagemagick yes :iminoptions -density 600 :imoutoptions -geometry 400 
263 : #+header: :fit yes :noweb yes :headers '("\\usepackage{tikz}")
264 : #+begin_src latex :exports results :file test.png 
265 :   <<test_plot()>>
266 : #+end_src
267
268
269 With this header, the LaTeX output of the TikZ device in R yields a
270 graph of the random number generation.
271
272 #+Caption: Results of evaluating a LaTeX source code block.
273 #+RESULTS: test_plot_png
274 [[file:images/test.png]]
275
276 If the header is changed so the results are not written to a file,
277 then the LaTeX code generated by the TikZ device is written to the Org
278 Mode buffer.  The results shown below have been shortened somewhat for
279 illustrative purposes.
280
281 : #+name: test_plot_tikz
282 : #+begin_src latex :noweb yes :exports results
283 :   <<test_plot()>>
284 : #+end_src
285
286 #+RESULTS: test_plot_tikz
287 : #+BEGIN_LaTeX
288 : % Created by tikzDevice version 0.6.2 on 2012-02-08 21:28:07
289 : % !TEX encoding = UTF-8 Unicode
290 : \begin{tikzpicture}[x=1pt,y=1pt]
291 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
292 : \definecolor[named]{fillColor}{rgb}{1.00,1.00,1.00}
293 : \fill[color=fillColor,fill opacity=0.00,] (0,0) rectangle (289.08,289.08);
294 : \begin{scope}
295 : \path[clip] ( 49.20, 61.20) rectangle (263.88,239.88);
296 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
297 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] (184.34, 99.14) circle (  2.25);
298 :
299 : ...
300 :
301 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] (143.44,134.70) circle (  2.25);
302 : \end{scope}
303 : \begin{scope}
304 : \path[clip] (  0.00,  0.00) rectangle (289.08,289.08);
305 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
306 :
307 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] ( 75.29, 61.20) -- (250.80, 61.20);
308 :
309 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] ( 49.20, 61.20) --
310 :       (263.88, 61.20) --
311 :       (263.88,239.88) --
312 :       ( 49.20,239.88) --
313 :       ( 49.20, 61.20);
314 : \end{scope}
315 : \begin{scope}
316 : \path[clip] (  0.00,  0.00) rectangle (289.08,289.08);
317 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
318
319 : \node[color=drawColor,anchor=base,inner sep=0pt, outer sep=0pt, scale=  1.00] at (156.54, 13.20) {rnorm(100)};
320 :
321 : \node[rotate= 90.00,color=drawColor,anchor=base,inner sep=0pt, outer sep=0pt, scale=  1.00] at ( 13.20,150.54) {rnorm(100)};
322 : \end{scope}
323 : \end{tikzpicture}
324 : #+END_LaTeX
325
326 ** Backend dependent execution -- conditionally export tikz to SVG on HTML export
327 This example demonstrates the handling of a LaTeX code block
328 differently depending on the export backend.  If the following file is
329 exported to HTML the tikz code block will be converted to an SVG
330 images, while on export to pdf (through LaTeX) the tikz code will
331 simply be inserted into the document verbatim.
332
333 : #+LATEX_HEADER: \usepackage{tikz}
334
335 : First execute the second code block, to define the convenience macro
336 : and to set the required new variables in ob-latex.el.  Then export to
337 : HTML and to pdf to see the tree exported as an SVG image and as
338 : embedded tikz respectively.
339
340 : * Tikz test
341 : Here's a tree, exported to both html and pdf.
342
343 : #+header: :file (by-backend (html "tree.svg") (t 'nil))
344 : #+header: :imagemagick
345 : #+header: :results (by-backend (pdf "latex") (t "raw"))
346 : #+begin_src latex
347 :   \usetikzlibrary{trees}
348 :   \begin{tikzpicture}
349 :     \node [circle, draw, fill=red!20] at (0,0) {1}
350 :     child { node [circle, draw, fill=blue!30] {2}
351 :       child { node [circle, draw, fill=green!30] {3} }
352 :       child { node [circle, draw, fill=yellow!30] {4} }};
353 :   \end{tikzpicture}
354 : #+end_src
355
356 : * COMMENT setup
357 : #+begin_src emacs-lisp :results silent
358 :   (setq org-babel-latex-htlatex "htlatex")
359 :   (defmacro by-backend (&rest body)
360 :     `(case (if (boundp 'backend) (org-export-backend-name backend) nil) ,@body))
361 : #+end_src
362
363 This allows for the automatic composition of beautiful scalable
364 graphics across both HTML and pdf from a single document and image
365 source.
366
367 ** Latex Options                                                   :noexport:
368 #+LATEX_HEADER: \usepackage{tikz}
369 * Footnotes
370
371 [fn:1] See
372   http://orgmode.org/manual/LaTeX-and-PDF-export.html#LaTeX-and-PDF-export
373   for LaTeX export instructions.
374
375 [fn:2] See http://orgmode.org/manual/Embedded-LaTeX.html#Embedded-LaTeX.
376
377 [fn:3] See http://www.tug.org/texshowcase/ for a showcase of TeX examples.
378
379 [fn:4] You can tangle a LaTeX file without a working LaTeX
380   installation, but it won't be possible to compile this file.
381
382 [fn:5] See http://lists.gnu.org/archive/html/emacs-orgmode/2011-02/msg01297.html.
383
384 [fn:6] See [[http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.html]]
385