Info on incompatibilites with old beamer export
[worg.git] / exporters / beamer / ox-beamer.org
1 #+TITLE:     Beamer presentations using the new export engine
2 #+AUTHOR:    Suvayu Ali
3 #+EMAIL:     fatkasuvayu+linux at gmail dot com
4 #+DATE:      2013-02-05
5 #+LANGUAGE:  en
6 #+OPTIONS:   H:2 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t
7 #+OPTIONS:   tex:t d:(HIDE) tags:not-in-toc
8 #+STARTUP:   fold
9 #+CATEGORY:   worg
10
11
12 * Introduction
13 This tutorial covers exporting org documents to LaTeX Beamer slides
14 using the new export engine, =org-elements= and =ox= (short for
15 org-export), written by Nicolas Goaziou.
16
17 _Note:_ It will not cover any of the basic features common with the
18 old beamer exporter; it will only focus on the improvements, new
19 additions and backwards incompatibilities.  It is also assumed that
20 the reader is already acquainted with GNU Emacs and Org mode itself.
21 Basic understanding of LaTeX and the Beamer package is also assumed.
22
23 ** Initial setup
24    :PROPERTIES:
25    :CUSTOM_ID: setup
26    :END:
27
28 Unlike the old exporter, requiring the beamer exporter is not enough
29 to export to beamer slides with =ox=.  This difference arises from a
30 new feature in =ox-beamer= that allows, in the author's words, a
31 beamer translation of *any* org document.  This is extremely useful
32 when creating handouts or article versions of your slides by loading
33 the =beamerarticle= package (see the [[http://www.tex.ac.uk/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf][beamer user guide]] for specifics).
34
35 You can use the following minimal setup to start exporting to the
36 beamer =documentclass=.  As of the latest Org mode version (8.0.3),
37 this setup is not necessary anymore.  If you want to customise this
38 variable, you should do it before loading =ox-beamer=.
39 #+begin_src emacs-lisp :eval no
40   (require 'ox-latex)
41   (add-to-list 'org-latex-classes
42                '("beamer"
43                  "\\documentclass\[presentation\]\{beamer\}"
44                  ("\\section\{%s\}" . "\\section*\{%s\}")
45                  ("\\subsection\{%s\}" . "\\subsection*\{%s\}")
46                  ("\\subsubsection\{%s\}" . "\\subsubsection*\{%s\}")))
47 #+end_src
48 The first string ~beamer~ in =org-latex-classes= is by no means
49 unique, it can be substituted for any convenient name you wish.  This
50 name however should be the argument to the =LaTeX_CLASS= file header
51 option (or =EXPORT_LaTeX_CLASS= subtree property).
52
53 Eric recently updated the [[file:presentation.org][old example presentation]] for beamer export
54 to work with =ox-beamer=.  You can take a look at that to get started.
55
56 * Configuring export options
57   :PROPERTIES:
58   :CUSTOM_ID: config
59   :END:
60
61 Apart from the usual export options provided by the =OPTIONS= keyword,
62 you can put additional beamer export options in the file header.  For
63 a minimal beamer export, you have to specify the =LaTeX_CLASS= and the
64 =LaTeX_CLASS_OPTIONS= keywords in the header of a file.  A preset
65 export template can be inserted by calling the interactive function
66 =org-beamer-insert-options-template=.  This can be further modified as
67 per your needs.  You can also do a subtree export; in that case you
68 can provide the keywords as subtree =PROPERTIES=.  However take note
69 that the keyword names should be prepended with =EXPORT_=.  A list of
70 supported keywords are,
71
72 #+caption: Export option keywords and corresponding subtree properties.
73 | File header keywords  | Subtree properties           |
74 |-----------------------+------------------------------|
75 | =OPTIONS=             | =EXPORT_OPTIONS=             |
76 | =LaTeX_CLASS=         | =EXPORT_LaTeX_CLASS=         |
77 | =LaTeX_CLASS_OPTIONS= | =EXPORT_LaTeX_CLASS_OPTIONS= |
78 | =LaTeX_HEADER=        | =EXPORT_LaTeX_HEADER=        |
79 | =BEAMER_THEME=        | =EXPORT_BEAMER_THEME=        |
80 | =BEAMER_COLOR_THEME=  | =EXPORT_BEAMER_COLOR_THEME=  |
81 | =BEAMER_FONT_THEME=   | =EXPORT_BEAMER_FONT_THEME=   |
82 | =BEAMER_INNER_THEME=  | =EXPORT_BEAMER_INNER_THEME=  |
83 | =BEAMER_OUTER_THEME=  | =EXPORT_BEAMER_OUTER_THEME=  |
84 | =BEAMER_HEADER=       |                              |
85
86 For a subtree export, a few extra keywords are supported.  For example
87 you can specify the exported filename with the =EXPORT_FILE_NAME=
88 property.
89
90 #+caption: Properties specific to subtree export
91 | Subtree properties | Functionality    |
92 |--------------------+------------------|
93 | =EXPORT_TITLE=     | Export title     |
94 | =EXPORT_AUTHOR=    | Export author    |
95 | =EXPORT_DATE=      | Export date      |
96 | =EXPORT_FILE_NAME= | Export file name |
97
98 ** A simple example
99    :PROPERTIES:
100    :CUSTOM_ID: simple-example
101    :END:
102
103 A simple file header might look like the example below.
104 #+begin_example
105   ,#+LaTeX_CLASS: beamer
106   ,#+LaTeX_CLASS_OPTIONS: [presentation,smaller]
107   ,#+BEAMER_THEME: default
108 #+end_example
109 A corresponding subtree export should have properties as shown below.
110 #+begin_example
111   ,* Exported title
112     :PROPERTIES:
113     :EXPORT_LaTeX_CLASS: beamer
114     :EXPORT_LaTeX_CLASS_OPTIONS: [presentation,smaller]
115     :EXPORT_BEAMER_THEME: default
116     :EXPORT_FILE_NAME: presentation.pdf
117     :END:
118 #+end_example
119
120 The export class, as defined in =org-latex-classes=, determines the
121 =documentclass=, and the class options are passed on as optional
122 arguments (note the presence of square brackets).
123 : \documentclass[smaller,presentation]{beamer}
124
125 ** Configuring frame export level
126    :PROPERTIES:
127    :CUSTOM_ID: frame-level
128    :END:
129 The new exporter allows the grouping slides into LaTeX sections.  The
130 sectioning behaviour is controlled by =org-latex-classes=, where as
131 heading levels to be exported as frames are controlled by the =H:n=
132 option to the =OPTIONS= keyword (=EXPORT_OPTIONS= property for subtree
133 export).  The ~n~ here is the headline level number that you want to
134 export as frames.  To elaborate with an example, to export third level
135 headlines as frames, use =#+OPTIONS: H:3= in the file header.  This
136 behaviour can be overridden per headline by setting the =BEAMER_env=
137 property to =frame=.  You can also provide options to a frame by
138 setting the =BEAMER_opt= property on the headline.  This also adds the
139 =fragile= option to the frame.
140
141 ** Use of filters to customise export
142    :PROPERTIES:
143    :CUSTOM_ID: export-filters
144    :END:
145 =ox= also gives you access to all =org-element= entities in the
146 exported text for customisation with user filters.  Filters are
147 essentially simple lisp functions that reformat the exported elements.
148 As a simple example; the =ox-beamer= translates *bold text* as
149 =\alert{bold text}=.  To revert this back to the old behaviour, you
150 can you a filter like this:
151 #+begin_src emacs-lisp :eval no
152   (defun my-beamer-bold (contents backend info)
153     (when (eq backend 'beamer)
154       (replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\textbf" contents)))
155
156   (add-to-list 'org-export-filter-bold-functions 'my-beamer-bold)
157 #+end_src
158 Another example would be to translate +strike through text+ to
159 =\structure{strike through text}= with the following filter.
160 #+begin_src emacs-lisp :eval no
161   (defun my-beamer-structure (contents backend info)
162     (when (eq backend 'beamer)
163       (replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\structure" contents)))
164
165   (add-to-list 'org-export-filter-strike-through-functions 'my-beamer-structure)
166 #+end_src
167
168 * Structure editing, environments and markup
169   :PROPERTIES:
170   :CUSTOM_ID: editing-environments-markup
171   :END:
172
173 All the usual Org mode structure editing commands work.  The minor
174 mode =org-beamer-mode= is also provided to make it convenient to
175 insert Beamer specific environments in an org-mode buffer.
176
177 A notable change in =ox-beamer= with regards to markup is, *bold text*
178 is translated as =\alert{bold text}= by default.
179
180 ** Block environments and overlay specifications
181    :PROPERTIES:
182    :CUSTOM_ID: environments-overlay
183    :END:
184
185 All headlines below the =org-beamer-frame-level= (i.e. below =H= value
186 in =OPTIONS=), are exported as blocks with =ox-beamer=.  You can
187 choose special block environments by setting the =BEAMER_env= property
188 on the headline.  Supported blocks are listed in
189 =org-beamer-environments-default=.  To specify an overlay
190 specification for a frame or block environment, set the =BEAMER_act=
191 property.  If the value is enclosed in square brackets, it is
192 interpreted as a default overlay specification.
193 #+begin_example
194   ,* A theorem block
195     :PROPERTIES:
196     :BEAMER_env: theorem
197     :BEAMER_act: <2->
198     :END:
199
200   The =BEAMER_act= property says to overlay this environment from the
201   second frame onwards.
202 #+end_example
203
204 You can add your own environments by customising the
205 =org-beamer-environments-extra= variable.  For example the snippet
206 below adds support for =only= environment and associates to the letter
207 ~O~.
208 #+begin_src emacs-lisp :eval no
209   (add-to-list 'org-beamer-environments-extra
210                '("onlyenv" "O" "\\begin{onlyenv}%a" "\\end{onlyenv}"))
211 #+end_src
212
213 ** Special enviroments
214   :PROPERTIES:
215   :CUSTOM_ID: special-environments
216   :END:
217
218 Environments can be put in a column by setting the =BEAMER_col=
219 property on a headline.  It accepts decimal point numbers which is
220 interpreted as a fraction of the text width.  If the beadline does not
221 have an enviroment the headline text is ignored and all the contents
222 are put inside the column environment.
223 #+begin_example
224   ,* A block in a column
225     :PROPERTIES:
226     :BEAMER_env: block
227     :BEAMER_col: 0.5
228     :END:
229
230   ,* Just a column with contents
231     :PROPERTIES:
232     :BEAMER_col: 0.5
233     :END:
234   Some text, the headline above is ignored
235 #+end_example
236
237 You can start an appendix by setting the =BEAMER_env= property to
238 =appendix= on a headline.  Similarly you can insert notes by setting
239 the property to =note= (use =noteNH= to exclude the headline from the
240 note).  You can also use Beamer's =againframe= command by setting the
241 same property.  The frame being refered to by =againframe= is
242 specified by the =BEAMER_ref= property.  You can also ignore a
243 headline by using =ignoreheading=.  This can also be used to close a
244 =column= environment.
245
246 All contiguous environments are automatically wrapped in a =columns=
247 environment, although it can be forced at any point by setting the
248 =BEAMER_env= property to =columns=.  This might be handy if you want
249 to pass special options.
250
251 * Migrating from the old to the new exporter
252   :PROPERTIES:
253   :CUSTOM_ID: migration
254   :END:
255
256 ** Configuration
257 Many configuration variables have been renamed, some might even have
258 slightly different meanings.  For a summary of these changes take a
259 look at the following entries:
260 - [[file:~/org/Worg/org-8.0.org::*Updating%20global%20export%20configuration%20options][Global export configuration options]]
261 - [[file:~/org/Worg/org-8.0.org::*Backend-specific%20configuration%20options][Backend-specific configuration options]]
262 If there is information missing from the above entries, please do not
263 hesitate to report on the Org mode mailing list.
264
265 Besides configuration variables, the earlier version allowed more
266 generic configuration of export using hooks.  This has been replaced
267 by export filters.  There is a nice [[file:~/org/Worg/exporters/filter-markup.org][article]] on how you could explore
268 available filters by Charles Berry.  A few simple examples were also
269 shown above.
270
271 That said, two old-style hooks are still available:
272 =org-export-before-parsing-hook=, and
273 =org-export-before-processing-hook=.  Take a look at their
274 documentation strings for more details.
275
276 ** Backwards incompatible changes
277    :PROPERTIES:
278    :CUSTOM_ID: backwards-compatibility
279    :END:
280 The new exporter has a few backwards incompatible changes.  The most
281 visible change is the export behaviour of headlines deeper than the
282 exported headline level.  You can configure the headline levels that
283 are exported with the =#+OPTIONS:= line ~H:n~ (as explained [[#frame-level][earlier]]).
284 If there are any headlines deeper than ~n~, they are exported as
285 blocks during beamer export.  For the old exporter, these were
286 exported as unordered lists.  [[http://thread.gmane.org/gmane.emacs.orgmode/76446][This thread]] from the mailing list
287 archive has some discussion on how to deal with this change.  If you
288 have anything to add to that discussion, please share on the mailing
289 list.
290
291 * New features available with the new exporter
292   :PROPERTIES:
293   :CUSTOM_ID: new-features
294   :END:
295
296 ** TODO Beamer article
297 Discuss that =EXPORT_LaTeX_CLASS= need not be beamer.  Useful to
298 export =beamerarticle= document for slides.
299
300 Email from Nicolas Goaziou discussing this feature:
301 http://mid.gmane.org/87hapz3na9.fsf@gmail.com
302
303 ** TODO Overlays
304 - [[#environments-overlay][Overlay specifications for frames and blocks]]
305
306 ** TODO Snippet translation
307
308 ** TODO Ordered and unordered lists
309
310 ** TODO Images
311
312 ** TODO Tables
313
314 ** TODO Source blocks
315
316 ** DONE Environments
317
318 * TODO Examples
319   :PROPERTIES:
320   :CUSTOM_ID: examples
321   :END:
322
323 1) [ ] Sectioning and TOC (progress state between sections)
324 2) [ ] Overlays
325 3) [ ] Blocks
326    1. [ ] Normal blocks
327    2. [ ] Verbatim blocks
328    3. [ ] Source blocks
329 4) [X] Columns
330 5) [ ] Text / LaTeX commands in between frames
331 6) [ ] Images
332    + Centering
333    + Captions
334 7) [ ] Footnotes and references
335 8) [X] Backup slides with =\appendix=
336 9) [ ] Caveats about using alternate TeX binaries