366dc404307667eedbe91d351e3761e2993ea82c
[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:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t
7 #+OPTIONS:   TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
8 #+STARTUP:   folded
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=.
37 #+begin_src emacs-lisp :eval no
38   (require 'ox-latex)
39   (add-to-list 'org-latex-classes
40                '("beamer"
41                  "\\documentclass\[presentation\]\{beamer\}"
42                  ("\\section\{%s\}" . "\\section*\{%s\}")
43                  ("\\subsection\{%s\}" . "\\subsection*\{%s\}")
44                  ("\\subsubsection\{%s\}" . "\\subsubsection*\{%s\}")))
45 #+end_src
46 The first string ~beamer~ in =org-latex-classes= is by no means
47 unique, it can be substituted for any convenient name you wish.  This
48 name however should be the argument to the =LaTeX_CLASS= file header
49 option (or =EXPORT_LaTeX_CLASS= subtree property).
50
51 * Configuring export options
52   :PROPERTIES:
53   :CUSTOM_ID: config
54   :END:
55
56 Apart from the usual export options provided by the =OPTIONS= keyword,
57 you can put additional beamer export options in the file header.  For
58 a minimal beamer export, you have to specify the =LaTeX_CLASS= and the
59 =LaTeX_CLASS_OPTIONS= keywords in the header of a file.  A preset
60 export template can be inserted by calling the interactive function
61 =org-beamer-insert-options-template=.  This can be further modified as
62 per your needs.  You can also do a subtree export; in that case you
63 can provide the keywords as subtree =PROPERTIES=.  However take note
64 that the keyword names should be prepended with =EXPORT_=.  A list of
65 supported keywords are,
66
67 #+caption: Export option keywords and corresponding subtree properties.
68 | File header keywords  | Subtree properties           |
69 |-----------------------+------------------------------|
70 | =OPTIONS=             | =EXPORT_OPTIONS=             |
71 | =LaTeX_CLASS=         | =EXPORT_LaTeX_CLASS=         |
72 | =LaTeX_CLASS_OPTIONS= | =EXPORT_LaTeX_CLASS_OPTIONS= |
73 | =LaTeX_HEADER=        | =EXPORT_LaTeX_HEADER=        |
74 | =BEAMER_THEME=        | =EXPORT_BEAMER_THEME=        |
75 | =BEAMER_FONT_THEME=   | =EXPORT_BEAMER_FONT_THEME=   |
76 | =BEAMER_INNER_THEME=  | =EXPORT_BEAMER_INNER_THEME=  |
77 | =BEAMER_OUTER_THEME=  | =EXPORT_BEAMER_OUTER_THEME=  |
78
79 For a subtree export, a few extra keywords are supported.  For example
80 you can specify the exported filename with the =EXPORT_FILE_NAME=
81 property.
82
83 #+caption: Properties specific to subtree export
84 | Subtree properties | Functionality    |
85 |--------------------+------------------|
86 | =EXPORT_TITLE=     | Export title     |
87 | =EXPORT_AUTHOR=    | Export author    |
88 | =EXPORT_DATE=      | Export date      |
89 | =EXPORT_FILE_NAME= | Export file name |
90
91 ** A simple example
92    :PROPERTIES:
93    :CUSTOM_ID: simple-example
94    :END:
95
96 A simple file header might look like the example below.
97 #+begin_example
98   ,#+LaTeX_CLASS: beamer
99   ,#+LaTeX_CLASS_OPTIONS: [presentation,smaller]
100   ,#+BEAMER_THEME: default
101 #+end_example
102 A corresponding subtree export should have properties as shown below.
103 #+begin_example
104   ,* Exported title
105     :PROPERTIES:
106     :EXPORT_LaTeX_CLASS: beamer
107     :EXPORT_LaTeX_CLASS_OPTIONS: [presentation,smaller]
108     :EXPORT_BEAMER_THEME: default
109     :EXPORT_FILE_NAME: presentation.pdf
110     :END:
111 #+end_example
112
113 The export class, as defined in =org-latex-classes=, determines the
114 =documentclass=, and the class options are passed on as optional
115 arguments (note the presence of square brackets).
116 : \documentclass[smaller,presentation]{beamer}
117
118 ** Configuring frame export level
119    :PROPERTIES:
120    :CUSTOM_ID: frame-level
121    :END:
122 The new exporter allows the grouping slides into LaTeX sections.  The
123 sectioning behaviour is controlled by =org-latex-classes=, where as
124 heading levels to be exported as frames are controlled by the =H:n=
125 option to the =OPTIONS= keyword (=EXPORT_OPTIONS= property for subtree
126 export).  The ~n~ here is the headline level number that you want to
127 export as frames.  To elaborate with an example, to export third level
128 headlines as frames, use =#+OPTIONS: H:3= in the file header.  This
129 behaviour can be overridden per headline by setting the =BEAMER_env=
130 property to =frame=.  You can also provide options to a frame by
131 setting the =BEAMER_opt= property on the headline.  This also adds the
132 =fragile= option to the frame.
133
134 ** Use of filters to customise export
135    :PROPERTIES:
136    :CUSTOM_ID: export-filters
137    :END:
138 =ox= also gives you access to all =org-element= entities in the
139 exported text for customisation with user filters.  Filters are
140 essentially simple lisp functions that reformat the exported elements.
141 As a simple example; the =ox-beamer= translates *bold text* as
142 =\alert{bold text}=.  To revert this back to the old behaviour, you
143 can you a filter like this:
144 #+begin_src emacs-lisp :eval no
145   (defun my-beamer-bold (contents backend info)
146     (when (eq backend 'beamer)
147       (replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\textbf" contents)))
148
149   (add-to-list 'org-export-filter-bold-functions 'my-beamer-bold)
150 #+end_src
151 Another example would be to translate +strike through text+ to
152 =\structure{strike through text}= with the following filter.
153 #+begin_src emacs-lisp :eval no
154   (defun my-beamer-structure (contents backend info)
155     (when (eq backend 'beamer)
156       (replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\structure" contents)))
157
158   (add-to-list 'org-export-filter-strike-through-functions 'my-beamer-structure)
159 #+end_src
160
161 * Structure editing, environments and markup
162   :PROPERTIES:
163   :CUSTOM_ID: editing-environments-markup
164   :END:
165 All the usual Org mode structure editing commands work.  The minor
166 mode =org-beamer-mode= is also provided to make it convenient to
167 insert Beamer specific environments in an org-mode buffer.
168
169 A notable change in =ox-beamer= with regards to markup is, *bold text*
170 is translated as =\alert{bold text}= by default.
171
172 ** Block environments and overlay specifications
173    :PROPERTIES:
174    :CUSTOM_ID: environments-overlay
175    :END:
176
177 All headlines below the =org-beamer-frame-level= (i.e. below =H= value
178 in =OPTIONS=), are exported as blocks with =ox-beamer=.  You can
179 choose special block environments by setting the =BEAMER_env= property
180 on the headline.  Supported blocks are listed in
181 =org-beamer-environments-default=.  To specify an overlay
182 specification for a frame or block environment, set the =BEAMER_act=
183 property.  If the value is enclosed in square brackets, it is
184 interpreted as a default overlay specification.
185 #+begin_example
186   ,* A theorem block
187     :PROPERTIES:
188     :BEAMER_env: theorem
189     :BEAMER_act: <2->
190     :END:
191
192   The =BEAMER_act= property says to overlay this environment from the
193   second frame onwards.
194 #+end_example
195
196 You can add your own environments by customising the
197 =org-beamer-environments-extra= variable.  For example the snippet
198 below adds support for =only= environment and associates to the letter
199 ~O~.
200 #+begin_src emacs-lisp :eval no
201   (add-to-list 'org-beamer-environments-extra
202                '("onlyenv" "O" "\\begin{onlyenv}%a" "\\end{onlyenv}"))
203 #+end_src
204
205 ** Special enviroments
206   :PROPERTIES:
207   :CUSTOM_ID: special-environments
208   :END:
209
210 Environments can be put in a column by setting the =BEAMER_col=
211 property on a headline.  It accepts decimal point numbers which is
212 interpreted as a fraction of the text width.  If the beadline does not
213 have an enviroment the headline text is ignored and all the contents
214 are put inside the column environment.
215 #+begin_example
216   ,* A block in a column
217     :PROPERTIES:
218     :BEAMER_env: block
219     :BEAMER_col: 0.5
220     :END:
221
222   ,* Just a column with contents
223     :PROPERTIES:
224     :BEAMER_col: 0.5
225     :END:
226   Some text, the headline above is ignored
227 #+end_example
228
229 You can start an appendix by setting the =BEAMER_env= property to
230 =appendix= on a headline.  Similarly you can insert notes by setting
231 the property to =note= (use =noteNH= to exclude the headline from the
232 note).  You can also use Beamer's =againframe= command by setting the
233 same property.  The frame being refered to by =againframe= is
234 specified by the =BEAMER_ref= property.  You can also ignore a
235 headline by using =ignoreheading=.  This can also be used to close a
236 =column= environment.
237
238 All contiguous environments are automatically wrapped in a =columns=
239 environment, although it can be forced at any point by setting the
240 =BEAMER_env= property to =columns=.  This might be handy if you want
241 to pass special options.
242
243 * New features available with the new exporter
244   :PROPERTIES:
245   :CUSTOM_ID: new-features
246   :END:
247
248 ** TODO Beamer article
249 Discuss that =EXPORT_LaTeX_CLASS= need not be beamer.  Useful to
250 export =beamerarticle= document for slides.
251
252 Email from Nicolas Goaziou discussing this feature:
253 http://mid.gmane.org/87hapz3na9.fsf@gmail.com
254
255 ** TODO Overlays
256 - [[*Block%20environments%20and%20overlay%20specifications][Overlay specifications for frames and blocks]]
257
258 ** TODO Snippet translation
259
260 ** TODO Ordered and unordered lists
261
262 ** TODO Images
263
264 ** TODO Tables
265
266 ** TODO Source blocks
267
268 ** DONE Environments
269
270 * TODO Examples
271   :PROPERTIES:
272   :CUSTOM_ID: examples
273   :END:
274
275 1) [ ] Sectioning and TOC (progress state between sections)
276 2) [ ] Overlays
277 3) [ ] Blocks
278    1. [ ] Normal blocks
279    2. [ ] Verbatim blocks
280    3. [ ] Source blocks
281 4) [X] Columns
282 5) [ ] Text / LaTeX commands in between frames
283 6) [ ] Images
284    + Centering
285    + Captions
286 7) [ ] Footnotes and references
287 8) [X] Backup slides with =\appendix=
288 9) [ ] Caveats about using alternate TeX binaries
289
290 * TODO Migrating from the old to the new exporter
291   :PROPERTIES:
292   :CUSTOM_ID: migration
293   :END:
294
295 - Backwards incompatible changes in the new exporter
296 - Configuration:
297   1. variable name changes,
298   2. filters instead of hooks (except for two)