emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@posteo.net>
To: Leo Butler <Leo.Butler@umanitoba.ca>
Cc: Org Mode Mailing List <emacs-orgmode@gnu.org>
Subject: Clarification on :results file vs. :results graphics file (was: [BUG] ob-doc-maxima.org and ob-maxima.el)
Date: Fri, 04 Nov 2022 04:03:06 +0000	[thread overview]
Message-ID: <87eduj5ptx.fsf@localhost> (raw)
In-Reply-To: <87edujkiq2.fsf@t14.reltub.ca>

[-- Attachment #1: Type: text/plain, Size: 3506 bytes --]

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual-Clarify-results-file-graphics-header-argu.patch --]
[-- Type: text/x-patch, Size: 1561 bytes --]

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


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


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

  parent reply	other threads:[~2022-11-04  4:03 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-11-02 19:39 [BUG] ob-doc-maxima.org and ob-maxima.el Leo Butler
2022-11-03  6:51 ` Ihor Radchenko
2022-11-03 18:15   ` Leo Butler
2022-11-04  3:38     ` Ihor Radchenko
2022-11-04 20:49       ` Leo Butler
2022-11-05  3:40         ` Ihor Radchenko
2022-11-07 14:24           ` Leo Butler
2022-11-04  4:03     ` Ihor Radchenko [this message]
2022-11-04 19:11       ` Clarification on :results file vs. :results graphics file Leo Butler
2022-11-05  3:41       ` Clarification on :results file vs. :results graphics file (was: [BUG] ob-doc-maxima.org and ob-maxima.el) Ihor Radchenko

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87eduj5ptx.fsf@localhost \
    --to=yantar92@posteo.net \
    --cc=Leo.Butler@umanitoba.ca \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).