* org-contrib/babel/languages/ob-doc-ditaa.org: Small changes to ditaa
[worg.git] / org-contrib / babel / languages / ob-doc-LaTeX.org.old
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil 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 Code Blocks in Babel
6 #+AUTHOR:     Tom Dye
7 #+EMAIL:      tsd at tsdye dot com
8 #+LANGUAGE:   en
9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+BABEL: :exports code
11
12 #+begin_html
13   <div id="subtitle" style="float: center; text-align: center;">
14   <p>
15   Babel support for LaTeX
16   </p>
17   <p>
18   </div>
19 #+end_html
20
21 * Notes                                                            :noexport:
22 ** Queries
23 ** Comments
24 * Requirements and Enhancements
25 ** [[http://www.gnu.org/software/auctex/][AucTeX]]
26    Strongly recommended for editing .tex files.  Add the following
27    line to .emacs:
28        
29 #+begin_src emacs-lisp 
30 (load "auctex.el" nil t t)
31 #+end_src
32
33 ** [[http://www.gnu.org/software/auctex/reftex.html][RefTeX]]
34     This cross-reference, bibliography, glossary, and index manager is
35     indispensable.  Add the following line to .emacs:
36 #+begin_src emacs-lisp 
37 (add-hook 'LaTeX-mode-hook 'turn-on-reftex) 
38 #+end_src
39
40 *** Recommended RefTeX Setting
41      - It can be helpful to name a default bibliography when editing
42        source code in Babel.  Add the following lines, edited to
43        conform to your setup, to .emacs:
44
45
46 #+begin_src emacs-lisp 
47   (setq reftex-default-bibliography
48         (quote
49          ("default.bib" "other-default.bib")))       
50 #+end_src
51
52 *** Enhanced RefTeX Support
53   - You can give RefTeX access to information in other LaTeX code
54     blocks with the following code
55
56   - Add the following lines to your .emacs (adapted from  Kevin Brubeck Unhammer's [[http://www.mfasold.net/blog/2009/02/using-emacs-org-mode-to-draft-papers/][Reftex Setup]])
57 #+begin_src emacs-lisp
58   (defun org-mode-article-modes ()
59     (reftex-mode t)
60     (and (buffer-file-name)
61          (file-exists-p (buffer-file-name))
62          (reftex-parse-all)))
63   
64   (add-hook 'org-mode-hook
65             (lambda ()
66               (if (member "REFTEX" org-todo-keywords-1)
67                   (org-mode-article-modes))))
68 #+end_src
69
70   - Add the following line to the top of an org-mode file that
71     contains LaTeX code blocks
72 #+begin_src latex
73     #+TODO: REFTEX
74 #+end_src
75
76   - When you open an org-mode file with this line, RefTeX will prompt
77     for the master .tex file
78
79 * Configuration in Babel
80 ** Activate LaTeX Evaluation
81   - Add the commented line to .emacs
82 #+begin_src emacs-lisp :tangle yes
83   (org-babel-do-load-languages
84    'org-babel-load-languages
85    '((R . t)
86      (ditaa . t)
87      (dot . t)
88      (emacs-lisp . t)
89      (gnuplot . nil)
90      (haskell . nil)
91      (latex . t) ; this is the entry to activate LaTeX
92      (ocaml . nil)
93      (perl . t)
94      (python . t)
95      (ruby . t)
96      (screen . nil)
97      (sh . t)
98      (sql . nil)
99      (sqlite . nil)))
100 #+end_src
101
102 * Language-specific Conventions
103   - Babel returns raw LaTeX code on evaluation, unless a =:file=
104     header argument is present
105   - The default value for the =:exports= header argument is
106     =results=[fn:1] 
107   - The default value for the =:results= header argument is =latex=
108 * Header Arguments
109   - Babel's LaTeX support uses the =:file= and =:buffer= header
110     arguments in language-specific ways  
111   - It adds these header arguments: =:pdfheight=, =:pdfwidth=,
112     =:packages=, =:fit=, and =:border=
113
114 ** Language Specific Header Arguments
115 - The =:file= header argument accepts a file name ending in =.png= or
116   =.pdf=
117 - When =:file FILENAME.png= is set, =:buffer no= specifies that buffer
118   colors won't be used in the =.png= file
119 - When =:file FILENAME.pdf= is set, =:pdfheight= and =:pdfwidth=
120   header arguments can be used to specify the size of the pdf image in
121   LaTeX lengths, e.g., =1in=, =6em=, =48pt=, etc.
122 - The =:packages= header argument can be passed an assoc-list that
123   temporarily adds one or more packages to
124   =org-export-latex-packages-alist=
125 - =:fit= will use the LaTeX [[http://www.ctan.org/tex-archive/macros/latex/contrib/preview/][preview]] package for neatly fitting the
126   size of the generated pdf file to the size of the figure or text
127   resulting from the code block.  This is only useful when a =.pdf=
128   file type is in use.
129 - the results of the =:fit= header argument mentioned above may seem
130   too tight.  The =:border= header argument is exactly like =:fit=
131   only it takes an argument specifying the size of border to place
132   around the image (e.g. =:border 1em=)
133 - the height and width of the generated =.pdf= file can also be
134   specified manually using the =:pdfheight= and =:pdfwidth= header
135   arguments, which take LaTeX length arguments (e.g. =:pdfwidth 3in=)
136 - LaTeX source code blocks do not support the =:session= header
137   argument
138
139 ** Examples of Use
140 *** Display the LaTeX logo in the Emacs buffer
141
142 : #+begin_src latex :file latex-logo.png
143 :   \LaTeX
144 : #+end_src
145
146 #+begin_src latex :file latex-logo.png :exports none
147   \LaTeX
148 #+end_src
149
150 *** Generate a complex figure
151 This example uses the excellent [[http://sourceforge.net/projects/pgf/][pgf/tikz]] package
152 : #+begin_src latex :file fsa.pdf :packages '(("" "tikz")) :border 1em
153 :   % Define block styles
154 :   \usetikzlibrary{shapes,arrows}
155 :   \tikzstyle{astate} = [circle, draw, text centered, font=\footnotesize, fill=blue!25]
156 :   \tikzstyle{rstate} = [circle, draw, text centered, font=\footnotesize, fill=red!25]
157
158 :   \begin{tikzpicture}[->,>=stealth', shorten >=1pt, auto, node distance=2.8cm, semithick]
159 :     \node [astate] (1) at (0,0) {1};
160 :     \node [astate] (2) at (1,0) {2};
161 :     \node [rstate] (3) at (2,0) {3};
162 :     \path (1) edge [bend left] node {b} (2)
163 :           (2) edge node {b} (3)
164 :           (2) edge [bend left] node {a} (1)
165 :           (3) edge [loop above] node {(a, b)} (3);
166 :   \end{tikzpicture}
167 : #+end_src
168
169 * Common Idioms
170
171   - Org-mode can export its outline structure to LaTeX, yielding a
172     serviceable document independent of Babel, see the [[http://orgmode.org/worg/org-tutorials/org-latex-export.html][LaTeX export tutorial]]
173
174 ** Creating and Including Graphics
175    - This example creates a graph in R, then inserts it into a LaTeX
176      clode block with a noweb reference
177
178 : #+name: r-complete-weight-histogram
179 : #+begin_src R :session adze :file r/adze_wt_log.pdf
180 :     adze.wt <- ggplot(whole.adze, aes(x = weight))
181 :     adze.wt + geom_histogram() + scale_x_log10()
182 :     ggsave(file = "adze_wt_log.pdf", width = 5, height = 3)
183 : #+end_src
184
185 : #+begin_src latex :tangle graphics-document.tex
186 :   \begin{figure}[htb!]
187 :     \centering
188 :     \includegraphics[width=5in]{<<r-complete-weight-histogram()>>}
189 :     \caption[Weight of complete adzes]{Weight of complete adzes on a
190 :       logarithmic scale.}
191 :     \label{fig:complete-weight}
192 :   \end{figure}
193 : #+end_src
194
195
196
197 ** Passing an Org-mode table to a LaTeX code block
198
199 Tables are difficult to set in type.  This was true when lead type was
200 set manually and it is still true with a sophisticated type-setting
201 engine like LaTeX.  One way to make a LaTeX table is to write it out
202 using an Org-mode table and then "export" the table into the LaTeX
203 code block using the function =orgtbl-to-generic=.
204
205 This Emacs lisp function, slightly modified from one written by Eric
206 Schulte, inserts an Org-mode table into a LaTeX code block.  It
207 depends on the [[http://www.ctan.org/tex-archive/macros/latex/contrib/booktabs/][LaTeX booktabs package]], which draws horizontal rules of
208 appropriate widths at the top and bottom of a table, as well as within
209 the table.
210
211 : #+name: booktabs-2
212 : #+begin_src emacs-lisp :var table='((:head) hline (:body))
213 : (flet ((to-tab (tab)
214 :                (orgtbl-to-generic
215 :                 (mapcar (lambda (lis)
216 :                           (if (listp lis)
217 :                               (mapcar (lambda (el)
218 :                                         (if (stringp el)
219 :                                             el
220 :                                           (format "%S" el))) lis)
221 :                             lis)) tab)
222 :                 (list :lend " \\\\" :sep " & " :hline "\\hline"))))
223 :   (org-fill-template
224 :    "
225 : \\toprule
226 : %table
227 : \\bottomrule\n"
228 :    (list
229 :     (cons "table"
230 :           ;; only use \midrule if it looks like there are column headers
231 :           (if (equal 'hline (second table))
232 :               (concat (to-tab (list (first table)))
233 :                       "\n\\midrule\n"
234 :                       (to-tab (cddr table)))
235 :             (to-tab table))))))
236 : #+end_src
237
238 The function can be called using noweb syntax, like this:
239
240 : #+begin_src latex :noweb yes
241 :  \begin{table}[htb!]
242 :    \centering
243 :    \caption{A test table}
244 :    \label{tab:test}
245 :    \begin{tabular}{rl}
246 :      <<booktabs-2(table=months)>>
247 :    \end{tabular}
248 :  \end{table}
249 : #+end_src
250
251
252 * Footnotes
253
254 [fn:1] *Note:* The default value of the =:exports= header argument
255     alters the expected behavior of Org-mode export to HTML and LaTeX.
256     LaTeX code blocks will require an explicit =:exports code= header
257     argument to export as described in the Org-mode manual.