[elpa] externals/org b3b35b03ff 1/2: lisp/ox-beamer.el: customize the beamer frame environment name

[ELPA Syncer]

branch: externals/org
commit b3b35b03ff8e0ea74edc2160fa590e8b8b897524
Author: Leo Butler <leo.butler@umanitoba.ca>
Commit: Ihor Radchenko <yantar92@posteo.net>

    lisp/ox-beamer.el: customize the beamer frame environment name
    
    * lisp/ox-beamer.el (org-beamer-frame-environment): A new customize
    variable.  It contains the name of an environment that serves as an
    alias for the beamer frame environment.
    
    (org-beamer-template): Insert the `org-beamer-frame-environment'
    environment definition into the beamer document.
    
    * lisp/org-lint.el (org-lint-beamer-frame): Check the body of each
    frame for an occurrence of \begin{orgframe} or \end{orgframe}, or
    whatever environment name is in `org-beamer-frame-environment' [4].
    The warning includes advice to see `org-beamer-frame-environment'.
    
    * etc/ORG-NEWS (New option ~org-beamer-frame-environment~): Announce
    the new option.
    
    Rationale: Code with \begin{frame} or \end{frame} cannot be embedded
    in a verbatim environment inside a beamer frame due to a design
    decision made by the beamer developers [1].  As suggested in that
    report, defining an alias for the beamer frame environment will allow
    such verbatim examples to compile correctly [2].
    
    This solution also works with instances of \againframe.
    
    Refs:
    [1] https://github.com/josephwright/beamer/issues/360
    [2] https://github.com/josephwright/beamer/issues/360#issuecomment-708705250
    [3] https://list.orgmode.org/orgmode/87le8eg1hs.fsf@localhost/T/
    [4] https://list.orgmode.org/orgmode/87il38i5tb.fsf@localhost/T/
---
 etc/ORG-NEWS      | 16 ++++++++++++++++
 lisp/org-lint.el  | 17 +++++++++++++++++
 lisp/ox-beamer.el | 36 ++++++++++++++++++++++++++++--------
 3 files changed, 61 insertions(+), 8 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 2da04e621f..7b9a4e3721 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -539,6 +539,22 @@ The change is breaking when ~org-use-property-inheritance~ 
is set to ~t~.
 
 The =TEST= parameter is better served by Emacs debugging tools.
 ** New and changed options
+*** New option ~org-beamer-frame-environment~
+
+The new option defines name of an alternative environment to be used
+for fragile beamer frames.  This option is needed to work around
+beamer bug with frame contents containing literal =\end{frame}= string
+(for example, inside example blocks).  See
+https://github.com/josephwright/beamer/issues/360
+
+The default value is =orgframe=.
+
+The option should normally not be changed, except when you need to put
+=\end{orgframe}= string inside beamer frames.
+
+A checker has been added to =M-x org-lint= to detect instances of
+~org-beamer-frame-environment~ in Org documents.
+
 *** New option ~org-export-process-citations~
 
 The new option controls whether to use citation processors to process
diff --git a/lisp/org-lint.el b/lisp/org-lint.el
index 4d2a55d156..e65f9a7eb2 100644
--- a/lisp/org-lint.el
+++ b/lisp/org-lint.el
@@ -1507,6 +1507,19 @@ AST is the buffer parse tree."
          ((memq (org-element-property :type deadline) '(inactive 
inactive-range))
           (list (org-element-begin planning) "Inactive timestamp in DEADLINE 
will not appear in agenda."))
          (t nil))))))
+
+(defvar org-beamer-frame-environment) ; defined in ox-beamer.el
+(defun org-lint-beamer-frame (ast)
+  "Check for occurrences of begin or end frame."
+  (require 'ox-beamer)
+  (org-with-point-at ast
+    (goto-char (point-min))
+    (let (result)
+      (while (re-search-forward
+              (concat "\\\\\\(begin\\|end\\){" org-beamer-frame-environment 
"}") nil t)
+        (push (list (match-beginning 0) "Beamer frame name may cause error 
when exporting.  Consider customizing `org-beamer-frame-environment'.") result))
+      result)))
+
 
 ;;; Checkers declaration
 
@@ -1787,6 +1800,10 @@ AST is the buffer parse tree."
   "Report $ that might be treated as LaTeX fragment boundary."
   #'org-lint-LaTeX-$-ambiguous
   :categories '(markup) :trust 'low)
+(org-lint-add-checker 'beamer-frame
+  "Report that frame text contains beamer frame environment."
+  #'org-lint-beamer-frame
+  :categories '(export) :trust 'low)
 (org-lint-add-checker 'timestamp-syntax
   "Report malformed timestamps."
   #'org-lint-timestamp-syntax
diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
index 571b9c2396..998810a288 100644
--- a/lisp/ox-beamer.el
+++ b/lisp/ox-beamer.el
@@ -148,6 +148,22 @@ which is replaced with the subtitle."
   :package-version '(Org . "8.3")
   :type '(string :tag "Format string"))
 
+(defcustom org-beamer-frame-environment "orgframe"
+  "Name of the alternative beamer frame environment.
+In frames marked as fragile, this environment is used in place of
+the usual frame environment.
+
+This permits insertion of a beamer frame inside example blocks,
+working around beamer limitations.  See
+https://list.orgmode.org/87a5nux3zr.fsf@t14.reltub.ca/T/#mc7221e93f138bdd56c916b194b9230d3a6c3de09
+
+This option may need to be changed when \"\\end{orgframe}\" string is
+used inside beamer slides."
+  :group 'org-export-beamer
+  :package-version '(Org . "9.7")
+  :type '(string :tag "Beamer frame")
+  :safe (lambda (str) (string-match-p "^[A-Za-z]+$" str)))
+
 
 ;;; Internal Variables
 
@@ -408,12 +424,14 @@ used as a communication channel."
   "Format HEADLINE as a frame.
 CONTENTS holds the contents of the headline.  INFO is a plist
 used as a communication channel."
-  (let ((fragilep
-        ;; FRAGILEP is non-nil when HEADLINE contains an element
-        ;; among `org-beamer-verbatim-elements'.
-        (org-element-map headline org-beamer-verbatim-elements 'identity
-                         info 'first-match)))
-    (concat "\\begin{frame}"
+  (let* ((fragilep
+         ;; FRAGILEP is non-nil when HEADLINE contains an element
+         ;; among `org-beamer-verbatim-elements'.
+         (org-element-map headline org-beamer-verbatim-elements 'identity
+                          info 'first-match))
+         (frame (or (and fragilep org-beamer-frame-environment)
+                    "frame")))
+    (concat "\\begin{" frame "}"
            ;; Overlay specification, if any. When surrounded by
            ;; square brackets, consider it as a default
            ;; specification.
@@ -480,7 +498,7 @@ used as a communication channel."
            ;; output.
            (if (not fragilep) contents
              (replace-regexp-in-string "\\`\n*" "\\& " (or contents "")))
-           "\\end{frame}")))
+           "\\end{" frame "}")))
 
 (defun org-beamer--format-block (headline contents info)
   "Format HEADLINE as a block.
@@ -814,7 +832,6 @@ contextual information."
          (org-export-get-reference radio-target info)
          text))
 
-
 ;;;; Template
 ;;
 ;; Template used is similar to the one used in `latex' backend,
@@ -834,6 +851,9 @@ holding export options."
      (org-latex--insert-compiler info)
      ;; Document class and packages.
      (org-latex-make-preamble info)
+     ;; Define the alternative frame environment.
+     (format 
"\\newenvironment<>{%s}[1][]{\\begin{frame}[environment=%1$s,#1]}{\\end{frame}}\n"
+             org-beamer-frame-environment)
      ;; Insert themes.
      (let ((format-theme
            (lambda (prop command)