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

[Ihor Radchenko]

Leo Butler <Leo.Butler@umanitoba.ca> 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.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
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 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>