emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

From: Tim Landscheidt <tim@tim-landscheidt.de>
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/)]
Date: Sat, 08 Apr 2023 13:28:50 +0000	[thread overview]
Message-ID: <87jzymv6y5.fsf@vagabond.tim-landscheidt.de> (raw)

With the Org file:

| #+BEGIN_SRC python :results silent :exports results
|   test = '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 = '1'" to "test = '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.
| […]

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.

next             reply	other threads:[~2023-04-08 13:29 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-04-08 13:28 Tim Landscheidt [this message]
2023-04-08 14:27 ` [BUG] Documentation for #+INCLUDE: does not specify order when exporting [9.5.5 (release_9.5.5 @ /usr/share/emacs/28.2/lisp/org/)] Ihor Radchenko
2024-02-12 13:59   ` Ihor Radchenko

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=87jzymv6y5.fsf@vagabond.tim-landscheidt.de \
    --to=tim@tim-landscheidt.de \
    --cc=emacs-orgmode@gnu.org \
    /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

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).