diff --git a/doc/org-manual.org b/doc/org-manual.org index 72e4e966e..4f414ea9d 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -16590,8 +16590,9 @@ Parse the temporary buffer, creating AST: settings, in-buffer keywords, =#+BIND= keywords, and buffer-local and global customization. The whole buffer is considered; -3. Determine contributing bibliographies and record them into export - options (see [[*Citations]]). The whole buffer is considered; +3. When ~org-org-with-cite-processors~ is non-nil (default), determine + contributing bibliographies and record them into export options + (see [[*Citations]]). The whole buffer is considered; 4. Execute ~org-export-filter-options-functions~; @@ -16633,9 +16634,10 @@ Parse the temporary buffer, creating AST: 8. Execute ~org-export-filter-parse-tree-functions~. These functions can modify the AST by side effects; -9. Replace citation AST nodes and =#+print_bibliography= keyword AST - nodes as prescribed by the selected citation export processor - (see [[*Citation export processors]]). +9. When ~org-org-with-cite-processors~ is non-nil (default), replace + citation AST nodes and =#+print_bibliography= keyword AST nodes as + prescribed by the selected citation export processor (see [[*Citation + export processors]]). #+texinfo: @noindent @@ -16672,7 +16674,8 @@ Post-process the exported text: by the export backend. Examples: Document author/title; HTML headers/footers; LaTeX preamble; - 4. Add bibliography metadata, as prescribed by the citation export + 4. When ~org-org-with-cite-processors~ is non-nil (default), add + bibliography metadata, as prescribed by the citation export processor; 5. Execute ~org-export-filter-final-output-functions~. diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 7d2f70ab6..ba7b0186f 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -13,6 +13,31 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org. * Version 9.7 (not released yet) ** Important announcements and breaking changes +*** Org export backends can now disable citation processors + +A new global export option ~:with-cite-processors~, when set to nil, +disables citation processors completely. This option is available to +export backends via ~:options-alist~ when defining the backend. + +The backends disabling citation processors must take care about +exporting citation objects and =print_bibliography= keywords via +transcoders. + +Users can disable citations processors by customizing new +~org-export-process-citations~ option. + +*** =ox-org= disables citation processors by default + +Previously, when exporting to Org, all the citations and +=print_bibliography= keywords, were transformed according to the +chosen citation processor. + +This is no loner the case. All the citation-related markup is now +exported as is. + +The previous behavior can be reverted by setting new custom option +~org-org-with-cite-processors~. + *** =ox-org= now exports special table rows by default Previously, when exporting to Org, special table rows (for example, @@ -508,6 +533,16 @@ 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-export-process-citations~ + +The new option controls whether to use citation processors to process +citations. + +*** New option ~org-org-with-cite-processors~ + +The new option controls whether to use citation processors to process +citations when exporting to Org. + *** New option ~org-org-with-special-rows~ The new options controls whether to export special table rows in diff --git a/lisp/ox-org.el b/lisp/ox-org.el index 8400e06e4..28f5ca26f 100644 --- a/lisp/ox-org.el +++ b/lisp/ox-org.el @@ -62,6 +62,11 @@ described in the Info node `(org)Advanced features'." :type 'boolean :package-version '(Org . "9.7")) +(defcustom org-org-with-cite-processors nil + "Non-nil means use citation processors when exporting citations." + :group 'org-export-org + :type 'boolean + :package-version '(Org . "9.7")) (org-export-define-backend 'org '((babel-call . org-org-identity) @@ -84,6 +89,8 @@ described in the Info node `(org)Advanced features'." (inline-src-block . org-org-identity) (inlinetask . org-org-identity) (italic . org-org-identity) + (citation . org-org-identity) + (citation-reference . org-org-identity) (item . org-org-identity) (keyword . org-org-keyword) (latex-environment . org-org-identity) @@ -124,7 +131,8 @@ described in the Info node `(org)Advanced features'." :filters-alist '((:filter-parse-tree . org-org--add-missing-sections)) :options-alist ;; Export special table rows. - '((:with-special-rows nil nil org-org-with-special-rows))) + '((:with-special-rows nil nil org-org-with-special-rows) + (:with-cite-processors nil nil org-org-with-cite-processors))) (defun org-org--add-missing-sections (tree _backend _info) "Ensure each headline has an associated section. diff --git a/lisp/ox.el b/lisp/ox.el index 5bf55ec3b..90eb20fa5 100644 --- a/lisp/ox.el +++ b/lisp/ox.el @@ -151,6 +151,7 @@ (:with-title nil "title" org-export-with-title) (:with-todo-keywords nil "todo" org-export-with-todo-keywords) ;; Citations processing. + (:with-cite-processors nil nil org-export-process-citations) (:cite-export "CITE_EXPORT" nil org-cite-export-processors)) "Alist between export properties and ways to set them. @@ -386,6 +387,10 @@ e.g. \"date:nil\"." :type 'boolean :safe #'booleanp) +(defcustom org-export-process-citations t + "Non-nil means process citations using citation processors. +nil will leave citation processing to export backend.") + (defcustom org-export-date-timestamp-format nil "Timestamp format string to use for DATE keyword. @@ -3004,7 +3009,8 @@ Return code as a string." (if (or (not (functionp template)) body-only) full-body (funcall template full-body info)))) ;; Call citation export finalizer. - (setq output (org-cite-finalize-export output info)) + (when (plist-get info :with-cite-processors) + (setq output (org-cite-finalize-export output info))) ;; Remove all text properties since they cannot be ;; retrieved from an external process. Finally call ;; final-output filter and return result. @@ -3074,8 +3080,9 @@ still inferior to file-local settings." info (org-export-get-environment backend subtreep ext-plist))) ;; Pre-process citations environment, i.e. install ;; bibliography list, and citation processor in INFO. - (org-cite-store-bibliography info) - (org-cite-store-export-processor info) + (when (plist-get info :with-cite-processors) + (org-cite-store-bibliography info) + (org-cite-store-export-processor info)) ;; De-activate uninterpreted data from parsed keywords. (dolist (entry (append (org-export-get-all-options backend) org-export-options-alist)) @@ -3115,8 +3122,9 @@ still inferior to file-local settings." ;; Process citations and bibliography. Replace each citation ;; and "print_bibliography" keyword in the parse tree with ;; the output of the selected citation export processor. - (org-cite-process-citations info) - (org-cite-process-bibliography info) + (when (plist-get info :with-cite-processors) + (org-cite-process-citations info) + (org-cite-process-bibliography info)) info)) ;;;###autoload