Beamer support

* Beamer support - 2nd round
@ 2009-12-03 16:10 Carsten Dominik
  2009-12-04 18:34 ` Eric S Fraga
                   ` (2 more replies)
  0 siblings, 3 replies; 22+ messages in thread
From: Carsten Dominik @ 2009-12-03 16:10 UTC (permalink / raw)
  To: emacs-orgmode Mode

Dear all,

after carefully listening to all your comments and thinking
things through more thoroughly, here is now my second attempt
to define beamer support in Org-mode.

What is described in this document should actually work on the
new "beamer" branch on our git repo - I am planning to leave the
code there until we have converged and ironed out the most
important bugs.

The philosophy is now that foremost, any not-too-deep Org-mode
tree should easily and without changes export as a beamer
presentation.  From then on, you can add meta data to improve
the presentation.

- Carsten

                               beamerdoc
                               =========

Author: Carsten Dominik <carsten.dominik@gmail.com>
Date: 2009-12-03 17:00:57 CET

Table of Contents
=================
1 Preparation
     1.1 Special setting
2 Organization
     2.1 Sections, Subsections, and Parts
     2.2 Frames
         2.2.1 Auto-fragile frames
     2.3 Outline structure below frames
     2.4 Block-like environments
     2.5 Columns
         2.5.1 Columns without additional outline structure
         2.5.2 Columns with additional outline structure
     2.6 Embedded LaTeX
     2.7 Adding special code for BEAMER
     2.8 Overlay/action in plain lists
3 Editing support with org-beamer-mode
     3.1 Tracking of the BEAMER_env property with tags
     3.2 Fast tag selection for beamer environments
     3.3 Column view
4 Open issues
5 Example

1 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 should at least define
a format for column view that will make it easy to change properties
that will be interpreted by beamer export.

1.1 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) %10BEAMER_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) %10BEAMER_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 themes.

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.

2 Organization
~~~~~~~~~~~~~~~

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

2.1 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, of 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.

2.2 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'.

2.2.1 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.

2.3 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.

2.4 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.

2.5 Columns
============

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

2.5.1 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 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.

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 disadvantage is that you cannot close the columns
environment and insert more text below it on the same frame.

2.5.2 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'.  If it is not just a number, it will be
   assumed that you have specified the unit yourself (e.g. "5cm").

2.6 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.

2.7 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.

2.8 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.

3 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

3.1 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'.

3.2 Fast tag selection for beamer environments
===============================================

The command `C-c C-b' will offer fast selection interface for the
various beamer environments.

3.3 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.

4 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?

5 Example
~~~~~~~~~~

Here is a (still very incomplete) example Org document that is
intended for beamer export.  It looks a bit complicated here
because all the property drawers are open.  In Org-mode,
and in particular in column mode, it looks a lot better.

   #+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: %30ITEM %8BEAMER_env(Env) %7BEAMER_opt(Options)  
%6BEAMER_dovl(DefOvl) %7BEAMER_ovl(Overlay) %4BEAMER_col(Col)
   #+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_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
   ***  
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!

^ permalink raw reply	[flat|nested] 22+ messages in thread