Re: [PATCH] ob-python: support header argument `:results file graphics'

[Jack Kamm]

Ihor Radchenko <yantar92@posteo.net> writes:

> Your patch appear to only add more confusion, IMHO.
>
> I feel that the description about :results file is confusing from the
> very beginning:

Well, I guess ":results file" has confusing behavior. So it's
difficult to write accurate, comprehensive, non-confusing
documentation for it ;)

> :results file may currently imply three things:
>
> 1. Results of evaluation are the _contents_ of a file
> 2. Results of evaluation are the path to a file
> 3. Results of evaluation are discarded and Org just inserts a constant
>    link, derived from header arguments.
>
> (3) is used for :results file graphics/:results file link
> (2) is used when Org is unable to deduce the file name from
>     :file/:file-ext+#+name
> (1) is used when the file name can be deduced from src block params    

Laying out the 3 behaviors this way seems clearer.

But I disagree that ":results graphics" means (3). It can behave as
(1) or (3), depending on the language. 

In practice (1) is the more common usage by far [*], and is also the
original intended use case [**].

(3) is just what happens when a Babel language doesn't implement
graphics (because then Org doesn't know how to save the graphical
results [***]).

If a Babel language doesn't implement graphics handling, the user can
workaround it by manually saving the plot. But this is just a
workaround, and we should discourage doing this with ":results
graphics", because it causes problems later if the language wants to
implement graphics support. Instead, ":results link" is the correct
usage for this case -- it always behaves as (3).

It is a mistake for the Org manual to define ":results link" and
":results graphics" as equivalent, because it is counter to the common
usage and understanding of ":results graphics", and because functions
like `org-babel-graphical-output-file' behave differently with
":results graphics". And what is the benefit of having 2 header
arguments with the same meaning? It is much more useful to define
":results graphics" for returning graphical output -- and indeed, that
is how ":results graphics" is generally used in practice.

[*] For example, nearly every code block in Worg with ":results
graphics" behaves as (1). Checking "grep results.\*graphics", I found
that 15 out of 16 code blocks behaved this way, inserting the
graphical results to file. The lone exception was in
ob-doc-clojure.org.

[**] ":results graphics" was originally created to implement (1) for
ob-R graphical results. See org commit 6bcbdce94, worg commit
8c49402c, and Version 7.5 Release Notes in worg/org-release-notes.org.
Also, see the Org Babel paper, which uses ":results graphics" with
behavior (1), not (3):

https://www.jstatsoft.org/article/view/v046i03

[***] Specifically, `org-babel-execute-src-block' doesn't know
anything about graphics, and needs to delegate to language-specific
implementation for that.