Re: Introducing Org-transclusion

[Noboru Ota]

Ihor Radchenko <yantar92@gmail.com> writes:
>
> Welcome ;)
>

Thank you.

> You have my +100500 to have this package as part of Org :D

Thank you again :) Is there anything I can/should do to make this
happen?  I would be happy to email the whole package as a "patch" for
code review, if this were the way but I feel that might clutter this
mailing list too much with a large amount of text (?)


> The package may allow several interesting things in Org:
>
> 1.  An alternative way to structure headings
>     Currently, we have a rigid headline structures in Org and
>     alternative tag-based approaches like Org Roam. Headline
>     transclusion will allow same subtree under several headings (aka
>     file system symlinks).

Org-transclusion will be probably of help here. I didn't think it in
this frame (like symlinks) but it has the :level property to control the
heading level of the transclusion, which can be different to the original.


> 2. A much faster tangle system. If we can directly transclude and sync
>    contents of source blocks with actual programming language buffer,
>    C-c ' can trivially support flycheck-mode and provide a more
>    IDE-like experience while still benefiting from literate programming
>    style.

It has ":src lang" property and can transclude a specific range of
source code into Org's source block. It is essentially read-only copy of
the original, and you can use "C-c C-c" as a normal Org source block to
execute/evaluate it.

For flycheck-mode, I am not sure; I don't use it (I use built-in
flymake).  It may be an interesting experiment for me, too.  One thing
is that transcluded source blocks are read-only.  I think it will
require a bit of work to get the correction to work on both the
transclusion and source buffers.


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

There is a parallel between #+INCLUDE and #+TRANSCLUDE.  Transclusions
are read-only copy so they can be exported.  I think in many cases they
can work as "visible #+INCLUDE".

But #+TRANSCLUDE does not support all the features #+INCLUDE
support. For example, noweb to include yet another block of text has
been reported to output an error.


> 4. Dynamic Org files like agenda views, but made of transcluded
>    headlines. Such files can be kept in Org mode with all its features.

Maybe... I don't use Org-agenda, so it didn't occur to me to test this
use case.  


> Transculation has been requested many times by different users. Some
> relevant links:
> - 
> https://emacs.stackexchange.com/questions/51814/embed-org-task-list-from-other-subtree
> - 
> https://www.reddit.com/r/emacs/comments/dz5xeb/is_there_a_way_to_include_an_org_file_in_another/
> - 
> https://www.reddit.com/r/emacs/comments/flxqei/cloningmirroring_a_region_to_some_other_location/fl22ele/
> - https://lists.gnu.org/archive/html/emacs-devel/2020-04/msg00141.html
> - 
> https://emacs.stackexchange.com/questions/57608/split-code-across-multiple-src-blocks
> - https://lists.gnu.org/archive/html/help-gnu-emacs/2020-06/msg00151.html
> - 
> https://reddit.com/r/emacs/comments/debean/possible_to_embed_another_org_file_or_entry_in_an/]]

Org-transclusion might provide some steps forward for some of the
desired functionality discussed in these threads.  Especially for the
"cloning" a body of text across multiple buffers, I have factored out
this part and created a stand-alone library called "Text-clone".  It is
available in the same repository at
https://github.com/nobiot/org-transclusion/blob/main/docs/text-clone.md.

This separation was born out of a suggestion by alphapapa on Reddit.

I feel that Text-clone can be taken further than the use in
Org-transclusion (I feel that Org-transclusion is only one use case for
Text-clone).


> Other attempted implementations:
> - https://github.com/legalnonsense/org-clones
> - https://github.com/magnars/multifiles.el
> - https://github.com/vspinu/lentic
> - https://github.com/whacked/transclusion-minor-mode

Yes, I have looked at some of them and also this question from John
Kitchen, recorded by alphapapa: 
(https://github.com/alphapapa/transclusion-in-emacs#org-mode).

I also looked at https://github.com/gregdetre/emacs-freex. 

Org-clones have given me some inspirations.  Multifiles looked to be too
complicated for me to understand and abandoned for a long time. I was
not aware of Lentic.  I dismissed Transclusion-minor-mode because it
requires a server.

Org-transclusion is rather simple. It only requires Emacs 27.1 and Org 9.4.

> Best,
> Ihor