all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* [BUG] Documentation for #+INCLUDE: does not specify order when exporting [9.5.5 (release_9.5.5 @ /usr/share/emacs/28.2/lisp/org/)]
@ 2023-04-08 13:28 Tim Landscheidt
  2023-04-08 14:27 ` Ihor Radchenko
  0 siblings, 1 reply; 3+ messages in thread
From: Tim Landscheidt @ 2023-04-08 13:28 UTC (permalink / raw)
  To: emacs-orgmode

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.


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [BUG] Documentation for #+INCLUDE: does not specify order when exporting [9.5.5 (release_9.5.5 @ /usr/share/emacs/28.2/lisp/org/)]
  2023-04-08 13:28 [BUG] Documentation for #+INCLUDE: does not specify order when exporting [9.5.5 (release_9.5.5 @ /usr/share/emacs/28.2/lisp/org/)] Tim Landscheidt
@ 2023-04-08 14:27 ` Ihor Radchenko
  2024-02-12 13:59   ` Ihor Radchenko
  0 siblings, 1 reply; 3+ messages in thread
From: Ihor Radchenko @ 2023-04-08 14:27 UTC (permalink / raw)
  To: Tim Landscheidt; +Cc: emacs-orgmode

Tim Landscheidt <tim@tim-landscheidt.de> writes:

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

Sure. We can add a section summarizing the export process at the end of
"13 Exporting". Patches welcome!

The export sequence is implemented in `org-export-as'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Confirmed.


^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: [BUG] Documentation for #+INCLUDE: does not specify order when exporting [9.5.5 (release_9.5.5 @ /usr/share/emacs/28.2/lisp/org/)]
  2023-04-08 14:27 ` Ihor Radchenko
@ 2024-02-12 13:59   ` Ihor Radchenko
  0 siblings, 0 replies; 3+ messages in thread
From: Ihor Radchenko @ 2024-02-12 13:59 UTC (permalink / raw)
  To: Tim Landscheidt; +Cc: emacs-orgmode

Ihor Radchenko <yantar92@posteo.net> writes:

>> But I do think it would be helpful if the "order" while ex-
>> porting would be documented in a meaningful way.

Details of the export flow have been added to the manual.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=46cf76259
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=5cbaa8747

Fixed, on main.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>


^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2024-02-12 13:56 UTC | newest]

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

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.