From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Beamer support - 2nd round Date: Thu, 3 Dec 2009 17:10:44 +0100 Message-ID: Mime-Version: 1.0 (Apple Message framework v936) Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NGEGd-0000iO-9P for emacs-orgmode@gnu.org; Thu, 03 Dec 2009 11:10:55 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NGEGY-0000cK-EE for emacs-orgmode@gnu.org; Thu, 03 Dec 2009 11:10:54 -0500 Received: from [199.232.76.173] (port=45869 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NGEGY-0000cC-97 for emacs-orgmode@gnu.org; Thu, 03 Dec 2009 11:10:50 -0500 Received: from mail-bw0-f215.google.com ([209.85.218.215]:42011) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NGEGX-0005wU-6G for emacs-orgmode@gnu.org; Thu, 03 Dec 2009 11:10:50 -0500 Received: by bwz7 with SMTP id 7so1324835bwz.26 for ; Thu, 03 Dec 2009 08:10:48 -0800 (PST) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org 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 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!