From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id WC7fAUxsMWRHfwEASxT56A (envelope-from ) for ; Sat, 08 Apr 2023 15:29:48 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id gAcYAUxsMWQsKwAA9RJhRA (envelope-from ) for ; Sat, 08 Apr 2023 15:29:48 +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 914A7FC25 for ; Sat, 8 Apr 2023 15:29:47 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pl8co-0002TS-FU; Sat, 08 Apr 2023 09:29:03 -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 1pl8ck-0002Sr-TK for emacs-orgmode@gnu.org; Sat, 08 Apr 2023 09:28:59 -0400 Received: from andalucia.tim-landscheidt.de ([2a01:4f8:1c1c:d4d0::1]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pl8ch-0004DB-Fw for emacs-orgmode@gnu.org; Sat, 08 Apr 2023 09:28:57 -0400 Received: from [195.226.160.202] (port=43054 helo=vagabond) by andalucia.tim-landscheidt.de with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1pl8cc-0002kJ-OL for emacs-orgmode@gnu.org; Sat, 08 Apr 2023 13:28:50 +0000 From: Tim Landscheidt To: emacs-orgmode@gnu.org Subject: [BUG] Documentation for #+INCLUDE: does not specify order when exporting [9.5.5 (release_9.5.5 @ /usr/share/emacs/28.2/lisp/org/)] Organization: https://www.tim-landscheidt.de/ Date: Sat, 08 Apr 2023 13:28:50 +0000 Message-ID: <87jzymv6y5.fsf@vagabond.tim-landscheidt.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a01:4f8:1c1c:d4d0::1; envelope-from=tim@tim-landscheidt.de; helo=andalucia.tim-landscheidt.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, 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: , 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 ARC-Seal: i=1; s=key1; d=yhetil.org; t=1680960587; a=rsa-sha256; cv=none; b=InVKVGJChmq2FKjgG1f1qHtagHV8gptwP9Uc3nw8cBJUfqqjXqiAEgIsHZBoZibzVja+2J zOCMbAvpyRmREPiV6Uw4rUBOREQViWndRH6SwzY7Yq0aOA8zLulzDVo0iIIDutRTKsKGZO ms/W8Fr81Do3BVqYu9FKVxc+kItcqbrAjMDjU4BO/CFGq/cEvfy7hO5JbbZIEWflGVNYJg mhsvXOa5+Ec5sRByxyNYBxj1uhpZvl37Bgy7VMFFLdNK2hVdGkKfMapjPF7vX+DOCm0vAg emUiunSRjixmy6Wd42GFY1c0MiL+J9feirkha72P+7D1D8efm2XLY/58N9BHsg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=none; 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" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1680960587; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=2DiXXvK6QbXW57ub3jkxw7ZY3Yf51AGOWh4vtlbPf0w=; b=IxKQN1mcESvlmnK01u1Rcl/Fn2TVuFW6co+orYr5jZlKdgl8wwYIY0jOaqhdmR9WV47Q9b fZPexlmSgWH0prMxSmPM0UWgb0n+NuaZ2JJOuOg5dYRU/UGzjymn9eYUsYNae/VHaRJuV4 glMmIlvZ5VEQM1gZ/lk11TD99vTv2Nc+RiagUdY+N251qQxi/hfVKlT2sImqr/X9IvgsHC i5ow/DSFmrGe+f0aaM9AYc+nDJ9m5kdID6dvCMewTYGU4lk0POVHUvibWfvCRCsln05u3f IMNw1TqKKMq4fUaiaUOjJRmulOsYR6oUCIRE2cYfZRijEirqLTPPDnyqEUMiFw== X-Migadu-Spam-Score: -3.02 X-Migadu-Scanner: scn1.migadu.com Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=none; 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-Spam-Score: -3.02 X-Migadu-Queue-Id: 914A7FC25 X-TUID: lfbTXxIvy/WB With the Org file: | #+BEGIN_SRC python :results silent :exports results | test =3D '1' | with open('test-a.log', 'w') as f: | f.write(f'Test {test}a\n') | with open('test-b.log', 'w') as f: | f.write(f'Test {test}b\n') | #+END_SRC | Test, part A: | #+INCLUDE: "test-a.log" verbatim | Test, part B: | #+INCLUDE: "test-b.log" verbatim and test-a.log and test-b.log not existing, on the first (unsuccessful) export, the error: | org-export-expand-include-keyword: Cannot include file /tmp/test-a.log is displayed. However, if these files already exist, they are included as is, and /after/ that inclusion, the Python source block is executed. This means that if one changes "test =3D '1'" to "test =3D '2'" in the Python source block, one has to export the Org file twice to see the changed result in the export. Technically, this is probably the "correct" behaviour as otherwise the order of execution would be very hard to de- termine. But why did I spend a few hours debugging this before final- ly understanding Org's mode of operation? The first sen- tence of the documentation in "13.4 Include Files" reads: | During export, you can include the content of another file. | [=E2=80=A6] I'm not a native speaker, but the word "during" drew the mental image for me that, when exporting, Org starts at the top of the document, reads through to the end, and if en- counters a "#+INCLUDE:" statement /during/ that, it includes the referenced file at that point. Now the Org manual is already beset with examples that look as if someone complained about something not being document- ed somewhere, and then someone adding one sentence just that somewhere, so I don't want to add to that with "just a quick fix". But I do think it would be helpful if the "order" while ex- porting would be documented in a meaningful way.