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

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

"Charles C. Berry" <ccberry@ucsd.edu> writes:

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

Thank you.

Thinking about it, wouldn't `org-export-use-babel' or even
`org-export-with-babel' (as `org-export-with-author'...) be simpler and
yet, as clear?

> 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.

It looks good.

> 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'

What about:

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

> * 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.

Could you also specify the functions, or the manual section, being
modified?

OTOH, I don't think the chande made to "org-compat" requires an entry.

> 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

Nitpick: Org files

> +when Org mode is used as the markup language for a wiki.  No header arguments

Nitpick: when Org is used as ...

Rationale : in both case, we refer to Org as a markup language, not as
an editing mode.

> +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.

Could you add

  @vindex org-export-process-with-babel

above the whole paragraph?

>  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)

I think it is cleaner to add :safe #'null in the defcustom.

Regards,

-- 
Nicolas Goaziou