Re: Clarification on :results file vs. :results graphics file (was: [BUG] ob-doc-maxima.org and ob-maxima.el)

[Ihor Radchenko]

Ihor Radchenko  writes:

> (Note: I'd say "nothing is written to the disk" is a bit misleading
> here. I am attaching a patch with clarification)

Applied onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=f5c89ba5f91a876ecbcc940e849adbb16fe2

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at .
Support Org development at ,
or support my work at 

Re: Clarification on :results file vs. :results graphics file

[Leo Butler]

On Fri, Nov 04 2022, Ihor Radchenko  wrote:

> Leo Butler  writes:
>
 @@ -145,7 +151,7 @@ This example is from 
 [[http://maxima.sourceforge.net/maxima-gnuplot.html][a tuto
  ,#+name: 3d-maxima
  ,#+header: :file images/maxima-3d.png
  ,#+header: :exports results
 -,#+header: :results graphics
 +,#+header: :results graphics file
>>>
>>> Using graphics together with file does not make sense.
>>
>> Ok. But I am not sure the code agrees with you. In ob-core.el,
>>  ...
>>
>> Is it, in your opinion, ob-maxima's responsibility to add "graphics" to
>> :result-params when :results file is specified?
>
> No.

Thank you for correcting yourself and me. I had arrived at the same
conclusion and was going to retract that `patch' to ob-maxima.el.

Leo

Clarification on :results file vs. :results graphics file (was: [BUG] ob-doc-maxima.org and ob-maxima.el)

[Ihor Radchenko]

Leo Butler  writes:

>>> @@ -145,7 +151,7 @@ This example is from 
>>> [[http://maxima.sourceforge.net/maxima-gnuplot.html][a tuto
>>>  ,#+name: 3d-maxima
>>>  ,#+header: :file images/maxima-3d.png
>>>  ,#+header: :exports results
>>> -,#+header: :results graphics
>>> +,#+header: :results graphics file
>>
>> Using graphics together with file does not make sense.
>
> Ok. But I am not sure the code agrees with you. In ob-core.el,
> `org-babel-graphical-output-file' is defined as:
>
> (defun org-babel-graphical-output-file (params)
>   "File where a babel block should send graphical output, per PARAMS.
> Return nil if no graphical output is expected.  Raise an error if
> the output file is ill-defined."
>   (let ((file (cdr (assq :file params
> (cond (file (and (member "graphics" (cdr (assq :result-params params)))
>file))
>  ...
>
> Is it, in your opinion, ob-maxima's responsibility to add "graphics" to
> :result-params when :results file is specified?

No. Let me put what the manual says on the question:

- :results header argument has multiple argument classes

Each code block can take only one option per class:

Collection
 For how the results should be collected from the code block;

Type
 For which type of result the code block will return; affects how
 Org processes and inserts results in the Org buffer;

Format
 For the result; affects how Org processes results;

Handling
 For inserting results once they are properly formatted.

:results file is the Type class.
:results graphics is the Format class.

They can be used together. I was wrong in my earlier reply.

‘file’
 Interpret as a filename.  Save the results of execution of the code
 block to that file, then insert a link to it.  You can control both
 the filename and the description associated to the link.

‘graphics’
 When used along with ‘file’ type, the result is a link to the file
 specified in ‘:file’ header argument.  However, unlike plain ‘file’
 type, nothing is written to the disk.  The block is used for its
 side-effects only, as in the following example:

(Note: I'd say "nothing is written to the disk" is a bit misleading
here. I am attaching a patch with clarification)

When we have :file foo.png :results file, Org will take the command
output, write it to foo.png, and insert the link to foo.png as code
block result.

When we have :file foo.png :results file graphics, Org will not write to
foo.png itself. Instead, it will expect the code execution to create
foo.png as a side effect. The code output will be ignored and the link
to foo.png will be inserted.

Note: ob-maxima wraps `org-babel-graphical-output-file' into
ignore-errors, which will hide missing :file spec error from user.
Unsure about the reasons behind it.

> @@ -77,6 +77,9 @@
>"Execute a block of Maxima entries with org-babel.
>  This function is called by `org-babel-execute-src-block'."
>(message "Executing Maxima source code block")
> +  ;; Make `:results file' imply `:results graphics file'
> +  (when (member "file" (assq :result-params params))
> +(push "graphics" (alist-get :result-params params)))

This will be wrong, as I explained above. :results file and :results
graphics file are expected to behave differently in the manual.

>From 73821c511e723e324e3f7aa9424003b8993ed412 Mon Sep 17 00:00:00 2001
Message-Id: <73821c511e723e324e3f7aa9424003b8993ed412.1667534563.git.yanta...@posteo.net>
From: Ihor Radchenko 
Date: Fri, 4 Nov 2022 12:01:19 +0800
Subject: [PATCH] org-manual: Clarify :results file graphics header argument
 meaning

* doc/org-manual.org (Format): Clarify the difference between
:results file and :results file graphics.  Update the example to
something that can be tried locally.
---
 doc/org-manual.org | 12 
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index dc2fc57cd..b3071ec6d 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18408,13 +18408,17 @@ *** Format
 
   When used along with =file= type, the result is a link to the file
   specified in =:file= header argument.  However, unlike plain =file=
-  type, nothing is written to the disk.  The block is used for its
-  side-effects only, as in the following example:
+  type, code block output is not written to the disk.  The block is
+  expected to generate the file by its side-effects only, as in the
+  following example:
 
   #+begin_example
-  ,#+begin_src shell :results file link :file "download.tar.gz"
-  wget -c "https://example.com/download.tar.gz;
+  ,#+begin_src shell :results file link :file "org-mode-unicorn.svg"
+wget -c "https://orgmode.org/resources/img/org-mode-unicorn.svg;
   ,#+end_src
+
+  ,#+RESULTS:
+  [[file:org-mode-unicorn.svg]]
   #+end_example
 
 - =org= ::
-- 
2.35.1


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more