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

[Ihor Radchenko]

Jack Kamm <jackkamm@gmail.com> writes:

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

Not necessarily confusing. We just need to clearly separate :results
file, :results graphics file, and :results file link.

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

":results graphics file" imply that graphics generated during code block
execution is saved to file specified in the :file header args.
This feature is only available for some backends that can derive
graphics data from the source block. When :file is not specified, using
the actual code block output is confusing, and we may want to reconsider
this behaviour.

>> :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.
> ...
> 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 [**].

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.

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