branch: externals/org
commit 80743e5c5591ae558b08871f2d16e515383fb072
Author: Pedro A. Aranda <[email protected]>
Commit: Ihor Radchenko <[email protected]>
ox-latex: Add `org-latex-default-example-environment'
Add custom variable to set the LaTeX environment for example blocks.
* lisp/ox-latex.el: (org-latex-default-example-environment) New custom
variable.
(org-latex-example-block): Use variable instead of literal string.
* testing/lisp/test-ox-latex.el: New
test `test-ox-latex/latex-default-example-with-options'.
* etc/ORG-NEWS: Announce.
* doc/org-manual.org: Restructure example block section in LaTeX
exports and document new variable.
---
doc/org-manual.org | 32 ++++++++++++++++++--------------
etc/ORG-NEWS | 5 +++++
lisp/ox-latex.el | 9 ++++++++-
testing/lisp/test-ox-latex.el | 18 +++++++++++++++++-
4 files changed, 48 insertions(+), 16 deletions(-)
diff --git a/doc/org-manual.org b/doc/org-manual.org
index ec84861013..9c4c278775 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -14788,13 +14788,16 @@ variables.
#+cindex: example blocks, in @LaTeX{} export
#+cindex: verbatim blocks, in @LaTeX{} export
#+cindex: @samp{ATTR_LATEX}, keyword
+#+vindex: org-latex-default-example-environment
-The LaTeX export backend wraps the contents of example blocks in
-a =verbatim= environment. To change this behavior to use another
-environment globally, specify an appropriate export filter (see
-[[*Advanced Export Configuration]]). To change this behavior to use
-another environment for each block, use the =:environment= parameter
-to specify a custom environment.
+The LaTeX export backend wraps the contents of example blocks in a
+=verbatim= environment. To control the environment used globally, you
+can change the value of custom variable
+~org-latex-default-example-environment~, or specify an appropriate
+export filter (see [[*Advanced Export Configuration]]).
+
+To use a different environment for specific example blocks, use the
+=:environment= parameter:
#+begin_example
,#+ATTR_LATEX: :environment myverbatim
@@ -14803,8 +14806,7 @@ to specify a custom environment.
,#+END_EXAMPLE
#+end_example
-You can also pass options to the environment with the ~:options~
-parameter. For example:
+To pass options to the environment, use the ~:options~ parameter:
#+begin_example
,#+ATTR_LATEX: :environment Verbatim :options [fontsize=\footnotesize]
@@ -14813,13 +14815,15 @@ parameter. For example:
,#+END_EXAMPLE
#+end_example
-exports to:
+#+vindex: org-latex-packages-alist
+*Note:* when you use ~Verbatim~ in one or more example blocks, add ~fancyvrb~
to
+~org-latex-packages-alist~, or include:
-#+begin_example
-\begin{Verbatim}[fontsize=\footnotesize]
- This sentence is false.
-\end{Verbatim}
-#+end_example
+#+BEGIN_SRC org
+,#+LATEX_HEADER: \usepackage{fancyvrb}
+#+END_SRC
+
+in your document header.
*** Special blocks in LaTeX export
:PROPERTIES:
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index fe1a3fe36f..40fa1e6aa9 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -46,6 +46,11 @@ set interactively from the priority context menus.
# adding new customizations, or changing the interpretation of the
# existing customizations.
+*** New custom variable ~org-latex-default-example-environment~
+
+You can set the LaTeX environment used in ~example~ blocks with this
+variable.
+
** New functions and changes in function arguments
# This also includes changes in function behavior from Elisp perspective.
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index c752e1e26a..5b9704b884 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -799,6 +799,13 @@ default we use here encompasses both."
:group 'org-export-latex
:type 'string)
+(defcustom org-latex-default-example-environment "verbatim"
+ "Default environment used in example blocks."
+ :group 'org-export-latex
+ :package-version '(Org . "10.0")
+ :type 'string
+ :safe #'stringp)
+
;;;; Tables
(defcustom org-latex-default-table-environment "tabular"
@@ -2226,7 +2233,7 @@ information."
(when (org-string-nw-p (org-element-property :value example-block))
(let ((environment (or (org-export-read-attribute
:attr_latex example-block :environment)
- "verbatim"))
+ org-latex-default-example-environment))
(options (or (org-export-read-attribute
:attr_latex example-block :options)
"")))
diff --git a/testing/lisp/test-ox-latex.el b/testing/lisp/test-ox-latex.el
index 28ccfe7254..7e82cb7892 100644
--- a/testing/lisp/test-ox-latex.el
+++ b/testing/lisp/test-ox-latex.el
@@ -372,8 +372,24 @@ Fake test document
(should (search-forward "\\documentclass" nil t))
;; And after this
(should (search-forward "\\begin{document}" nil t))))
+(ert-deftest test-ox-latex/latex-default-example-with-options ()
+ "Test #+ATTR_LATEX: :options with custom environment"
+ (let ((org-latex-default-example-environment "Verbatim"))
+ (org-test-with-exported-text
+ 'latex
+ "#+TITLE: Test adding options to EXAMPLE
-(ert-deftest test-ox-latex/math-in-alt-title ()
+* Test
+
+#+ATTR_LATEX: :options [frame=double]
+#+BEGIN_EXAMPLE
+How do you do?
+#+END_EXAMPLE
+"
+ (goto-char (point-min))
+ (should (search-forward "\\begin{document}\n" nil t))
+ (should (search-forward "\\begin{Verbatim}[frame=double]\n" nil t)))))
+ (ert-deftest test-ox-latex/math-in-alt-title ()
"Test math wrapping in ALT_TITLE properties."
(org-test-with-exported-text
'latex
