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.