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

[Jack Kamm]

Ihor Radchenko <yantar92@posteo.net> writes:

> Jack Kamm <jackkamm@gmail.com> writes:
>
>> I think the Worg documentation is accurately describing the behavior of
>> ob-python -- it's just that ob-python uses ":results file" in a
>> nonstandard way.
>
> May you please point me to the place in ob-python where :results file is
> specially treated?

ob-python doesn't treat :results file specially.  So "nonstandard" may
not be the right term.

In fact, :results file also works this way for other Babel languages.
And I used this behavior before for plotting with ob-reticulate blocks.

I attach a patch to fix the documentation in the manual about this.

As an aside: I would like ":results graphics" to partially revert its
old behavior before Org 9.3.  Prior to then, ob-R could generate a plot
with

:results graphics :file filename.png

but since commit 26ed66b23, we require the more verbose

:results graphics file :file filename.png

which seems unnecessarily verbose (since ":results graphics" doesn't do
anything without ":results file"), and also annoyingly broke many of my
Org documents before 2020.  I think it would be better if ":results
graphics" was equivalent to ":results graphics file", and may propose a
patch for this in future.

>From 538c464ca88c8a1646a1b80352f0c8fb9f114f08 Mon Sep 17 00:00:00 2001
From: Jack Kamm <jackkamm@gmail.com>
Date: Wed, 5 Jul 2023 19:02:25 -0700
Subject: [PATCH] doc/org-manual: Clarify undocumented uses of :results file

(Type):
(Format): Document that :results file is using the source block result
as file path when :file header argument is not present.  Document that
some Babel languages require :results graphics for plotting.
---
 doc/org-manual.org | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 71ad4d9e8..3bf1c7d7f 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -18558,11 +18558,7 @@ described in the documentation for individual 
languages.  See
   #+cindex: @samp{file-ext}, header argument
   If =file= header argument is missing, Org generates the base name of
   the output file from the name of the code block, and its extension
-  from the =file-ext= header argument.  In that case, both the name
-  and the extension are mandatory.
-
-  Result can also be interpreted as path to file.  See =:results
-  link=.
+  from the =file-ext= header argument.
 
   #+begin_example
   ,#+name: circle
@@ -18572,6 +18568,30 @@ described in the documentation for individual 
languages.  See
   ,#+END_SRC
   #+end_example
 
+  If both =file= and =file-ext= header arguments are missing, then
+  result is interpreted as path to file.
+
+  #+begin_example
+  ,#+BEGIN_SRC python :results file
+  import matplotlib.pyplot as plt
+  import numpy as np
+
+  fname = "path/to/file.png"
+
+  plt.plot(np.arange(5))
+  plt.savefig(fname)
+
+  return fname # return filename to org-mode
+  ,#+END_SRC
+  #+end_example
+
+  When =file= or =file-ext= header arguments are present, you can
+  prevent Org from directly writing to that file by using =:results
+  link= or =:results graphics=.  This might be desirable if you write
+  to the file within the code block itself.  Some Babel languages also
+  require these extra header arguments for plotting.  See =:results
+  link= for more details.
+
   #+cindex: @samp{file-desc}, header argument
   The =file-desc= header argument defines the description (see [[*Link
   Format]]) for the link.  If =file-desc= is present but has no value,
@@ -18644,8 +18664,11 @@ follows from the type specified above.
   [[file:org-mode-unicorn.svg]]
   #+end_example
 
-  If =:file= header argument is omitted, interpret source block result
-  as the file path.
+  =:results file graphics= is also needed by some languages for
+  plotting, such as ob-R, ob-julia, and ob-octave, because they save
+  plots to file via wrapper code in their respective languages rather
+  than via elisp.  Consult the documentation for the respective Babel
+  languages for more details.
 
 - =org= ::
 
-- 
2.41.0