Tool time: org-mode and beamer

2013-09-07emacslatexorg-modeslides

This year I’ve become a devoted user of org-mode for making presentations, using the excellent beamer package for LaTeX export. Although this tool set can produce great-looking slides, using open-source software, without using silly point-and-click tools, it does have a steep learning curve. Having gone through at least the initial phases of this curve, I hope that I can help out other folks in their presentation efforts by giving some pointers here.

There are two important files to create to make a presentation in this way: the org-mode file, and the beamer theme file. I am going to assume that you already know what LaTeX is, and that you already know how to use Emacs to edit text files, but I will start out by briefly describing as much of org-mode as I think you’ll need for this particular task. After that, I’ll talk about the org-mode file that you write to create a presentation, and finally I’ll describe the beamer theme file that you can use to customize your slide appearance.

Org-mode in a minute §

Org-mode is a crazy, beautiful, complicated swiss-army knife of an information management system in Emacs. The basic idea behind org-mode is that it helps you maintain semi-structured data using a bunch of text files containing outlines, lists, and tables. Text files preserve the portability of your data, while allowing you to make use of your accumulated Emacs-fu: moving around (C-a, C-e, C-p, M->) remains the same, undo (C-_) remains the same, swapping characters (C-t) words (M-t) or lines (C-x C-t) remains the same, killing (C-w, M-w, C-k) and yanking (C-y, M-y) … in short, all of these things you already know about Emacs remain the same. Org-mode extends this basic editing functionality by essentially adding a powerful “outline editing mode” on top.

An org-mode document is usually divided into sections, each of which starts with a title prefixed by a number of asterisk (*) characters. A level 1 title, for instance, might look like this:

* Introduction

while a level 3 title, followed by some text, might look like this:

*** Procedures of the Roman Senate

The Romans had a Senate.

- Senators *could not* engage in banking
- Any Senator could /filibuster/ a vote

Below each title comes one or more blocks of text, just like in a LaTeX document. In addition to simple text blocks, org-mode provide some basic text formatting tools—like Markdown or ReStructuredText—that allow you to write bulleted and numbered lists, bold text, and so forth, without all of the LaTeX-specific markup. Basically, writing with this level of org-mode is similar to writing a LaTeX document using Markdown.

Org-mode allows you to do all sorts of crazy stuff using the outline of your document, but I won’t go into that here. I will mention that when you open an org-mode document, org-mode by default collapses all of the sections in your document. To cycle through expanding all of your document’s sections, press S-<tab> several times. (To toggle expansion of a single section, move point to that section and press <tab>.)

Finally, I will also note that the first several lines of an org-mode file typically contain lines starting with #+, which is a prefix indicating some sort of metadata. The big three metadata elements are TITLE, AUTHOR, and DATE:

#+TITLE: Rain and Freedom in "Sometimes a Great Notion"
#+AUTHOR: Mildred Ratched
#+DATE: January 22, 1978

These metadata elements are used when you ask org-mode to publish your file to some other output format—in our case here, LaTeX.

So, now you have a tool that knows about metadata and sections, and allows you to edit text in an intelligent way. Sounds like the perfect place to start writing some slides!

To get started, create a single text file with Emacs, and turn on org-mode: M-x org-mode.

Header §

The header of an org-mode file, particularly one that is intended to be published using LaTeX, typically includes a bunch of metadata that will help produce the final document in just the right way. I usually use a header based more or less on the following template:

#+STARTUP: beamer
#+OPTIONS: toc:nil
#+DATE: A Conference, 2013
#+LaTeX_CLASS: beamer
#+LaTeX_CLASS_OPTIONS: [t]
#+LaTeX_HEADER: \usetheme{utcs}
#+LaTeX_HEADER: \usepackage{mathpazo}
#+LaTeX_HEADER: \usepackage{stmaryrd}
#+LaTeX_HEADER: \DeclareMathOperator*{\argmin}{arg\,min}
#+LaTeX_HEADER: \DeclareMathOperator*{\argmax}{arg\,max}
#+BEAMER_FRAME_LEVEL: 2
#+BEAMER_HEADER_EXTRA: \title[Slide Tools]{A Method for Making Slides Using Text Files}
#+BEAMER_HEADER_EXTRA: \author[Johnson, Wuzzy]{Leif Johnson, Fuzzy Wuzzy}

What do all of these things do? I’ll step through them briefly here.

Beamer document §

To tell org-mode that you want to create a beamer document, you’ll need to set a couple different header elements. First, and most important, you need to configure the LaTeX output to create a beamer document:

#+LaTeX_CLASS: beamer

This is just the standard mechanism for selecting the documentclass in exported LaTeX output.

#+STARTUP: beamer

Org-mode hasn’t figured out yet that if you are exporting a beamer document in LaTeX, then you are also probably writing a beamer document in org-mode. So this header tells org-mode to turn on beamer-specific functions when you load the document.

Presentation metadata §

There are several fields that you can set to specify what your presentation is about, who wrote it, and so forth. These elements naturally show up on the title slide of your presentation, but also, depending on your beamer theme settings, in the footer area of each slide.

Typically, org-mode uses the DATE, TITLE, and AUTHOR fields for this purpose, but when exporting slides, two of these metadata fields have some drawbacks, so I recommend using this strategy instead:

#+DATE: Conference, 2013
#+BEAMER_HEADER_EXTRA: \title[Pose Coding and Regression]{Unified Losses for Multi-Modal Pose Coding and Regression}
#+BEAMER_HEADER_EXTRA: \author[Johnson, Cooper, Ballard]{Leif Johnson, Joseph Cooper, Dana Ballard}

Here I’ve ignored the standard org-mode TITLE and AUTHOR headers, because org-mode doesn’t have a way to export short forms of these elements (the part between square brackets). I’ve found the short title and author form to be critical: typically my presentation titles are rather long, being based on a computer science paper of some sort, and if exported without a short form these elements will overflow the small-ish areas devoted to them in the slide footer. It’s not critical, but I think having a little polish goes a long way in a presentation.

Organization §

Org-mode has all sorts of ways of handling outlined documents, which I think are generally really helpful. However, I don’t like having outlines in my presentations, since they often serve as crutches to compensate for lack of a coherent story. So, I disable the automatic table of contents using the standard org-mode OPTIONS header:

#+OPTIONS: toc:nil

There is also the question of how sections, subsections, and so forth will map onto beamer frames (slides). By default, all level 1 titles will create a new frame. However, you can change this behavior by telling org-mode which header level should start a new frame:

#+BEAMER_FRAME_LEVEL: 2

I like using 2 for this value because it allows you to group frames into logical chunks in your presentation. In addition, setting this value to 2 works better with beamer themes that include slide icons grouped by section. In the rest of this tutorial I’ll assume that you’ve set this value to 2.

Slide appearance §

By default, the content on a beamer frame is centered vertically. You can change this by passing document class options to LaTeX. For example, to align all frame content to the top by default, include this header line:

#+LaTeX_CLASS_OPTIONS: [t]

You can also use this field to select the font size for your slides; the default is 11 points, but you can set this to any value between 8 and 14.

Also, you will probably want to specify the beamer theme to use when laying out your slides. Beamer comes with many different available themes, but I think my slides end up looking a lot nicer if I am able to set things like colors and spacing more explicitly. For example, to use a theme file that matches the official University of Texas colors and includes the Computer Science Department as my institution, I use:

#+LaTeX_HEADER: \usetheme{utcs}

and then create a beamer theme file in the same directory as the org-mode file, named beamerthemeutcs.sty. I’ll talk more about this theme file at the end of this tutorial.

Finally, this is a personal preference, but I think the Palatino font set and mathematics look really nice in a presentation. You can select them by supplying this standard header to LaTeX:

#+LaTeX_HEADER: \usepackage{mathpazo}

For that matter, you can include any LaTeX header information that you should desire using this metadata field. Go wild!

Frames §

A frame is, more or less, a slide. It has a title, an optional subtitle, and some content. Depending on your beamer theme, it might also appear with a sidebar or a footer, but those elements are added by the beamer theme you select and do not show up anywhere in your actual org-mode file.

Here’s a basic frame in an org-mode document:

** Napoleon's Infamous Campaign

\includegraphics{map.jpg}

- Crossed a river, August 1812
- Fled to Paris, December 1812
- Lost more than 90% of army

Title §

The title of your frame is just the section title, and the subtitle (if any) is included by appending \\ to your section title. For example:

** Frame Title

Would just have a title, and

** Frame Title \\ Subtitle here

includes a subtitle as well.

Contents §

Following the title, you can include whatever content you like in your slide. In the example above, I’ve included an image file (from the same directory as the org-mode file) called map.jpg, and followed it by a bulleted list with three elements.

You can include multiple graphics in your frames. If you’d like several images to appear on the same line, keep the includes together:

\includegraphics[width=4cm]{map.jpg}
\hspace{1cm}
\includegraphics[height=3cm]{tallies.pdf}

Often, as above, it’s a good idea to control the width and/or height of your included graphics. Be sure to remember that the exported size of a beamer frame is 128mm by 96mm (this relatively small page size eliminates most of the need to scale fonts in a strange way compared with standard LaTeX documents), and that the title often takes up a good bit of the top of the frame. Finally, in the example above, I’ve used the LaTeX \hspace{} command to separate the two images by a little bit—by default LaTeX will not insert any whitespace there.

If you’d like the images to appear one after another vertically, just put the two include statements in separate “paragraphs”:

\includegraphics[width=4cm]{map.jpg}

\centering
\includegraphics[height=3cm]{tallies.pdf}

As above, you can center an image horizontally by including the \centering command.

Math §

You can insert math in your slides using the standard LaTeX tools:

\[ 0 = e^{i\frac{\tau}{2}} + 1 \]

Now we rewrite the above equation using $\frac{\tau}{2} = \pi$

Because it’s LaTeX, the math will be typeset beautifully, and it’s just as easy to edit as it is in your LaTeX documents!

Blocks §

I’ve found that you can get pretty far using just the tools above. However, there are times when you need a little more organizational power, or when you want to take advantage of the stylistic effects of a beamer “block.”

** Calvin or Hobbes? \\ Epistemology of cunning

Hobbes often lies in wait for Calvin:

*** Pouncing                               :B_example:
    :PROPERTIES:
    :BEAMER_env: example
    :END:

\includegraphics{pounce.jpg}

Here, we’ve created a sub-title within our frame, and designated it as an “example” block. To do this with org-mode, you can either copy the text above and modify it as needed. Alternatively, write out the title:

*** Pouncing

then type C-c C-b. This will bring up an org-mode menu that will let you choose which type of block you’d like to use. (You can change the block type later by using the same keypress.)

You can also configure blocks to appear in multiple columns on a slide. To do this, add a :BEAMER_col: field to the properties drawer of the block:

*** Pouncing                              :B_example:
    :PROPERTIES:
    :BEAMER_env: example
    :BEAMER_col: 0.55
    :END:

\includegraphics[width=4cm]{pounce.jpg}

*** Leaping                               :B_example:
    :PROPERTIES:
    :BEAMER_env: example
    :BEAMER_col: 0.45
    :END:

\includegraphics[width=3cm]{leap.jpg}

This will set up the blocks on your frame with the given widths (specified as a fraction of the frame width). Anything below a block title will be included in the block, until org-mode encounters the start of a new frame or a new block.

To include content that spans the entire frame after a columnized block or blocks, create a new block using the ignoreheading format that has a width of 1:

*** Leaping                         :B_ignoreheading:
    :PROPERTIES:
    :BEAMER_env: ignoreheading
    :BEAMER_col: 1
    :END:

This content will span the frame width

Progressive reveal and overlays §

You can specify that elements on your frames get displayed progressively, from what I can tell, in two different ways.

Probably the easiest is just to include \pause in your slide wherever you want to press a key to reveal the next thing on your slide. For instance, each element on this slide will be revealed progressively:

* Slot Machine Madness

\pause
\includegraphics[width=3cm]{bandit.jpg}

\pause
- The house always wins
  \pause
  - Even when you take this fact into account
\pause
- So it's not a great idea to gamble
\pause
- Not even the lottery

This can get rather annoying if you intend to reveal every bullet in your entire presentation progressively, so there is another way to do it. Just add a header to the top of your org-mode file:

#+BEAMER: \beamerdefaultoverlayspecification{<+->}

This will reveal each bullet element in your slides progressively. It will not, however, reveal images and non-list-item text progressively (these will be visible from the get-go), so you might need to do some tweaking to get things just the way you want them.

Beamer gives you more control over exactly when things appear and disappear on your slides, by including a special <N-M> marker on elements that you want to reveal progressively. The marker means that the element will first appear on the Nth step of the reveal for that slide, and will remain in appearance up to the Mth step. M can be omitted if you want things to appear until the slide is over, and N can be + if you want elements on the slide to be revealed in sequence. (This is what the <+-> in the above default overlay specification does.)

Just as an example, you might show elements in a list progressively:

- <1-> First element (first reveal onwards)
- <1-2> Second (first two reveals)
- <3-6> Third (third to sixth reveals

You get the idea.

Babel §

One of the neato features of org-mode is its ability to embed output from other programs or programming languages, by including source code directly inside the org-mode document. This feature is called “babel” in org-mode; it allows you to, for example, use dot to draw graphs that will be included in your exported slides:

* The Numbers

#+BEGIN_dot numbers.pdf -Tpdf
digraph example {
  complex -> real -> rational -> whole;
  even -> whole [label="subset?"];
  e -> real;
}
#+END_dot

Instead of including this messy source in your slides, org-mode will call the dot executable, passing it the code embedded between the BEGIN and END markers. dot will draw a directed graph using this code, and then org-mode will include the resulting PDF file in your slides!

TiKZ §

This babel embedding is a really nice feature, and can be used to include many other programming languages (Python, ruby, shell, etc.) or environments directly in your org-mode documents. I think it’s really the first exposure I’ve had to what might be called “literate programming.”

However, if you’re focused on including diagrams in slides, it’s pretty hard to beat another crazy, complicated, beautiful program : TiKZ. TiKZ is a vector drawing package for LaTeX that, like org-mode, can pretty much do anything you want it to do—provided you know how to convince it in the right way. I won’t get into TiKZ in this tutorial, but I recommend giving it a look if you find yourself needing vector graphics in your slides.

Beamer theme §

For further reading, here’s a nice cheat sheet (PDF) with some Beamer style information.