From: Jack Kamm <jackkamm@gmail.com>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: Liu Hui <liuhui1610@gmail.com>, emacs-orgmode@gnu.org
Subject: Re: [PATCH] ob-python: support header argument `:results file graphics'
Date: Wed, 05 Jul 2023 19:49:42 -0700 [thread overview]
Message-ID: <87sfa121q1.fsf@gmail.com> (raw)
In-Reply-To: <87y1ju8vpp.fsf@localhost>
[-- Attachment #1: Type: text/plain, Size: 1254 bytes --]
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.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-org-manual-Clarify-undocumented-uses-of-results-.patch --]
[-- Type: text/x-patch, Size: 2847 bytes --]
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
next prev parent reply other threads:[~2023-07-06 2:50 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-07-03 4:31 [PATCH] ob-python: support header argument `:results file graphics' Liu Hui
2023-07-03 9:28 ` Ihor Radchenko
2023-07-03 10:40 ` Liu Hui
2023-07-03 11:41 ` Ihor Radchenko
2023-07-03 13:23 ` Liu Hui
2023-07-04 11:29 ` Ihor Radchenko
2023-07-05 5:23 ` Jack Kamm
2023-07-05 11:05 ` Ihor Radchenko
2023-07-06 2:49 ` Jack Kamm [this message]
2023-07-07 10:53 ` Ihor Radchenko
2023-07-08 13:55 ` Jack Kamm
2023-07-09 9:12 ` Ihor Radchenko
2023-07-12 5:10 ` Jack Kamm
2023-07-12 8:38 ` Ihor Radchenko
2023-07-14 2:47 ` Jack Kamm
2023-07-05 8:09 ` Liu Hui
2023-07-05 4:55 ` Jack Kamm
2023-07-07 10:56 ` Ihor Radchenko
2023-07-05 5:13 ` Jack Kamm
2023-07-05 8:11 ` Liu Hui
2023-07-06 3:49 ` Jack Kamm
2023-07-06 9:54 ` Liu Hui
2023-07-08 13:59 ` Jack Kamm
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=87sfa121q1.fsf@gmail.com \
--to=jackkamm@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=liuhui1610@gmail.com \
--cc=yantar92@posteo.net \
/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).