From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id iAmaMxyPZGOn6wAAbAwnHQ (envelope-from ) for ; Fri, 04 Nov 2022 05:03:40 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id sPCjMxyPZGOpIQEAauVa8A (envelope-from ) for ; Fri, 04 Nov 2022 05:03:40 +0100 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 445EA39A90 for ; Fri, 4 Nov 2022 05:03:39 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqnud-00019l-5w; Fri, 04 Nov 2022 00:02:35 -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 1oqnub-00018O-Hh for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 00:02:33 -0400 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqnuZ-0001eW-15 for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 00:02:33 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 7F820240101 for ; Fri, 4 Nov 2022 05:02:27 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1667534547; bh=zScL8YWSMMOoEjTcriBshsduwoIqSR5x0oJfEKl4rNk=; h=From:To:Cc:Subject:Date:From; b=hyd7koiWew5lXr9SbKs97MFkcmEEjKOhdCZ+Vo5te2xYGOzx68CEO5p91Igj1+tKN TcceUr73yzEoe7sqMRT8q74kB/SM0wQQLFL0vueue++e4jV6gkXH5E+di2bSGTq77Z cq5SqzSoMvwkjnNhRqFERx59bdlN9+e675KciEjoZcT8r0zVUXHYxfS9rrpmN18Z9W zMGpgHQuC5f/UQf8eqBTvmW3OMJdZNBOyckINb4zbNka82ghPEarh2IMJ1VZ6yM8Hm 39QZ8uYqCcdUdSGRoyZhPPM02RfA9MS8XboFcLBQWjw5Hu1OnlyduxiRrONIWV1YB7 iOhwzH2e6zKyg== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N3Rm217YJz6tm4; Fri, 4 Nov 2022 05:02:25 +0100 (CET) From: Ihor Radchenko To: Leo Butler Cc: Org Mode Mailing List Subject: Clarification on :results file vs. :results graphics file (was: [BUG] ob-doc-maxima.org and ob-maxima.el) In-Reply-To: <87edujkiq2.fsf@t14.reltub.ca> References: <87edulm9hk.fsf@t14.reltub.ca> <87wn8c7cpn.fsf@localhost> <87edujkiq2.fsf@t14.reltub.ca> Date: Fri, 04 Nov 2022 04:03:06 +0000 Message-ID: <87eduj5ptx.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.posteo.de 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, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 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: , Sender: "Emacs-orgmode" Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1667534620; 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=NWZRmgpxLUfxbOBBR2RIyJvU9TgL+SY8fuycHyHgJIA=; b=d+ju9ZbOUpENu3Nc7HcpjyYcq6LE5e1hztoI8Dw0kwO21rPKdK8qMILz+xl/18zkRJbd4p CjSkrFCSWKwQZa5tPoYbku+e9gmlHt9rzQQNwNPfVQ5rHxoS4RAneG3cHkpAdmGPyAgrKb AlNkvvklBTOP7Zqox17GXW1RDC669Mi1cxwoTvHkdVAc9G6WBkTK+mBVRysDZdm7FbmT4+ 5+ulDQpAf7vYftS6mkun0wZ2OpJxcFJZrqZ+LWYgnqjIcPot9HwA33HXhtYg8rDWYYXihL uPcPn8xAZmEcXufGRE63IqopZR7rpRcanzwlBdCcjS0kL85JCh0VrkYW2OI19g== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667534620; a=rsa-sha256; cv=none; b=P6X09VugE+ijMfmtbXli6zX8hjVcdpAVf3At0yMBf7kgAI866rtcVhXlC6OS3UKG11pyGh YFLlx9OoedXC7+l3SjrpiJuprTHsL+EW6QhHBEzd1veVvKYJi7eV3LUaPo5it3xNIMUjMo H3jQwMqYjBVFydk9qkOxUR0CF3RxUKe5mGKqrZoztaA/RuDSpd+hl8DQ4aFLFF7fj7vJIF wyNlpKyRLjG6v/P2gfci9Gnwvzc71ag/DjOXV3bKFkVOVuSuT4sQ2WTOJoHRd/ynfh8aYa anKpOucal9v0xdYe8/5rg8cgFOsijS84R/IBwazTjI2IGym6cHVvkkD6H0sJRQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=hyd7koiW; dmarc=pass (policy=none) header.from=posteo.net; 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" X-Migadu-Spam-Score: -8.50 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=hyd7koiW; dmarc=pass (policy=none) header.from=posteo.net; 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" X-Migadu-Queue-Id: 445EA39A90 X-Spam-Score: -8.50 X-Migadu-Scanner: scn0.migadu.com X-TUID: jnvf3Q374M9B --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Leo Butler writes: >>> @@ -145,7 +151,7 @@ This example is from [[http://maxima.sourceforge.ne= t/maxima-gnuplot.html][a tuto >>> ,#+name: 3d-maxima >>> ,#+header: :file images/maxima-3d.png >>> ,#+header: :exports results >>> -,#+header: :results graphics >>> +,#+header: :results graphics file >> >> Using graphics together with file does not make sense. > > Ok. But I am not sure the code agrees with you. In ob-core.el, > `org-babel-graphical-output-file' is defined as: > > (defun org-babel-graphical-output-file (params) > "File where a babel block should send graphical output, per PARAMS. > Return nil if no graphical output is expected. Raise an error if > the output file is ill-defined." > (let ((file (cdr (assq :file params)))) > (cond (file (and (member "graphics" (cdr (assq :result-params params)= )) > file)) > ... > > Is it, in your opinion, ob-maxima's responsibility to add "graphics" to > :result-params when :results file is specified? No. Let me put what the manual says on the question: - :results header argument has multiple argument classes Each code block can take only one option per class: =20=20=20=20 Collection For how the results should be collected from the code block; =20=20=20=20 Type For which type of result the code block will return; affects how Org processes and inserts results in the Org buffer; =20=20=20=20 Format For the result; affects how Org processes results; =20=20=20=20 Handling For inserting results once they are properly formatted. :results file is the Type class. :results graphics is the Format class. They can be used together. I was wrong in my earlier reply. =E2=80=98file=E2=80=99 Interpret as a filename. Save the results of execution of the code block to that file, then insert a link to it. You can control both the filename and the description associated to the link. =E2=80=98graphics=E2=80=99 When used along with =E2=80=98file=E2=80=99 type, the result is a link= to the file specified in =E2=80=98:file=E2=80=99 header argument. However, unlike= plain =E2=80=98file=E2=80=99 type, nothing is written to the disk. The block is used for its side-effects only, as in the following example: (Note: I'd say "nothing is written to the disk" is a bit misleading here. I am attaching a patch with clarification) When we have :file foo.png :results file, Org will take the command output, write it to foo.png, and insert the link to foo.png as code block result. When we have :file foo.png :results file graphics, Org will not write to foo.png itself. Instead, it will expect the code execution to create foo.png as a side effect. The code output will be ignored and the link to foo.png will be inserted. Note: ob-maxima wraps `org-babel-graphical-output-file' into ignore-errors, which will hide missing :file spec error from user. Unsure about the reasons behind it. > @@ -77,6 +77,9 @@ > "Execute a block of Maxima entries with org-babel. > This function is called by `org-babel-execute-src-block'." > (message "Executing Maxima source code block") > + ;; Make `:results file' imply `:results graphics file' > + (when (member "file" (assq :result-params params)) > + (push "graphics" (alist-get :result-params params))) This will be wrong, as I explained above. :results file and :results graphics file are expected to behave differently in the manual. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-org-manual-Clarify-results-file-graphics-header-argu.patch >From 73821c511e723e324e3f7aa9424003b8993ed412 Mon Sep 17 00:00:00 2001 Message-Id: <73821c511e723e324e3f7aa9424003b8993ed412.1667534563.git.yantar92@posteo.net> From: Ihor Radchenko Date: Fri, 4 Nov 2022 12:01:19 +0800 Subject: [PATCH] org-manual: Clarify :results file graphics header argument meaning * doc/org-manual.org (Format): Clarify the difference between :results file and :results file graphics. Update the example to something that can be tried locally. --- doc/org-manual.org | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index dc2fc57cd..b3071ec6d 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -18408,13 +18408,17 @@ *** Format When used along with =file= type, the result is a link to the file specified in =:file= header argument. However, unlike plain =file= - type, nothing is written to the disk. The block is used for its - side-effects only, as in the following example: + type, code block output is not written to the disk. The block is + expected to generate the file by its side-effects only, as in the + following example: #+begin_example - ,#+begin_src shell :results file link :file "download.tar.gz" - wget -c "https://example.com/download.tar.gz" + ,#+begin_src shell :results file link :file "org-mode-unicorn.svg" + wget -c "https://orgmode.org/resources/img/org-mode-unicorn.svg" ,#+end_src + + ,#+RESULTS: + [[file:org-mode-unicorn.svg]] #+end_example - =org= :: -- 2.35.1 --=-=-= Content-Type: text/plain -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at --=-=-=--