ob-core: Allow never-export as :eval value
[org-mode/org-tableheadings.git] / lisp / ox-beamer.el
blob3306a6d2846c888172d7c48824dc809341245b16
1 ;;; ox-beamer.el --- Beamer Back-End for Org Export Engine
3 ;; Copyright (C) 2007-2015 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 (eval-when-compile (require 'cl))
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 %o the options argument of the template
109 %h the headline text
110 %r the raw headline text (i.e. without any processing)
111 %H if there is headline text, that raw text in {} braces
112 %U if there is headline text, that raw text in [] brackets
113 close The closing string of the environment."
114 :group 'org-export-beamer
115 :version "24.4"
116 :package-version '(Org . "8.1")
117 :type '(repeat
118 (list
119 (string :tag "Environment")
120 (string :tag "Selection key")
121 (string :tag "Begin")
122 (string :tag "End"))))
124 (defcustom org-beamer-outline-frame-title "Outline"
125 "Default title of a frame containing an outline."
126 :group 'org-export-beamer
127 :type '(string :tag "Outline frame title"))
129 (defcustom org-beamer-outline-frame-options ""
130 "Outline frame options appended after \\begin{frame}.
131 You might want to put e.g. \"allowframebreaks=0.9\" here."
132 :group 'org-export-beamer
133 :type '(string :tag "Outline frame options"))
136 (defcustom org-beamer-subtitle-format "\\subtitle{%s}"
137 "Format string used for transcoded subtitle.
138 The format string should have at most one \"%s\"-expression,
139 which is replaced with the subtitle."
140 :group 'org-export-beamer
141 :version "25.1"
142 :package-version '(Org . "8.3")
143 :type '(string :tag "Format string"))
146 ;;; Internal Variables
148 (defconst org-beamer-column-widths
149 "0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 0.0 :ETC"
150 "The column widths that should be installed as allowed property values.")
152 (defconst org-beamer-environments-special
153 '(("againframe" "A")
154 ("appendix" "x")
155 ("column" "c")
156 ("columns" "C")
157 ("frame" "f")
158 ("fullframe" "F")
159 ("ignoreheading" "i")
160 ("note" "n")
161 ("noteNH" "N"))
162 "Alist of environments treated in a special way by the back-end.
163 Keys are environment names, as strings, values are bindings used
164 in `org-beamer-select-environment'. Environments listed here,
165 along with their binding, are hard coded and cannot be modified
166 through `org-beamer-environments-extra' variable.")
168 (defconst org-beamer-environments-default
169 '(("block" "b" "\\begin{block}%a{%h}" "\\end{block}")
170 ("alertblock" "a" "\\begin{alertblock}%a{%h}" "\\end{alertblock}")
171 ("verse" "v" "\\begin{verse}%a %% %h" "\\end{verse}")
172 ("quotation" "q" "\\begin{quotation}%a %% %h" "\\end{quotation}")
173 ("quote" "Q" "\\begin{quote}%a %% %h" "\\end{quote}")
174 ("structureenv" "s" "\\begin{structureenv}%a %% %h" "\\end{structureenv}")
175 ("theorem" "t" "\\begin{theorem}%a%U" "\\end{theorem}")
176 ("definition" "d" "\\begin{definition}%a%U" "\\end{definition}")
177 ("example" "e" "\\begin{example}%a%U" "\\end{example}")
178 ("exampleblock" "E" "\\begin{exampleblock}%a{%h}" "\\end{exampleblock}")
179 ("proof" "p" "\\begin{proof}%a%U" "\\end{proof}")
180 ("beamercolorbox" "o" "\\begin{beamercolorbox}%o{%h}" "\\end{beamercolorbox}"))
181 "Environments triggered by properties in Beamer export.
182 These are the defaults - for user definitions, see
183 `org-beamer-environments-extra'.")
185 (defconst org-beamer-verbatim-elements
186 '(code example-block fixed-width inline-src-block src-block verbatim)
187 "List of element or object types producing verbatim text.
188 This is used internally to determine when a frame should have the
189 \"fragile\" option.")
193 ;;; Internal functions
195 (defun org-beamer--normalize-argument (argument type)
196 "Return ARGUMENT string with proper boundaries.
198 TYPE is a symbol among the following:
199 `action' Return ARGUMENT within angular brackets.
200 `defaction' Return ARGUMENT within both square and angular brackets.
201 `option' Return ARGUMENT within square brackets."
202 (if (not (string-match "\\S-" argument)) ""
203 (case type
204 (action (if (string-match "\\`<.*>\\'" argument) argument
205 (format "<%s>" argument)))
206 (defaction (cond
207 ((string-match "\\`\\[<.*>\\]\\'" argument) argument)
208 ((string-match "\\`<.*>\\'" argument)
209 (format "[%s]" argument))
210 ((string-match "\\`\\[\\(.*\\)\\]\\'" argument)
211 (format "[<%s>]" (match-string 1 argument)))
212 (t (format "[<%s>]" argument))))
213 (option (if (string-match "\\`\\[.*\\]\\'" argument) argument
214 (format "[%s]" argument)))
215 (otherwise argument))))
217 (defun org-beamer--element-has-overlay-p (element)
218 "Non-nil when ELEMENT has an overlay specified.
219 An element has an overlay specification when it starts with an
220 `beamer' export-snippet whose value is between angular brackets.
221 Return overlay specification, as a string, or nil."
222 (let ((first-object (car (org-element-contents element))))
223 (when (eq (org-element-type first-object) 'export-snippet)
224 (let ((value (org-element-property :value first-object)))
225 (and (string-match "\\`<.*>\\'" value) value)))))
229 ;;; Define Back-End
231 (org-export-define-derived-backend 'beamer 'latex
232 :export-block "BEAMER"
233 :menu-entry
234 '(?l 1
235 ((?B "As LaTeX buffer (Beamer)" org-beamer-export-as-latex)
236 (?b "As LaTeX file (Beamer)" org-beamer-export-to-latex)
237 (?P "As PDF file (Beamer)" org-beamer-export-to-pdf)
238 (?O "As PDF file and open (Beamer)"
239 (lambda (a s v b)
240 (if a (org-beamer-export-to-pdf t s v b)
241 (org-open-file (org-beamer-export-to-pdf nil s v b)))))))
242 :options-alist
243 '((:headline-levels nil "H" org-beamer-frame-level)
244 (:latex-class "LATEX_CLASS" nil "beamer" t)
245 (:beamer-subtitle-format nil nil org-beamer-subtitle-format)
246 (:beamer-column-view-format "COLUMNS" nil org-beamer-column-view-format)
247 (:beamer-theme "BEAMER_THEME" nil org-beamer-theme)
248 (:beamer-color-theme "BEAMER_COLOR_THEME" nil nil t)
249 (:beamer-font-theme "BEAMER_FONT_THEME" nil nil t)
250 (:beamer-inner-theme "BEAMER_INNER_THEME" nil nil t)
251 (:beamer-outer-theme "BEAMER_OUTER_THEME" nil nil t)
252 (:beamer-header "BEAMER_HEADER" nil nil newline)
253 (:beamer-environments-extra nil nil org-beamer-environments-extra)
254 (:beamer-frame-default-options nil nil org-beamer-frame-default-options)
255 (:beamer-outline-frame-options nil nil org-beamer-outline-frame-options)
256 (:beamer-outline-frame-title nil nil org-beamer-outline-frame-title))
257 :translate-alist '((bold . org-beamer-bold)
258 (export-block . org-beamer-export-block)
259 (export-snippet . org-beamer-export-snippet)
260 (headline . org-beamer-headline)
261 (item . org-beamer-item)
262 (keyword . org-beamer-keyword)
263 (link . org-beamer-link)
264 (plain-list . org-beamer-plain-list)
265 (radio-target . org-beamer-radio-target)
266 (target . org-beamer-target)
267 (template . org-beamer-template)))
271 ;;; Transcode Functions
273 ;;;; Bold
275 (defun org-beamer-bold (bold contents info)
276 "Transcode BLOCK object into Beamer code.
277 CONTENTS is the text being bold. INFO is a plist used as
278 a communication channel."
279 (format "\\alert%s{%s}"
280 (or (org-beamer--element-has-overlay-p bold) "")
281 contents))
284 ;;;; Export Block
286 (defun org-beamer-export-block (export-block contents info)
287 "Transcode an EXPORT-BLOCK element into Beamer code.
288 CONTENTS is nil. INFO is a plist used as a communication
289 channel."
290 (when (member (org-element-property :type export-block) '("BEAMER" "LATEX"))
291 (org-remove-indentation (org-element-property :value export-block))))
294 ;;;; Export Snippet
296 (defun org-beamer-export-snippet (export-snippet contents info)
297 "Transcode an EXPORT-SNIPPET object into Beamer code.
298 CONTENTS is nil. INFO is a plist used as a communication
299 channel."
300 (let ((backend (org-export-snippet-backend export-snippet))
301 (value (org-element-property :value export-snippet)))
302 ;; Only "latex" and "beamer" snippets are retained.
303 (cond ((eq backend 'latex) value)
304 ;; Ignore "beamer" snippets specifying overlays.
305 ((and (eq backend 'beamer)
306 (or (org-export-get-previous-element export-snippet info)
307 (not (string-match "\\`<.*>\\'" value))))
308 value))))
311 ;;;; Headline
313 ;; The main function to translate a headline is
314 ;; `org-beamer-headline'.
316 ;; Depending on the level at which a headline is considered as
317 ;; a frame (given by `org-beamer--frame-level'), the headline is
318 ;; either a section (`org-beamer--format-section'), a frame
319 ;; (`org-beamer--format-frame') or a block
320 ;; (`org-beamer--format-block').
322 ;; `org-beamer-headline' also takes care of special environments
323 ;; like "ignoreheading", "note", "noteNH", "appendix" and
324 ;; "againframe".
326 (defun org-beamer--get-label (headline info)
327 "Return label for HEADLINE, as a string.
329 INFO is a plist used as a communication channel.
331 The value is either the label specified in \"BEAMER_opt\"
332 property, or a fallback value built from headline's number. This
333 function assumes HEADLINE will be treated as a frame."
334 (let ((opt (org-element-property :BEAMER_OPT headline)))
335 (if (and (org-string-nw-p opt)
336 (string-match "\\(?:^\\|,\\)label=\\(.*?\\)\\(?:$\\|,\\)" opt))
337 (match-string 1 opt)
338 (format "sec-%s"
339 (mapconcat 'number-to-string
340 (org-export-get-headline-number headline info)
341 "-")))))
343 (defun org-beamer--frame-level (headline info)
344 "Return frame level in subtree containing HEADLINE.
345 INFO is a plist used as a communication channel."
347 ;; 1. Look for "frame" environment in parents, starting from the
348 ;; farthest.
349 (catch 'exit
350 (dolist (parent (nreverse (org-element-lineage headline)))
351 (let ((env (org-element-property :BEAMER_ENV parent)))
352 (when (and env (member-ignore-case env '("frame" "fullframe")))
353 (throw 'exit (org-export-get-relative-level parent info))))))
354 ;; 2. Look for "frame" environment in HEADLINE.
355 (let ((env (org-element-property :BEAMER_ENV headline)))
356 (and env (member-ignore-case env '("frame" "fullframe"))
357 (org-export-get-relative-level headline info)))
358 ;; 3. Look for "frame" environment in sub-tree.
359 (org-element-map headline 'headline
360 (lambda (hl)
361 (let ((env (org-element-property :BEAMER_ENV hl)))
362 (when (and env (member-ignore-case env '("frame" "fullframe")))
363 (org-export-get-relative-level hl info))))
364 info 'first-match)
365 ;; 4. No "frame" environment in tree: use default value.
366 (plist-get info :headline-levels)))
368 (defun org-beamer--format-section (headline contents info)
369 "Format HEADLINE as a sectioning part.
370 CONTENTS holds the contents of the headline. INFO is a plist
371 used as a communication channel."
372 (let ((latex-headline
373 (org-export-with-backend
374 ;; We create a temporary export back-end which behaves the
375 ;; same as current one, but adds "\protect" in front of the
376 ;; output of some objects.
377 (org-export-create-backend
378 :parent 'latex
379 :transcoders
380 (let ((protected-output
381 (function
382 (lambda (object contents info)
383 (let ((code (org-export-with-backend
384 'beamer object contents info)))
385 (if (org-string-nw-p code) (concat "\\protect" code)
386 code))))))
387 (mapcar #'(lambda (type) (cons type protected-output))
388 '(bold footnote-reference italic strike-through timestamp
389 underline))))
390 headline
391 contents
392 info))
393 (mode-specs (org-element-property :BEAMER_ACT headline)))
394 (if (and mode-specs
395 (string-match "\\`\\\\\\(.*?\\)\\(?:\\*\\|\\[.*\\]\\)?{"
396 latex-headline))
397 ;; Insert overlay specifications.
398 (replace-match (concat (match-string 1 latex-headline)
399 (format "<%s>" mode-specs))
400 nil nil latex-headline 1)
401 latex-headline)))
403 (defun org-beamer--format-frame (headline contents info)
404 "Format HEADLINE as a frame.
405 CONTENTS holds the contents of the headline. INFO is a plist
406 used as a communication channel."
407 (let ((fragilep
408 ;; FRAGILEP is non-nil when HEADLINE contains an element
409 ;; among `org-beamer-verbatim-elements'.
410 (org-element-map headline org-beamer-verbatim-elements 'identity
411 info 'first-match)))
412 (concat "\\begin{frame}"
413 ;; Overlay specification, if any. When surrounded by
414 ;; square brackets, consider it as a default
415 ;; specification.
416 (let ((action (org-element-property :BEAMER_ACT headline)))
417 (cond
418 ((not action) "")
419 ((string-match "\\`\\[.*\\]\\'" action )
420 (org-beamer--normalize-argument action 'defaction))
421 (t (org-beamer--normalize-argument action 'action))))
422 ;; Options, if any.
423 (let* ((beamer-opt (org-element-property :BEAMER_OPT headline))
424 (options
425 ;; Collect options from default value and headline's
426 ;; properties. Also add a label for links.
427 (append
428 (org-split-string
429 (plist-get info :beamer-frame-default-options) ",")
430 (and beamer-opt
431 (org-split-string
432 ;; Remove square brackets if user provided
433 ;; them.
434 (and (string-match "^\\[?\\(.*\\)\\]?$" beamer-opt)
435 (match-string 1 beamer-opt))
436 ","))
437 ;; Provide an automatic label for the frame
438 ;; unless the user specified one. Also refrain
439 ;; from labeling `allowframebreaks' frames; this
440 ;; is not allowed by beamer.
441 (unless (and beamer-opt
442 (or (string-match "\\(^\\|,\\)label=" beamer-opt)
443 (string-match "allowframebreaks" beamer-opt)))
444 (list
445 (format "label=%s"
446 (org-beamer--get-label headline info)))))))
447 ;; Change options list into a string.
448 (org-beamer--normalize-argument
449 (mapconcat
450 'identity
451 (if (or (not fragilep) (member "fragile" options)) options
452 (cons "fragile" options))
453 ",")
454 'option))
455 ;; Title.
456 (let ((env (org-element-property :BEAMER_ENV headline)))
457 (format "{%s}"
458 (if (and env (equal (downcase env) "fullframe")) ""
459 (org-export-data
460 (org-element-property :title headline) info))))
461 "\n"
462 ;; The following workaround is required in fragile frames
463 ;; as Beamer will append "\par" to the beginning of the
464 ;; contents. So we need to make sure the command is
465 ;; separated from the contents by at least one space. If
466 ;; it isn't, it will create "\parfirst-word" command and
467 ;; remove the first word from the contents in the PDF
468 ;; output.
469 (if (not fragilep) contents
470 (replace-regexp-in-string "\\`\n*" "\\& " (or contents "")))
471 "\\end{frame}")))
473 (defun org-beamer--format-block (headline contents info)
474 "Format HEADLINE as a block.
475 CONTENTS holds the contents of the headline. INFO is a plist
476 used as a communication channel."
477 (let* ((column-width (org-element-property :BEAMER_COL headline))
478 ;; ENVIRONMENT defaults to "block" if none is specified and
479 ;; there is no column specification. If there is a column
480 ;; specified but still no explicit environment, ENVIRONMENT
481 ;; is "column".
482 (environment (let ((env (org-element-property :BEAMER_ENV headline)))
483 (cond
484 ;; "block" is the fallback environment.
485 ((and (not env) (not column-width)) "block")
486 ;; "column" only.
487 ((not env) "column")
488 ;; Use specified environment.
489 (t env))))
490 (raw-title (org-element-property :raw-value headline))
491 (env-format
492 (cond ((member environment '("column" "columns")) nil)
493 ((assoc environment
494 (append (plist-get info :beamer-environments-extra)
495 org-beamer-environments-default)))
496 (t (user-error "Wrong block type at a headline named \"%s\""
497 raw-title))))
498 (title (org-export-data (org-element-property :title headline) info))
499 (options (let ((options (org-element-property :BEAMER_OPT headline)))
500 (if (not options) ""
501 (org-beamer--normalize-argument options 'option))))
502 ;; Start a "columns" environment when explicitly requested or
503 ;; when there is no previous headline or the previous
504 ;; headline do not have a BEAMER_column property.
505 (parent-env (org-element-property
506 :BEAMER_ENV (org-export-get-parent-headline headline)))
507 (start-columns-p
508 (or (equal environment "columns")
509 (and column-width
510 (not (and parent-env
511 (equal (downcase parent-env) "columns")))
512 (or (org-export-first-sibling-p headline info)
513 (not (org-element-property
514 :BEAMER_COL
515 (org-export-get-previous-element
516 headline info)))))))
517 ;; End the "columns" environment when explicitly requested or
518 ;; when there is no next headline or the next headline do not
519 ;; have a BEAMER_column property.
520 (end-columns-p
521 (or (equal environment "columns")
522 (and column-width
523 (not (and parent-env
524 (equal (downcase parent-env) "columns")))
525 (or (org-export-last-sibling-p headline info)
526 (not (org-element-property
527 :BEAMER_COL
528 (org-export-get-next-element headline info))))))))
529 (concat
530 (when start-columns-p
531 ;; Column can accept options only when the environment is
532 ;; explicitly defined.
533 (if (not (equal environment "columns")) "\\begin{columns}\n"
534 (format "\\begin{columns}%s\n" options)))
535 (when column-width
536 (format "\\begin{column}%s{%s}\n"
537 ;; One can specify placement for column only when
538 ;; HEADLINE stands for a column on its own.
539 (if (equal environment "column") options "")
540 (format "%s\\columnwidth" column-width)))
541 ;; Block's opening string.
542 (when (nth 2 env-format)
543 (concat
544 (org-fill-template
545 (nth 2 env-format)
546 (nconc
547 ;; If BEAMER_act property has its value enclosed in square
548 ;; brackets, it is a default overlay specification and
549 ;; overlay specification is empty. Otherwise, it is an
550 ;; overlay specification and the default one is nil.
551 (let ((action (org-element-property :BEAMER_ACT headline)))
552 (cond
553 ((not action) (list (cons "a" "") (cons "A" "")))
554 ((string-match "\\`\\[.*\\]\\'" action)
555 (list
556 (cons "A" (org-beamer--normalize-argument action 'defaction))
557 (cons "a" "")))
559 (list (cons "a" (org-beamer--normalize-argument action 'action))
560 (cons "A" "")))))
561 (list (cons "o" options)
562 (cons "h" title)
563 (cons "r" raw-title)
564 (cons "H" (if (equal raw-title "") ""
565 (format "{%s}" raw-title)))
566 (cons "U" (if (equal raw-title "") ""
567 (format "[%s]" raw-title))))))
568 "\n"))
569 contents
570 ;; Block's closing string, if any.
571 (and (nth 3 env-format) (concat (nth 3 env-format) "\n"))
572 (when column-width "\\end{column}\n")
573 (when end-columns-p "\\end{columns}"))))
575 (defun org-beamer-headline (headline contents info)
576 "Transcode HEADLINE element into Beamer code.
577 CONTENTS is the contents of the headline. INFO is a plist used
578 as a communication channel."
579 (unless (org-element-property :footnote-section-p headline)
580 (let ((level (org-export-get-relative-level headline info))
581 (frame-level (org-beamer--frame-level headline info))
582 (environment (let ((env (org-element-property :BEAMER_ENV headline)))
583 (or (org-string-nw-p env) "block"))))
584 (cond
585 ;; Case 1: Resume frame specified by "BEAMER_ref" property.
586 ((equal environment "againframe")
587 (let ((ref (org-element-property :BEAMER_REF headline)))
588 ;; Reference to frame being resumed is mandatory. Ignore
589 ;; the whole headline if it isn't provided.
590 (when (org-string-nw-p ref)
591 (concat "\\againframe"
592 ;; Overlay specification.
593 (let ((overlay (org-element-property :BEAMER_ACT headline)))
594 (when overlay
595 (org-beamer--normalize-argument
596 overlay
597 (if (string-match "^\\[.*\\]$" overlay) 'defaction
598 'action))))
599 ;; Options.
600 (let ((options (org-element-property :BEAMER_OPT headline)))
601 (when options
602 (org-beamer--normalize-argument options 'option)))
603 ;; Resolve reference provided by "BEAMER_ref"
604 ;; property. This is done by building a minimal fake
605 ;; link and calling the appropriate resolve function,
606 ;; depending on the reference syntax.
607 (let* ((type
608 (progn
609 (string-match "^\\(id:\\|#\\|\\*\\)?\\(.*\\)" ref)
610 (cond
611 ((or (not (match-string 1 ref))
612 (equal (match-string 1 ref) "*")) 'fuzzy)
613 ((equal (match-string 1 ref) "id:") 'id)
614 (t 'custom-id))))
615 (link (list 'link (list :path (match-string 2 ref))))
616 (target (if (eq type 'fuzzy)
617 (org-export-resolve-fuzzy-link link info)
618 (org-export-resolve-id-link link info))))
619 ;; Now use user-defined label provided in TARGET
620 ;; headline, or fallback to standard one.
621 (format "{%s}" (org-beamer--get-label target info)))))))
622 ;; Case 2: Creation of an appendix is requested.
623 ((equal environment "appendix")
624 (concat "\\appendix"
625 (org-element-property :BEAMER_ACT headline)
626 "\n"
627 (make-string (org-element-property :pre-blank headline) ?\n)
628 contents))
629 ;; Case 3: Ignore heading.
630 ((equal environment "ignoreheading")
631 (concat (make-string (org-element-property :pre-blank headline) ?\n)
632 contents))
633 ;; Case 4: HEADLINE is a note.
634 ((member environment '("note" "noteNH"))
635 (format "\\note{%s}"
636 (concat (and (equal environment "note")
637 (concat
638 (org-export-data
639 (org-element-property :title headline) info)
640 "\n"))
641 (org-trim contents))))
642 ;; Case 5: HEADLINE is a frame.
643 ((= level frame-level)
644 (org-beamer--format-frame headline contents info))
645 ;; Case 6: Regular section, extracted from
646 ;; `org-latex-classes'.
647 ((< level frame-level)
648 (org-beamer--format-section headline contents info))
649 ;; Case 7: Otherwise, HEADLINE is a block.
650 (t (org-beamer--format-block headline contents info))))))
653 ;;;; Item
655 (defun org-beamer-item (item contents info)
656 "Transcode an ITEM element into Beamer code.
657 CONTENTS holds the contents of the item. INFO is a plist holding
658 contextual information."
659 (org-export-with-backend
660 ;; Delegate item export to `latex'. However, we use `beamer'
661 ;; transcoders for objects in the description tag.
662 (org-export-create-backend
663 :parent 'beamer
664 :transcoders
665 (list
666 (cons
667 'item
668 (lambda (item c i)
669 (let ((action
670 (let ((first (car (org-element-contents item))))
671 (and (eq (org-element-type first) 'paragraph)
672 (org-beamer--element-has-overlay-p first))))
673 (output (org-latex-item item contents info)))
674 (if (not (and action (string-match "\\\\item" output))) output
675 ;; If the item starts with a paragraph and that paragraph
676 ;; starts with an export snippet specifying an overlay,
677 ;; append it to the \item command.
678 (replace-match (concat "\\\\item" action) nil nil output)))))))
679 item contents info))
682 ;;;; Keyword
684 (defun org-beamer-keyword (keyword contents info)
685 "Transcode a KEYWORD element into Beamer code.
686 CONTENTS is nil. INFO is a plist used as a communication
687 channel."
688 (let ((key (org-element-property :key keyword))
689 (value (org-element-property :value keyword)))
690 ;; Handle specifically BEAMER and TOC (headlines only) keywords.
691 ;; Otherwise, fallback to `latex' back-end.
692 (cond
693 ((equal key "BEAMER") value)
694 ((and (equal key "TOC") (string-match "\\<headlines\\>" value))
695 (let ((depth (or (and (string-match "[0-9]+" value)
696 (string-to-number (match-string 0 value)))
697 (plist-get info :with-toc)))
698 (options (and (string-match "\\[.*?\\]" value)
699 (match-string 0 value))))
700 (concat
701 (when (wholenump depth) (format "\\setcounter{tocdepth}{%s}\n" depth))
702 "\\tableofcontents" options)))
703 (t (org-export-with-backend 'latex keyword contents info)))))
706 ;;;; Link
708 (defun org-beamer-link (link contents info)
709 "Transcode a LINK object into Beamer code.
710 CONTENTS is the description part of the link. INFO is a plist
711 used as a communication channel."
712 (let ((type (org-element-property :type link))
713 (path (org-element-property :path link)))
714 (cond
715 ;; Link type is handled by a special function.
716 ((org-export-custom-protocol-maybe link contents 'beamer))
717 ;; Use \hyperlink command for all internal links.
718 ((equal type "radio")
719 (let ((destination (org-export-resolve-radio-link link info)))
720 (if (not destination) contents
721 (format "\\hyperlink%s{%s}{%s}"
722 (or (org-beamer--element-has-overlay-p link) "")
723 (org-export-get-reference destination info)
724 contents))))
725 ((and (member type '("custom-id" "fuzzy" "id"))
726 (let ((destination (if (string= type "fuzzy")
727 (org-export-resolve-fuzzy-link link info)
728 (org-export-resolve-id-link link info))))
729 (case (org-element-type destination)
730 (headline
731 (let ((label
732 (format "sec-%s"
733 (mapconcat
734 'number-to-string
735 (org-export-get-headline-number
736 destination info)
737 "-"))))
738 (if (and (plist-get info :section-numbers) (not contents))
739 (format "\\ref{%s}" label)
740 (format "\\hyperlink%s{%s}{%s}"
741 (or (org-beamer--element-has-overlay-p link) "")
742 label
743 contents))))
744 (target
745 (let ((ref (org-export-get-reference destination info)))
746 (if (not contents) (format "\\ref{%s}" ref)
747 (format "\\hyperlink%s{%s}{%s}"
748 (or (org-beamer--element-has-overlay-p link) "")
750 contents))))))))
751 ;; Otherwise, use `latex' back-end.
752 (t (org-export-with-backend 'latex link contents info)))))
755 ;;;; Plain List
757 ;; Plain lists support `:environment', `:overlay' and `:options'
758 ;; attributes.
760 (defun org-beamer-plain-list (plain-list contents info)
761 "Transcode a PLAIN-LIST element into Beamer code.
762 CONTENTS is the contents of the list. INFO is a plist holding
763 contextual information."
764 (let* ((type (org-element-property :type plain-list))
765 (attributes (org-combine-plists
766 (org-export-read-attribute :attr_latex plain-list)
767 (org-export-read-attribute :attr_beamer plain-list)))
768 (latex-type (let ((env (plist-get attributes :environment)))
769 (cond (env)
770 ((eq type 'ordered) "enumerate")
771 ((eq type 'descriptive) "description")
772 (t "itemize")))))
773 (org-latex--wrap-label
774 plain-list
775 (format "\\begin{%s}%s%s\n%s\\end{%s}"
776 latex-type
777 ;; Default overlay specification, if any.
778 (org-beamer--normalize-argument
779 (or (plist-get attributes :overlay) "")
780 'defaction)
781 ;; Second optional argument depends on the list type.
782 (org-beamer--normalize-argument
783 (or (plist-get attributes :options) "")
784 'option)
785 ;; Eventually insert contents and close environment.
786 contents
787 latex-type)
788 info)))
791 ;;;; Radio Target
793 (defun org-beamer-radio-target (radio-target text info)
794 "Transcode a RADIO-TARGET object into Beamer code.
795 TEXT is the text of the target. INFO is a plist holding
796 contextual information."
797 (format "\\hypertarget%s{%s}{%s}"
798 (or (org-beamer--element-has-overlay-p radio-target) "")
799 (org-export-get-reference radio-target info)
800 text))
803 ;;;; Target
805 (defun org-beamer-target (target contents info)
806 "Transcode a TARGET object into Beamer code.
807 CONTENTS is nil. INFO is a plist holding contextual
808 information."
809 (format "\\label{%s}" (org-export-get-reference target info)))
812 ;;;; Template
814 ;; Template used is similar to the one used in `latex' back-end,
815 ;; excepted for the table of contents and Beamer themes.
817 (defun org-beamer-template (contents info)
818 "Return complete document string after Beamer conversion.
819 CONTENTS is the transcoded contents string. INFO is a plist
820 holding export options."
821 (let ((title (org-export-data (plist-get info :title) info))
822 (subtitle (org-export-data (plist-get info :subtitle) info)))
823 (concat
824 ;; 1. Time-stamp.
825 (and (plist-get info :time-stamp-file)
826 (format-time-string "%% Created %Y-%m-%d %a %H:%M\n"))
827 ;; 2. Document class and packages.
828 (let* ((class (plist-get info :latex-class))
829 (class-options (plist-get info :latex-class-options))
830 (header (nth 1 (assoc class org-latex-classes)))
831 (document-class-string
832 (and (stringp header)
833 (if (not class-options) header
834 (replace-regexp-in-string
835 "^[ \t]*\\\\documentclass\\(\\(\\[[^]]*\\]\\)?\\)"
836 class-options header t nil 1)))))
837 (if (not document-class-string)
838 (user-error "Unknown LaTeX class `%s'" class)
839 (org-latex-guess-babel-language
840 (org-latex-guess-inputenc
841 (org-element-normalize-string
842 (org-splice-latex-header
843 document-class-string
844 org-latex-default-packages-alist
845 org-latex-packages-alist nil
846 (concat (org-element-normalize-string
847 (plist-get info :latex-header))
848 (org-element-normalize-string
849 (plist-get info :latex-header-extra))))))
850 info)))
851 ;; 3. Insert themes.
852 (let ((format-theme
853 (function
854 (lambda (prop command)
855 (let ((theme (plist-get info prop)))
856 (when theme
857 (concat command
858 (if (not (string-match "\\[.*\\]" theme))
859 (format "{%s}\n" theme)
860 (format "%s{%s}\n"
861 (match-string 0 theme)
862 (org-trim
863 (replace-match "" nil nil theme)))))))))))
864 (mapconcat (lambda (args) (apply format-theme args))
865 '((:beamer-theme "\\usetheme")
866 (:beamer-color-theme "\\usecolortheme")
867 (:beamer-font-theme "\\usefonttheme")
868 (:beamer-inner-theme "\\useinnertheme")
869 (:beamer-outer-theme "\\useoutertheme"))
870 ""))
871 ;; 4. Possibly limit depth for headline numbering.
872 (let ((sec-num (plist-get info :section-numbers)))
873 (when (integerp sec-num)
874 (format "\\setcounter{secnumdepth}{%d}\n" sec-num)))
875 ;; 5. Author.
876 (let ((author (and (plist-get info :with-author)
877 (let ((auth (plist-get info :author)))
878 (and auth (org-export-data auth info)))))
879 (email (and (plist-get info :with-email)
880 (org-export-data (plist-get info :email) info))))
881 (cond ((and author email (not (string= "" email)))
882 (format "\\author{%s\\thanks{%s}}\n" author email))
883 ((or author email) (format "\\author{%s}\n" (or author email)))))
884 ;; 6. Date.
885 (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
886 (format "\\date{%s}\n" (org-export-data date info)))
887 ;; 7. Title
888 (format "\\title{%s}\n" title)
889 (when (org-string-nw-p subtitle)
890 (concat (format (plist-get info :beamer-subtitle-format) subtitle) "\n"))
891 ;; 8. Beamer-header
892 (let ((beamer-header (plist-get info :beamer-header)))
893 (when beamer-header
894 (format "%s\n" (plist-get info :beamer-header))))
895 ;; 9. Hyperref options.
896 (let ((template (plist-get info :latex-hyperref-template)))
897 (and (stringp template)
898 (format-spec template (org-latex--format-spec info))))
899 ;; 10. Document start.
900 "\\begin{document}\n\n"
901 ;; 11. Title command.
902 (org-element-normalize-string
903 (cond ((not (plist-get info :with-title)) nil)
904 ((string= "" title) nil)
905 ((not (stringp org-latex-title-command)) nil)
906 ((string-match "\\(?:[^%]\\|^\\)%s"
907 org-latex-title-command)
908 (format org-latex-title-command title))
909 (t org-latex-title-command)))
910 ;; 12. Table of contents.
911 (let ((depth (plist-get info :with-toc)))
912 (when depth
913 (concat
914 (format "\\begin{frame}%s{%s}\n"
915 (org-beamer--normalize-argument
916 (plist-get info :beamer-outline-frame-options) 'option)
917 (plist-get info :beamer-outline-frame-title))
918 (when (wholenump depth)
919 (format "\\setcounter{tocdepth}{%d}\n" depth))
920 "\\tableofcontents\n"
921 "\\end{frame}\n\n")))
922 ;; 13. Document's body.
923 contents
924 ;; 14. Creator.
925 (if (plist-get info :with-creator)
926 (concat (plist-get info :creator) "\n")
928 ;; 15. Document end.
929 "\\end{document}")))
933 ;;; Minor Mode
936 (defvar org-beamer-mode-map (make-sparse-keymap)
937 "The keymap for `org-beamer-mode'.")
938 (define-key org-beamer-mode-map "\C-c\C-b" 'org-beamer-select-environment)
940 ;;;###autoload
941 (define-minor-mode org-beamer-mode
942 "Support for editing Beamer oriented Org mode files."
943 nil " Bm" 'org-beamer-mode-map)
945 (when (fboundp 'font-lock-add-keywords)
946 (font-lock-add-keywords
947 'org-mode
948 '((":\\(B_[a-z]+\\|BMCOL\\):" 1 'org-beamer-tag prepend))
949 'prepend))
951 (defface org-beamer-tag '((t (:box (:line-width 1 :color grey40))))
952 "The special face for beamer tags."
953 :group 'org-export-beamer)
955 (defun org-beamer-property-changed (property value)
956 "Track the BEAMER_env property with tags.
957 PROPERTY is the name of the modified property. VALUE is its new
958 value."
959 (cond
960 ((equal property "BEAMER_env")
961 (save-excursion
962 (org-back-to-heading t)
963 ;; Filter out Beamer-related tags and install environment tag.
964 (let ((tags (org-remove-if (lambda (x) (string-match "^B_" x))
965 (org-get-tags)))
966 (env-tag (and (org-string-nw-p value) (concat "B_" value))))
967 (org-set-tags-to (if env-tag (cons env-tag tags) tags))
968 (when env-tag (org-toggle-tag env-tag 'on)))))
969 ((equal property "BEAMER_col")
970 (org-toggle-tag "BMCOL" (if (org-string-nw-p value) 'on 'off)))))
972 (add-hook 'org-property-changed-functions 'org-beamer-property-changed)
974 (defun org-beamer-allowed-property-values (property)
975 "Supply allowed values for PROPERTY."
976 (cond
977 ((and (equal property "BEAMER_env")
978 (not (org-entry-get nil (concat property "_ALL") 'inherit)))
979 ;; If no allowed values for BEAMER_env have been defined,
980 ;; supply all defined environments
981 (mapcar 'car (append org-beamer-environments-special
982 org-beamer-environments-extra
983 org-beamer-environments-default)))
984 ((and (equal property "BEAMER_col")
985 (not (org-entry-get nil (concat property "_ALL") 'inherit)))
986 ;; If no allowed values for BEAMER_col have been defined,
987 ;; supply some
988 (org-split-string org-beamer-column-widths " "))))
990 (add-hook 'org-property-allowed-value-functions
991 'org-beamer-allowed-property-values)
995 ;;; Commands
997 ;;;###autoload
998 (defun org-beamer-export-as-latex
999 (&optional async subtreep visible-only body-only ext-plist)
1000 "Export current buffer as a Beamer buffer.
1002 If narrowing is active in the current buffer, only export its
1003 narrowed part.
1005 If a region is active, export that region.
1007 A non-nil optional argument ASYNC means the process should happen
1008 asynchronously. The resulting buffer should be accessible
1009 through the `org-export-stack' interface.
1011 When optional argument SUBTREEP is non-nil, export the sub-tree
1012 at point, extracting information from the headline properties
1013 first.
1015 When optional argument VISIBLE-ONLY is non-nil, don't export
1016 contents of hidden elements.
1018 When optional argument BODY-ONLY is non-nil, only write code
1019 between \"\\begin{document}\" and \"\\end{document}\".
1021 EXT-PLIST, when provided, is a property list with external
1022 parameters overriding Org default settings, but still inferior to
1023 file-local settings.
1025 Export is done in a buffer named \"*Org BEAMER Export*\", which
1026 will be displayed when `org-export-show-temporary-export-buffer'
1027 is non-nil."
1028 (interactive)
1029 (org-export-to-buffer 'beamer "*Org BEAMER Export*"
1030 async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode))))
1032 ;;;###autoload
1033 (defun org-beamer-export-to-latex
1034 (&optional async subtreep visible-only body-only ext-plist)
1035 "Export current buffer as a Beamer presentation (tex).
1037 If narrowing is active in the current buffer, only export its
1038 narrowed part.
1040 If a region is active, export that region.
1042 A non-nil optional argument ASYNC means the process should happen
1043 asynchronously. The resulting file should be accessible through
1044 the `org-export-stack' interface.
1046 When optional argument SUBTREEP is non-nil, export the sub-tree
1047 at point, extracting information from the headline properties
1048 first.
1050 When optional argument VISIBLE-ONLY is non-nil, don't export
1051 contents of hidden elements.
1053 When optional argument BODY-ONLY is non-nil, only write code
1054 between \"\\begin{document}\" and \"\\end{document}\".
1056 EXT-PLIST, when provided, is a property list with external
1057 parameters overriding Org default settings, but still inferior to
1058 file-local settings.
1060 Return output file's name."
1061 (interactive)
1062 (let ((file (org-export-output-file-name ".tex" subtreep)))
1063 (org-export-to-file 'beamer file
1064 async subtreep visible-only body-only ext-plist)))
1066 ;;;###autoload
1067 (defun org-beamer-export-to-pdf
1068 (&optional async subtreep visible-only body-only ext-plist)
1069 "Export current buffer as a Beamer presentation (PDF).
1071 If narrowing is active in the current buffer, only export its
1072 narrowed part.
1074 If a region is active, export that region.
1076 A non-nil optional argument ASYNC means the process should happen
1077 asynchronously. The resulting file should be accessible through
1078 the `org-export-stack' interface.
1080 When optional argument SUBTREEP is non-nil, export the sub-tree
1081 at point, extracting information from the headline properties
1082 first.
1084 When optional argument VISIBLE-ONLY is non-nil, don't export
1085 contents of hidden elements.
1087 When optional argument BODY-ONLY is non-nil, only write code
1088 between \"\\begin{document}\" and \"\\end{document}\".
1090 EXT-PLIST, when provided, is a property list with external
1091 parameters overriding Org default settings, but still inferior to
1092 file-local settings.
1094 Return PDF file's name."
1095 (interactive)
1096 (let ((file (org-export-output-file-name ".tex" subtreep)))
1097 (org-export-to-file 'beamer file
1098 async subtreep visible-only body-only ext-plist
1099 (lambda (file) (org-latex-compile file)))))
1101 ;;;###autoload
1102 (defun org-beamer-select-environment ()
1103 "Select the environment to be used by beamer for this entry.
1104 While this uses (for convenience) a tag selection interface, the
1105 result of this command will be that the BEAMER_env *property* of
1106 the entry is set.
1108 In addition to this, the command will also set a tag as a visual
1109 aid, but the tag does not have any semantic meaning."
1110 (interactive)
1111 ;; Make sure `org-beamer-environments-special' has a higher
1112 ;; priority than `org-beamer-environments-extra'.
1113 (let* ((envs (append org-beamer-environments-special
1114 org-beamer-environments-extra
1115 org-beamer-environments-default))
1116 (org-tag-alist
1117 (append '((:startgroup))
1118 (mapcar (lambda (e) (cons (concat "B_" (car e))
1119 (string-to-char (nth 1 e))))
1120 envs)
1121 '((:endgroup))
1122 '(("BMCOL" . ?|))))
1123 (org-tag-persistent-alist nil)
1124 (org-use-fast-tag-selection t)
1125 (org-fast-tag-selection-single-key t))
1126 (org-set-tags)
1127 (let ((tags (or (ignore-errors (org-get-tags-string)) "")))
1128 (cond
1129 ;; For a column, automatically ask for its width.
1130 ((eq org-last-tag-selection-key ?|)
1131 (if (string-match ":BMCOL:" tags)
1132 (org-set-property "BEAMER_col" (read-string "Column width: "))
1133 (org-delete-property "BEAMER_col")))
1134 ;; For an "againframe" section, automatically ask for reference
1135 ;; to resumed frame and overlay specifications.
1136 ((eq org-last-tag-selection-key ?A)
1137 (if (equal (org-entry-get nil "BEAMER_env") "againframe")
1138 (progn (org-entry-delete nil "BEAMER_env")
1139 (org-entry-delete nil "BEAMER_ref")
1140 (org-entry-delete nil "BEAMER_act"))
1141 (org-entry-put nil "BEAMER_env" "againframe")
1142 (org-set-property
1143 "BEAMER_ref"
1144 (read-string "Frame reference (*Title, #custom-id, id:...): "))
1145 (org-set-property "BEAMER_act"
1146 (read-string "Overlay specification: "))))
1147 ((string-match (concat ":B_\\(" (mapconcat 'car envs "\\|") "\\):") tags)
1148 (org-entry-put nil "BEAMER_env" (match-string 1 tags)))
1149 (t (org-entry-delete nil "BEAMER_env"))))))
1151 ;;;###autoload
1152 (defun org-beamer-publish-to-latex (plist filename pub-dir)
1153 "Publish an Org file to a Beamer presentation (LaTeX).
1155 FILENAME is the filename of the Org file to be published. PLIST
1156 is the property list for the given project. PUB-DIR is the
1157 publishing directory.
1159 Return output file name."
1160 (org-publish-org-to 'beamer filename ".tex" plist pub-dir))
1162 ;;;###autoload
1163 (defun org-beamer-publish-to-pdf (plist filename pub-dir)
1164 "Publish an Org file to a Beamer presentation (PDF, via LaTeX).
1166 FILENAME is the filename of the Org file to be published. PLIST
1167 is the property list for the given project. PUB-DIR is the
1168 publishing directory.
1170 Return output file name."
1171 ;; Unlike to `org-beamer-publish-to-latex', PDF file is generated in
1172 ;; working directory and then moved to publishing directory.
1173 (org-publish-attachment
1174 plist
1175 (org-latex-compile
1176 (org-publish-org-to
1177 'beamer filename ".tex" plist (file-name-directory filename)))
1178 pub-dir))
1181 (provide 'ox-beamer)
1183 ;; Local variables:
1184 ;; generated-autoload-file: "org-loaddefs.el"
1185 ;; End:
1187 ;;; ox-beamer.el ends here