Ihor Radchenko <yanta...@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.
