[elpa] externals/org b8ee1315a1 2/7: ox-org: Do not process citations by default

[ELPA Syncer]

branch: externals/org
commit b8ee1315a1cd80fb92f2577f480c475486a71907
Author: Ihor Radchenko <yantar92@posteo.net>
Commit: Ihor Radchenko <yantar92@posteo.net>

    ox-org: Do not process citations by default
    
    * lisp/ox.el (org-export-options-alist): Add new export option
    :with-cite-processors that allows disabling citation processors.
    (org-export-process-citations): New customization (t by default)
    defining the default value of :with-cite-processors export option.
    (org-export-as):
    (org-export--annotate-info): Disable citation processors when
    :with-cite-processors is nil.
    * lisp/ox-org.el (org-org-with-cite-processors): New custom
    option (nil by default) controlling whether to use citation processors
    when exporting to Org.
    (org): Set :with-cite-processors according to the new option.  Declare
    transcoders for citation and citation-reference objects.
    * doc/org-manual.org (Summary of the export process): Update the
    export flow description.
    * etc/ORG-NEWS (Org export backends can now disable citation processors):
    (=ox-org= disables citation processors by default):
    (New option ~org-export-process-citations~):
    (New option ~org-org-with-cite-processors~): Document the changes.
    
    The change in ox-org behavior also fixes citation objects being
    removed unconditionally from table src block results.
    
    Reported-by: Stanislav Vlasov <S.Vlasov@tilburguniversity.edu>
    Link: https://orgmode.org/list/87edrin6jw.fsf@localhost
---
 doc/org-manual.org | 15 +++++++++------
 etc/ORG-NEWS       | 35 +++++++++++++++++++++++++++++++++++
 lisp/ox-org.el     | 10 +++++++++-
 lisp/ox.el         | 18 +++++++++++++-----
 4 files changed, 66 insertions(+), 12 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 72e4e966e1..4f414ea9d7 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 7d2f70ab64..ba7b0186f1 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 8400e06e49..28f5ca26fb 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 5bf55ec3b3..90eb20fa55 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