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 @@ 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 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 @@ 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 fe73bf686..e6232d8d2 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 4a077bb27..f81625b45 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 "\\" 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 @@ 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 25e02b258..28f950813 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.