This tutorial covers exporting org documents to LaTeX Beamer slides
using the new export engine, org-elements and ox (short for
org-export), written by Nicolas Goaziou.
Note: It will not cover any of the basic features common with the old beamer exporter; it will only focus on the improvements, new additions and backwards incompatibilities. It is also assumed that the reader is already acquainted with GNU Emacs and Org mode itself. Basic understanding of LaTeX and the Beamer package is also assumed.
Unlike the old exporter, requiring the beamer exporter is not enough
to export to beamer slides with ox. This difference arises from a
new feature in ox-beamer that allows, in the author’s words, a
beamer translation of any Org document. This is extremely useful
when creating handouts or article versions of your slides by loading
the beamerarticle package (see the beamer user guide for specifics).
You can use the following minimal setup to start exporting to the
beamer documentclass. As of the latest Org mode version (8.0.3),
this setup is not necessary anymore. If you want to customise this
variable, you should do it before loading ox-beamer.
(require 'ox-latex)
(add-to-list 'org-latex-classes
'("beamer"
"\\documentclass\[presentation\]\{beamer\}"
("\\section\{%s\}" . "\\section*\{%s\}")
("\\subsection\{%s\}" . "\\subsection*\{%s\}")
("\\subsubsection\{%s\}" . "\\subsubsection*\{%s\}")))The first string beamer in org-latex-classes is by no means
unique, it can be substituted for any convenient name you wish. This
name however should be the argument to the LaTeX_CLASS file header
option (or EXPORT_LaTeX_CLASS subtree property).
Eric recently updated the old example presentation for beamer export
to work with ox-beamer. You can take a look at that to get started.
Apart from the usual export options provided by the OPTIONS keyword,
you can put additional beamer export options in the file header. For
a minimal beamer export, you have to specify the LaTeX_CLASS and the
LaTeX_CLASS_OPTIONS keywords in the header of a file. A preset
export template can be inserted by calling the interactive function
org-beamer-insert-options-template. This can be further modified as
per your needs. You can also do a subtree export; in that case you
can provide the keywords as subtree PROPERTIES. However take note
that the keyword names should be prepended with EXPORT_. A list of
supported keywords are,
| File header keywords | Subtree properties |
|---|---|
OPTIONS | EXPORT_OPTIONS |
LaTeX_CLASS | EXPORT_LaTeX_CLASS |
LaTeX_CLASS_OPTIONS | EXPORT_LaTeX_CLASS_OPTIONS |
LaTeX_HEADER | EXPORT_LaTeX_HEADER |
BEAMER_THEME | EXPORT_BEAMER_THEME |
BEAMER_COLOR_THEME | EXPORT_BEAMER_COLOR_THEME |
BEAMER_FONT_THEME | EXPORT_BEAMER_FONT_THEME |
BEAMER_INNER_THEME | EXPORT_BEAMER_INNER_THEME |
BEAMER_OUTER_THEME | EXPORT_BEAMER_OUTER_THEME |
BEAMER_HEADER |
For a subtree export, a few extra keywords are supported. For example
you can specify the exported filename with the EXPORT_FILE_NAME
property.
| Subtree properties | Functionality |
|---|---|
EXPORT_TITLE | Export title |
EXPORT_AUTHOR | Export author |
EXPORT_DATE | Export date |
EXPORT_FILE_NAME | Export file name |
A simple file header might look like the example below.
#+LaTeX_CLASS: beamer #+LaTeX_CLASS_OPTIONS: [presentation,smaller] #+BEAMER_THEME: default
A corresponding subtree export should have properties as shown below.
* Exported title :PROPERTIES: :EXPORT_LaTeX_CLASS: beamer :EXPORT_LaTeX_CLASS_OPTIONS: [presentation,smaller] :EXPORT_BEAMER_THEME: default :EXPORT_FILE_NAME: presentation.pdf :END:
The export class, as defined in org-latex-classes, determines the
documentclass, and the class options are passed on as optional
arguments (note the presence of square brackets).
\documentclass[smaller,presentation]{beamer}
The new exporter allows the grouping slides into LaTeX sections. The
sectioning behaviour is controlled by org-latex-classes, where as
heading levels to be exported as frames are controlled by the H:n
option to the OPTIONS keyword (EXPORT_OPTIONS property for subtree
export). The n here is the headline level number that you want to
export as frames. To elaborate with an example, to export third level
headlines as frames, use #+OPTIONS: H:3 in the file header. This
behaviour can be overridden per headline by setting the BEAMER_env
property to frame. You can also provide options to a frame by
setting the BEAMER_opt property on the headline. This also adds the
fragile option to the frame.
ox also gives you access to all org-element entities in the
exported text for customisation with user filters. Filters are
essentially simple lisp functions that reformat the exported elements.
As a simple example; the ox-beamer translates bold text as
\alert{bold text}. To revert this back to the old behaviour, you
can you a filter like this:
(defun my-beamer-bold (contents backend info)
(when (eq backend 'beamer)
(replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\textbf" contents)))
(add-to-list 'org-export-filter-bold-functions 'my-beamer-bold)Another example would be to translate strike through text to
\structure{strike through text} with the following filter.
(defun my-beamer-structure (contents backend info)
(when (eq backend 'beamer)
(replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\structure" contents)))
(add-to-list 'org-export-filter-strike-through-functions 'my-beamer-structure)All the usual Org mode structure editing commands work. The minor
mode org-beamer-mode is also provided to make it convenient to
insert Beamer specific environments in an Org mode buffer.
A notable change in ox-beamer with regards to markup is, bold text
is translated as \alert{bold text} by default.
All headlines below the org-beamer-frame-level (i.e. below H value
in OPTIONS), are exported as blocks with ox-beamer. You can
choose special block environments by setting the BEAMER_env property
on the headline. Supported blocks are listed in
org-beamer-environments-default. To specify an overlay
specification for a frame or block environment, set the BEAMER_act
property. If the value is enclosed in square brackets, it is
interpreted as a default overlay specification.
* A theorem block :PROPERTIES: :BEAMER_env: theorem :BEAMER_act: <2-> :END: The =BEAMER_act= property says to overlay this environment from the second frame onwards.
You can add your own environments by customising the
org-beamer-environments-extra variable. For example the snippet
below adds support for only environment and associates to the letter
O.
(add-to-list 'org-beamer-environments-extra
'("onlyenv" "O" "\\begin{onlyenv}%a" "\\end{onlyenv}"))Environments can be put in a column by setting the BEAMER_col
property on a headline. It accepts decimal point numbers which is
interpreted as a fraction of the text width. If the headline does not
have an environment the headline text is ignored and all the contents
are put inside the column environment.
* A block in a column :PROPERTIES: :BEAMER_env: block :BEAMER_col: 0.5 :END: * Just a column with contents :PROPERTIES: :BEAMER_col: 0.5 :END: Some text, the headline above is ignored
You can start an appendix by setting the BEAMER_env property to
appendix on a headline. Similarly you can insert notes by setting
the property to note (use noteNH to exclude the headline from the
note). You can also use Beamer’s againframe command by setting the
same property. The frame being referred to by againframe is
specified by the BEAMER_ref property. You can also ignore a
headline by using ignoreheading. This can also be used to close a
column environment.
All contiguous environments are automatically wrapped in a columns
environment, although it can be forced at any point by setting the
BEAMER_env property to columns. This might be handy if you want
to pass special options.
Many configuration variables have been renamed, some might even have slightly different meanings. For a summary of these changes take a look at the following entries:
If there is information missing from the above entries, please do not hesitate to report on the Org mode mailing list.
Besides configuration variables, the earlier version allowed more generic configuration of export using hooks. This has been replaced by export filters. There is a nice article on how you could explore available filters by Charles Berry. A few simple examples were also shown above.
That said, two old-style hooks are still available:
org-export-before-parsing-hook, and
org-export-before-processing-hook. Take a look at their
documentation strings for more details.
The new exporter has a few backwards incompatible changes. The most
visible change is the export behaviour of headlines deeper than the
exported headline level. You can configure the headline levels that
are exported with the #+OPTIONS: H:n line (as explained earlier).
If there are any headlines deeper than n, they are exported as
blocks during beamer export. For the old exporter, these were
exported as unordered lists. This thread from the mailing list
archive has some discussion on how to deal with this change. If you
have anything to add to that discussion, please share on the mailing
list.
Show some non-trivial hacks that can be used to achieve customised output. Often one needs to do these when trying to work with beamer specific features like overlay. One example: http://mid.gmane.org/[email protected]
Discuss that EXPORT_LaTeX_CLASS need not be beamer. Useful to
export beamerarticle document for slides.
Email from Nicolas Goaziou discussing this feature: http://mid.gmane.org/[email protected]
- [ ] Sectioning and TOC (progress state between sections)
- [ ] Overlays
- [ ] Blocks
- [ ] Normal blocks
- [ ] Verbatim blocks
- [ ] Source blocks
- [X] Columns
- [ ] Text / LaTeX commands in between frames
- [ ] Images
- Centering
- Captions
- [ ] Footnotes and references
- [X] Backup slides with
\appendix - [ ] Caveats about using alternate TeX binaries