From e6dfd941daf06beb859ae6effd0be9d734121897 Mon Sep 17 00:00:00 2001 From: TEC Date: Sat, 7 May 2022 14:46:28 +0800 Subject: [PATCH 07/13] 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 c0d38cd8c..60bded419 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -11159,7 +11159,7 @@ ** Literal Examples #+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 @@ **** LaTeX specific properties | ~: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 @@ * Footnotes 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 27de6da62..ebb3cd649 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 a29f206a4..704197645 100644 --- a/lisp/org-compat.el +++ b/lisp/org-compat.el @@ -324,6 +324,8 @@ (define-obsolete-variable-alias 'org-latex-create-formula-image-program '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 fe73bf686..e6232d8d2 100644 --- a/lisp/ox-beamer.el +++ b/lisp/ox-beamer.el @@ -858,7 +858,7 @@ (defun org-beamer-template (contents info) (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 4a077bb27..f81625b45 100644 --- a/lisp/ox-latex.el +++ b/lisp/ox-latex.el @@ -143,7 +143,7 @@ (org-export-define-backend 'latex (: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 @@ (defcustom org-latex-format-inlinetask-function ;; 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 @@ (defcustom org-latex-listings nil 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 @@ (defcustom org-latex-listings nil 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 @@ (defcustom org-latex-engraved-preamble [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 @@ (defun org-latex--caption/label-string (element info) 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 @@ (defun org-latex--caption/label-string (element info) (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 @@ (defun org-latex-template (contents info) (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 @@ (defun org-latex-inline-src-block (inline-src-block _contents info) 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 @@ (defun org-latex-keyword (keyword _contents info) (concat depth (and depth "\n") "\\tableofcontents")))) ((string-match-p "\\" value) "\\listoftables") ((string-match-p "\\" 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 @@ (defun org-latex-src-block (src-block _contents info) (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 25e02b258..28f950813 100644 --- a/testing/lisp/test-ox.el +++ b/testing/lisp/test-ox.el @@ -3978,7 +3978,7 @@ (ert-deftest test-org-export/latex-src-block-verbatim-caption () \\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. -- 2.35.3