1 ;;; ox-beamer.el --- Beamer Back-End for Org Export Engine
3 ;; Copyright (C) 2007-2013 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten.dominik AT gmail DOT com>
6 ;; Nicolas Goaziou <n.goaziou AT gmail DOT com>
7 ;; Keywords: org, wp, tex
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;; This library implements both a Beamer back-end, derived from the
25 ;; LaTeX one and a minor mode easing structure edition of the
28 ;; Depending on the desired output format, three commands are provided
29 ;; for export: `org-beamer-export-as-latex' (temporary buffer),
30 ;; `org-beamer-export-to-latex' ("tex" file) and
31 ;; `org-beamer-export-to-pdf' ("pdf" file).
33 ;; This back-end supports every buffer keyword, attribute and options
34 ;; items (see `org-latex-options-alist') already supported by `latex'
35 ;; back-end. As such, it is suggested to add an entry in
36 ;; `org-latex-classes' variable which is appropriate for Beamer
39 ;; On top of this, the `beamer' back-end also introduces the following
40 ;; keywords: "BEAMER_THEME", "BEAMER_COLOR_THEME",
41 ;; "BEAMER_FONT_THEME", "BEAMER_INNER_THEME", "BEAMER_OUTER_THEME" and
42 ;; "BEAMER_HEADER". All but the latter accept options in square
45 ;; Moreover, headlines now fall into three categories: sectioning
46 ;; elements, frames and blocks.
48 ;; - Headlines become frames when their level is equal to
49 ;; `org-beamer-frame-level' (or "H" value in the OPTIONS line).
50 ;; Though, if an headline in the current tree has a "BEAMER_env"
51 ;; (see below) property set to either "frame" or "fullframe", its
52 ;; level overrides the variable. A "fullframe" is a frame with an
53 ;; empty (ignored) title.
55 ;; - All frames' children become block environments. Special block
56 ;; types can be enforced by setting headline's "BEAMER_env" property
57 ;; to an appropriate value (see `org-beamer-environments-default'
58 ;; for supported value and `org-beamer-environments-extra' for
61 ;; - As a special case, if the "BEAMER_env" property is set to either
62 ;; "appendix", "note", "noteNH" or "againframe", the headline will
63 ;; become, respectively, an appendix, a note (within frame or
64 ;; between frame, depending on its level), a note with its title
65 ;; ignored or an againframe command. In the latter case,
66 ;; a "BEAMER_ref" property is mandatory in order to refer to the
67 ;; frame being resumed, and contents are ignored.
69 ;; Also, an headline with an "ignoreheading" environment will have
70 ;; its contents only inserted in the output. This special value is
71 ;; useful to have data between frames, or to properly close
72 ;; a "column" environment.
74 ;; Along with "BEAMER_env", headlines also support the "BEAMER_act"
75 ;; and "BEAMER_opt" properties. The former is translated as an
76 ;; overlay/action specification (or a default overlay specification
77 ;; when enclosed within square brackets) whereas the latter specifies
78 ;; options for the current frame ("fragile" option is added
79 ;; automatically, though).
81 ;; Moreover, headlines handle the "BEAMER_col" property. Its value
82 ;; should be a decimal number representing the width of the column as
83 ;; a fraction of the total text width. If the headline has no
84 ;; specific environment, its title will be ignored and its contents
85 ;; will fill the column created. Otherwise, the block will fill the
86 ;; whole column and the title will be preserved. Two contiguous
87 ;; headlines with a non-nil "BEAMER_col" value share the same
88 ;; "columns" LaTeX environment. It will end before the next headline
89 ;; without such a property. This environment is generated
90 ;; automatically. Although, it can also be explicitly created, with
91 ;; a special "columns" value for "BEAMER_env" property (if it needs to
92 ;; be set up with some specific options, for example).
94 ;; Every plain list has support for `:environment', `:overlay' and
95 ;; `:options' attributes (through ATTR_BEAMER affiliated keyword).
96 ;; The first one allows to use a different environment, the second
97 ;; sets overlay specifications and the last one inserts optional
98 ;; arguments in current list environment.
100 ;; Eventually, an export snippet with a value enclosed within angular
101 ;; brackets put at the beginning of an element or object whose type is
102 ;; among `bold', `item', `link', `radio-target' and `target' will
103 ;; control its overlay specifications.
105 ;; On the minor mode side, `org-beamer-select-environment' (bound by
106 ;; default to "C-c C-b") and `org-beamer-insert-options-template' are
107 ;; the two entry points.
111 (eval-when-compile (require 'cl
))
116 ;;; User-Configurable Variables
118 (defgroup org-export-beamer nil
119 "Options specific for using the beamer class in LaTeX export."
124 (defcustom org-beamer-frame-level
1
125 "The level at which headlines become frames.
127 Headlines at a lower level will be translated into a sectioning
128 structure. At a higher level, they will be translated into
131 If an headline with a \"BEAMER_env\" property set to \"frame\" is
132 found within a tree, its level locally overrides this number.
134 This variable has no effect on headlines with the \"BEAMER_env\"
135 property set to either \"ignoreheading\", \"appendix\", or
136 \"note\", which will respectively, be invisible, become an
139 This integer is relative to the minimal level of an headline
140 within the parse tree, defined as 1."
141 :group
'org-export-beamer
144 (defcustom org-beamer-frame-default-options
""
145 "Default options string to use for frames.
146 For example, it could be set to \"allowframebreaks\"."
147 :group
'org-export-beamer
148 :type
'(string :tag
"[options]"))
150 (defcustom org-beamer-column-view-format
151 "%45ITEM %10BEAMER_env(Env) %10BEAMER_act(Act) %4BEAMER_col(Col) %8BEAMER_opt(Opt)"
152 "Column view format that should be used to fill the template."
153 :group
'org-export-beamer
155 (const :tag
"Do not insert Beamer column view format" nil
)
156 (string :tag
"Beamer column view format")))
158 (defcustom org-beamer-theme
"default"
159 "Default theme used in Beamer presentations."
160 :group
'org-export-beamer
162 (const :tag
"Do not insert a Beamer theme" nil
)
163 (string :tag
"Beamer theme")))
165 (defcustom org-beamer-environments-extra nil
166 "Environments triggered by tags in Beamer export.
167 Each entry has 4 elements:
169 name Name of the environment
170 key Selection key for `org-beamer-select-environment'
171 open The opening template for the environment, with the following escapes
172 %a the action/overlay specification
173 %A the default action/overlay specification
174 %o the options argument of the template
176 %H if there is headline text, that text in {} braces
177 %U if there is headline text, that text in [] brackets
178 close The closing string of the environment."
179 :group
'org-export-beamer
182 (string :tag
"Environment")
183 (string :tag
"Selection key")
184 (string :tag
"Begin")
185 (string :tag
"End"))))
187 (defcustom org-beamer-outline-frame-title
"Outline"
188 "Default title of a frame containing an outline."
189 :group
'org-export-beamer
190 :type
'(string :tag
"Outline frame title"))
192 (defcustom org-beamer-outline-frame-options
""
193 "Outline frame options appended after \\begin{frame}.
194 You might want to put e.g. \"allowframebreaks=0.9\" here."
195 :group
'org-export-beamer
196 :type
'(string :tag
"Outline frame options"))
200 ;;; Internal Variables
202 (defconst org-beamer-column-widths
203 "0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 0.0 :ETC"
204 "The column widths that should be installed as allowed property values.")
206 (defconst org-beamer-environments-special
213 ("ignoreheading" "i")
216 "Alist of environments treated in a special way by the back-end.
217 Keys are environment names, as strings, values are bindings used
218 in `org-beamer-select-environment'. Environments listed here,
219 along with their binding, are hard coded and cannot be modified
220 through `org-beamer-environments-extra' variable.")
222 (defconst org-beamer-environments-default
223 '(("block" "b" "\\begin{block}%a{%h}" "\\end{block}")
224 ("alertblock" "a" "\\begin{alertblock}%a{%h}" "\\end{alertblock}")
225 ("verse" "v" "\\begin{verse}%a %% %h" "\\end{verse}")
226 ("quotation" "q" "\\begin{quotation}%a %% %h" "\\end{quotation}")
227 ("quote" "Q" "\\begin{quote}%a %% %h" "\\end{quote}")
228 ("structureenv" "s" "\\begin{structureenv}%a %% %h" "\\end{structureenv}")
229 ("theorem" "t" "\\begin{theorem}%a%U" "\\end{theorem}")
230 ("definition" "d" "\\begin{definition}%a%U" "\\end{definition}")
231 ("example" "e" "\\begin{example}%a%U" "\\end{example}")
232 ("exampleblock" "E" "\\begin{exampleblock}%a{%h}" "\\end{exampleblock}")
233 ("proof" "p" "\\begin{proof}%a%U" "\\end{proof}")
234 ("beamercolorbox" "o" "\\begin{beamercolorbox}%o{%h}" "\\end{beamercolorbox}"))
235 "Environments triggered by properties in Beamer export.
236 These are the defaults - for user definitions, see
237 `org-beamer-environments-extra'.")
239 (defconst org-beamer-verbatim-elements
240 '(code example-block fixed-width inline-src-block src-block verbatim
)
241 "List of element or object types producing verbatim text.
242 This is used internally to determine when a frame should have the
243 \"fragile\" option.")
247 ;;; Internal functions
249 (defun org-beamer--normalize-argument (argument type
)
250 "Return ARGUMENT string with proper boundaries.
252 TYPE is a symbol among the following:
253 `action' Return ARGUMENT within angular brackets.
254 `defaction' Return ARGUMENT within both square and angular brackets.
255 `option' Return ARGUMENT within square brackets."
256 (if (not (string-match "\\S-" argument
)) ""
258 (action (if (string-match "\\`<.*>\\'" argument
) argument
259 (format "<%s>" argument
)))
261 ((string-match "\\`\\[<.*>\\]\\'" argument
) argument
)
262 ((string-match "\\`<.*>\\'" argument
)
263 (format "[%s]" argument
))
264 ((string-match "\\`\\[\\(.*\\)\\]\\'" argument
)
265 (format "[<%s>]" (match-string 1 argument
)))
266 (t (format "[<%s>]" argument
))))
267 (option (if (string-match "\\`\\[.*\\]\\'" argument
) argument
268 (format "[%s]" argument
)))
269 (otherwise argument
))))
271 (defun org-beamer--element-has-overlay-p (element)
272 "Non-nil when ELEMENT has an overlay specified.
273 An element has an overlay specification when it starts with an
274 `beamer' export-snippet whose value is between angular brackets.
275 Return overlay specification, as a string, or nil."
276 (let ((first-object (car (org-element-contents element
))))
277 (when (eq (org-element-type first-object
) 'export-snippet
)
278 (let ((value (org-element-property :value first-object
)))
279 (and (string-match "\\`<.*>\\'" value
) value
)))))
285 (org-export-define-derived-backend beamer latex
286 :export-block
"BEAMER"
289 ((?B
"As LaTeX buffer (Beamer)" org-beamer-export-as-latex
)
290 (?b
"As LaTeX file (Beamer)" org-beamer-export-to-latex
)
291 (?P
"As PDF file (Beamer)" org-beamer-export-to-pdf
)
292 (?O
"As PDF file and open (Beamer)"
294 (if a
(org-beamer-export-to-pdf t s v b
)
295 (org-open-file (org-beamer-export-to-pdf nil s v b
)))))))
297 ((:beamer-theme
"BEAMER_THEME" nil org-beamer-theme
)
298 (:beamer-color-theme
"BEAMER_COLOR_THEME" nil nil t
)
299 (:beamer-font-theme
"BEAMER_FONT_THEME" nil nil t
)
300 (:beamer-inner-theme
"BEAMER_INNER_THEME" nil nil t
)
301 (:beamer-outer-theme
"BEAMER_OUTER_THEME" nil nil t
)
302 (:beamer-header-extra
"BEAMER_HEADER" nil nil newline
)
303 (:headline-levels nil
"H" org-beamer-frame-level
))
304 :translate-alist
((bold . org-beamer-bold
)
305 (export-block . org-beamer-export-block
)
306 (export-snippet . org-beamer-export-snippet
)
307 (headline . org-beamer-headline
)
308 (item . org-beamer-item
)
309 (keyword . org-beamer-keyword
)
310 (link . org-beamer-link
)
311 (plain-list . org-beamer-plain-list
)
312 (radio-target . org-beamer-radio-target
)
313 (target . org-beamer-target
)
314 (template . org-beamer-template
)))
318 ;;; Transcode Functions
322 (defun org-beamer-bold (bold contents info
)
323 "Transcode BLOCK object into Beamer code.
324 CONTENTS is the text being bold. INFO is a plist used as
325 a communication channel."
326 (format "\\alert%s{%s}"
327 (or (org-beamer--element-has-overlay-p bold
) "")
333 (defun org-beamer-export-block (export-block contents info
)
334 "Transcode an EXPORT-BLOCK element into Beamer code.
335 CONTENTS is nil. INFO is a plist used as a communication
337 (when (member (org-element-property :type export-block
) '("BEAMER" "LATEX"))
338 (org-remove-indentation (org-element-property :value export-block
))))
343 (defun org-beamer-export-snippet (export-snippet contents info
)
344 "Transcode an EXPORT-SNIPPET object into Beamer code.
345 CONTENTS is nil. INFO is a plist used as a communication
347 (let ((backend (org-export-snippet-backend export-snippet
))
348 (value (org-element-property :value export-snippet
)))
349 ;; Only "latex" and "beamer" snippets are retained.
350 (cond ((eq backend
'latex
) value
)
351 ;; Ignore "beamer" snippets specifying overlays.
352 ((and (eq backend
'beamer
)
353 (or (org-export-get-previous-element export-snippet info
)
354 (not (string-match "\\`<.*>\\'" value
))))
360 ;; The main function to translate an headline is
361 ;; `org-beamer-headline'.
363 ;; Depending on the level at which an headline is considered as
364 ;; a frame (given by `org-beamer--frame-level'), the headline is
365 ;; either a section (`org-beamer--format-section'), a frame
366 ;; (`org-beamer--format-frame') or a block
367 ;; (`org-beamer--format-block').
369 ;; `org-beamer-headline' also takes care of special environments
370 ;; like "ignoreheading", "note", "noteNH", "appendix" and
373 (defun org-beamer--get-label (headline info
)
374 "Return label for HEADLINE, as a string.
376 INFO is a plist used as a communication channel.
378 The value is either the label specified in \"BEAMER_opt\"
379 property, or a fallback value built from headline's number. This
380 function assumes HEADLINE will be treated as a frame."
381 (let ((opt (org-element-property :BEAMER_OPT headline
)))
382 (if (and (org-string-nw-p opt
)
383 (string-match "\\(?:^\\|,\\)label=\\(.*?\\)\\(?:$\\|,\\)" opt
))
386 (mapconcat 'number-to-string
387 (org-export-get-headline-number headline info
)
390 (defun org-beamer--frame-level (headline info
)
391 "Return frame level in subtree containing HEADLINE.
392 INFO is a plist used as a communication channel."
394 ;; 1. Look for "frame" environment in parents, starting from the
397 (mapc (lambda (parent)
398 (let ((env (org-element-property :BEAMER_ENV parent
)))
399 (when (and env
(member (downcase env
) '("frame" "fullframe")))
400 (throw 'exit
(org-export-get-relative-level parent info
)))))
401 (nreverse (org-export-get-genealogy headline
)))
403 ;; 2. Look for "frame" environment in HEADLINE.
404 (let ((env (org-element-property :BEAMER_ENV headline
)))
405 (and env
(member (downcase env
) '("frame" "fullframe"))
406 (org-export-get-relative-level headline info
)))
407 ;; 3. Look for "frame" environment in sub-tree.
408 (org-element-map headline
'headline
410 (let ((env (org-element-property :BEAMER_ENV hl
)))
411 (when (and env
(member (downcase env
) '("frame" "fullframe")))
412 (org-export-get-relative-level hl info
))))
414 ;; 4. No "frame" environment in tree: use default value.
415 (plist-get info
:headline-levels
)))
417 (defun org-beamer--format-section (headline contents info
)
418 "Format HEADLINE as a sectioning part.
419 CONTENTS holds the contents of the headline. INFO is a plist
420 used as a communication channel."
421 ;; Use `latex' back-end output, inserting overlay specifications
423 (let ((latex-headline (org-export-with-backend 'latex headline contents info
))
424 (mode-specs (org-element-property :BEAMER_ACT headline
)))
426 (string-match "\\`\\\\\\(.*?\\)\\(?:\\*\\|\\[.*\\]\\)?{"
428 (replace-match (concat (match-string 1 latex-headline
)
429 (format "<%s>" mode-specs
))
430 nil nil latex-headline
1)
433 (defun org-beamer--format-frame (headline contents info
)
434 "Format HEADLINE as a frame.
435 CONTENTS holds the contents of the headline. INFO is a plist
436 used as a communication channel."
438 ;; FRAGILEP is non-nil when HEADLINE contains an element
439 ;; among `org-beamer-verbatim-elements'.
440 (org-element-map headline org-beamer-verbatim-elements
'identity
442 (concat "\\begin{frame}"
443 ;; Overlay specification, if any. When surrounded by
444 ;; square brackets, consider it as a default
446 (let ((action (org-element-property :BEAMER_ACT headline
)))
449 ((string-match "\\`\\[.*\\]\\'" action
)
450 (org-beamer--normalize-argument action
'defaction
))
451 (t (org-beamer--normalize-argument action
'action
))))
453 (let* ((beamer-opt (org-element-property :BEAMER_OPT headline
))
455 ;; Collect options from default value and headline's
456 ;; properties. Also add a label for links.
458 (org-split-string org-beamer-frame-default-options
",")
461 ;; Remove square brackets if user provided
463 (and (string-match "^\\[?\\(.*\\)\\]?$" beamer-opt
)
464 (match-string 1 beamer-opt
))
466 ;; Provide an automatic label for the frame
467 ;; unless the user specified one.
468 (unless (and beamer-opt
469 (string-match "\\(^\\|,\\)label=" beamer-opt
))
472 (org-beamer--get-label headline info
)))))))
473 ;; Change options list into a string.
474 (org-beamer--normalize-argument
477 (if (or (not fragilep
) (member "fragile" options
)) options
478 (cons "fragile" options
))
482 (let ((env (org-element-property :BEAMER_ENV headline
)))
484 (if (and env
(equal (downcase env
) "fullframe")) ""
486 (org-element-property :title headline
) info
))))
488 ;; The following workaround is required in fragile frames
489 ;; as Beamer will append "\par" to the beginning of the
490 ;; contents. So we need to make sure the command is
491 ;; separated from the contents by at least one space. If
492 ;; it isn't, it will create "\parfirst-word" command and
493 ;; remove the first word from the contents in the PDF
495 (if (not fragilep
) contents
496 (replace-regexp-in-string "\\`\n*" "\\& " contents
))
499 (defun org-beamer--format-block (headline contents info
)
500 "Format HEADLINE as a block.
501 CONTENTS holds the contents of the headline. INFO is a plist
502 used as a communication channel."
503 (let* ((column-width (org-element-property :BEAMER_COL headline
))
504 ;; ENVIRONMENT defaults to "block" if none is specified and
505 ;; there is no column specification. If there is a column
506 ;; specified but still no explicit environment, ENVIRONMENT
508 (environment (let ((env (org-element-property :BEAMER_ENV headline
)))
510 ;; "block" is the fallback environment.
511 ((and (not env
) (not column-width
)) "block")
514 ;; Use specified environment.
515 (t (downcase env
)))))
516 (env-format (unless (member environment
'("column" "columns"))
518 (append org-beamer-environments-special
519 org-beamer-environments-extra
520 org-beamer-environments-default
))))
521 (title (org-export-data (org-element-property :title headline
) info
))
522 (options (let ((options (org-element-property :BEAMER_OPT headline
)))
524 (org-beamer--normalize-argument options
'option
))))
525 ;; Start a "columns" environment when explicitly requested or
526 ;; when there is no previous headline or the previous
527 ;; headline do not have a BEAMER_column property.
528 (parent-env (org-element-property
529 :BEAMER_ENV
(org-export-get-parent-headline headline
)))
531 (or (equal environment
"columns")
534 (equal (downcase parent-env
) "columns")))
535 (or (org-export-first-sibling-p headline info
)
536 (not (org-element-property
538 (org-export-get-previous-element
540 ;; End the "columns" environment when explicitly requested or
541 ;; when there is no next headline or the next headline do not
542 ;; have a BEAMER_column property.
544 (or (equal environment
"columns")
547 (equal (downcase parent-env
) "columns")))
548 (or (org-export-last-sibling-p headline info
)
549 (not (org-element-property
551 (org-export-get-next-element headline info
))))))))
553 (when start-columns-p
554 ;; Column can accept options only when the environment is
555 ;; explicitly defined.
556 (if (not (equal environment
"columns")) "\\begin{columns}\n"
557 (format "\\begin{columns}%s\n" options
)))
559 (format "\\begin{column}%s{%s}\n"
560 ;; One can specify placement for column only when
561 ;; HEADLINE stands for a column on its own.
562 (if (equal environment
"column") options
"")
563 (format "%s\\textwidth" column-width
)))
564 ;; Block's opening string.
570 ;; If BEAMER_act property has its value enclosed in square
571 ;; brackets, it is a default overlay specification and
572 ;; overlay specification is empty. Otherwise, it is an
573 ;; overlay specification and the default one is nil.
574 (let ((action (org-element-property :BEAMER_ACT headline
)))
576 ((not action
) (list (cons "a" "") (cons "A" "")))
577 ((string-match "\\`\\[.*\\]\\'" action
)
579 (cons "A" (org-beamer--normalize-argument action
'defaction
))
582 (list (cons "a" (org-beamer--normalize-argument action
'action
))
584 (list (cons "o" options
)
586 (cons "H" (if (equal title
"") "" (format "{%s}" title
)))
587 (cons "U" (if (equal title
"") "" (format "[%s]" title
))))))
590 ;; Block's closing string.
591 (when environment
(concat (nth 3 env-format
) "\n"))
592 (when column-width
"\\end{column}\n")
593 (when end-columns-p
"\\end{columns}"))))
595 (defun org-beamer-headline (headline contents info
)
596 "Transcode HEADLINE element into Beamer code.
597 CONTENTS is the contents of the headline. INFO is a plist used
598 as a communication channel."
599 (unless (org-element-property :footnote-section-p headline
)
600 (let ((level (org-export-get-relative-level headline info
))
601 (frame-level (org-beamer--frame-level headline info
))
602 (environment (let ((env (org-element-property :BEAMER_ENV headline
)))
603 (if (stringp env
) (downcase env
) "block"))))
605 ;; Case 1: Resume frame specified by "BEAMER_ref" property.
606 ((equal environment
"againframe")
607 (let ((ref (org-element-property :BEAMER_REF headline
)))
608 ;; Reference to frame being resumed is mandatory. Ignore
609 ;; the whole headline if it isn't provided.
610 (when (org-string-nw-p ref
)
611 (concat "\\againframe"
612 ;; Overlay specification.
613 (let ((overlay (org-element-property :BEAMER_ACT headline
)))
615 (org-beamer--normalize-argument
617 (if (string-match "^\\[.*\\]$" overlay
) 'defaction
620 (let ((options (org-element-property :BEAMER_OPT headline
)))
622 (org-beamer--normalize-argument options
'option
)))
623 ;; Resolve reference provided by "BEAMER_ref"
624 ;; property. This is done by building a minimal fake
625 ;; link and calling the appropriate resolve function,
626 ;; depending on the reference syntax.
629 (string-match "^\\(id:\\|#\\|\\*\\)?\\(.*\\)" ref
)
631 ((or (not (match-string 1 ref
))
632 (equal (match-string 1 ref
) "*")) 'fuzzy
)
633 ((equal (match-string 1 ref
) "id:") 'id
)
635 (link (list 'link
(list :path
(match-string 2 ref
))))
636 (target (if (eq type
'fuzzy
)
637 (org-export-resolve-fuzzy-link link info
)
638 (org-export-resolve-id-link link info
))))
639 ;; Now use user-defined label provided in TARGET
640 ;; headline, or fallback to standard one.
641 (format "{%s}" (org-beamer--get-label target info
)))))))
642 ;; Case 2: Creation of an appendix is requested.
643 ((equal environment
"appendix")
645 (org-element-property :BEAMER_ACT headline
)
647 (make-string (org-element-property :pre-blank headline
) ?
\n)
649 ;; Case 3: Ignore heading.
650 ((equal environment
"ignoreheading")
651 (concat (make-string (org-element-property :pre-blank headline
) ?
\n)
653 ;; Case 4: HEADLINE is a note.
654 ((member environment
'("note" "noteNH"))
656 (concat (and (equal environment
"note")
659 (org-element-property :title headline
) info
)
661 (org-trim contents
))))
662 ;; Case 5: HEADLINE is a frame.
663 ((= level frame-level
)
664 (org-beamer--format-frame headline contents info
))
665 ;; Case 6: Regular section, extracted from
666 ;; `org-latex-classes'.
667 ((< level frame-level
)
668 (org-beamer--format-section headline contents info
))
669 ;; Case 7: Otherwise, HEADLINE is a block.
670 (t (org-beamer--format-block headline contents info
))))))
675 (defun org-beamer-item (item contents info
)
676 "Transcode an ITEM element into Beamer code.
677 CONTENTS holds the contents of the item. INFO is a plist holding
678 contextual information."
679 (let ((action (let ((first-element (car (org-element-contents item
))))
680 (and (eq (org-element-type first-element
) 'paragraph
)
681 (org-beamer--element-has-overlay-p first-element
))))
682 (output (org-export-with-backend 'latex item contents info
)))
683 (if (not action
) output
684 ;; If the item starts with a paragraph and that paragraph starts
685 ;; with an export snippet specifying an overlay, insert it after
687 (replace-regexp-in-string "\\\\item" (concat "\\\\item" action
) output
))))
692 (defun org-beamer-keyword (keyword contents info
)
693 "Transcode a KEYWORD element into Beamer code.
694 CONTENTS is nil. INFO is a plist used as a communication
696 (let ((key (org-element-property :key keyword
))
697 (value (org-element-property :value keyword
)))
698 ;; Handle specifically BEAMER and TOC (headlines only) keywords.
699 ;; Otherwise, fallback to `latex' back-end.
701 ((equal key
"BEAMER") value
)
702 ((and (equal key
"TOC") (string-match "\\<headlines\\>" value
))
703 (let ((depth (or (and (string-match "[0-9]+" value
)
704 (string-to-number (match-string 0 value
)))
705 (plist-get info
:with-toc
)))
706 (options (and (string-match "\\[.*?\\]" value
)
707 (match-string 0 value
))))
710 (when (wholenump depth
) (format "\\setcounter{tocdepth}{%s}\n" depth
))
711 "\\tableofcontents" options
"\n"
713 (t (org-export-with-backend 'latex keyword contents info
)))))
718 (defun org-beamer-link (link contents info
)
719 "Transcode a LINK object into Beamer code.
720 CONTENTS is the description part of the link. INFO is a plist
721 used as a communication channel."
722 (let ((type (org-element-property :type link
))
723 (path (org-element-property :path link
)))
724 ;; Use \hyperlink command for all internal links.
726 ((equal type
"radio")
727 (let ((destination (org-export-resolve-radio-link link info
)))
729 (format "\\hyperlink%s{%s}{%s}"
730 (or (org-beamer--element-has-overlay-p link
) "")
731 (org-export-solidify-link-text path
)
732 (org-export-data (org-element-contents destination
) info
)))))
733 ((and (member type
'("custom-id" "fuzzy" "id"))
734 (let ((destination (if (string= type
"fuzzy")
735 (org-export-resolve-fuzzy-link link info
)
736 (org-export-resolve-id-link link info
))))
737 (case (org-element-type destination
)
743 (org-export-get-headline-number
746 (if (and (plist-get info
:section-numbers
) (not contents
))
747 (format "\\ref{%s}" label
)
748 (format "\\hyperlink%s{%s}{%s}"
749 (or (org-beamer--element-has-overlay-p link
) "")
753 (let ((path (org-export-solidify-link-text path
)))
754 (if (not contents
) (format "\\ref{%s}" path
)
755 (format "\\hyperlink%s{%s}{%s}"
756 (or (org-beamer--element-has-overlay-p link
) "")
759 ;; Otherwise, use `latex' back-end.
760 (t (org-export-with-backend 'latex link contents info
)))))
765 ;; Plain lists support `:environment', `:overlay' and `:options'
768 (defun org-beamer-plain-list (plain-list contents info
)
769 "Transcode a PLAIN-LIST element into Beamer code.
770 CONTENTS is the contents of the list. INFO is a plist holding
771 contextual information."
772 (let* ((type (org-element-property :type plain-list
))
773 (attributes (org-combine-plists
774 (org-export-read-attribute :attr_latex plain-list
)
775 (org-export-read-attribute :attr_beamer plain-list
)))
776 (latex-type (let ((env (plist-get attributes
:environment
)))
777 (cond (env (format "%s" env
))
778 ((eq type
'ordered
) "enumerate")
779 ((eq type
'descriptive
) "description")
781 (org-latex--wrap-label
783 (format "\\begin{%s}%s%s\n%s\\end{%s}"
785 ;; Default overlay specification, if any.
786 (org-beamer--normalize-argument
787 (format "%s" (or (plist-get attributes
:overlay
) ""))
789 ;; Second optional argument depends on the list type.
790 (org-beamer--normalize-argument
791 (format "%s" (or (plist-get attributes
:options
) ""))
793 ;; Eventually insert contents and close environment.
800 (defun org-beamer-radio-target (radio-target text info
)
801 "Transcode a RADIO-TARGET object into Beamer code.
802 TEXT is the text of the target. INFO is a plist holding
803 contextual information."
804 (format "\\hypertarget%s{%s}{%s}"
805 (or (org-beamer--element-has-overlay-p radio-target
) "")
806 (org-export-solidify-link-text
807 (org-element-property :value radio-target
))
813 (defun org-beamer-target (target contents info
)
814 "Transcode a TARGET object into Beamer code.
815 CONTENTS is nil. INFO is a plist holding contextual
817 (format "\\hypertarget{%s}{}"
818 (org-export-solidify-link-text (org-element-property :value target
))))
823 ;; Template used is similar to the one used in `latex' back-end,
824 ;; excepted for the table of contents and Beamer themes.
826 (defun org-beamer-template (contents info
)
827 "Return complete document string after Beamer conversion.
828 CONTENTS is the transcoded contents string. INFO is a plist
829 holding export options."
830 (let ((title (org-export-data (plist-get info
:title
) info
)))
833 (and (plist-get info
:time-stamp-file
)
834 (format-time-string "%% Created %Y-%m-%d %a %H:%M\n"))
835 ;; 2. Document class and packages.
836 (let ((class (plist-get info
:latex-class
))
837 (class-options (plist-get info
:latex-class-options
)))
838 (org-element-normalize-string
839 (let* ((header (nth 1 (assoc class org-latex-classes
)))
840 (document-class-string
841 (and (stringp header
)
842 (if (not class-options
) header
843 (replace-regexp-in-string
844 "^[ \t]*\\\\documentclass\\(\\(\\[[^]]*\\]\\)?\\)"
845 class-options header t nil
1)))))
846 (if (not document-class-string
)
847 (user-error "Unknown LaTeX class `%s'" class
)
848 (org-latex-guess-babel-language
849 (org-latex-guess-inputenc
850 (org-splice-latex-header
851 document-class-string
852 org-latex-default-packages-alist
853 org-latex-packages-alist nil
854 (concat (plist-get info
:latex-header-extra
)
855 (plist-get info
:beamer-header-extra
))))
860 (lambda (prop command
)
861 (let ((theme (plist-get info prop
)))
864 (if (not (string-match "\\[.*\\]" theme
))
865 (format "{%s}\n" theme
)
867 (match-string 0 theme
)
869 (replace-match "" nil nil theme
)))))))))))
870 (mapconcat (lambda (args) (apply format-theme args
))
871 '((:beamer-theme
"\\usetheme")
872 (:beamer-color-theme
"\\usecolortheme")
873 (:beamer-font-theme
"\\usefonttheme")
874 (:beamer-inner-theme
"\\useinnertheme")
875 (:beamer-outer-theme
"\\useoutertheme"))
877 ;; 4. Possibly limit depth for headline numbering.
878 (let ((sec-num (plist-get info
:section-numbers
)))
879 (when (integerp sec-num
)
880 (format "\\setcounter{secnumdepth}{%d}\n" sec-num
)))
882 (let ((author (and (plist-get info
:with-author
)
883 (let ((auth (plist-get info
:author
)))
884 (and auth
(org-export-data auth info
)))))
885 (email (and (plist-get info
:with-email
)
886 (org-export-data (plist-get info
:email
) info
))))
887 (cond ((and author email
(not (string= "" email
)))
888 (format "\\author{%s\\thanks{%s}}\n" author email
))
889 (author (format "\\author{%s}\n" author
))
892 (let ((date (and (plist-get info
:with-date
) (plist-get info
:date
))))
893 (format "\\date{%s}\n"
894 (cond ((not date
) "")
895 ;; If `:date' consists in a single timestamp and
896 ;; `:date-format' is provided, apply it.
897 ((and (plist-get info
:date-format
)
899 (eq (org-element-type (car date
)) 'timestamp
))
900 (org-timestamp-format
901 (car date
) (plist-get info
:date-format
)))
902 (t (org-export-data date info
)))))
904 (format "\\title{%s}\n" title
)
905 ;; 8. Hyperref options.
906 (when (plist-get info
:latex-hyperref-p
)
907 (format "\\hypersetup{\n pdfkeywords={%s},\n pdfsubject={%s},\n pdfcreator={%s}}\n"
908 (or (plist-get info
:keywords
) "")
909 (or (plist-get info
:description
) "")
910 (if (not (plist-get info
:with-creator
)) ""
911 (plist-get info
:creator
))))
912 ;; 9. Document start.
913 "\\begin{document}\n\n"
914 ;; 10. Title command.
915 (org-element-normalize-string
916 (cond ((string= "" title
) nil
)
917 ((not (stringp org-latex-title-command
)) nil
)
918 ((string-match "\\(?:[^%]\\|^\\)%s"
919 org-latex-title-command
)
920 (format org-latex-title-command title
))
921 (t org-latex-title-command
)))
922 ;; 11. Table of contents.
923 (let ((depth (plist-get info
:with-toc
)))
926 (format "\\begin{frame}%s{%s}\n"
927 (org-beamer--normalize-argument
928 org-beamer-outline-frame-options
'option
)
929 org-beamer-outline-frame-title
)
930 (when (wholenump depth
)
931 (format "\\setcounter{tocdepth}{%d}\n" depth
))
932 "\\tableofcontents\n"
933 "\\end{frame}\n\n")))
934 ;; 12. Document's body.
937 (let ((creator-info (plist-get info
:with-creator
)))
939 ((not creator-info
) "")
940 ((eq creator-info
'comment
)
941 (format "%% %s\n" (plist-get info
:creator
)))
942 (t (concat (plist-get info
:creator
) "\n"))))
951 (defvar org-beamer-mode-map
(make-sparse-keymap)
952 "The keymap for `org-beamer-mode'.")
953 (define-key org-beamer-mode-map
"\C-c\C-b" 'org-beamer-select-environment
)
956 (define-minor-mode org-beamer-mode
957 "Support for editing Beamer oriented Org mode files."
958 nil
" Bm" 'org-beamer-mode-map
)
960 (when (fboundp 'font-lock-add-keywords
)
961 (font-lock-add-keywords
963 '((":\\(B_[a-z]+\\|BMCOL\\):" 1 'org-beamer-tag prepend
))
966 (defface org-beamer-tag
'((t (:box
(:line-width
1 :color grey40
))))
967 "The special face for beamer tags."
968 :group
'org-export-beamer
)
970 (defun org-beamer-property-changed (property value
)
971 "Track the BEAMER_env property with tags.
972 PROPERTY is the name of the modified property. VALUE is its new
975 ((equal property
"BEAMER_env")
977 (org-back-to-heading t
)
978 ;; Filter out Beamer-related tags and install environment tag.
979 (let ((tags (org-remove-if (lambda (x) (string-match "^B_" x
))
981 (env-tag (and (org-string-nw-p value
) (concat "B_" value
))))
982 (org-set-tags-to (if env-tag
(cons env-tag tags
) tags
))
983 (when env-tag
(org-toggle-tag env-tag
'on
)))))
984 ((equal property
"BEAMER_col")
985 (org-toggle-tag "BMCOL" (if (org-string-nw-p value
) 'on
'off
)))))
987 (add-hook 'org-property-changed-functions
'org-beamer-property-changed
)
989 (defun org-beamer-allowed-property-values (property)
990 "Supply allowed values for PROPERTY."
992 ((and (equal property
"BEAMER_env")
993 (not (org-entry-get nil
(concat property
"_ALL") 'inherit
)))
994 ;; If no allowed values for BEAMER_env have been defined,
995 ;; supply all defined environments
996 (mapcar 'car
(append org-beamer-environments-special
997 org-beamer-environments-extra
998 org-beamer-environments-default
)))
999 ((and (equal property
"BEAMER_col")
1000 (not (org-entry-get nil
(concat property
"_ALL") 'inherit
)))
1001 ;; If no allowed values for BEAMER_col have been defined,
1003 (org-split-string org-beamer-column-widths
" "))))
1005 (add-hook 'org-property-allowed-value-functions
1006 'org-beamer-allowed-property-values
)
1013 (defun org-beamer-export-as-latex
1014 (&optional async subtreep visible-only body-only ext-plist
)
1015 "Export current buffer as a Beamer buffer.
1017 If narrowing is active in the current buffer, only export its
1020 If a region is active, export that region.
1022 A non-nil optional argument ASYNC means the process should happen
1023 asynchronously. The resulting buffer should be accessible
1024 through the `org-export-stack' interface.
1026 When optional argument SUBTREEP is non-nil, export the sub-tree
1027 at point, extracting information from the headline properties
1030 When optional argument VISIBLE-ONLY is non-nil, don't export
1031 contents of hidden elements.
1033 When optional argument BODY-ONLY is non-nil, only write code
1034 between \"\\begin{document}\" and \"\\end{document}\".
1036 EXT-PLIST, when provided, is a property list with external
1037 parameters overriding Org default settings, but still inferior to
1038 file-local settings.
1040 Export is done in a buffer named \"*Org BEAMER Export*\", which
1041 will be displayed when `org-export-show-temporary-export-buffer'
1045 (org-export-async-start
1047 (with-current-buffer (get-buffer-create "*Org BEAMER Export*")
1050 (goto-char (point-min))
1052 (org-export-add-to-stack (current-buffer) 'beamer
)))
1053 `(org-export-as 'beamer
,subtreep
,visible-only
,body-only
1055 (let ((outbuf (org-export-to-buffer
1056 'beamer
"*Org BEAMER Export*"
1057 subtreep visible-only body-only ext-plist
)))
1058 (with-current-buffer outbuf
(LaTeX-mode))
1059 (when org-export-show-temporary-export-buffer
1060 (switch-to-buffer-other-window outbuf
)))))
1063 (defun org-beamer-export-to-latex
1064 (&optional async subtreep visible-only body-only ext-plist
)
1065 "Export current buffer as a Beamer presentation (tex).
1067 If narrowing is active in the current buffer, only export its
1070 If a region is active, export that region.
1072 A non-nil optional argument ASYNC means the process should happen
1073 asynchronously. The resulting file should be accessible through
1074 the `org-export-stack' interface.
1076 When optional argument SUBTREEP is non-nil, export the sub-tree
1077 at point, extracting information from the headline properties
1080 When optional argument VISIBLE-ONLY is non-nil, don't export
1081 contents of hidden elements.
1083 When optional argument BODY-ONLY is non-nil, only write code
1084 between \"\\begin{document}\" and \"\\end{document}\".
1086 EXT-PLIST, when provided, is a property list with external
1087 parameters overriding Org default settings, but still inferior to
1088 file-local settings.
1090 Return output file's name."
1092 (let ((outfile (org-export-output-file-name ".tex" subtreep
)))
1094 (org-export-async-start
1095 (lambda (f) (org-export-add-to-stack f
'beamer
))
1098 'beamer
,outfile
,subtreep
,visible-only
,body-only
1101 'beamer outfile subtreep visible-only body-only ext-plist
))))
1104 (defun org-beamer-export-to-pdf
1105 (&optional async subtreep visible-only body-only ext-plist
)
1106 "Export current buffer as a Beamer presentation (PDF).
1108 If narrowing is active in the current buffer, only export its
1111 If a region is active, export that region.
1113 A non-nil optional argument ASYNC means the process should happen
1114 asynchronously. The resulting file should be accessible through
1115 the `org-export-stack' interface.
1117 When optional argument SUBTREEP is non-nil, export the sub-tree
1118 at point, extracting information from the headline properties
1121 When optional argument VISIBLE-ONLY is non-nil, don't export
1122 contents of hidden elements.
1124 When optional argument BODY-ONLY is non-nil, only write code
1125 between \"\\begin{document}\" and \"\\end{document}\".
1127 EXT-PLIST, when provided, is a property list with external
1128 parameters overriding Org default settings, but still inferior to
1129 file-local settings.
1131 Return PDF file's name."
1134 (let ((outfile (org-export-output-file-name ".tex" subtreep
)))
1135 (org-export-async-start
1136 (lambda (f) (org-export-add-to-stack f
'beamer
))
1140 'beamer
,outfile
,subtreep
,visible-only
,body-only
1143 (org-beamer-export-to-latex
1144 nil subtreep visible-only body-only ext-plist
))))
1147 (defun org-beamer-select-environment ()
1148 "Select the environment to be used by beamer for this entry.
1149 While this uses (for convenience) a tag selection interface, the
1150 result of this command will be that the BEAMER_env *property* of
1153 In addition to this, the command will also set a tag as a visual
1154 aid, but the tag does not have any semantic meaning."
1156 ;; Make sure `org-beamer-environments-special' has a higher
1157 ;; priority than `org-beamer-environments-extra'.
1158 (let* ((envs (append org-beamer-environments-special
1159 org-beamer-environments-extra
1160 org-beamer-environments-default
))
1162 (append '((:startgroup
))
1163 (mapcar (lambda (e) (cons (concat "B_" (car e
))
1164 (string-to-char (nth 1 e
))))
1168 (org-fast-tag-selection-single-key t
))
1170 (let ((tags (or (ignore-errors (org-get-tags-string)) "")))
1172 ;; For a column, automatically ask for its width.
1173 ((eq org-last-tag-selection-key ?|
)
1174 (if (string-match ":BMCOL:" tags
)
1175 (org-set-property "BEAMER_col" (read-string "Column width: "))
1176 (org-delete-property "BEAMER_col")))
1177 ;; For an "againframe" section, automatically ask for reference
1178 ;; to resumed frame and overlay specifications.
1179 ((eq org-last-tag-selection-key ?A
)
1180 (if (equal (org-entry-get nil
"BEAMER_env") "againframe")
1181 (progn (org-entry-delete nil
"BEAMER_env")
1182 (org-entry-delete nil
"BEAMER_ref")
1183 (org-entry-delete nil
"BEAMER_act"))
1184 (org-entry-put nil
"BEAMER_env" "againframe")
1187 (read-string "Frame reference (*Title, #custom-id, id:...): "))
1188 (org-set-property "BEAMER_act"
1189 (read-string "Overlay specification: "))))
1190 ((string-match (concat ":B_\\(" (mapconcat 'car envs
"\\|") "\\):") tags
)
1191 (org-entry-put nil
"BEAMER_env" (match-string 1 tags
)))
1192 (t (org-entry-delete nil
"BEAMER_env"))))))
1195 (defun org-beamer-insert-options-template (&optional kind
)
1196 "Insert a settings template, to make sure users do this right."
1198 (message "Current [s]ubtree or [g]lobal?")
1199 (if (eq (read-char-exclusive) ?g
) (list 'global
)
1201 (if (eq kind
'subtree
)
1203 (org-back-to-heading t
)
1205 (org-entry-put nil
"EXPORT_LaTeX_CLASS" "beamer")
1206 (org-entry-put nil
"EXPORT_LaTeX_CLASS_OPTIONS" "[presentation]")
1207 (org-entry-put nil
"EXPORT_FILE_NAME" "presentation.pdf")
1208 (when org-beamer-column-view-format
1209 (org-entry-put nil
"COLUMNS" org-beamer-column-view-format
))
1210 (org-entry-put nil
"BEAMER_col_ALL" org-beamer-column-widths
))
1211 (insert "#+LaTeX_CLASS: beamer\n")
1212 (insert "#+LaTeX_CLASS_OPTIONS: [presentation]\n")
1213 (when org-beamer-theme
(insert "#+BEAMER_THEME: " org-beamer-theme
"\n"))
1214 (when org-beamer-column-view-format
1215 (insert "#+COLUMNS: " org-beamer-column-view-format
"\n"))
1216 (insert "#+PROPERTY: BEAMER_col_ALL " org-beamer-column-widths
"\n")))
1219 (defun org-beamer-publish-to-latex (plist filename pub-dir
)
1220 "Publish an Org file to a Beamer presentation (LaTeX).
1222 FILENAME is the filename of the Org file to be published. PLIST
1223 is the property list for the given project. PUB-DIR is the
1224 publishing directory.
1226 Return output file name."
1227 (org-publish-org-to 'beamer filename
".tex" plist pub-dir
))
1230 (defun org-beamer-publish-to-pdf (plist filename pub-dir
)
1231 "Publish an Org file to a Beamer presentation (PDF, via LaTeX).
1233 FILENAME is the filename of the Org file to be published. PLIST
1234 is the property list for the given project. PUB-DIR is the
1235 publishing directory.
1237 Return output file name."
1238 ;; Unlike to `org-beamer-publish-to-latex', PDF file is generated in
1239 ;; working directory and then moved to publishing directory.
1240 (org-publish-attachment
1242 (org-latex-compile (org-publish-org-to 'beamer filename
".tex" plist
))
1246 (provide 'ox-beamer
)
1249 ;; generated-autoload-file: "org-loaddefs.el"
1252 ;;; ox-beamer.el ends here