org-beamer

Preparation

A beamer presentation can either be the entire Org document, or a subtree in the document. There are a number of important settings which should be in place to make editing the presentation easy. For most settings, a default is available, but you at least define a format for column view that will make it easy to change properties that will be interpreted by beamer export.

Special setting

If the document is the presentation, special settings for beamer export look like this:

#+LaTeX_CLASS: beamer
#+LaTeX_CLASS_OPTIONS: [presentation]
#+BEAMER_FRAME_LEVEL: 1
#+BEAMER_HEADER_EXTRA: \usetheme{default}\usecolortheme{default}
#+COLUMNS: %40ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Env Args) %4BEAMER_col(Col) %8BEAMER_extra(Extra)

If a subtree is set up as a presentation, the special settings can also be in properties, to allow different settings for different presentations in the same file:

** Presentation
   :PROPERTIES:
   :LaTeX_CLASS: beamer
   :LaTeX_CLASS_OPTIONS: [presentation]
   :BEAMER_FRAME_LEVEL: 1
   :BEAMER_HEADER_EXTRA: \usetheme{default}\usecolortheme{default}
   :COLUMNS: %40ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Env Args) %4BEAMER_col(Col) %8BEAMER_extra(Extra)
   :END:

The meaning of these settings are:

LaTeX_CLASS
The key to the beamer entry in org-export-latex-classes.
LaTeX_CLASS_OPTIONS
The options to be used with \documentclass{beamer}.
BEAMER_FRAME_LEVEL
The outline level that defines frames, or 0 to make frame definition manual. The default is 1 (see the variable org-beamer-frame-level)
BEAMER_HEADER_EXTRA
Text that will be added to the BEAMER document header - useful for example to set beamer theses.
COLUMNS
A format specification for column view that makes it easy to edit the properties influencing BEAMER export.

You can insert a template for these options with

M-x org-beamer-settings-template RET

The command will ask if these are options for a subtree or for the file as a whole.

Organization

By default, level one headlines become frames in the beamer document. When exporting a subtree as a beamer presentation, the direct children of the subtree head become the frames. However, frame selection can also be more flexible, see below.

Sections, Subsections, and Parts

If you want to have a sectioning structure above the frames as it is used for presentations with table of contents, use the BEAMER_FRAME_LEVEL setting to change this. Setting it to 2 will allow sections, 3 will allow subsections as well. Setting it to 0 means that any levels above (the manually selected) frames will automatically be section/subsection. Finally, if you also set the variable org-beamer-use-parts, then level 1 will define parts and sections and subsections will move down one level in the hierarchy.

Frames

The BEAMER_FRAME_LEVEL setting governs which levels become frames. If that option is set to 0, then frames are only created by setting the BEAMER_env property of an entry to the value frame.

The heading of the entry will become the frame title. If the frame title contains the string \\, the line will be split at that location, and the second half will become the frame subtitle. If you need a line break in the frame title, use \newline or \linebreak.

Auto-fragile frames

If the regular expression org-beamer-fragile-re matches inside a frame (in the final LaTeX file), the frame will automatically receive the fragile option. By default, this is the case for verbatim environments, which includes all source code examples created by Org.

Outline structure below frames

The outline structure below the frame level becomes a nested itemize structure. You can also use plain lists to create that structure, including ordered lists.

Block-like environments

A headline that has the property BEAMER_env set to an environment name will get this subtree exported with the corresponding environment, instead of itemize. Some environments are listed and configured in org-beamer-environments-default. Additional environments may be defined in org-beamer-environments-extra. For example, a value block will trigger the creation of a block environment, while theorem will trigger the creation of a theorem environment.

When it makes sense, the headline text is used in an appropriate argument of the environment. When that does not make sense, the headline will be ignored.

The property BEAMER_envargs can contain the three kinds of additional arguments for the environment, like "[..]" for the optional argument, "[<..>]" for the default overlay specification for the environment content, and "<..>" for the overlay specification for the environment itself. These arguments can be given in arbitrary sequence and may, but don't have to be, separated by space characters.

Columns

There are several ways to create columns when exporting an Org document as a beamer presentation.

Columns without additional outline structure

When an entry has a property BEAMER_col, Org-mode will start first a columns environment and then a column environment with the value of the BEAMER_col property as width. If that width is just a number, it will be interpreted as a fraction of \textwidth -- otherwise it will be assumed that you have already specified the unit, as in "5cm".

The column ends at the next entry with such a property. When the frame ends, the last column environment and the last columns environment will be closed automatically.

The entry that triggers the start of the column will still be normally processes as part of the column content. It can also still have a BEAMER_env property, so you could make two columns, each of which is a block environment from just two headlines with appropriate properties. If you need to pass an option argument to the implicitly created columns and column environments, write something like C[OPTIONS] (for the columns environment) or c[OPTIONS] (for the column environment).

The advantage of this setup is that no additional outline structure has to be created and that the document still exports very well to other backends. The limitation is that you cannot close the columns environment end insert more text below it on the same frame.

Columns with additional outline structure

To gain more control, you can create additional outline structure just to make the columns and column environments.

The advantage of this approach is that you can close a columns environment on the slide and insert text after it. Also, Org-mode structure editing make it then easy to move columns around.

  • Making the columns environment

    A headline with the BEAMER_env property columns will create a columns environment. The headline will be ignored. It is useful to to set it to something that will make sense during export to another backend, but will not be needed in the presentation.

  • Making the column environment

    You can use a headline with BEAMER_env property set to column in order to create a column. The headline of the column should then be a number between 0 and 1, indicating the width of the column as a fraction of \textwidth.

Embedded LaTeX

As is normal for Org-mode, you can embed LaTeX commands into the text, and they will be transferred literally into the exported document.

Adding special code for BEAMER

You can use

#+BEAMER: this line if for beamer export only
#+BEGIN_BEAMER
   so is this line
   and this
#+END_BEAMER

to add special code that should be emitted only during BEAMER export. Code intended for the LaTeX backend will be included as well.

Overlay/action in plain lists

For plain list environments (ordered, unordered, and description lists) you can start each item optionally with an overlay specification <...>. If any item in the list contains a default specification [<...>], this will be moved into the begin statement of the itemize/enumerate/description environment, to provide a default setting for the list items. This does not look good when exporting the same content to a different backend - if you are planning to do this, consider to continue the outline structure inside frames to produce the frame content.

Editing support with org-beamer-mode

Org defines a minor mode with editing support for Org files that will be exported as beamer presentations. To turn on this mode in a specific file, use

#+STARTUP: beamer

Tracking of the BEAMER_env property with tags

To provide instant knowledge about the beamer environment that will be used for a node, changing the BEAMER_env property will cause a tag :B_environment: to be set, where environment stands for the actual environment. So a node that is becoming a frame (if that is triggered by property and not by level) will have the tag :B_frame: These tags will have a special font-lock face, org-beamer-tag.

Fast tag selection for beamer environments

The command C-c C-b will offer fast selection interface for the various beamer environments. In addition to setting environments, C-c C-b | will toggle the presence of a BEAMER_col property.

Column view

Column view provides a great way to set the environment of a node and other important parameters. Make sure you are using a COLUMN format that is geared toward this special purpose. The command org-beamer-settings-template does define such a format.

Special properties

The following properties are special for BEAMER export

BEAMER_env
The environment to be created for this node.
BEAMER_envargs
The environment arguments for this node, can contain a option, and overlay, and a default overlay specification is the environment supports them. Also, if the node has a BEAMER_col property, c[OPTION] will be passed to the column environment, and C[OPTION] will be passed to the implicitly created columns environment.
BEAMER_col
Start a column with the property value as width.
BEAMER_extra
Extra LaTeX code that will be inserted right after the environment begins. For example, in a frame environment, this can define a transition.

Open issues

Here are some issues I have not yet addressed, and where I don't know how to deal with them:

  1. Is the in-buffer customization OK the way I did it, or does it have to be more elegant?
  2. How about notes, what is a good way to define text that will be wrapped into the \note macro
  3. What else is needed?

Example

Here is a (still very incomplete) example Org document that is intended for beamer export.

#+LaTeX_CLASS: beamer
#+TITLE: Example Presentation
#+AUTHOR: Carsten Dominik
#+LaTeX_CLASS_OPTIONS: [presentation]
#+BEAMER_FRAME_LEVEL: 2
#+BEAMER_HEADER_EXTRA: \usetheme{Madrid}\usecolortheme{default}
#+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Env Args) %4BEAMER_col(Col) %8BEAMER_extra(Extra)
#+OPTIONS: tags:nil


* This is the first structural section

** Frame 1 \\ with a subtitle
*** Thanks to Eric Fraga                                            :B_block:
    :PROPERTIES:
    :BEAMER_env: block
    :BEAMER_envargs: C[t]
    :BEAMER_col: 0.5
    :END:
    for the first viable beamer setup in Org
*** Thanks to everyone else                                         :B_block:
    :PROPERTIES:
    :BEAMER_col: 0.5
    :BEAMER_env: block
    :BEAMER_envargs: <2->
    :END:
    for contributing to the discussion
** Frame 2 \\ Like 1, but now with explicit columns
    :PROPERTIES:
    :BEAMER_extra: \transblindsvertical[duration=1]
    :END:
*** columns                                                       :B_columns:
    :PROPERTIES:
    :BEAMER_env: columns
    :END:
**** 0.5                                                           :B_column:
     :PROPERTIES:
     :BEAMER_env: column
     :END:
***** Thanks to Eric Fraga                                          :B_block:
      :PROPERTIES:
      :BEAMER_env: block
      :BEAMER_col: 
      :END:
      for the first viable beamer setup in Org

**** 0.5                                                           :B_column:
     :PROPERTIES:
     :BEAMER_env: column
     :END:

***** Thanks to everyone else                                       :B_block:
      :PROPERTIES:
      :BEAMER_col: 
      :BEAMER_env: block
      :BEAMER_envargs: <2->
      :END:
      for contributing to the discussion
** Frame 2 \\ where we will not use columns
*** Request                                                         :B_block:
    Please test this stuff!