Merge branch 'maint'
[org-mode/org-tableheadings.git] / lisp / ox-beamer.el
blob82651d3848ef0f2b9e10c2137022fb8c8e989d99
1 ;;; ox-beamer.el --- Beamer Back-End for Org Export Engine -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2007-2017 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 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;; This library implements both a Beamer back-end, derived from the
27 ;; LaTeX one and a minor mode easing structure edition of the
28 ;; document. See Org manual for more information.
30 ;;; Code:
32 (require 'cl-lib)
33 (require 'ox-latex)
35 ;; Install a default set-up for Beamer export.
36 (unless (assoc "beamer" org-latex-classes)
37 (add-to-list 'org-latex-classes
38 '("beamer"
39 "\\documentclass[presentation]{beamer}"
40 ("\\section{%s}" . "\\section*{%s}")
41 ("\\subsection{%s}" . "\\subsection*{%s}")
42 ("\\subsubsection{%s}" . "\\subsubsection*{%s}"))))
46 ;;; User-Configurable Variables
48 (defgroup org-export-beamer nil
49 "Options specific for using the beamer class in LaTeX export."
50 :tag "Org Beamer"
51 :group 'org-export
52 :version "24.2")
54 (defcustom org-beamer-frame-level 1
55 "The level at which headlines become frames.
57 Headlines at a lower level will be translated into a sectioning
58 structure. At a higher level, they will be translated into
59 blocks.
61 If a headline with a \"BEAMER_env\" property set to \"frame\" is
62 found within a tree, its level locally overrides this number.
64 This variable has no effect on headlines with the \"BEAMER_env\"
65 property set to either \"ignoreheading\", \"appendix\", or
66 \"note\", which will respectively, be invisible, become an
67 appendix or a note.
69 This integer is relative to the minimal level of a headline
70 within the parse tree, defined as 1."
71 :group 'org-export-beamer
72 :type 'integer)
74 (defcustom org-beamer-frame-default-options ""
75 "Default options string to use for frames.
76 For example, it could be set to \"allowframebreaks\"."
77 :group 'org-export-beamer
78 :type '(string :tag "[options]"))
80 (defcustom org-beamer-column-view-format
81 "%45ITEM %10BEAMER_env(Env) %10BEAMER_act(Act) %4BEAMER_col(Col) %8BEAMER_opt(Opt)"
82 "Column view format that should be used to fill the template."
83 :group 'org-export-beamer
84 :version "24.4"
85 :package-version '(Org . "8.0")
86 :type '(choice
87 (const :tag "Do not insert Beamer column view format" nil)
88 (string :tag "Beamer column view format")))
90 (defcustom org-beamer-theme "default"
91 "Default theme used in Beamer presentations."
92 :group 'org-export-beamer
93 :version "24.4"
94 :package-version '(Org . "8.0")
95 :type '(choice
96 (const :tag "Do not insert a Beamer theme" nil)
97 (string :tag "Beamer theme")))
99 (defcustom org-beamer-environments-extra nil
100 "Environments triggered by tags in Beamer export.
101 Each entry has 4 elements:
103 name Name of the environment
104 key Selection key for `org-beamer-select-environment'
105 open The opening template for the environment, with the following escapes
106 %a the action/overlay specification
107 %A the default action/overlay specification
108 %R the raw BEAMER_act value
109 %o the options argument, with square brackets
110 %O the raw BEAMER_opt value
111 %h the headline text
112 %r the raw headline text (i.e. without any processing)
113 %H if there is headline text, that raw text in {} braces
114 %U if there is headline text, that raw text in [] brackets
115 close The closing string of the environment."
116 :group 'org-export-beamer
117 :version "24.4"
118 :package-version '(Org . "8.1")
119 :type '(repeat
120 (list
121 (string :tag "Environment")
122 (string :tag "Selection key")
123 (string :tag "Begin")
124 (string :tag "End"))))
126 (defcustom org-beamer-outline-frame-title "Outline"
127 "Default title of a frame containing an outline."
128 :group 'org-export-beamer
129 :type '(string :tag "Outline frame title"))
131 (defcustom org-beamer-outline-frame-options ""
132 "Outline frame options appended after \\begin{frame}.
133 You might want to put e.g. \"allowframebreaks=0.9\" here."
134 :group 'org-export-beamer
135 :type '(string :tag "Outline frame options"))
138 (defcustom org-beamer-subtitle-format "\\subtitle{%s}"
139 "Format string used for transcoded subtitle.
140 The format string should have at most one \"%s\"-expression,
141 which is replaced with the subtitle."
142 :group 'org-export-beamer
143 :version "26.1"
144 :package-version '(Org . "8.3")
145 :type '(string :tag "Format string"))
148 ;;; Internal Variables
150 (defconst org-beamer-column-widths
151 "0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 0.0 :ETC"
152 "The column widths that should be installed as allowed property values.")
154 (defconst org-beamer-environments-special
155 '(("againframe" "A")
156 ("appendix" "x")
157 ("column" "c")
158 ("columns" "C")
159 ("frame" "f")
160 ("fullframe" "F")
161 ("ignoreheading" "i")
162 ("note" "n")
163 ("noteNH" "N"))
164 "Alist of environments treated in a special way by the back-end.
165 Keys are environment names, as strings, values are bindings used
166 in `org-beamer-select-environment'. Environments listed here,
167 along with their binding, are hard coded and cannot be modified
168 through `org-beamer-environments-extra' variable.")
170 (defconst org-beamer-environments-default
171 '(("block" "b" "\\begin{block}%a{%h}" "\\end{block}")
172 ("alertblock" "a" "\\begin{alertblock}%a{%h}" "\\end{alertblock}")
173 ("verse" "v" "\\begin{verse}%a %% %h" "\\end{verse}")
174 ("quotation" "q" "\\begin{quotation}%a %% %h" "\\end{quotation}")
175 ("quote" "Q" "\\begin{quote}%a %% %h" "\\end{quote}")
176 ("structureenv" "s" "\\begin{structureenv}%a %% %h" "\\end{structureenv}")
177 ("theorem" "t" "\\begin{theorem}%a%U" "\\end{theorem}")
178 ("definition" "d" "\\begin{definition}%a%U" "\\end{definition}")
179 ("example" "e" "\\begin{example}%a%U" "\\end{example}")
180 ("exampleblock" "E" "\\begin{exampleblock}%a{%h}" "\\end{exampleblock}")
181 ("proof" "p" "\\begin{proof}%a%U" "\\end{proof}")
182 ("beamercolorbox" "o" "\\begin{beamercolorbox}%o{%h}" "\\end{beamercolorbox}"))
183 "Environments triggered by properties in Beamer export.
184 These are the defaults - for user definitions, see
185 `org-beamer-environments-extra'.")
187 (defconst org-beamer-verbatim-elements
188 '(code example-block fixed-width inline-src-block src-block verbatim)
189 "List of element or object types producing verbatim text.
190 This is used internally to determine when a frame should have the
191 \"fragile\" option.")
195 ;;; Internal functions
197 (defun org-beamer--normalize-argument (argument type)
198 "Return ARGUMENT string with proper boundaries.
200 TYPE is a symbol among the following:
201 `action' Return ARGUMENT within angular brackets.
202 `defaction' Return ARGUMENT within both square and angular brackets.
203 `option' Return ARGUMENT within square brackets."
204 (if (not (string-match "\\S-" argument)) ""
205 (cl-case type
206 (action (format "<%s>" (org-unbracket-string "<" ">" argument)))
207 (defaction
208 (format "[<%s>]"
209 (org-unbracket-string "<" ">" (org-unbracket-string "[" "]" argument))))
210 (option (format "[%s]" (org-unbracket-string "[" "]" argument)))
211 (otherwise (error "Invalid `type' argument to `org-beamer--normalize-argument': %s"
212 type)))))
214 (defun org-beamer--element-has-overlay-p (element)
215 "Non-nil when ELEMENT has an overlay specified.
216 An element has an overlay specification when it starts with an
217 `beamer' export-snippet whose value is between angular brackets.
218 Return overlay specification, as a string, or nil."
219 (let ((first-object (car (org-element-contents element))))
220 (when (eq (org-element-type first-object) 'export-snippet)
221 (let ((value (org-element-property :value first-object)))
222 (and (string-prefix-p "<" value) (string-suffix-p ">" value)
223 value)))))
227 ;;; Define Back-End
229 (org-export-define-derived-backend 'beamer 'latex
230 :menu-entry
231 '(?l 1
232 ((?B "As LaTeX buffer (Beamer)" org-beamer-export-as-latex)
233 (?b "As LaTeX file (Beamer)" org-beamer-export-to-latex)
234 (?P "As PDF file (Beamer)" org-beamer-export-to-pdf)
235 (?O "As PDF file and open (Beamer)"
236 (lambda (a s v b)
237 (if a (org-beamer-export-to-pdf t s v b)
238 (org-open-file (org-beamer-export-to-pdf nil s v b)))))))
239 :options-alist
240 '((:headline-levels nil "H" org-beamer-frame-level)
241 (:latex-class "LATEX_CLASS" nil "beamer" t)
242 (:beamer-subtitle-format nil nil org-beamer-subtitle-format)
243 (:beamer-column-view-format "COLUMNS" nil org-beamer-column-view-format)
244 (:beamer-theme "BEAMER_THEME" nil org-beamer-theme)
245 (:beamer-color-theme "BEAMER_COLOR_THEME" nil nil t)
246 (:beamer-font-theme "BEAMER_FONT_THEME" nil nil t)
247 (:beamer-inner-theme "BEAMER_INNER_THEME" nil nil t)
248 (:beamer-outer-theme "BEAMER_OUTER_THEME" nil nil t)
249 (:beamer-header "BEAMER_HEADER" nil nil newline)
250 (:beamer-environments-extra nil nil org-beamer-environments-extra)
251 (:beamer-frame-default-options nil nil org-beamer-frame-default-options)
252 (:beamer-outline-frame-options nil nil org-beamer-outline-frame-options)
253 (:beamer-outline-frame-title nil nil org-beamer-outline-frame-title))
254 :translate-alist '((bold . org-beamer-bold)
255 (export-block . org-beamer-export-block)
256 (export-snippet . org-beamer-export-snippet)
257 (headline . org-beamer-headline)
258 (item . org-beamer-item)
259 (keyword . org-beamer-keyword)
260 (link . org-beamer-link)
261 (plain-list . org-beamer-plain-list)
262 (radio-target . org-beamer-radio-target)
263 (template . org-beamer-template)))
267 ;;; Transcode Functions
269 ;;;; Bold
271 (defun org-beamer-bold (bold contents _info)
272 "Transcode BLOCK object into Beamer code.
273 CONTENTS is the text being bold. INFO is a plist used as
274 a communication channel."
275 (format "\\alert%s{%s}"
276 (or (org-beamer--element-has-overlay-p bold) "")
277 contents))
280 ;;;; Export Block
282 (defun org-beamer-export-block (export-block _contents _info)
283 "Transcode an EXPORT-BLOCK element into Beamer code.
284 CONTENTS is nil. INFO is a plist used as a communication
285 channel."
286 (when (member (org-element-property :type export-block) '("BEAMER" "LATEX"))
287 (org-remove-indentation (org-element-property :value export-block))))
290 ;;;; Export Snippet
292 (defun org-beamer-export-snippet (export-snippet _contents info)
293 "Transcode an EXPORT-SNIPPET object into Beamer code.
294 CONTENTS is nil. INFO is a plist used as a communication
295 channel."
296 (let ((backend (org-export-snippet-backend export-snippet))
297 (value (org-element-property :value export-snippet)))
298 ;; Only "latex" and "beamer" snippets are retained.
299 (cond ((eq backend 'latex) value)
300 ;; Ignore "beamer" snippets specifying overlays.
301 ((and (eq backend 'beamer)
302 (or (org-export-get-previous-element export-snippet info)
303 (not (string-match "\\`<.*>\\'" value))))
304 value))))
307 ;;;; Headline
309 ;; The main function to translate a headline is
310 ;; `org-beamer-headline'.
312 ;; Depending on the level at which a headline is considered as
313 ;; a frame (given by `org-beamer--frame-level'), the headline is
314 ;; either a section (`org-beamer--format-section'), a frame
315 ;; (`org-beamer--format-frame') or a block
316 ;; (`org-beamer--format-block').
318 ;; `org-beamer-headline' also takes care of special environments
319 ;; like "ignoreheading", "note", "noteNH", "appendix" and
320 ;; "againframe".
322 (defun org-beamer--get-label (headline info)
323 "Return label for HEADLINE, as a string.
325 INFO is a plist used as a communication channel.
327 The value is either the label specified in \"BEAMER_opt\"
328 property, the custom ID, if there is one and
329 `:latex-prefer-user-labels' property has a non nil value, or
330 a unique internal label. This function assumes HEADLINE will be
331 treated as a frame."
332 (cond
333 ((let ((opt (org-element-property :BEAMER_OPT headline)))
334 (and (stringp opt)
335 (string-match "\\(?:^\\|,\\)label=\\(.*?\\)\\(?:$\\|,\\)" opt)
336 (let ((label (match-string 1 opt)))
337 (if (string-match-p "\\`{.*}\\'" label)
338 (substring label 1 -1)
339 label)))))
340 ((and (plist-get info :latex-prefer-user-labels)
341 (org-element-property :CUSTOM_ID headline)))
342 (t (format "sec:%s" (org-export-get-reference headline info)))))
344 (defun org-beamer--frame-level (headline info)
345 "Return frame level in subtree containing HEADLINE.
346 INFO is a plist used as a communication channel."
348 ;; 1. Look for "frame" environment in parents, starting from the
349 ;; farthest.
350 (catch 'exit
351 (dolist (parent (nreverse (org-element-lineage headline)))
352 (let ((env (org-element-property :BEAMER_ENV parent)))
353 (when (and env (member-ignore-case env '("frame" "fullframe")))
354 (throw 'exit (org-export-get-relative-level parent info))))))
355 ;; 2. Look for "frame" environment in HEADLINE.
356 (let ((env (org-element-property :BEAMER_ENV headline)))
357 (and env (member-ignore-case env '("frame" "fullframe"))
358 (org-export-get-relative-level headline info)))
359 ;; 3. Look for "frame" environment in sub-tree.
360 (org-element-map headline 'headline
361 (lambda (hl)
362 (let ((env (org-element-property :BEAMER_ENV hl)))
363 (when (and env (member-ignore-case env '("frame" "fullframe")))
364 (org-export-get-relative-level hl info))))
365 info 'first-match)
366 ;; 4. No "frame" environment in tree: use default value.
367 (plist-get info :headline-levels)))
369 (defun org-beamer--format-section (headline contents info)
370 "Format HEADLINE as a sectioning part.
371 CONTENTS holds the contents of the headline. INFO is a plist
372 used as a communication channel."
373 (let ((latex-headline
374 (org-export-with-backend
375 ;; We create a temporary export back-end which behaves the
376 ;; same as current one, but adds "\protect" in front of the
377 ;; output of some objects.
378 (org-export-create-backend
379 :parent 'latex
380 :transcoders
381 (let ((protected-output
382 (function
383 (lambda (object contents info)
384 (let ((code (org-export-with-backend
385 'beamer object contents info)))
386 (if (org-string-nw-p code) (concat "\\protect" code)
387 code))))))
388 (mapcar #'(lambda (type) (cons type protected-output))
389 '(bold footnote-reference italic strike-through timestamp
390 underline))))
391 headline
392 contents
393 info))
394 (mode-specs (org-element-property :BEAMER_ACT headline)))
395 (if (and mode-specs
396 (string-match "\\`\\\\\\(.*?\\)\\(?:\\*\\|\\[.*\\]\\)?{"
397 latex-headline))
398 ;; Insert overlay specifications.
399 (replace-match (concat (match-string 1 latex-headline)
400 (format "<%s>" mode-specs))
401 nil nil latex-headline 1)
402 latex-headline)))
404 (defun org-beamer--format-frame (headline contents info)
405 "Format HEADLINE as a frame.
406 CONTENTS holds the contents of the headline. INFO is a plist
407 used as a communication channel."
408 (let ((fragilep
409 ;; FRAGILEP is non-nil when HEADLINE contains an element
410 ;; among `org-beamer-verbatim-elements'.
411 (org-element-map headline org-beamer-verbatim-elements 'identity
412 info 'first-match)))
413 (concat "\\begin{frame}"
414 ;; Overlay specification, if any. When surrounded by
415 ;; square brackets, consider it as a default
416 ;; specification.
417 (let ((action (org-element-property :BEAMER_ACT headline)))
418 (cond
419 ((not action) "")
420 ((string-match "\\`\\[.*\\]\\'" action )
421 (org-beamer--normalize-argument action 'defaction))
422 (t (org-beamer--normalize-argument action 'action))))
423 ;; Options, if any.
424 (let* ((beamer-opt (org-element-property :BEAMER_OPT headline))
425 (options
426 ;; Collect options from default value and headline's
427 ;; properties. Also add a label for links.
428 (append
429 (org-split-string
430 (plist-get info :beamer-frame-default-options) ",")
431 (and beamer-opt
432 (org-split-string
433 ;; Remove square brackets if user provided
434 ;; them.
435 (and (string-match "^\\[?\\(.*\\)\\]?$" beamer-opt)
436 (match-string 1 beamer-opt))
437 ","))
438 ;; Provide an automatic label for the frame
439 ;; unless the user specified one. Also refrain
440 ;; from labeling `allowframebreaks' frames; this
441 ;; is not allowed by beamer.
442 (unless (and beamer-opt
443 (or (string-match "\\(^\\|,\\)label=" beamer-opt)
444 (string-match "allowframebreaks" beamer-opt)))
445 (list
446 (let ((label (org-beamer--get-label headline info)))
447 ;; Labels containing colons need to be
448 ;; wrapped within braces.
449 (format (if (string-match-p ":" label)
450 "label={%s}"
451 "label=%s")
452 label)))))))
453 ;; Change options list into a string.
454 (org-beamer--normalize-argument
455 (mapconcat
456 'identity
457 (if (or (not fragilep) (member "fragile" options)) options
458 (cons "fragile" options))
459 ",")
460 'option))
461 ;; Title.
462 (let ((env (org-element-property :BEAMER_ENV headline)))
463 (format "{%s}"
464 (if (and env (equal (downcase env) "fullframe")) ""
465 (org-export-data
466 (org-element-property :title headline) info))))
467 "\n"
468 ;; The following workaround is required in fragile frames
469 ;; as Beamer will append "\par" to the beginning of the
470 ;; contents. So we need to make sure the command is
471 ;; separated from the contents by at least one space. If
472 ;; it isn't, it will create "\parfirst-word" command and
473 ;; remove the first word from the contents in the PDF
474 ;; output.
475 (if (not fragilep) contents
476 (replace-regexp-in-string "\\`\n*" "\\& " (or contents "")))
477 "\\end{frame}")))
479 (defun org-beamer--format-block (headline contents info)
480 "Format HEADLINE as a block.
481 CONTENTS holds the contents of the headline. INFO is a plist
482 used as a communication channel."
483 (let* ((column-width (org-element-property :BEAMER_COL headline))
484 ;; ENVIRONMENT defaults to "block" if none is specified and
485 ;; there is no column specification. If there is a column
486 ;; specified but still no explicit environment, ENVIRONMENT
487 ;; is "column".
488 (environment (let ((env (org-element-property :BEAMER_ENV headline)))
489 (cond
490 ;; "block" is the fallback environment.
491 ((and (not env) (not column-width)) "block")
492 ;; "column" only.
493 ((not env) "column")
494 ;; Use specified environment.
495 (t env))))
496 (raw-title (org-element-property :raw-value headline))
497 (env-format
498 (cond ((member environment '("column" "columns")) nil)
499 ((assoc environment
500 (append (plist-get info :beamer-environments-extra)
501 org-beamer-environments-default)))
502 (t (user-error "Wrong block type at a headline named \"%s\""
503 raw-title))))
504 (title (org-export-data (org-element-property :title headline) info))
505 (raw-options (org-element-property :BEAMER_OPT headline))
506 (options (if raw-options
507 (org-beamer--normalize-argument raw-options 'option)
508 ""))
509 ;; Start a "columns" environment when explicitly requested or
510 ;; when there is no previous headline or the previous
511 ;; headline do not have a BEAMER_column property.
512 (parent-env (org-element-property
513 :BEAMER_ENV (org-export-get-parent-headline headline)))
514 (start-columns-p
515 (or (equal environment "columns")
516 (and column-width
517 (not (and parent-env
518 (equal (downcase parent-env) "columns")))
519 (or (org-export-first-sibling-p headline info)
520 (not (org-element-property
521 :BEAMER_COL
522 (org-export-get-previous-element
523 headline info)))))))
524 ;; End the "columns" environment when explicitly requested or
525 ;; when there is no next headline or the next headline do not
526 ;; have a BEAMER_column property.
527 (end-columns-p
528 (or (equal environment "columns")
529 (and column-width
530 (not (and parent-env
531 (equal (downcase parent-env) "columns")))
532 (or (org-export-last-sibling-p headline info)
533 (not (org-element-property
534 :BEAMER_COL
535 (org-export-get-next-element headline info))))))))
536 (concat
537 (when start-columns-p
538 ;; Column can accept options only when the environment is
539 ;; explicitly defined.
540 (if (not (equal environment "columns")) "\\begin{columns}\n"
541 (format "\\begin{columns}%s\n" options)))
542 (when column-width
543 (format "\\begin{column}%s{%s}\n"
544 ;; One can specify placement for column only when
545 ;; HEADLINE stands for a column on its own.
546 (if (equal environment "column") options "")
547 (format "%s\\columnwidth" column-width)))
548 ;; Block's opening string.
549 (when (nth 2 env-format)
550 (concat
551 (org-fill-template
552 (nth 2 env-format)
553 (nconc
554 ;; If BEAMER_act property has its value enclosed in square
555 ;; brackets, it is a default overlay specification and
556 ;; overlay specification is empty. Otherwise, it is an
557 ;; overlay specification and the default one is nil.
558 (let ((action (org-element-property :BEAMER_ACT headline)))
559 (cond
560 ((not action) (list (cons "a" "") (cons "A" "") (cons "R" "")))
561 ((and (string-prefix-p "[" action)
562 (string-suffix-p "]" action))
563 (list
564 (cons "A" (org-beamer--normalize-argument action 'defaction))
565 (cons "a" "")
566 (cons "R" action)))
568 (list (cons "a" (org-beamer--normalize-argument action 'action))
569 (cons "A" "")
570 (cons "R" action)))))
571 (list (cons "o" options)
572 (cons "O" (or raw-options ""))
573 (cons "h" title)
574 (cons "r" raw-title)
575 (cons "H" (if (equal raw-title "") ""
576 (format "{%s}" raw-title)))
577 (cons "U" (if (equal raw-title "") ""
578 (format "[%s]" raw-title))))))
579 "\n"))
580 contents
581 ;; Block's closing string, if any.
582 (and (nth 3 env-format) (concat (nth 3 env-format) "\n"))
583 (when column-width "\\end{column}\n")
584 (when end-columns-p "\\end{columns}"))))
586 (defun org-beamer-headline (headline contents info)
587 "Transcode HEADLINE element into Beamer code.
588 CONTENTS is the contents of the headline. INFO is a plist used
589 as a communication channel."
590 (unless (org-element-property :footnote-section-p headline)
591 (let ((level (org-export-get-relative-level headline info))
592 (frame-level (org-beamer--frame-level headline info))
593 (environment (let ((env (org-element-property :BEAMER_ENV headline)))
594 (or (org-string-nw-p env) "block"))))
595 (cond
596 ;; Case 1: Resume frame specified by "BEAMER_ref" property.
597 ((equal environment "againframe")
598 (let ((ref (org-element-property :BEAMER_REF headline)))
599 ;; Reference to frame being resumed is mandatory. Ignore
600 ;; the whole headline if it isn't provided.
601 (when (org-string-nw-p ref)
602 (concat "\\againframe"
603 ;; Overlay specification.
604 (let ((overlay (org-element-property :BEAMER_ACT headline)))
605 (when overlay
606 (org-beamer--normalize-argument
607 overlay
608 (if (string-match "\\`\\[.*\\]\\'" overlay) 'defaction
609 'action))))
610 ;; Options.
611 (let ((options (org-element-property :BEAMER_OPT headline)))
612 (when options
613 (org-beamer--normalize-argument options 'option)))
614 ;; Resolve reference provided by "BEAMER_ref"
615 ;; property. This is done by building a minimal
616 ;; fake link and calling the appropriate resolve
617 ;; function, depending on the reference syntax.
618 (let ((target
619 (if (string-match "\\`\\(id:\\|#\\)" ref)
620 (org-export-resolve-id-link
621 `(link (:path ,(substring ref (match-end 0))))
622 info)
623 (org-export-resolve-fuzzy-link
624 `(link (:path
625 ;; Look for headlines only.
626 ,(if (eq (string-to-char ref) ?*) ref
627 (concat "*" ref))))
628 info))))
629 ;; Now use user-defined label provided in TARGET
630 ;; headline, or fallback to standard one.
631 (format "{%s}" (org-beamer--get-label target info)))))))
632 ;; Case 2: Creation of an appendix is requested.
633 ((equal environment "appendix")
634 (concat "\\appendix"
635 (org-element-property :BEAMER_ACT headline)
636 "\n"
637 (make-string (org-element-property :pre-blank headline) ?\n)
638 contents))
639 ;; Case 3: Ignore heading.
640 ((equal environment "ignoreheading")
641 (concat (make-string (org-element-property :pre-blank headline) ?\n)
642 contents))
643 ;; Case 4: HEADLINE is a note.
644 ((member environment '("note" "noteNH"))
645 (format "\\note{%s}"
646 (concat (and (equal environment "note")
647 (concat
648 (org-export-data
649 (org-element-property :title headline) info)
650 "\n"))
651 (org-trim contents))))
652 ;; Case 5: HEADLINE is a frame.
653 ((= level frame-level)
654 (org-beamer--format-frame headline contents info))
655 ;; Case 6: Regular section, extracted from
656 ;; `org-latex-classes'.
657 ((< level frame-level)
658 (org-beamer--format-section headline contents info))
659 ;; Case 7: Otherwise, HEADLINE is a block.
660 (t (org-beamer--format-block headline contents info))))))
663 ;;;; Item
665 (defun org-beamer-item (item contents info)
666 "Transcode an ITEM element into Beamer code.
667 CONTENTS holds the contents of the item. INFO is a plist holding
668 contextual information."
669 (org-export-with-backend
670 ;; Delegate item export to `latex'. However, we use `beamer'
671 ;; transcoders for objects in the description tag.
672 (org-export-create-backend
673 :parent 'beamer
674 :transcoders
675 (list
676 (cons
677 'item
678 (lambda (item _c _i)
679 (let ((action
680 (let ((first (car (org-element-contents item))))
681 (and (eq (org-element-type first) 'paragraph)
682 (org-beamer--element-has-overlay-p first))))
683 (output (org-latex-item item contents info)))
684 (if (not (and action (string-match "\\\\item" output))) output
685 ;; If the item starts with a paragraph and that paragraph
686 ;; starts with an export snippet specifying an overlay,
687 ;; append it to the \item command.
688 (replace-match (concat "\\\\item" action) nil nil output)))))))
689 item contents info))
692 ;;;; Keyword
694 (defun org-beamer-keyword (keyword contents info)
695 "Transcode a KEYWORD element into Beamer code.
696 CONTENTS is nil. INFO is a plist used as a communication
697 channel."
698 (let ((key (org-element-property :key keyword))
699 (value (org-element-property :value keyword)))
700 ;; Handle specifically BEAMER and TOC (headlines only) keywords.
701 ;; Otherwise, fallback to `latex' back-end.
702 (cond
703 ((equal key "BEAMER") value)
704 ((and (equal key "TOC") (string-match "\\<headlines\\>" value))
705 (let ((depth (or (and (string-match "[0-9]+" value)
706 (string-to-number (match-string 0 value)))
707 (plist-get info :with-toc)))
708 (options (and (string-match "\\[.*?\\]" value)
709 (match-string 0 value))))
710 (concat
711 (when (wholenump depth) (format "\\setcounter{tocdepth}{%s}\n" depth))
712 "\\tableofcontents" options)))
713 (t (org-export-with-backend 'latex keyword contents info)))))
716 ;;;; Link
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 (or (org-export-custom-protocol-maybe link contents 'beamer)
723 ;; Fall-back to LaTeX export. However, prefer "\hyperlink" over
724 ;; "\hyperref" since the former handles overlay specifications.
725 (let ((latex-link (org-export-with-backend 'latex link contents info)))
726 (if (string-match "\\`\\\\hyperref\\[\\(.*?\\)\\]" latex-link)
727 (replace-match
728 (format "\\\\hyperlink%s{\\1}"
729 (or (org-beamer--element-has-overlay-p link) ""))
730 nil nil latex-link)
731 latex-link))))
734 ;;;; Plain List
736 ;; Plain lists support `:environment', `:overlay' and `:options'
737 ;; attributes.
739 (defun org-beamer-plain-list (plain-list contents info)
740 "Transcode a PLAIN-LIST element into Beamer code.
741 CONTENTS is the contents of the list. INFO is a plist holding
742 contextual information."
743 (let* ((type (org-element-property :type plain-list))
744 (attributes (org-combine-plists
745 (org-export-read-attribute :attr_latex plain-list)
746 (org-export-read-attribute :attr_beamer plain-list)))
747 (latex-type (let ((env (plist-get attributes :environment)))
748 (cond (env)
749 ((eq type 'ordered) "enumerate")
750 ((eq type 'descriptive) "description")
751 (t "itemize")))))
752 (org-latex--wrap-label
753 plain-list
754 (format "\\begin{%s}%s%s\n%s\\end{%s}"
755 latex-type
756 ;; Default overlay specification, if any.
757 (org-beamer--normalize-argument
758 (or (plist-get attributes :overlay) "")
759 'defaction)
760 ;; Second optional argument depends on the list type.
761 (org-beamer--normalize-argument
762 (or (plist-get attributes :options) "")
763 'option)
764 ;; Eventually insert contents and close environment.
765 contents
766 latex-type)
767 info)))
770 ;;;; Radio Target
772 (defun org-beamer-radio-target (radio-target text info)
773 "Transcode a RADIO-TARGET object into Beamer code.
774 TEXT is the text of the target. INFO is a plist holding
775 contextual information."
776 (format "\\hypertarget%s{%s}{%s}"
777 (or (org-beamer--element-has-overlay-p radio-target) "")
778 (org-export-get-reference radio-target info)
779 text))
782 ;;;; Template
784 ;; Template used is similar to the one used in `latex' back-end,
785 ;; excepted for the table of contents and Beamer themes.
787 (defun org-beamer-template (contents info)
788 "Return complete document string after Beamer conversion.
789 CONTENTS is the transcoded contents string. INFO is a plist
790 holding export options."
791 (let ((title (org-export-data (plist-get info :title) info))
792 (subtitle (org-export-data (plist-get info :subtitle) info)))
793 (concat
794 ;; Time-stamp.
795 (and (plist-get info :time-stamp-file)
796 (format-time-string "%% Created %Y-%m-%d %a %H:%M\n"))
797 ;; LaTeX compiler
798 (org-latex--insert-compiler info)
799 ;; Document class and packages.
800 (org-latex-make-preamble info)
801 ;; Insert themes.
802 (let ((format-theme
803 (function
804 (lambda (prop command)
805 (let ((theme (plist-get info prop)))
806 (when theme
807 (concat command
808 (if (not (string-match "\\[.*\\]" theme))
809 (format "{%s}\n" theme)
810 (format "%s{%s}\n"
811 (match-string 0 theme)
812 (org-trim
813 (replace-match "" nil nil theme)))))))))))
814 (mapconcat (lambda (args) (apply format-theme args))
815 '((:beamer-theme "\\usetheme")
816 (:beamer-color-theme "\\usecolortheme")
817 (:beamer-font-theme "\\usefonttheme")
818 (:beamer-inner-theme "\\useinnertheme")
819 (:beamer-outer-theme "\\useoutertheme"))
820 ""))
821 ;; Possibly limit depth for headline numbering.
822 (let ((sec-num (plist-get info :section-numbers)))
823 (when (integerp sec-num)
824 (format "\\setcounter{secnumdepth}{%d}\n" sec-num)))
825 ;; Author.
826 (let ((author (and (plist-get info :with-author)
827 (let ((auth (plist-get info :author)))
828 (and auth (org-export-data auth info)))))
829 (email (and (plist-get info :with-email)
830 (org-export-data (plist-get info :email) info))))
831 (cond ((and author email (not (string= "" email)))
832 (format "\\author{%s\\thanks{%s}}\n" author email))
833 ((or author email) (format "\\author{%s}\n" (or author email)))))
834 ;; Date.
835 (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
836 (format "\\date{%s}\n" (org-export-data date info)))
837 ;; Title
838 (format "\\title{%s}\n" title)
839 (when (org-string-nw-p subtitle)
840 (concat (format (plist-get info :beamer-subtitle-format) subtitle) "\n"))
841 ;; Beamer-header
842 (let ((beamer-header (plist-get info :beamer-header)))
843 (when beamer-header
844 (format "%s\n" (plist-get info :beamer-header))))
845 ;; 9. Hyperref options.
846 (let ((template (plist-get info :latex-hyperref-template)))
847 (and (stringp template)
848 (format-spec template (org-latex--format-spec info))))
849 ;; Document start.
850 "\\begin{document}\n\n"
851 ;; Title command.
852 (org-element-normalize-string
853 (cond ((not (plist-get info :with-title)) nil)
854 ((string= "" title) nil)
855 ((not (stringp org-latex-title-command)) nil)
856 ((string-match "\\(?:[^%]\\|^\\)%s"
857 org-latex-title-command)
858 (format org-latex-title-command title))
859 (t org-latex-title-command)))
860 ;; Table of contents.
861 (let ((depth (plist-get info :with-toc)))
862 (when depth
863 (concat
864 (format "\\begin{frame}%s{%s}\n"
865 (org-beamer--normalize-argument
866 (plist-get info :beamer-outline-frame-options) 'option)
867 (plist-get info :beamer-outline-frame-title))
868 (when (wholenump depth)
869 (format "\\setcounter{tocdepth}{%d}\n" depth))
870 "\\tableofcontents\n"
871 "\\end{frame}\n\n")))
872 ;; Document's body.
873 contents
874 ;; Creator.
875 (if (plist-get info :with-creator)
876 (concat (plist-get info :creator) "\n")
878 ;; Document end.
879 "\\end{document}")))
883 ;;; Minor Mode
886 (defvar org-beamer-mode-map (make-sparse-keymap)
887 "The keymap for `org-beamer-mode'.")
888 (define-key org-beamer-mode-map "\C-c\C-b" 'org-beamer-select-environment)
890 ;;;###autoload
891 (define-minor-mode org-beamer-mode
892 "Support for editing Beamer oriented Org mode files."
893 nil " Bm" 'org-beamer-mode-map)
895 (when (fboundp 'font-lock-add-keywords)
896 (font-lock-add-keywords
897 'org-mode
898 '((":\\(B_[a-z]+\\|BMCOL\\):" 1 'org-beamer-tag prepend))
899 'prepend))
901 (defface org-beamer-tag '((t (:box (:line-width 1 :color grey40))))
902 "The special face for beamer tags."
903 :group 'org-export-beamer)
905 (defun org-beamer-property-changed (property value)
906 "Track the BEAMER_env property with tags.
907 PROPERTY is the name of the modified property. VALUE is its new
908 value."
909 (cond
910 ((equal property "BEAMER_env")
911 (save-excursion
912 (org-back-to-heading t)
913 ;; Filter out Beamer-related tags and install environment tag.
914 (let ((tags (cl-remove-if (lambda (x) (string-match "^B_" x))
915 (org-get-tags)))
916 (env-tag (and (org-string-nw-p value) (concat "B_" value))))
917 (org-set-tags-to (if env-tag (cons env-tag tags) tags))
918 (when env-tag (org-toggle-tag env-tag 'on)))))
919 ((equal property "BEAMER_col")
920 (org-toggle-tag "BMCOL" (if (org-string-nw-p value) 'on 'off)))))
922 (add-hook 'org-property-changed-functions 'org-beamer-property-changed)
924 (defun org-beamer-allowed-property-values (property)
925 "Supply allowed values for PROPERTY."
926 (cond
927 ((and (equal property "BEAMER_env")
928 (not (org-entry-get nil (concat property "_ALL") 'inherit)))
929 ;; If no allowed values for BEAMER_env have been defined,
930 ;; supply all defined environments
931 (mapcar 'car (append org-beamer-environments-special
932 org-beamer-environments-extra
933 org-beamer-environments-default)))
934 ((and (equal property "BEAMER_col")
935 (not (org-entry-get nil (concat property "_ALL") 'inherit)))
936 ;; If no allowed values for BEAMER_col have been defined,
937 ;; supply some
938 (org-split-string org-beamer-column-widths " "))))
940 (add-hook 'org-property-allowed-value-functions
941 'org-beamer-allowed-property-values)
945 ;;; Commands
947 ;;;###autoload
948 (defun org-beamer-export-as-latex
949 (&optional async subtreep visible-only body-only ext-plist)
950 "Export current buffer as a Beamer buffer.
952 If narrowing is active in the current buffer, only export its
953 narrowed part.
955 If a region is active, export that region.
957 A non-nil optional argument ASYNC means the process should happen
958 asynchronously. The resulting buffer should be accessible
959 through the `org-export-stack' interface.
961 When optional argument SUBTREEP is non-nil, export the sub-tree
962 at point, extracting information from the headline properties
963 first.
965 When optional argument VISIBLE-ONLY is non-nil, don't export
966 contents of hidden elements.
968 When optional argument BODY-ONLY is non-nil, only write code
969 between \"\\begin{document}\" and \"\\end{document}\".
971 EXT-PLIST, when provided, is a property list with external
972 parameters overriding Org default settings, but still inferior to
973 file-local settings.
975 Export is done in a buffer named \"*Org BEAMER Export*\", which
976 will be displayed when `org-export-show-temporary-export-buffer'
977 is non-nil."
978 (interactive)
979 (org-export-to-buffer 'beamer "*Org BEAMER Export*"
980 async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode))))
982 ;;;###autoload
983 (defun org-beamer-export-to-latex
984 (&optional async subtreep visible-only body-only ext-plist)
985 "Export current buffer as a Beamer presentation (tex).
987 If narrowing is active in the current buffer, only export its
988 narrowed part.
990 If a region is active, export that region.
992 A non-nil optional argument ASYNC means the process should happen
993 asynchronously. The resulting file should be accessible through
994 the `org-export-stack' interface.
996 When optional argument SUBTREEP is non-nil, export the sub-tree
997 at point, extracting information from the headline properties
998 first.
1000 When optional argument VISIBLE-ONLY is non-nil, don't export
1001 contents of hidden elements.
1003 When optional argument BODY-ONLY is non-nil, only write code
1004 between \"\\begin{document}\" and \"\\end{document}\".
1006 EXT-PLIST, when provided, is a property list with external
1007 parameters overriding Org default settings, but still inferior to
1008 file-local settings.
1010 Return output file's name."
1011 (interactive)
1012 (let ((file (org-export-output-file-name ".tex" subtreep)))
1013 (org-export-to-file 'beamer file
1014 async subtreep visible-only body-only ext-plist)))
1016 ;;;###autoload
1017 (defun org-beamer-export-to-pdf
1018 (&optional async subtreep visible-only body-only ext-plist)
1019 "Export current buffer as a Beamer presentation (PDF).
1021 If narrowing is active in the current buffer, only export its
1022 narrowed part.
1024 If a region is active, export that region.
1026 A non-nil optional argument ASYNC means the process should happen
1027 asynchronously. The resulting file should be accessible through
1028 the `org-export-stack' interface.
1030 When optional argument SUBTREEP is non-nil, export the sub-tree
1031 at point, extracting information from the headline properties
1032 first.
1034 When optional argument VISIBLE-ONLY is non-nil, don't export
1035 contents of hidden elements.
1037 When optional argument BODY-ONLY is non-nil, only write code
1038 between \"\\begin{document}\" and \"\\end{document}\".
1040 EXT-PLIST, when provided, is a property list with external
1041 parameters overriding Org default settings, but still inferior to
1042 file-local settings.
1044 Return PDF file's name."
1045 (interactive)
1046 (let ((file (org-export-output-file-name ".tex" subtreep)))
1047 (org-export-to-file 'beamer file
1048 async subtreep visible-only body-only ext-plist
1049 (lambda (file) (org-latex-compile file)))))
1051 ;;;###autoload
1052 (defun org-beamer-select-environment ()
1053 "Select the environment to be used by beamer for this entry.
1054 While this uses (for convenience) a tag selection interface, the
1055 result of this command will be that the BEAMER_env *property* of
1056 the entry is set.
1058 In addition to this, the command will also set a tag as a visual
1059 aid, but the tag does not have any semantic meaning."
1060 (interactive)
1061 ;; Make sure `org-beamer-environments-special' has a higher
1062 ;; priority than `org-beamer-environments-extra'.
1063 (let* ((envs (append org-beamer-environments-special
1064 org-beamer-environments-extra
1065 org-beamer-environments-default))
1066 (org-current-tag-alist
1067 (append '((:startgroup))
1068 (mapcar (lambda (e) (cons (concat "B_" (car e))
1069 (string-to-char (nth 1 e))))
1070 envs)
1071 '((:endgroup))
1072 '(("BMCOL" . ?|))))
1073 (org-tag-persistent-alist nil)
1074 (org-use-fast-tag-selection t)
1075 (org-fast-tag-selection-single-key t))
1076 (org-set-tags)
1077 (let ((tags (or (ignore-errors (org-get-tags-string)) "")))
1078 (cond
1079 ;; For a column, automatically ask for its width.
1080 ((eq org-last-tag-selection-key ?|)
1081 (if (string-match ":BMCOL:" tags)
1082 (org-set-property "BEAMER_col" (read-string "Column width: "))
1083 (org-delete-property "BEAMER_col")))
1084 ;; For an "againframe" section, automatically ask for reference
1085 ;; to resumed frame and overlay specifications.
1086 ((eq org-last-tag-selection-key ?A)
1087 (if (equal (org-entry-get nil "BEAMER_env") "againframe")
1088 (progn (org-entry-delete nil "BEAMER_env")
1089 (org-entry-delete nil "BEAMER_ref")
1090 (org-entry-delete nil "BEAMER_act"))
1091 (org-entry-put nil "BEAMER_env" "againframe")
1092 (org-set-property
1093 "BEAMER_ref"
1094 (read-string "Frame reference (*Title, #custom-id, id:...): "))
1095 (org-set-property "BEAMER_act"
1096 (read-string "Overlay specification: "))))
1097 ((string-match (concat ":B_\\(" (mapconcat 'car envs "\\|") "\\):") tags)
1098 (org-entry-put nil "BEAMER_env" (match-string 1 tags)))
1099 (t (org-entry-delete nil "BEAMER_env"))))))
1101 ;;;###autoload
1102 (defun org-beamer-publish-to-latex (plist filename pub-dir)
1103 "Publish an Org file to a Beamer presentation (LaTeX).
1105 FILENAME is the filename of the Org file to be published. PLIST
1106 is the property list for the given project. PUB-DIR is the
1107 publishing directory.
1109 Return output file name."
1110 (org-publish-org-to 'beamer filename ".tex" plist pub-dir))
1112 ;;;###autoload
1113 (defun org-beamer-publish-to-pdf (plist filename pub-dir)
1114 "Publish an Org file to a Beamer presentation (PDF, via LaTeX).
1116 FILENAME is the filename of the Org file to be published. PLIST
1117 is the property list for the given project. PUB-DIR is the
1118 publishing directory.
1120 Return output file name."
1121 ;; Unlike to `org-beamer-publish-to-latex', PDF file is generated in
1122 ;; working directory and then moved to publishing directory.
1123 (org-publish-attachment
1124 plist
1125 ;; Default directory could be anywhere when this function is
1126 ;; called. We ensure it is set to source file directory during
1127 ;; compilation so as to not break links to external documents.
1128 (let ((default-directory (file-name-directory filename)))
1129 (org-latex-compile
1130 (org-publish-org-to
1131 'beamer filename ".tex" plist (file-name-directory filename))))
1132 pub-dir))
1135 (provide 'ox-beamer)
1137 ;; Local variables:
1138 ;; generated-autoload-file: "org-loaddefs.el"
1139 ;; End:
1141 ;;; ox-beamer.el ends here