[elpa] externals/org b4e4b3c502 07/13: ox-latex: Replace `org-latex-listings'

[ELPA Syncer]

branch: externals/org
commit b4e4b3c502691180c20a57b8b0598160f5ffdc3f
Author: TEC <tec@tecosaur.com>
Commit: TEC <tec@tecosaur.com>

    ox-latex: Replace `org-latex-listings'
    
    * lisp/ox-latex.el (org-latex-src-block, org-latex-keyword,
    org-latex-inline-src-block, org-latex-template,
    org-latex--caption/label-string, org-latex-engraved-preamble,
    org-latex-listings): Replace `org-latex-listings' with
    `org-latex-src-block-backend', which now can be set to listings/verbatim
    and no longer advertises t/nil as valid values.
    
    * lisp/ox-beamer.el (org-beamer-template): Update in the same manner as
    `org-latex-template'.
    
    * lisp/org-compat.el: Make `org-latex-listings' an obsolete alias for
    `org-latex-src-block-backend'.
    
    * testing/lisp/test-ox.el: Replace `org-latex-listings' reference with
    `org-latex-src-block-backend'.
    
    * doc/org-manual.org (Footnotes, LaTeX specific properties, Literal
    Examples): Replace references to `org-latex-listings' with
    `org-latex-src-block-backend'.
    
    * etc/ORG-NEWS: Add a news entry noting this change.
    
    The variable `org-latex-listings' originally indicated whether source
    blocks should use the listings LaTeX package, or not.  This usage has
    evolved over the years, and now it sets one of four different
    fontification backends.  This renaming should make the variable name a
    bit less misleading.
---
 doc/org-manual.org      |   6 +--
 etc/ORG-NEWS            |   9 ++++
 lisp/org-compat.el      |   2 +
 lisp/ox-beamer.el       |   2 +-
 lisp/ox-latex.el        | 117 +++++++++++++++++++++++++++---------------------
 testing/lisp/test-ox.el |   2 +-
 6 files changed, 81 insertions(+), 57 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index c0d38cd8c3..60bded4198 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11159,7 +11159,7 @@ Here is an example
 #+end_example
 
 #+cindex: formatting source code, markup rules
-#+vindex: org-latex-listings
+#+vindex: org-latex-src-block-backend
 If the example is source code from a programming language, or any
 other text that can be marked up by Font Lock in Emacs, you can ask
 for the example to look like the fontified Emacs buffer[fn:114].  This
@@ -16304,12 +16304,12 @@ Settings]]), however, override everything.
 | ~:latex-link-with-unknown-path-format~ | 
~org-latex-link-with-unknown-path-format~ |
 | ~:latex-listings-langs~                | ~org-latex-listings-langs~          
      |
 | ~:latex-listings-options~              | ~org-latex-listings-options~        
      |
-| ~:latex-listings~                      | ~org-latex-listings~                
      |
 | ~:latex-minted-langs~                  | ~org-latex-minted-langs~            
      |
 | ~:latex-minted-options~                | ~org-latex-minted-options~          
      |
 | ~:latex-prefer-user-labels~            | ~org-latex-prefer-user-labels~      
      |
 | ~:latex-subtitle-format~               | ~org-latex-subtitle-format~         
      |
 | ~:latex-subtitle-separate~             | ~org-latex-subtitle-separate~       
      |
+| ~:latex-src-block-backend~             | ~org-latex-src-block-backend~       
      |
 | ~:latex-table-scientific-notation~     | 
~org-latex-table-scientific-notation~     |
 | ~:latex-tables-booktabs~               | ~org-latex-tables-booktabs~         
      |
 | ~:latex-tables-centered~               | ~org-latex-tables-centered~         
      |
@@ -22256,7 +22256,7 @@ a fragment, see the documentation of the function
 version 1.34 of the =htmlize.el= package, which you need to install).
 Fontified code chunks in LaTeX can be achieved using either the
 [[https://www.ctan.org/pkg/listings][listings]] package or the 
[[https://www.ctan.org/pkg/minted][minted]] package.  Refer to
-~org-latex-listings~ for details.
+~org-latex-src-block-backend~ for details.
 
 [fn:115] Source code in code blocks may also be evaluated either
 interactively or on export.  See [[*Working with Source Code]] for more
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 27de6da624..ebb3cd6493 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -273,6 +273,15 @@ Chmod-style permissions are based on the new variable
 ~org-babel-tangle-default-file-mode~.
 
 *** A new custom setting =org-agenda-clock-report-header= to add a header to 
org agenda clock report
+
+*** ~org-latex-listings~ has been replaced with ~org-latex-src-block-backend~
+
+~org-latex-listings~ has been renamed to better reflect the current
+purpose of the variable.  The replacement variable
+~org-latex-src-block-backend~ acts in exactly the same way, however it
+accepts =listings= and =verbatim= in place of =t= and =nil= (which
+still work, but are no longer listed as valid options).
+
 * Version 9.5
 
 ** Important announcements and breaking changes
diff --git a/lisp/org-compat.el b/lisp/org-compat.el
index a29f206a4b..7041976452 100644
--- a/lisp/org-compat.el
+++ b/lisp/org-compat.el
@@ -324,6 +324,8 @@ Counting starts at 1."
   'org-preview-latex-default-process "9.0")
 (define-obsolete-variable-alias 'org-latex-preview-ltxpng-directory
   'org-preview-latex-image-directory "9.0")
+(define-obsolete-variable-alias 'org-latex-listings
+  'org-latex-src-block-backend "9.6")
 (define-obsolete-function-alias 'org-table-p 'org-at-table-p "9.0")
 (define-obsolete-function-alias 'org-on-heading-p 'org-at-heading-p "9.0")
 (define-obsolete-function-alias 'org-at-regexp-p 'org-in-regexp "8.3")
diff --git a/lisp/ox-beamer.el b/lisp/ox-beamer.el
index fe73bf6865..e6232d8d27 100644
--- a/lisp/ox-beamer.el
+++ b/lisp/ox-beamer.el
@@ -858,7 +858,7 @@ holding export options."
        (and (stringp template)
            (format-spec template (org-latex--format-spec info))))
      ;; engrave-faces-latex preamble
-     (when (and (eq org-latex-listings 'engraved)
+     (when (and (eq org-latex-src-block-backend 'engraved)
                 (org-element-map (plist-get info :parse-tree)
                     '(src-block inline-src-block) #'identity
                     info t))
diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index 4a077bb277..f81625b45a 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -143,7 +143,7 @@
     (:latex-inactive-timestamp-format nil nil 
org-latex-inactive-timestamp-format)
     (:latex-inline-image-rules nil nil org-latex-inline-image-rules)
     (:latex-link-with-unknown-path-format nil nil 
org-latex-link-with-unknown-path-format)
-    (:latex-listings nil nil org-latex-listings)
+    (:latex-src-block-backend nil nil org-latex-src-block-backend)
     (:latex-listings-langs nil nil org-latex-listings-langs)
     (:latex-listings-options nil nil org-latex-listings-options)
     (:latex-minted-langs nil nil org-latex-minted-langs)
@@ -937,22 +937,22 @@ The function should return the string to be exported."
 
 ;; Src blocks
 
-(defcustom org-latex-listings nil
-  "Non-nil means export source code using the listings package.
+(defcustom org-latex-src-block-backend 'verbatim
+  "Backend used to generate source code listings.
 
-This package will fontify source code, possibly even with color.
-There are four implementations of this functionality you may
+This sets the behaviour for fontifying source code, possibly even with
+color.  There are four implementations of this functionality you may
 choose from (ordered from least to most capable):
-1. Verbatim (nil)
-2. Listings (t)
-3. Minted (minted)
-4. Engraved (engraved)
+1. Verbatim
+2. Listings
+3. Minted
+4. Engraved
 
 The first two options provide basic syntax
 highlighting (listings), or none at all (verbatim).
 
-When using listings, you also need to make use of the LaTeX
-\"listings\" package. The \"color\" package is also needed if you
+When using listings, you also need to make use of LaTeX package
+\"listings\"e. The \"color\" LaTeX package is also needed if you
 would like color too.  These can simply be added to
 `org-latex-packages-alist', using customise or something like:
 
@@ -963,27 +963,12 @@ would like color too.  These can simply be added to
 There are two further options for more comprehensive
 fontification. The first can be set with,
 
-  (setq org-latex-listings \\='engraved)
+  (setq org-latex-src-block-backend \\='minted)
 
-which causes source code to be run through
-`engrave-faces-latex-buffer', which generates colorings using
-Emacs' font-lock information.  This requires the engrave-faces
-package (availible from ELPA), and the fvextra LaTeX package be
-installed.
-
-The styling of the engraved result can customised with
-`org-latex-engraved-preamble' and `org-latex-engraved-options'.
-The default preamble also uses the tcolorbox LaTeX package in
-addition to fvextra.
-
-The second more comprehensive option can be set with,
-
-  (setq org-latex-listings \\='minted)
-
-which causes source code to be exported using the minted package
-as opposed to listings.  If you want to use minted, you need to
-add the minted package to `org-latex-packages-alist', for example
-using customize, or with
+which causes source code to be exported using the LaTeX package
+minted as opposed to listings.  If you want to use minted, you
+need to add the minted package to `org-latex-packages-alist', for
+example using customize, or with
 
   (require \\='ox-latex)
   (add-to-list \\='org-latex-packages-alist \\='(\"newfloat\" \"minted\"))
@@ -996,14 +981,29 @@ passed to pdflatex.
 The minted choice has possible repercussions on the preview of
 latex fragments (see `org-preview-latex-fragment').  If you run
 into previewing problems, please consult
-URL `https://orgmode.org/worg/org-tutorials/org-latex-preview.html'."
+URL `https://orgmode.org/worg/org-tutorials/org-latex-preview.html'.
+
+The most comprehensive option can be set with,
+
+  (setq org-latex-src-block-backend \\='engraved)
+
+which causes source code to be run through
+`engrave-faces-latex-buffer', which generates colorings using
+Emacs' font-lock information.  This requires the Emacs package
+engrave-faces (availible from ELPA), and the LaTeX package
+fvextra be installed.
+
+The styling of the engraved result can customised with
+`org-latex-engraved-preamble' and `org-latex-engraved-options'.
+The default preamble also uses the LaTeX package tcolorbox in
+addition to fvextra."
   :group 'org-export-latex
   :type '(choice
-         (const :tag "Use listings" t)
+         (const :tag "Use listings" listings)
          (const :tag "Use minted" minted)
          (const :tag "Use engrave-faces-latex" engraved)
-         (const :tag "Export verbatim" nil))
-  :safe (lambda (s) (memq s '(t nil minted engraved))))
+         (const :tag "Export verbatim" verbatim))
+  :safe (lambda (s) (memq s '(listings minted engraved verbatim))))
 
 (defcustom org-latex-listings-langs
   '((emacs-lisp "Lisp") (lisp "Lisp") (clojure "Lisp")
@@ -1203,7 +1203,7 @@ will produce
 
 [LISTINGS-SETUP]"
   "Preamble content injected when using engrave-faces-latex for source blocks.
-This is relevant when `org-latex-listings' is set to `engraved'.
+This is relevant when `org-latex-src-block-backend' is set to `engraved'.
 
 There is quite a lot of flexibility in what this preamble can be,
 as long as it:
@@ -1526,7 +1526,8 @@ For non-floats, see `org-latex--wrap-label'."
                            main)
                       (and (eq type 'src-block)
                            (not (plist-get attr :float))
-                           (null (plist-get info :latex-listings)))))
+                           (memq (plist-get info :latex-src-block-backend)
+                                  '(verbatim nil)))))
         (short (org-export-get-caption element t))
         (caption-from-attr-latex (plist-get attr :caption)))
     (cond
@@ -1546,7 +1547,8 @@ For non-floats, see `org-latex--wrap-label'."
                      (paragraph "figure")
                      (image "figure")
                      (special-block "figure")
-                     (src-block (if (plist-get info :latex-listings)
+                     (src-block (if (not (memq (plist-get info 
:latex-src-block-backend)
+                                                '(verbatim nil)))
                                     "listing"
                                   "figure"))
                      (t (symbol-name type*)))
@@ -1933,7 +1935,7 @@ holding export options."
        (and (stringp template)
             (format-spec template spec)))
      ;; engrave-faces-latex preamble
-     (when (and (eq org-latex-listings 'engraved)
+     (when (and (eq org-latex-src-block-backend 'engraved)
                 (org-element-map (plist-get info :parse-tree)
                     '(src-block inline-src-block) #'identity
                     info t))
@@ -2321,11 +2323,17 @@ CONTENTS holds the contents of the item.  INFO is a 
plist holding
 contextual information."
   (let ((code (org-element-property :value inline-src-block))
         (lang (org-element-property :language inline-src-block)))
-    (pcase (plist-get info :latex-listings)
-      ('nil (org-latex--text-markup code 'code info))
-      ('minted (org-latex-inline-src-block--minted info code lang))
-      ('engraved (org-latex-inline-src-block--engraved info code lang))
-      (_ (org-latex-inline-src-block--listings info code lang)))))
+    (pcase (plist-get info :latex-src-block-backend)
+      (`verbatim (org-latex--text-markup code 'code info))
+      (`minted (org-latex-inline-src-block--minted info code lang))
+      (`engraved (org-latex-inline-src-block--engraved info code lang))
+      (`listings (org-latex-inline-src-block--listings info code lang))
+      (oldval
+       (message "Please update the LaTeX src-block-backend to %s"
+                (if oldval "listings" "verbatim"))
+       (if oldval
+           (org-latex-inline-src-block--listings info code lang)
+         (org-latex--text-markup code 'code info))))))
 
 (defun org-latex-inline-src-block--minted (info code lang)
   "Transcode an inline src block's content from Org to LaTeX, using minted.
@@ -2508,7 +2516,7 @@ CONTENTS is nil.  INFO is a plist holding contextual 
information."
              (concat depth (and depth "\n") "\\tableofcontents"))))
         ((string-match-p "\\<tables\\>" value) "\\listoftables")
         ((string-match-p "\\<listings\\>" value)
-         (cl-case (plist-get info :latex-listings)
+         (cl-case (plist-get info :latex-src-block-backend)
            ((nil) "\\listoffigures")
            (minted "\\listoflistings")
            (engraved "\\listoflistings")
@@ -3195,15 +3203,20 @@ contextual information."
            (num-start (org-export-get-loc src-block info))
            (retain-labels (org-element-property :retain-labels src-block))
            (attributes (org-export-read-attribute :attr_latex src-block))
-           (float (plist-get attributes :float))
-           (listings (plist-get info :latex-listings)))
+           (float (plist-get attributes :float)))
       (funcall
-       (pcase listings
-         ((or (pred not) (guard (not lang))) #'org-latex-src-block--verbatim)
+       (pcase (plist-get info :latex-src-block-backend)
+         ((or `verbatim (guard (not lang))) #'org-latex-src-block--verbatim)
+         (`minted #'org-latex-src-block--minted)
+         (`engraved #'org-latex-src-block--engraved)
+         (`listings #'org-latex-src-block--listings)
          ((guard custom-env) #'org-latex-src-block--custom)
-         ('minted #'org-latex-src-block--minted)
-         ('engraved #'org-latex-src-block--engraved)
-         (_ #'org-latex-src-block--listings))
+         (oldval
+          (message "Please update the LaTeX src-block-backend to %s"
+                   (if oldval "listings" "verbatim"))
+          (if oldval
+              #'org-latex-src-block--listings
+            #'org-latex-src-block--verbatim)))
        :src-block src-block
        :info info
        :lang lang
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 25e02b2588..28f9508132 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -3978,7 +3978,7 @@ This test does not cover listings and custom 
environments."
 \\end{verbatim}
 \\caption{Caption is below, 60\\%s}
 \\end{figure*}"
-            (let ((org-latex-listings 'minted) ; inactive due to missing lang
+            (let ((org-latex-src-block-backend 'minted) ; inactive due to 
missing lang
                   (org-latex-default-figure-position "tp"))
               ;; Namely "multicolumn" value to get just figure environment
               ;; looks like a bug.