Re: Introducing Org-transclusion

[Ihor Radchenko]

Noboru Ota <me@nobiot.com> writes:

>> 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 (?)

Attached patches is the workflow in this mailing list. Do not worry
about cluttering. Clutter is meaningless text, not a patch. We have
recommendations about submitting new patches at
https://orgmode.org/worg/org-contribute.html

Once you submit _something_, core maintainers will be more inclined to
jump in and provide their opinion on including the new feature.

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

I actually had something slightly different in mind. If we have a way to
copy and sync text between different places, we can as well compile all
the related source blocks into a temporary buffer in the correct
prog-mode. Then, C-c ' can simply jump to that buffer with all the code
from different source blocks bundled together. Changes in the temporary
buffer can then be synced on exit.

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

Can be flymake as well. The problem with current implementation of
source blocks is that only the code from individual source block is
visible for flymake. Imagine the following

#+begin_src emacs-lisp
(progn
 (message "A")
#+end_src

#+begin_src emacs-lisp
 (message "B"))
#+end_src

If you open the top source block with C-c ', flymake will report errors
because of unmatched parenthesis. The errors will be correct from
flymake's perspective because all flymake will see is text in the first
source block. However, the code is correct when you tangle the file.

If we can have a single buffer with all the source blocks, C-c ' can
simply jump to that buffer and narrow to region representing the current
source block. flymake will behave correctly because all the code will be
present in the buffer. Moreover, the user may widen the buffer
conveniently see all the code together. Tangling will be mostly a
question of simply saving the temporary buffer.

Trnasclusion is required to correctly keep the temporary code buffer and
actual Org file in sync.

Of course, things like noweb will be tricky. You may need something
similar to bi-directional text transformation like implemented in
lentic, when changes in text are not simply mirrored, but the text is
also transformed when syncing transcluded regions. You implemented
something similar in the :level parameter.

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

I noticed that you are using overlays in text-clone. It may potentially
cause slowdown in large Org buffers. Of course, it does not mean that
org-transclusion should not be accepted. Just something that may be
optimised.

Best,
Ihor