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

[Ihor Radchenko]

Jack Kamm <jackkamm@gmail.com> writes:

> Ihor Radchenko <yantar92@posteo.net> writes:
>
>> ":results file" imply that results of the code block are written to a file
>> (the file is specified using header args).
>>
>> ":results file link" imply that results of the code block are interpreted
>> as file link. The fact that presence of :file header arg overrides this
>> behaviour is something we may want to reconsider - it is confusing.
>
> I think this is a lot clearer and more intuitive than the current
> behavior, and worth doing.
>
> But it is a breaking change, so it would be good to provide a variable
> to re-enable the previous behavior, for back-compatibility of older
> Org documents.

Not necessarily. We may instead arrange org-lint and possibly ob-core to
throw a warning when an src block uses confusing setting combinations.

Without changing the underlying behaviour.

Basically, discourage using confusing staff.

> In particular, the Worg matplotlib example of ":results file" without
> ":file" header arg is fairly old, and I have a few Org docs using
> ":results file" this way as well. So I would appreciate a
> backwards-compatibility variable if we change this.

We should update the docs to avoid such examples.

> On a related note, I think we should revert most of b088389c6 on
> bugfix branch. That documentation causes more harm than good, and is
> based on some confusion in [1] ("graphics" and "link" are _not_
> equivalent in general).

We should generally rewrite that part of the manual, I think.
My previous message was a tentative outline on how the things should be
presented in the manual.

And I do not think that we should do it on bugfix. It is a non-trivial
change, so it should go on main.

>> Sorry, but I do not fully understand.
>> Generated graphics is not what Org sees as "results of evaluation".
>> I think it is well illustrated by
>>
>>   #+begin_src R :file img.png
>>   hist(rnorm(100))
>>   "img.png is going to contain this string."
>>   #+end_src
>>
>>   #+begin_src R :file img.png :results graphics
>>   hist(rnorm(100))
>>   "But now img.png is going to contain graphics."
>>   #+end_src
>>
>> The latter has nothing to do with block output, which is a string.
>
> IMO block _value_ is string, while block _output_ is string AND
> graphics.

>From the point of view of ob-core.el, the output is stdout.
We even display stderr separately (except sessions, where they are
indistinguishable).

But I can see where the confusion is coming from.
"Output" can mean many things, including stdout, stderr, graphical
display (plot window), a file, a sound, or maybe even interactive
terminal ncurses interface.
I do not have a solid idea how to deal with such confusion on design
level.

> So by my interpretation, ob-R is slightly incorrect in how it handles
> ":results output graphics" vs ":results value graphics".  IMO the more
> technically correct approach is in the ob-python patch that I proposed
> a couple years ago [2], and plan to revisit soon. In that patch,
> ob-python ":results graphics output" will plot from pyplot.gcf(),
> while ":results graphics value" will expect a matplotlib.Figure object
> to be returned for plotting.

Sounds reasonable. Let me know if you need any help along the way.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>