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