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: Sat, 08 Jul 2023 06:55:17 -0700 [thread overview]
Message-ID: <87h6qe1pa2.fsf@gmail.com> (raw)
In-Reply-To: <871qhkxaay.fsf@localhost>
Ihor Radchenko <yantar92@posteo.net> writes:
> Your patch appear to only add more confusion, IMHO.
>
> I feel that the description about :results file is confusing from the
> very beginning:
Well, I guess ":results file" has confusing behavior. So it's
difficult to write accurate, comprehensive, non-confusing
documentation for it ;)
> :results file may currently imply three things:
>
> 1. Results of evaluation are the _contents_ of a file
> 2. Results of evaluation are the path to a file
> 3. Results of evaluation are discarded and Org just inserts a constant
> link, derived from header arguments.
>
> (3) is used for :results file graphics/:results file link
> (2) is used when Org is unable to deduce the file name from
> :file/:file-ext+#+name
> (1) is used when the file name can be deduced from src block params
Laying out the 3 behaviors this way seems clearer.
But I disagree that ":results graphics" means (3). It can behave as
(1) or (3), depending on the language.
In practice (1) is the more common usage by far [*], and is also the
original intended use case [**].
(3) is just what happens when a Babel language doesn't implement
graphics (because then Org doesn't know how to save the graphical
results [***]).
If a Babel language doesn't implement graphics handling, the user can
workaround it by manually saving the plot. But this is just a
workaround, and we should discourage doing this with ":results
graphics", because it causes problems later if the language wants to
implement graphics support. Instead, ":results link" is the correct
usage for this case -- it always behaves as (3).
It is a mistake for the Org manual to define ":results link" and
":results graphics" as equivalent, because it is counter to the common
usage and understanding of ":results graphics", and because functions
like `org-babel-graphical-output-file' behave differently with
":results graphics". And what is the benefit of having 2 header
arguments with the same meaning? It is much more useful to define
":results graphics" for returning graphical output -- and indeed, that
is how ":results graphics" is generally used in practice.
[*] For example, nearly every code block in Worg with ":results
graphics" behaves as (1). Checking "grep results.\*graphics", I found
that 15 out of 16 code blocks behaved this way, inserting the
graphical results to file. The lone exception was in
ob-doc-clojure.org.
[**] ":results graphics" was originally created to implement (1) for
ob-R graphical results. See org commit 6bcbdce94, worg commit
8c49402c, and Version 7.5 Release Notes in worg/org-release-notes.org.
Also, see the Org Babel paper, which uses ":results graphics" with
behavior (1), not (3):
https://www.jstatsoft.org/article/view/v046i03
[***] Specifically, `org-babel-execute-src-block' doesn't know
anything about graphics, and needs to delegate to language-specific
implementation for that.
next prev parent reply other threads:[~2023-07-08 13:56 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
2023-07-07 10:53 ` Ihor Radchenko
2023-07-08 13:55 ` Jack Kamm [this message]
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=87h6qe1pa2.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).