From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id GF0/GfhqqWTRggAASxT56A (envelope-from ) for ; Sat, 08 Jul 2023 15:56:08 +0200 Received: from aspmx1.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id kAxeGfhqqWTq5wAA9RJhRA (envelope-from ) for ; Sat, 08 Jul 2023 15:56:08 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 05B2E381A3 for ; Sat, 8 Jul 2023 15:56:07 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=TJ+1W0o3; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1688824568; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=PYgkYScr5m21YVaIgVgOslmYtNng8JOx7tLbXur0ZNs=; b=ODtxY3I0YFgFpYfweVwKB4YOz5mJ/0raCXnrs54J8uLinIIACIk5DtZHe0RRG3WibXbjEC AyTndgALxjHSNQJ7DO0kjqVIezU9YUc/dG440YVUCH3PZpLT+UPy05r8ds7cthxN04hyCz +TtqwU99NKFKmu+ThS0B2HLDPfwG5qduqK0vGcELvG3DfVRnoEQemWyOV+joJ7dmMEpFis nSFjjl3LXBuCq1n8AmPlEDEyiiZobMQ0tktKkxEeILtEi9dFQrUjGKoj9ZSG1e+LnXTRi2 lmB8mwwpNhDttk1+i4x3ej6TXE6/ksaj9qb3ozcyLA3LAuhKg0qEa0NVKEXQvw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1688824568; a=rsa-sha256; cv=none; b=JG+737M1CTmy6IKSycKiQ1Fqd38/JMnC+1C8HX9AyFxu1Vg3RmGoG0UVrLPPOzbLWZ7mQz WMskzODFpYU31YMc6P328qa2dJ1ds8B6PFinRf2UU6YhNpF4X/MQefLk2KCMeInnH8+Jh9 WZbth7zS5ssI4V+taOWP0fSRMjID4VO83ZrGTn8nE+i2dbWEhcjGn2WaIJEmYajtLUxNIO KXykggFF+tVk9JzHsfqJT1yPLo2tPqn0gKxxh7bPjElefVsZrSFKtG7Ga49wndGtOWlcDZ JONCNRn3QaagAsJiMcXdy4bLYmAmD68JQR999MnzEhjezTV1dtCXyWzoiNbHwA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=TJ+1W0o3; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gmail.com Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qI8PE-00037K-VU; Sat, 08 Jul 2023 09:55:24 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qI8PD-000375-Ol for emacs-orgmode@gnu.org; Sat, 08 Jul 2023 09:55:23 -0400 Received: from mail-pf1-x42a.google.com ([2607:f8b0:4864:20::42a]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qI8PB-0006GQ-UZ for emacs-orgmode@gnu.org; Sat, 08 Jul 2023 09:55:23 -0400 Received: by mail-pf1-x42a.google.com with SMTP id d2e1a72fcca58-6726d5d92afso2701538b3a.1 for ; Sat, 08 Jul 2023 06:55:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1688824520; x=1691416520; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:from:to:cc:subject:date:message-id:reply-to; bh=PYgkYScr5m21YVaIgVgOslmYtNng8JOx7tLbXur0ZNs=; b=TJ+1W0o3+4PI4NhLDo+nmlotEW8NB72P8f0pB26YAM4pCb6A3UUAL93B/E7W6b4rme a6zLAGoQptlQV8brztzN45dBjKnpJsjaVQbfa+sxWn4OPruFkZ1bQyhifJMtX05WF3ZV 3Wn7tcmvx1PqXwoFWOv/8jcvn7+Fqu8wUroNs3/O9iS/4OHzHsk9BK64Zze5Yxc/viCF rxmvBBfjhj2yHzbZX7vX2MOQKLlz7I03XhVLT3qYxjYuJqCCD0lyzO9XNVpBGbaWCqNH D5QCmHHmQn2jrT+m/ixKcV1TvVyos3VMfIXK9omHjzD6zY/imuKOqxxcROQvl+2mDpfV kyEg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1688824520; x=1691416520; h=mime-version:message-id:date:references:in-reply-to:subject:cc:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=PYgkYScr5m21YVaIgVgOslmYtNng8JOx7tLbXur0ZNs=; b=e5GN9a1qegHASeIL1yRF6FJgLHK1mHejAvLfyV5pRPfcayDra4uXwtKOxsZIKow0g5 NqPGPHmAAA4IiuTu20wo/w9Mxkiadg3dwjZrIqKOv0QhPFQ00aWu/j+/UHWgYNCu07rK mHv+oIGoBY7FHEJBBBksLx4tKfMfwxMHI9NB9d0ZhCaQSb5OJp3nTBIJ03E68rA86kR6 o7yZW9QTAR25H+1Z8mzex0UehhZrf9CU7VZFVslk/e5C5S5Wue6M1NJXgOa/+k5tUJwd 0CYidevur2SqzZdO3+z9+nH5YdBtN04Q5n9OFhdXsRjqsKNec+XLvwRzd6zcQKnT81tJ zpvg== X-Gm-Message-State: ABy/qLblfGT4uNpZ4LJeDPz0c8xdXTZKjITE/hmr/gmlUEAmBOduGhnc vMvIRv73uK7AhUdG/7pDaGbZ1tHVJLI= X-Google-Smtp-Source: APBJJlFggi/g/PoykSnwv6beIH6ebruaIX/IQypYKypx9LIR8zj/AeV6fQ+PXDiU4l3Vl7JQ24eTrw== X-Received: by 2002:a05:6a21:788f:b0:130:89b2:d0d2 with SMTP id bf15-20020a056a21788f00b0013089b2d0d2mr6892777pzc.30.1688824519952; Sat, 08 Jul 2023 06:55:19 -0700 (PDT) Received: from localhost (157-131-78-143.fiber.dynamic.sonic.net. [157.131.78.143]) by smtp.gmail.com with ESMTPSA id k18-20020aa78212000000b0067a1f4f4f7dsm4386066pfi.169.2023.07.08.06.55.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 08 Jul 2023 06:55:19 -0700 (PDT) From: Jack Kamm To: Ihor Radchenko Cc: Liu Hui , emacs-orgmode@gnu.org Subject: Re: [PATCH] ob-python: support header argument `:results file graphics' In-Reply-To: <871qhkxaay.fsf@localhost> References: <877crh8htb.fsf@localhost> <875y71fcic.fsf@localhost> <877crfvrsf.fsf@localhost> <87v8ez0w41.fsf@gmail.com> <87y1ju8vpp.fsf@localhost> <87sfa121q1.fsf@gmail.com> <871qhkxaay.fsf@localhost> Date: Sat, 08 Jul 2023 06:55:17 -0700 Message-ID: <87h6qe1pa2.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::42a; envelope-from=jackkamm@gmail.com; helo=mail-pf1-x42a.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: -7.95 X-Spam-Score: -7.95 X-Migadu-Queue-Id: 05B2E381A3 X-Migadu-Scanner: mx2.migadu.com X-TUID: tJkMjQZGPkUM Ihor Radchenko 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.