Include lines in setupfile are not evaluated: bug or feature?

Include lines in setupfile are not evaluated: bug or feature?

[Jarmo Hurri]

Greetings.

I am (still) trying to figure out a SINGLE common setup/include file for
all settings for a large batch of files.

I found out recently that common #properties can be set in a setup file
(but not in an included file). However, now it seems that in a setup
file I can not include all common included files. Is this intended
behaviour?

Below is an example that demonstrates this. First the main (exported
file):

# ----------------------- file main-file.org ----------------------------
#+setupfile: setup-file.org

src_elisp[:exports results :results raw]{(org-entry-get nil "MY_PROPERTY" t)}
# -----------------------------------------------------------------------

Then the setup file:

# ------------------ file setup-file.org ----------------------------
#+property: MY_PROPERTY true
#+include: setup-included.org
# -----------------------------------------------------------------------

Then the file that is supposed to be included in the setup file (and,
consequently, in the main file):

# ------------------ file setup-included.org ----------------------------
Some text to be included.
# -----------------------------------------------------------------------

But the text is not included in the main file. Documentation of
#setupfile says that

"Org parses the contents of this document as if it was included in the
buffer."

https://orgmode.org/manual/In_002dbuffer-settings.html

But that does not seem to be the case.

Jarmo

Re: Include lines in setupfile are not evaluated: bug or feature?

[Nicolas Goaziou]

Jarmo Hurri <jarmo.hurri@iki.fi> writes:

> Greetings.
>
> I am (still) trying to figure out a SINGLE common setup/include file for
> all settings for a large batch of files.
>
> I found out recently that common #properties can be set in a setup file
> (but not in an included file). However, now it seems that in a setup
> file I can not include all common included files. Is this intended
> behaviour?
>
> Below is an example that demonstrates this. First the main (exported
> file):
>
> # ----------------------- file main-file.org ----------------------------
>
> #+setupfile: setup-file.org
>
> src_elisp[:exports results :results raw]{(org-entry-get nil "MY_PROPERTY" t)}
> # -----------------------------------------------------------------------
>
> Then the setup file:
>
> # ------------------ file setup-file.org ----------------------------
>
> #+property: MY_PROPERTY true
> #+include: setup-included.org
>
> # -----------------------------------------------------------------------
>
> Then the file that is supposed to be included in the setup file (and,
> consequently, in the main file):
>
> # ------------------ file setup-included.org ----------------------------
> Some text to be included.
> # -----------------------------------------------------------------------
>
> But the text is not included in the main file. Documentation of
> #setupfile says that
>
> "Org parses the contents of this document as if it was included in the
> buffer."
>
> https://orgmode.org/manual/In_002dbuffer-settings.html
>
> But that does not seem to be the case.

SETUPFILE and INCLUDE are orthogonal. There is no point in mixing them.

SETUPFILE keyword recursively loads configuration from other files,
without inserting anything. INCLUDE keyword recursively inserts contents
from other files in the current document, but there is no guarantee that
configuration from these files will be inherited.

As a rule of thumb, if you want to access to metadata (i.e., keywords),
use SETUPFILE, if you are interested in contents, use INCLUDE. Note that
you can have both for a single file.

Regards,

-- 
Nicolas Goaziou

Re: Include lines in setupfile are not evaluated: bug or feature?

[Jarmo Hurri]

Hello Nicolas!

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> SETUPFILE and INCLUDE are orthogonal. There is no point in mixing
> them.

Ok. As a programmer I was hoping to mix them, because it would be
logical to have _one_ header file that defines all the common things for
a set of related files.

But perhaps I can get away with using SETUPFILEs only. I will see.

> Jarmo Hurri <jarmo.hurri@iki.fi> writes:
>> Documentation of #setupfile says that
>>
>> "Org parses the contents of this document as if it was included in the
>> buffer."
>>
>> https://orgmode.org/manual/In_002dbuffer-settings.html
>>
>> But that does not seem to be the case.
>
> SETUPFILE keyword recursively loads configuration from other files,
> without inserting anything. INCLUDE keyword recursively inserts
> contents from other files in the current document, but there is no
> guarantee that configuration from these files will be inherited.

Do I understand correctly: the description in the documentation is not
correct in the sense that not all contents from SETUPFILE is evaluated
as if it were included in the buffer?

I am just trying to think about how this limitation, if it exists,
should be expressed in documentation. Shall I give it a try?

Thanks for the clarifying response!

Jarmo

Re: Include lines in setupfile are not evaluated: bug or feature?

[Nicolas Goaziou]

Hello,

Jarmo Hurri <jarmo.hurri@iki.fi> writes:

> Ok. As a programmer I was hoping to mix them, because it would be
> logical to have _one_ header file that defines all the common things for
> a set of related files.

Again, there is no overlap between the two keywords. SETUPFILE is what
you want. INCLUDE is only meaningful during export (and is only
documented there). I cannot think of a real situation where you would
need both for the same file.

> Do I understand correctly: the description in the documentation is not
> correct in the sense that not all contents from SETUPFILE is evaluated
> as if it were included in the buffer?

I think the document is correct, although I understand it can be
misleading: it uses the verb "to include", but with a different meaning
than INCLUDE keyword. It includes in-buffer settings, not full contents.

> I am just trying to think about how this limitation, if it exists,
> should be expressed in documentation. Shall I give it a try?

Sure, but please do not mix SETUPFILE and INCLUDE, which are unrelated.

Regards,

-- 
Nicolas Goaziou

Re: Include lines in setupfile are not evaluated: bug or feature?

[Jarmo Hurri]

Greetings again.

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

>> Ok. As a programmer I was hoping to mix them, because it would be
>> logical to have _one_ header file that defines all the common things
>> for a set of related files.
>
> Again, there is no overlap between the two keywords. SETUPFILE is what
> you want. INCLUDE is only meaningful during export (and is only
> documented there). I cannot think of a real situation where you would
> need both for the same file.

I have such documents regularly.
1. One type is a handout containing common contents at the beginning
   (included) and settings (setup).
2. The other case is a set of files sharing setup info and code (babel
   blocks, included).

>> Do I understand correctly: the description in the documentation is
>> not correct in the sense that not all contents from SETUPFILE is
>> evaluated as if it were included in the buffer?
>
> I think the document is correct, although I understand it can be
> misleading: it uses the verb "to include", but with a different
> meaning than INCLUDE keyword. It includes in-buffer settings, not full
> contents.
>
>> I am just trying to think about how this limitation, if it exists,
>> should be expressed in documentation. Shall I give it a try?
>
> Sure, but please do not mix SETUPFILE and INCLUDE, which are
> unrelated.

I will give it a try during the Christmas break.

All the best,

Jarmo

Re: Include lines in setupfile are not evaluated: bug or feature?

[Nicolas Goaziou]

Hello,

Jarmo Hurri <jarmo.hurri@iki.fi> writes:

> I have such documents regularly.
> 1. One type is a handout containing common contents at the beginning
>    (included) and settings (setup).
> 2. The other case is a set of files sharing setup info and code (babel
>    blocks, included).

Then I suggest to unravel what is needed at runtime and what is required
at export time.

Regards,

-- 
Nicolas Goaziou