Have you considered overloading `#+include:`?

[tecosaur]

I think this could be nice, and so here's an issue for discussion :slightly_smiling_face:

[nobiot]

No. Because... What does "overloading" mean? 😅

[tecosaur]

Well, my thought is that #+transclude and #+include have a lot of semantic overlap, so you could use #+include statements, and just recognise 'extra' properties for the full functionality function of #+transclude. The only case I can think of this being problematic is if one want's to #+transclude something, but not #+include -- but this doesn't feel like a hard problem.

[nobiot]

oh yes. I see. I think you asked me this before on Reddit. I guess we can find out by having a branch and test out the idea.

I'll see if I can do something tomorrow or in about two weeks time.

I'm not going to sit in front of PC this evening and I will have a vacation for two weeks after tomorrow (probably with no laptop) ;)

[nobiot]

As an exploration, added a new branch explore/0.2.1-include. At the moment, I am thinking that you should consciously decide whether or not to use #+include as a transclude keyword, so have added a user option org-transclusion-include-is-also-transclude (default t for this branch).

The idea is that when you export, #+include should also work as normal. This requires a little more work. Notably, I will need to change the syntax to also parse a link within double quotation marks. See below.

This is standard include syntax; not transcluded
#+include: "include-content.org::Heading to be included" :only-contents nil

This gets transcluded
#+include: [[file:include-content.org::Heading to be included]] :only-contents

I'll stop here for now. I'll be checking GitHub on iPad but won't carry my laptop with me for my vacation; I'll come back in 2 weeks or so :)

[alphapapa]

FWIW, that looks confusing to me, because the word "transclude" is nowhere to be found in it. :)

I think that overloading #+include: is not a good idea. Inclusion and transclusion are distinct operations. As well, inclusion is built-in, while transclusion is a third-party package.

[tecosaur]

So, I've ended up being unfortunately busy and juggling notifications (why life?), but seeing this mentioned on the Org ML recently jogged my memory about this. Regarding #+include and transclusion, I see @alphapapa's concern that it's mixing a built-in operation with a package/extra, but isn't #+include basically at-export-time transclusion?

[nobiot]

Soon after this conversation in June, I tried to change the code to support both #+transclude and #+include keywords -- I failed; it's a bit more complicated than I initially assumed.

I'm not settled either way, but I am leaning toward leaving #+include as it is now. I would like to see how the discussion in the mailing list evolves.

isn't #+include basically at-export-time transclusion?

I think the same way, conceptually speaking.

And this part of Ihor Radchenko's reply is going in the same direction:

3. Visible #+INCLUDE directives. I recall multiple requests to be able to see the INCLUDEd files right inside source Org buffer.

Functionally, though, there are some differences. Notably, I don't seem to be able to support "noweb references" (I'm still unsure what this really is, but I know there is a limitation).

Org-transclusion does not support expansion of noweb references when a transcluded source block code has them Refer to issue #86. You will get “Text-only” error when export tries to expand the noweb references into the source code.

[daraul]

Personally, I see #+transclude as a natural "evolution" of #+include. I would not mind if it extended the #+include keyword; some people may have existing documents with the #+include keyword, and may not want to have to go around changing those keywords to get the transclusion functionality.