3cdd06001171c296551990f9ee797e1b3d65be69
[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 * New features available with the new exporter
252   :PROPERTIES:
253   :CUSTOM_ID: new-features
254   :END:
255
256 ** TODO Beamer article
257 Discuss that =EXPORT_LaTeX_CLASS= need not be beamer.  Useful to
258 export =beamerarticle= document for slides.
259
260 Email from Nicolas Goaziou discussing this feature:
261 http://mid.gmane.org/87hapz3na9.fsf@gmail.com
262
263 ** TODO Overlays
264 - [[#environments-overlay][Overlay specifications for frames and blocks]]
265
266 ** TODO Snippet translation
267
268 ** TODO Ordered and unordered lists
269
270 ** TODO Images
271
272 ** TODO Tables
273
274 ** TODO Source blocks
275
276 ** DONE Environments
277
278 * TODO Examples
279   :PROPERTIES:
280   :CUSTOM_ID: examples
281   :END:
282
283 1) [ ] Sectioning and TOC (progress state between sections)
284 2) [ ] Overlays
285 3) [ ] Blocks
286    1. [ ] Normal blocks
287    2. [ ] Verbatim blocks
288    3. [ ] Source blocks
289 4) [X] Columns
290 5) [ ] Text / LaTeX commands in between frames
291 6) [ ] Images
292    + Centering
293    + Captions
294 7) [ ] Footnotes and references
295 8) [X] Backup slides with =\appendix=
296 9) [ ] Caveats about using alternate TeX binaries
297
298 * TODO Migrating from the old to the new exporter
299   :PROPERTIES:
300   :CUSTOM_ID: migration
301   :END:
302
303 - Backwards incompatible changes in the new exporter
304 - Configuration:
305   1. variable name changes,
306   2. filters instead of hooks (except for two)