[PATCH] Re: HTML export with ":export" parameter with Orgmode 9.0

["Charles C. Berry" <ccberry@ucsd.edu>]

[-- Attachment #1: Type: text/plain, Size: 643 bytes --]

On Sat, 12 Nov 2016, Nicolas Goaziou wrote:

[discussion of problems interpreting the variable 
`org-export-babel-evaluate' deleted]

>>
>> It is tempting to `make-obsolete-variable' this variable and change
>> its name to something that more completely describes what does not
>> happen when set to nil.
>
> It can be done for Org 9.1.
>

OK. I changed the name to `org-export-process-with-babel', which I hope 
suggests more profound actions than `org-export-babel-evaluate'.

I think the attached patch does this properly, but this is my first use of 
`define-obsolete-function-alias', so it might be best to check what I have 
done.

Chuck

[-- Attachment #2: patch file --]
[-- Type: text/plain, Size: 14535 bytes --]

From 3885129980a02eb0d4694e9e15888dea6ee95c60 Mon Sep 17 00:00:00 2001
From: Charles Berry <ccberry@ucsd.edu>
Date: Sat, 12 Nov 2016 18:54:20 -0800
Subject: [PATCH] make-obsolete-variable `org-export-babel-evaluate'

* doc/org.texi: Better explain what the variable
  `org-export-process-with-babel' does.

* lisp/ob-exp.el: Small docstring change.

* lisp/org-compat.el: Define `org-export-babel-evaluate' as the
  obsolete alias for `org-export-process-with-babel'.

* lisp/ox-icalendar.el, lisp/ox.el, testing/lisp/test-ob-exp.el,
  testing/lisp/test-ob-lob.el, testing/lisp/test-ox.el: Change the
  obsolete variable name in many places.

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-process-with-babel' will better convey that everything
babel does can be switched off with this variable.
---
 doc/org.texi                | 24 +++++++++++++-----------
 lisp/ob-exp.el              | 12 ++++++------
 lisp/org-compat.el          |  2 ++
 lisp/ox-icalendar.el        |  2 +-
 lisp/ox.el                  |  2 +-
 testing/lisp/test-ob-exp.el | 36 ++++++++++++++++++------------------
 testing/lisp/test-ob-lob.el |  2 +-
 testing/lisp/test-ox.el     |  2 +-
 8 files changed, 43 insertions(+), 39 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index ede2352..81364d2 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -14938,17 +14938,19 @@ 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.
+It is possible to inhibit the evaluation of code blocks and ignore header
+arguments during export.  Setting the @code{org-export-process-with-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 mode files are exported in an automated fashion, for example
+when Org mode 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..1d77e6a 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-process-with-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'."
@@ -50,7 +50,7 @@ argument `:eval never-export'."
   :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)
+(put 'org-export-process-with-babel 'safe-local-variable #'null)
 
 (defmacro org-babel-exp--at-source (&rest body)
   "Evaluate BODY at the source of the Babel block at point.
@@ -128,10 +128,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-process-with-babel
     (save-window-excursion
       (let ((case-fold-search t)
-	    (regexp (if (eq org-export-babel-evaluate 'inline-only)
+	    (regexp (if (eq org-export-process-with-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..dc01a48 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-process-with-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..6a480f4 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-process-with-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..d67c56a 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-process-with-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..e32a03c 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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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-process-with-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..246cdb7 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-process-with-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..7705298 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-process-with-babel t))
 	      (org-export-as (org-test-default-backend) 'subtree)))))
   ;; Subtree export should ignore leading planning line and property
   ;; drawer.
-- 
2.6.4 (Apple Git-63)