e9d036cc4d22a795283d75c69819a86f7cf85e26
[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
212 ** "Hello World"
213
214 At its simplest, Org Mode evaluation of LaTeX source code blocks with
215 =C-c C-c= wraps the results in a =#+BEGIN_LaTeX ... #+END_LaTeX=
216 block.
217
218 : #+name: hello-world
219 : #+BEGIN_SRC latex
220 : \LaTeX
221 : #+END_SRC
222
223 : #+RESULTS: hello-world
224 : #+BEGIN_LaTeX
225 : \LaTeX
226 : #+END_LaTeX
227
228 ** Andreas Leha
229 This complex example was posted to the Org Mode list by Andreas Leha.
230 It depends on a working installation of the R statistical
231 software.[fn:6] The code makes use of R sessions to preserve state
232 between R source code blocks.
233
234 The first source code block loads the
235 [[http://www.texample.net/tikz/resources/][TikZ package]], which
236 defines a language to produce vector graphics from a
237 geometric/algebraic description.
238
239 #+begin_src R :session :exports code :results silent
240   library("tikzDevice")
241 #+end_src
242
243 A simple plot is generated and output as LaTeX code by the TikZ
244 device in R.
245
246 #+name: test_plot
247 #+begin_src R :session :exports code :results output latex
248   tikz(console=TRUE, width=4, height=4)
249   plot(rnorm(100), rnorm(100))
250   dummy <- dev.off()
251 #+end_src
252
253 The LaTeX output of this R code is processed by a LaTeX source code
254 block, using Org Mode's noweb syntax.  Note the various =#+header:=
255 lines and their settings, which serve to configure ImageMagick.  In
256 this case, a png file is being produced outside the usual Org Mode
257 path through =dvipng=.  Note that the header presented here has been
258 simplified somewhat.  Interested readers might want to review Andreas'
259 original post.
260
261 : #+name: test_plot_png
262 : #+header: :exports results :file test.png 
263 : #+header: :imagemagick yes :iminoptions -density 600 :imoutoptions -geometry 400 
264 : #+header: :fit yes :noweb yes :headers '("\\usepackage{tikz}")
265 : #+begin_src latex :exports results :file test.png 
266 :   <<test_plot()>>
267 : #+end_src
268
269
270 With this header, the LaTeX output of the TikZ device in R yields a
271 graph of the random number generation.
272
273 #+Caption: Results of evaluating a LaTeX source code block.
274 #+RESULTS: test_plot_png
275 [[file:images/test.png]]
276
277 If the header is changed so the results are not written to a file,
278 then the LaTeX code generated by the TikZ device is written to the Org
279 Mode buffer.  The results shown below have been shortened somewhat for
280 illustrative purposes.
281
282 : #+name: test_plot_tikz
283 : #+begin_src latex :noweb yes :exports results
284 :   <<test_plot()>>
285 : #+end_src
286
287 #+RESULTS: test_plot_tikz
288 : #+BEGIN_LaTeX
289 : % Created by tikzDevice version 0.6.2 on 2012-02-08 21:28:07
290 : % !TEX encoding = UTF-8 Unicode
291 : \begin{tikzpicture}[x=1pt,y=1pt]
292 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
293 : \definecolor[named]{fillColor}{rgb}{1.00,1.00,1.00}
294 : \fill[color=fillColor,fill opacity=0.00,] (0,0) rectangle (289.08,289.08);
295 : \begin{scope}
296 : \path[clip] ( 49.20, 61.20) rectangle (263.88,239.88);
297 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
298 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] (184.34, 99.14) circle (  2.25);
299 :
300 : ...
301 :
302 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] (143.44,134.70) circle (  2.25);
303 : \end{scope}
304 : \begin{scope}
305 : \path[clip] (  0.00,  0.00) rectangle (289.08,289.08);
306 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
307 :
308 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] ( 75.29, 61.20) -- (250.80, 61.20);
309 :
310 : \draw[color=drawColor,line cap=round,line join=round,fill opacity=0.00,] ( 49.20, 61.20) --
311 :       (263.88, 61.20) --
312 :       (263.88,239.88) --
313 :       ( 49.20,239.88) --
314 :       ( 49.20, 61.20);
315 : \end{scope}
316 : \begin{scope}
317 : \path[clip] (  0.00,  0.00) rectangle (289.08,289.08);
318 : \definecolor[named]{drawColor}{rgb}{0.00,0.00,0.00}
319
320 : \node[color=drawColor,anchor=base,inner sep=0pt, outer sep=0pt, scale=  1.00] at (156.54, 13.20) {rnorm(100)};
321 :
322 : \node[rotate= 90.00,color=drawColor,anchor=base,inner sep=0pt, outer sep=0pt, scale=  1.00] at ( 13.20,150.54) {rnorm(100)};
323 : \end{scope}
324 : \end{tikzpicture}
325 : #+END_LaTeX
326
327
328 ** Latex Options                                                   :noexport:
329 #+LATEX_HEADER: \usepackage{tikz}
330 * Footnotes
331
332 [fn:1] See
333   http://orgmode.org/manual/LaTeX-and-PDF-export.html#LaTeX-and-PDF-export
334   for LaTeX export instructions.
335
336 [fn:2] See http://orgmode.org/manual/Embedded-LaTeX.html#Embedded-LaTeX.
337
338 [fn:3] See http://www.tug.org/texshowcase/ for a showcase of TeX examples.
339
340 [fn:4] You can tangle a LaTeX file without a working LaTeX
341   installation, but it won't be possible to compile this file.
342
343 [fn:5] See http://lists.gnu.org/archive/html/emacs-orgmode/2011-02/msg01297.html.
344
345 [fn:6] See [[http://orgmode.org/worg/org-contrib/babel/languages/ob-doc-R.html]]
346