Replace `org-export-babel-evaluate' with `org-export-use-babel'

* lisp/ob-exp.el (org-babel-exp-process-buffer): Change variable
  name `org-export-babel-evaluate' to `org-export-use-babel'.  Also
  change the name in its `defcustom' and set the `:safe' key.

* lisp/ox-icalendar.el (org-icalendar-export-current-agenda): Change
  variable name.

* lisp/ox.el (org-export-as): Change variable name.

* doc/org.texi (Exporting code blocks): Change variable name.  Amplify
   the explanation of what the variable does.  Add variable index entry.

* testing/lisp/test-ob-exp.el: Change variable name.

* testing/lisp/test-ob-lob.el: Change variable name.

* testing/lisp/test-ox.el: Change variable name.

Users were often confused that setting this variable to `nil' will
cause header arguments to be ignored in addition to preventing code
from being evaluated.  It is hoped that the documentation changes and
the name `org-export-use-babel' will better convey that everything
babel does can be switched off with this variable.

8 files changed, 47 insertions, 40 deletions

diff --git a/doc/org.texi b/doc/org.texi
index bd585da..7cf2a9b 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -14944,17 +14944,21 @@ Both the code block and its results will be exported.
 Neither the code block nor its results will be exported.
 @end table
 
-It is possible to inhibit the evaluation of code blocks during export.
-Setting the @code{org-export-babel-evaluate} variable to @code{nil} will
-ensure that no code blocks are evaluated as part of the export process.  This
-can be useful in situations where potentially untrusted Org mode files are
-exported in an automated fashion, for example when Org mode is used as the
-markup language for a wiki.  It is also possible to set this variable to
-@code{inline-only}.  In that case, only inline code blocks will be
-evaluated, in order to insert their results.  Non-inline code blocks are
-assumed to have their results already inserted in the buffer by manual
-evaluation.  This setting is useful to avoid expensive recalculations during
-export, not to provide security.
+@vindex org-export-use-babel
+
+It is possible to inhibit the evaluation of code blocks and ignore header
+arguments during export.  Setting the @code{org-export-use-babel} variable to
+@code{nil} will ensure that no code blocks are evaluated as part of the
+export process.  This can be useful in situations where potentially untrusted
+Org files are exported in an automated fashion, for example when Org is used
+as the markup language for a wiki.  No header arguments will be processed.
+For this reason it is often better to set `:eval never-export' to prevent
+code evaluation but still allow headers to be honored.  It is also possible
+to set this variable to @code{inline-only}.  In that case, only inline code
+blocks will be evaluated, in order to insert their results.  Non-inline code
+blocks are assumed to have their results already inserted in the buffer by
+manual evaluation.  This setting is useful to avoid expensive recalculations
+during export, not to provide security.
 
 Code blocks in commented subtrees (@pxref{Comment lines}) are never evaluated
 on export.  However, code blocks in subtrees excluded from export
diff --git a/lisp/ob-exp.el b/lisp/ob-exp.el
index 6aebcd5..a9b4b0b 100644
--- a/lisp/ob-exp.el
+++ b/lisp/ob-exp.el
@@ -38,10 +38,10 @@
 
 (defvar org-src-preserve-indentation)
 
-(defcustom org-export-babel-evaluate t
-  "Switch controlling code evaluation during export.
+(defcustom org-export-use-babel t
+  "Switch controlling code evaluation and header processing during export.
 When set to nil no code will be evaluated as part of the export
-process and no header argumentss will be obeyed.  When set to
+process and no header arguments will be obeyed.  When set to
 `inline-only', only inline code blocks will be executed.  Users
 who wish to avoid evaluating code on export should use the header
 argument `:eval never-export'."
@@ -49,8 +49,9 @@ argument `:eval never-export'."
   :version "24.1"
   :type '(choice (const :tag "Never" nil)
 		 (const :tag "Only inline code" inline-only)
-		 (const :tag "Always" t)))
-(put 'org-export-babel-evaluate 'safe-local-variable #'null)
+		 (const :tag "Always" t))
+  :safe #'null)
+
 
 (defmacro org-babel-exp--at-source (&rest body)
   "Evaluate BODY at the source of the Babel block at point.
@@ -128,10 +129,10 @@ this template."
 (defun org-babel-exp-process-buffer ()
   "Execute all Babel blocks in current buffer."
   (interactive)
-  (when org-export-babel-evaluate
+  (when org-export-use-babel
     (save-window-excursion
       (let ((case-fold-search t)
-	    (regexp (if (eq org-export-babel-evaluate 'inline-only)
+	    (regexp (if (eq org-export-use-babel 'inline-only)
 			"\\(call\\|src\\)_"
 		      "\\(call\\|src\\)_\\|^[ \t]*#\\+\\(BEGIN_SRC\\|CALL:\\)"))
 	    ;; Get a pristine copy of current buffer so Babel
diff --git a/lisp/org-compat.el b/lisp/org-compat.el
index 202b728..b7424b4 100644
--- a/lisp/org-compat.el
+++ b/lisp/org-compat.el
@@ -191,6 +191,8 @@ Counting starts at 1."
 (define-obsolete-variable-alias 'org-html-style 'org-html-head "24.4")
 (define-obsolete-function-alias 'org-insert-columns-dblock
   'org-columns-insert-dblock "Org 9.0")
+(define-obsolete-function-alias 'org-export-babel-evaluate
+  'org-export-use-babel "Org 9.1")
 
 (defun org-in-fixed-width-region-p ()
   "Non-nil if point in a fixed-width region."
diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el
index c22866a..157108a 100644
--- a/lisp/ox-icalendar.el
+++ b/lisp/ox-icalendar.el
@@ -879,7 +879,7 @@ The file is stored under the name chosen in
   "Export current agenda view to an iCalendar FILE.
 This function assumes major mode for current buffer is
 `org-agenda-mode'."
-  (let* ((org-export-babel-evaluate)	; Don't evaluate Babel block.
+  (let* ((org-export-use-babel)	; Don't evaluate Babel block.
 	 (contents
 	  (org-export-string-as
 	   (with-output-to-string
diff --git a/lisp/ox.el b/lisp/ox.el
index ca1143c..08578a4 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -3042,7 +3042,7 @@ Return code as a string."
 	 ;; again after executing Babel code.
 	 (org-set-regexps-and-options)
 	 (org-update-radio-target-regexp)
-	 (when org-export-babel-evaluate
+	 (when org-export-use-babel
 	   (org-babel-exp-process-buffer)
 	   (org-set-regexps-and-options)
 	   (org-update-radio-target-regexp))
diff --git a/testing/lisp/test-ob-exp.el b/testing/lisp/test-ob-exp.el
index 744234c..4b96b72 100644
--- a/testing/lisp/test-ob-exp.el
+++ b/testing/lisp/test-ob-exp.el
@@ -29,7 +29,7 @@
 Current buffer is a copy of the original buffer."
   `(let ((string (org-with-wide-buffer (buffer-string)))
 	 (narrowing (list (point-min) (point-max)))
-	 (org-export-babel-evaluate t))
+	 (org-export-use-babel t))
      (with-temp-buffer
        (org-mode)
        (insert string)
@@ -183,7 +183,7 @@ a table."
 (ert-deftest ob-exp/evaluate-all-executables-in-order ()
   (should
    (equal '(5 4 3 2 1)
-	  (let ((org-export-babel-evaluate t) *evaluation-collector*)
+	  (let ((org-export-use-babel t) *evaluation-collector*)
 	    (org-test-at-id "96cc7073-97ec-4556-87cf-1f9bffafd317"
 	      (org-narrow-to-subtree)
 	      (buffer-string)
@@ -202,7 +202,7 @@ Here is one at the end of a line. {{{results(=2=)}}}
 
 (ert-deftest ob-exp/exports-inline-code ()
   (let ((org-babel-inline-result-wrap "=%s=")
-	(org-export-babel-evaluate t))
+	(org-export-use-babel t))
     (should
      (string-match "\\`src_emacs-lisp\\(?:\\[]\\)?{(\\+ 1 1)}$"
 		   (org-test-with-temp-text
@@ -259,7 +259,7 @@ Here is one that is also evaluated: src_sh[]{echo 4} {{{results(=4=)}}}")
 results), the resulting code block `src_emacs-lisp{2}' should also be
 evaluated."
   (let ((org-babel-inline-result-wrap "=%s=")
-	(org-export-babel-evaluate t))
+	(org-export-use-babel t))
     (should
      (string-match "\\`{{{results(src_emacs-lisp\\[\\]{2})}}}$"
 		   (org-test-with-temp-text
@@ -270,7 +270,7 @@ evaluated."
 (ert-deftest ob-exp/exports-inline-code-eval-code-once ()
   "Ibid above, except that the resulting inline code block should not
 be evaluated."
-  (let ((org-export-babel-evaluate t))
+  (let ((org-export-use-babel t))
     (should
      (string-match "{{{results(src_emacs-lisp\\(?:\\[[: a-zA-Z]+]\\)?{2})}}}$"
 		   (org-test-with-temp-text
@@ -280,7 +280,7 @@ be evaluated."
 		     (buffer-string))))))
 
 (ert-deftest ob-exp/exports-inline-code-double-eval-exports-both ()
-  (let ((org-export-babel-evaluate t))
+  (let ((org-export-use-babel t))
     (should
      (string-match (concat "\\`src_emacs-lisp\\(?:\\[]\\)?{(\\+ 1 1)} "
 			   "{{{results(src_emacs-lisp\\[ :exports code\\]{2})}}}$")
@@ -351,7 +351,7 @@ be evaluated."
 			    result)))))
 
 (ert-deftest ob-exp/export-from-a-temp-buffer ()
-  (let ((org-export-babel-evaluate t))
+  (let ((org-export-use-babel t))
     (org-test-with-temp-text
 	"
 #+Title: exporting from a temporary buffer
@@ -377,7 +377,7 @@ be evaluated."
 
 (ert-deftest ob-export/export-with-results-before-block ()
   "Test export when results are inserted before source block."
-  (let ((org-export-babel-evaluate t))
+  (let ((org-export-use-babel t))
     (should
      (equal
       "#+RESULTS: src1
@@ -452,7 +452,7 @@ be evaluated."
 
 (ert-deftest ob-export/export-under-commented-headline ()
   "Test evaluation of code blocks under COMMENT headings."
-  (let ((org-export-babel-evaluate t)
+  (let ((org-export-use-babel t)
 	(org-babel-inline-result-wrap "=%s="))
     ;; Do not eval block in a commented headline.
     (should
@@ -516,21 +516,21 @@ src_emacs-lisp{(+ 1 1)}"
      (org-babel-exp-process-buffer) t)))
 
 (ert-deftest ob-export/babel-evaluate ()
-  "Test `org-export-babel-evaluate' effect."
+  "Test `org-export-use-babel' effect."
   ;; When nil, no Babel code is executed.
   (should-not
    (string-match-p
     "2"
     (org-test-with-temp-text
 	"#+BEGIN_SRC emacs-lisp :exports results\n(+ 1 1)\n#+END_SRC"
-      (let ((org-export-babel-evaluate nil)) (org-babel-exp-process-buffer))
+      (let ((org-export-use-babel nil)) (org-babel-exp-process-buffer))
       (buffer-string))))
   (should-not
    (string-match-p
     "2"
     (org-test-with-temp-text
 	"src_emacs-lisp{(+ 1 1)}"
-      (let ((org-export-babel-evaluate nil)) (org-babel-exp-process-buffer))
+      (let ((org-export-use-babel nil)) (org-babel-exp-process-buffer))
       (buffer-string))))
   ;; When non-nil, all Babel code types are executed.
   (should
@@ -538,14 +538,14 @@ src_emacs-lisp{(+ 1 1)}"
     "2"
     (org-test-with-temp-text
 	"#+BEGIN_SRC emacs-lisp :exports results\n(+ 1 1)\n#+END_SRC"
-      (let ((org-export-babel-evaluate t)) (org-babel-exp-process-buffer))
+      (let ((org-export-use-babel t)) (org-babel-exp-process-buffer))
       (buffer-string))))
   (should
    (string-match-p
     "2"
     (org-test-with-temp-text
 	"src_emacs-lisp{(+ 1 1)}"
-      (let ((org-export-babel-evaluate t)) (org-babel-exp-process-buffer))
+      (let ((org-export-use-babel t)) (org-babel-exp-process-buffer))
       (buffer-string))))
   ;; When set to `inline-only' limit evaluation to inline code.
   (should-not
@@ -553,7 +553,7 @@ src_emacs-lisp{(+ 1 1)}"
     "2"
     (org-test-with-temp-text
 	"#+BEGIN_SRC emacs-lisp :exports results\n(+ 1 1)\n#+END_SRC"
-      (let ((org-export-babel-evaluate 'inline-only))
+      (let ((org-export-use-babel 'inline-only))
 	(org-babel-exp-process-buffer))
       (buffer-string))))
   (should
@@ -561,7 +561,7 @@ src_emacs-lisp{(+ 1 1)}"
     "2"
     (org-test-with-temp-text
 	"src_emacs-lisp{(+ 1 1)}"
-      (let ((org-export-babel-evaluate 'inline-only))
+      (let ((org-export-use-babel 'inline-only))
 	(org-babel-exp-process-buffer))
       (buffer-string)))))
 
@@ -571,7 +571,7 @@ src_emacs-lisp{(+ 1 1)}"
    (equal "#+BEGIN_SRC emacs-lisp\n0 (ref:foo)\n#+END_SRC"
 	  (org-test-with-temp-text
 	      "#+BEGIN_SRC emacs-lisp :exports code\n0 (ref:foo)\n#+END_SRC"
-	    (let ((org-export-babel-evaluate t)
+	    (let ((org-export-use-babel t)
 		  (org-coderef-label-format "(ref:foo)"))
 	      (org-babel-exp-process-buffer))
 	    (buffer-string))))
@@ -580,7 +580,7 @@ src_emacs-lisp{(+ 1 1)}"
     "#+BEGIN_SRC emacs-lisp -l \"r:%s\"\n1 r:foo\n#+END_SRC"
     (org-test-with-temp-text
 	"#+BEGIN_SRC emacs-lisp -l \"r:%s\" -lisp :exports code\n1 r:foo\n#+END_SRC"
-      (let ((org-export-babel-evaluate t))
+      (let ((org-export-use-babel t))
 	(org-babel-exp-process-buffer))
       (buffer-string)))))
 
diff --git a/testing/lisp/test-ob-lob.el b/testing/lisp/test-ob-lob.el
index 55a01ef..c89c8e9 100644
--- a/testing/lisp/test-ob-lob.el
+++ b/testing/lisp/test-ob-lob.el
@@ -80,7 +80,7 @@
 (ert-deftest test-ob-lob/export-lob-lines ()
   "Test the export of a variety of library babel call lines."
   (let ((org-babel-inline-result-wrap "=%s=")
-	(org-export-babel-evaluate t))
+	(org-export-use-babel t))
     (org-test-at-id "72ddeed3-2d17-4c7f-8192-a575d535d3fc"
       (org-narrow-to-subtree)
       (let ((string (org-with-wide-buffer (buffer-string)))
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 5300f52..c4cf154 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -900,7 +900,7 @@ Paragraph <2012-03-29 Thu>[2012-03-29 Thu]"
 #+BEGIN_SRC emacs-lisp
 \(+ 1 2)
 #+END_SRC"
-	    (let ((org-export-babel-evaluate t))
+	    (let ((org-export-use-babel t))
 	      (org-export-as (org-test-default-backend) 'subtree)))))
   ;; Subtree export should ignore leading planning line and property
   ;; drawer.