Org-babel-doc-LaTeX

Org-babel support for LaTeX

Table of Contents

Requirements and Enhancements

AucTeX

Strongly recommended for editing .tex files. Add the following line to .emacs: 

(load "auctex.el" nil t t)

RefTeX

This cross-reference, bibliography, glossary, and index manager is indispensable. Add the following line to .emacs: 

(add-hook 'LaTeX-mode-hook 'turn-on-reftex)

Recommended RefTeX Setting

  • It can be helpful to name a default bibliography when editing source code in Org-babel. Add the following lines, edited to conform to your setup, to .emacs: 
(setq reftex-default-bibliography
      (quote
       ("default.bib" "other-default.bib")))

Enhanced RefTeX Support

  • You can give RefTeX access to information in other LaTeX code blocks with the following code
  • Add the following lines to your .emacs (adapted from Kevin Brubeck Unhammer's Reftex Setup) 
(defun org-mode-article-modes ()
  (reftex-mode t)
  (and (buffer-file-name)
       (file-exists-p (buffer-file-name))
       (reftex-parse-all)))

(add-hook 'org-mode-hook
          (lambda ()
            (if (member "REFTEX" org-todo-keywords-1)
                (org-mode-article-modes))))
  • Add the following line to the top of an org-mode file that contains LaTeX code blocks 
#+TODO: REFTEX
  • When you open an org-mode file with this line, RefTeX will prompt for the master .tex file

Configuration in Org-babel

Activate LaTeX Evaluation

  • Add the following line to .emacs 
(require 'org-babel-latex)

Raise Noweb-type Errors

  • Add LaTeX to a list of languages that raise noweb-type errors
  • Edit the following example to include the languages you use in Org-babel 
(setq org-babel-noweb-error-langs '("R" "python" "latex"))

Language-specific Conventions

  • Org-babel returns raw LaTeX code on evaluation, unless a :file header argument is present
  • The default value for the :exports header argument is results=[fn:1] - The default value for the =:results header argument is latex

Additions to Org-babel

  • Org-babel's LaTeX support uses the :file and :buffer header arguments in language-specific ways
  • It adds three header arguments: :pdfheight, :pdfwidth, and :packages

Header Arguments

  • The :file header argument accepts a file name ending in .png or .pdf
  • When :file FILENAME.png is set, :buffer no specifies that buffer colors won't be used in the .png file
  • When :file FILENAME.pdf is set, :pdfheight and :pdfwidth header arguments can be used to specify the size of the pdf image in LaTeX lengths, e.g., 1in, 6em, 48pt, etc.
  • The :packages header argument can be passed an assoc-list that temporarily adds one or more packages to org-export-latex-packages-alist
  • LaTeX source code blocks do not support the :session header argument

Examples of Use

Display the LaTeX logo in the Emacs buffer 

#+begin_src latex :file latex-logo.png
  \LaTeX
#+end_src

\LaTeX

Generate a complex figure

  • This example uses the excellent pgf/tikz package 
    #+begin_src latex :file fsa.pdf :packages '(("" "tikz")) :pdfwidth 3in :pdfheight 3in
  % Define block styles
  \usetikzlibrary{shapes,arrows}
  \tikzstyle{astate} = [circle, draw, text centered, font=\footnotesize, fill=blue!25]
  \tikzstyle{rstate} = [circle, draw, text centered, font=\footnotesize, fill=red!25]

  \begin{tikzpicture}[->,>=stealth', shorten >=1pt, auto, node distance=2.8cm, semithick]
    \node [astate] (1) at (0,0) {1};
    \node [astate] (2) at (1,0) {2};
    \node [rstate] (3) at (2,0) {3};
    \path (1) edge [bend left] node {b} (2)
          (2) edge node {b} (3)
          (2) edge [bend left] node {a} (1)
          (3) edge [loop above] node {(a, b)} (3);
  \end{tikzpicture}
#+end_src

Common Idioms

  • Org-mode can export its outline structure to LaTeX, yielding a serviceable document

Creating and Including Graphics

  • This example creates a graph in R, then inserts it with a noweb reference to the results of the R code block 
    #+srcname: r-complete-weight-histogram
#+begin_src R :session adze :file r/adze_wt_log.pdf
    adze.wt <- ggplot(whole.adze, aes(x = weight))
    adze.wt + geom_histogram() + scale_x_log10()
    ggsave(file = "adze_wt_log.pdf", width = 5, height = 3)
#+end_src

    #+begin_src latex :tangle graphics-document.tex
  \begin{figure}[htb!]
    \centering
    \includegraphics[width=5in]{<<r-complete-weight-histogram()>>}
    \caption[Weight of complete adzes]{Weight of complete adzes on a
      logarithmic scale.}
    \label{fig:complete-weight}
  \end{figure}
#+end_src

[fn:1] Note: The default value of the :exports header argument alters the expected behavior of Org-mode export to HTML and LaTeX. LaTeX code blocks will require an explicit :exports code header argument to export as described in the Org-mode manual.